1# drawing_bitmap.h 2 3<!--Kit: ArkGraphics 2D--> 4<!--Subsystem: Graphic--> 5<!--Owner: @hangmengxin--> 6<!--Designer: @wangyanglan--> 7<!--Tester: @nobuggers--> 8<!--Adviser: @ge-yafang--> 9 10## 概述 11 12文件中定义了与位图相关的功能函数。 13 14<!--RP1--> 15**相关示例：** [NDKAPIDrawing (API14)](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/DocsSample/Drawing/NDKAPIDrawing)<!--RP1End--> 16 17**引用文件：** <native_drawing/drawing_bitmap.h> 18 19**库：** libnative_drawing.so 20 21**起始版本：** 8 22 23**相关模块：** [Drawing](capi-drawing.md) 24 25## 汇总 26 27### 结构体 28 29| 名称 | typedef关键字 | 描述 | 30| -- | -- | -- | 31| [OH_Drawing_BitmapFormat](capi-drawing-oh-drawing-bitmapformat.md) | OH_Drawing_BitmapFormat | 结构体用于描述位图像素的格式，包括颜色类型和透明度类型。 | 32 33### 函数 34 35| 名称 | 描述 | 36| -- | -- | 37| [OH_Drawing_Bitmap* OH_Drawing_BitmapCreate(void)](#oh_drawing_bitmapcreate) | 用于创建一个位图对象。 | 38| [void OH_Drawing_BitmapDestroy(OH_Drawing_Bitmap* bitmap)](#oh_drawing_bitmapdestroy) | 用于销毁位图对象并回收该对象占有内存。 | 39| [OH_Drawing_Bitmap* OH_Drawing_BitmapCreateFromPixels(OH_Drawing_Image_Info* imageInfo, void* pixels, uint32_t rowBytes)](#oh_drawing_bitmapcreatefrompixels) | 用于创建一个位图对象，并将位图像素存储内存地址设置为开发者申请内存的地址。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>imageInfo、pixels任意一个为NULL或者rowBytes等于0时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 40| [void OH_Drawing_BitmapBuild(OH_Drawing_Bitmap* bitmap,const uint32_t width, const uint32_t height, const OH_Drawing_BitmapFormat* bitmapFormat)](#oh_drawing_bitmapbuild) | 用于初始化位图对象的宽度和高度，并且为该位图设置像素格式。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>bitmap、bitmapFormat任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 41| [uint32_t OH_Drawing_BitmapGetWidth(OH_Drawing_Bitmap* bitmap)](#oh_drawing_bitmapgetwidth) | 用于获取指定位图的宽度。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>bitmap为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 42| [uint32_t OH_Drawing_BitmapGetHeight(OH_Drawing_Bitmap* bitmap)](#oh_drawing_bitmapgetheight) | 用于获取指定位图的高度。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>bitmap为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 43| [OH_Drawing_ColorFormat OH_Drawing_BitmapGetColorFormat(OH_Drawing_Bitmap* bitmap)](#oh_drawing_bitmapgetcolorformat) | 用于获取指定位图的像素存储格式。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>bitmap为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 44| [OH_Drawing_AlphaFormat OH_Drawing_BitmapGetAlphaFormat(OH_Drawing_Bitmap* bitmap)](#oh_drawing_bitmapgetalphaformat) | 用于获取指定位图的像素透明度分量。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>bitmap为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 45| [void* OH_Drawing_BitmapGetPixels(OH_Drawing_Bitmap* bitmap)](#oh_drawing_bitmapgetpixels) | 用于获取指定位图的像素地址，可以通过像素地址获取到位图的像素数据。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>bitmap为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 46| [void OH_Drawing_BitmapGetImageInfo(OH_Drawing_Bitmap* bitmap, OH_Drawing_Image_Info* imageInfo)](#oh_drawing_bitmapgetimageinfo) | 用于获取指定位图的信息。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>bitmap、imageInfo任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 47| [bool OH_Drawing_BitmapReadPixels(OH_Drawing_Bitmap* bitmap, const OH_Drawing_Image_Info* dstInfo,void* dstPixels, size_t dstRowBytes, int32_t srcX, int32_t srcY)](#oh_drawing_bitmapreadpixels) | 将位图中的矩形区域像素数据读取到指定的内存缓冲区中。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>bitmap、dstInfo、dstPixels任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 48 49## 函数说明 50 51### OH_Drawing_BitmapCreate() 52 53``` 54OH_Drawing_Bitmap* OH_Drawing_BitmapCreate(void) 55``` 56 57**描述** 58 59用于创建一个位图对象。 60 61**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 62 63**起始版本：** 8 64 65**返回：** 66 67| 类型 | 说明 | 68| -- | -- | 69| [OH_Drawing_Bitmap](capi-drawing-oh-drawing-bitmap.md)* | 函数会返回一个指针，指针指向创建的位图对象。 | 70 71### OH_Drawing_BitmapDestroy() 72 73``` 74void OH_Drawing_BitmapDestroy(OH_Drawing_Bitmap* bitmap) 75``` 76 77**描述** 78 79用于销毁位图对象并回收该对象占有内存。 80 81**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 82 83**起始版本：** 8 84 85 86**参数：** 87 88| 参数项 | 描述 | 89| -- | -- | 90| [OH_Drawing_Bitmap](capi-drawing-oh-drawing-bitmap.md)* bitmap | 指向位图对象的指针。 | 91 92### OH_Drawing_BitmapCreateFromPixels() 93 94``` 95OH_Drawing_Bitmap* OH_Drawing_BitmapCreateFromPixels(OH_Drawing_Image_Info* imageInfo, void* pixels, uint32_t rowBytes) 96``` 97 98**描述** 99 100用于创建一个位图对象，并将位图像素存储内存地址设置为开发者申请内存的地址。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>imageInfo、pixels任意一个为NULL或者rowBytes等于0时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 101 102**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 103 104**起始版本：** 12 105 106 107**参数：** 108 109| 参数项 | 描述 | 110| -- | -- | 111| [OH_Drawing_Image_Info](capi-drawing-oh-drawing-image-info.md)* imageInfo | 指向图片信息对象[OH_Drawing_Image_Info](capi-drawing-oh-drawing-image-info.md)的指针。 | 112| void* pixels | 指向像素存储的内存首地址，内存由开发者申请，保证有效性。 | 113| uint32_t rowBytes | 每行像素的大小，小于等于0时无效。 | 114 115**返回：** 116 117| 类型 | 说明 | 118| -- | -- | 119| [OH_Drawing_Bitmap](capi-drawing-oh-drawing-bitmap.md)* | 函数返回一个指针，指针指向创建的位图对象[OH_Drawing_Bitmap](capi-drawing-oh-drawing-bitmap.md)。 | 120 121### OH_Drawing_BitmapBuild() 122 123``` 124void OH_Drawing_BitmapBuild(OH_Drawing_Bitmap* bitmap,const uint32_t width, const uint32_t height, const OH_Drawing_BitmapFormat* bitmapFormat) 125``` 126 127**描述** 128 129用于初始化位图对象的宽度和高度，并且为该位图设置像素格式。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>bitmap、bitmapFormat任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 130 131**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 132 133**起始版本：** 8 134 135 136**参数：** 137 138| 参数项 | 描述 | 139| -- | -- | 140| [OH_Drawing_Bitmap](capi-drawing-oh-drawing-bitmap.md)* bitmap | 指向位图对象的指针。 | 141| const uint32_t width | 位图要初始化设置的宽度。 | 142| const uint32_t height | 位图要初始化设置的高度。 | 143| const [OH_Drawing_BitmapFormat](capi-drawing-oh-drawing-bitmapformat.md)* bitmapFormat | 位图要初始化设置的像素格式，包括像素的颜色类型和透明度类型。 | 144 145### OH_Drawing_BitmapGetWidth() 146 147``` 148uint32_t OH_Drawing_BitmapGetWidth(OH_Drawing_Bitmap* bitmap) 149``` 150 151**描述** 152 153用于获取指定位图的宽度。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>bitmap为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 154 155**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 156 157**起始版本：** 8 158 159 160**参数：** 161 162| 参数项 | 描述 | 163| -- | -- | 164| [OH_Drawing_Bitmap](capi-drawing-oh-drawing-bitmap.md)* bitmap | 指向位图对象的指针。 | 165 166**返回：** 167 168| 类型 | 说明 | 169| -- | -- | 170| uint32_t | 函数返回位图的宽度。 | 171 172### OH_Drawing_BitmapGetHeight() 173 174``` 175uint32_t OH_Drawing_BitmapGetHeight(OH_Drawing_Bitmap* bitmap) 176``` 177 178**描述** 179 180用于获取指定位图的高度。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>bitmap为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 181 182**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 183 184**起始版本：** 8 185 186 187**参数：** 188 189| 参数项 | 描述 | 190| -- | -- | 191| [OH_Drawing_Bitmap](capi-drawing-oh-drawing-bitmap.md)* bitmap | 指向位图对象的指针。 | 192 193**返回：** 194 195| 类型 | 说明 | 196| -- | -- | 197| uint32_t | 函数返回位图的高度。 | 198 199### OH_Drawing_BitmapGetColorFormat() 200 201``` 202OH_Drawing_ColorFormat OH_Drawing_BitmapGetColorFormat(OH_Drawing_Bitmap* bitmap) 203``` 204 205**描述** 206 207用于获取指定位图的像素存储格式。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>bitmap为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 208 209**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 210 211**起始版本：** 12 212 213 214**参数：** 215 216| 参数项 | 描述 | 217| -- | -- | 218| [OH_Drawing_Bitmap](capi-drawing-oh-drawing-bitmap.md)* bitmap | 指向位图对象的指针。 | 219 220**返回：** 221 222| 类型 | 说明 | 223| -- | -- | 224| [OH_Drawing_ColorFormat](capi-drawing-types-h.md#oh_drawing_colorformat) | 函数返回位图的像素存储格式，支持格式参考[OH_Drawing_ColorFormat](capi-drawing-types-h.md#oh_drawing_colorformat)。 | 225 226### OH_Drawing_BitmapGetAlphaFormat() 227 228``` 229OH_Drawing_AlphaFormat OH_Drawing_BitmapGetAlphaFormat(OH_Drawing_Bitmap* bitmap) 230``` 231 232**描述** 233 234用于获取指定位图的像素透明度分量。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>bitmap为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 235 236**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 237 238**起始版本：** 12 239 240 241**参数：** 242 243| 参数项 | 描述 | 244| -- | -- | 245| [OH_Drawing_Bitmap](capi-drawing-oh-drawing-bitmap.md)* bitmap | 指向位图对象的指针。 | 246 247**返回：** 248 249| 类型 | 说明 | 250| -- | -- | 251| [OH_Drawing_AlphaFormat](capi-drawing-types-h.md#oh_drawing_alphaformat) | 函数返回位图的像素透明度分量，支持格式参考[OH_Drawing_AlphaFormat](capi-drawing-types-h.md#oh_drawing_alphaformat)。 | 252 253### OH_Drawing_BitmapGetPixels() 254 255``` 256void* OH_Drawing_BitmapGetPixels(OH_Drawing_Bitmap* bitmap) 257``` 258 259**描述** 260 261用于获取指定位图的像素地址，可以通过像素地址获取到位图的像素数据。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>bitmap为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 262 263**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 264 265**起始版本：** 8 266 267 268**参数：** 269 270| 参数项 | 描述 | 271| -- | -- | 272| [OH_Drawing_Bitmap](capi-drawing-oh-drawing-bitmap.md)* bitmap | 指向位图对象的指针。 | 273 274**返回：** 275 276| 类型 | 说明 | 277| -- | -- | 278| void* | 函数返回位图的像素地址。 | 279 280### OH_Drawing_BitmapGetImageInfo() 281 282``` 283void OH_Drawing_BitmapGetImageInfo(OH_Drawing_Bitmap* bitmap, OH_Drawing_Image_Info* imageInfo) 284``` 285 286**描述** 287 288用于获取指定位图的信息。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>bitmap、imageInfo任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 289 290**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 291 292**起始版本：** 12 293 294 295**参数：** 296 297| 参数项 | 描述 | 298| -- | -- | 299| [OH_Drawing_Bitmap](capi-drawing-oh-drawing-bitmap.md)* bitmap | 指向位图对象[OH_Drawing_Bitmap](capi-drawing-oh-drawing-bitmap.md)的指针。 | 300| [OH_Drawing_Image_Info](capi-drawing-oh-drawing-image-info.md)* imageInfo | 指向图片信息对象[OH_Drawing_Image_Info](capi-drawing-oh-drawing-image-info.md)的指针。 | 301 302### OH_Drawing_BitmapReadPixels() 303 304``` 305bool OH_Drawing_BitmapReadPixels(OH_Drawing_Bitmap* bitmap, const OH_Drawing_Image_Info* dstInfo,void* dstPixels, size_t dstRowBytes, int32_t srcX, int32_t srcY) 306``` 307 308**描述** 309 310将位图中的矩形区域像素数据读取到指定的内存缓冲区中。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>bitmap、dstInfo、dstPixels任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 311 312**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 313 314**起始版本：** 12 315 316 317**参数：** 318 319| 参数项 | 描述 | 320| -- | -- | 321| [OH_Drawing_Bitmap](capi-drawing-oh-drawing-bitmap.md)* bitmap | 指向位图对象[OH_Drawing_Bitmap](capi-drawing-oh-drawing-bitmap.md)的指针。 | 322| const [OH_Drawing_Image_Info](capi-drawing-oh-drawing-image-info.md)* dstInfo | 指向图片信息对象[OH_Drawing_Image_Info](capi-drawing-oh-drawing-image-info.md)的指针。 | 323| void* dstPixels | 目标像素存储区域。 | 324| size_t dstRowBytes | 目标像素数据每行的字节数，应大于或等于图片信息对象中的最小每行字节数。 | 325| int32_t srcX | 源位图中读取像素数据的起始x轴坐标，应小于源位图的宽度。 | 326| int32_t srcY | 源位图中读取像素数据的起始y轴坐标，应小于源位图的高度。 | 327 328**返回：** 329 330| 类型 | 说明 | 331| -- | -- | 332| bool | 返回接口调用成功与否的结果。true表示复制成功，false表示复制失败。 |