1# Image 2 3 4Provides APIs for obtaining pixel map data and information. 5 6To use the APIs in this file, **libpixelmap_ndk.z.so** is required. 7 8@Syscap SystemCapability.Multimedia.Image 9 10**Since** 11 128 13 14 15## Summary 16 17 18### Files 19 20| Name| Description| 21| -------- | -------- | 22| [image_pixel_map_napi.h](image__pixel__map__napi_8h.md) | Declares the APIs that can lock, access, and unlock a pixel map.<br>File to include:: <multimedia/image_framework/image_pixel_map_napi.h>| 23 24 25### Structs 26 27| Name| Description| 28| -------- | -------- | 29| [OhosPixelMapInfo](_ohos_pixel_map_info.md) | Defines the pixel map information.| 30| [OhosPixelMapCreateOps](_ohos_pixel_map_create_ops.md) | Defines the options used for creating a pixel map.| 31 32 33### Types 34 35| Name| Description| 36| -------- | -------- | 37| [NativePixelMap](#nativepixelmap) | Defines the data type name of the native pixel map.| 38 39 40### Enums 41 42| Name| Description| 43| -------- | -------- | 44| { OHOS_IMAGE_RESULT_SUCCESS = 0, OHOS_IMAGE_RESULT_BAD_PARAMETER = -1 } | Enumerates the error codes returned by the functions.| 45| { OHOS_PIXEL_MAP_FORMAT_NONE = 0, OHOS_PIXEL_MAP_FORMAT_RGBA_8888 = 3, OHOS_PIXEL_MAP_FORMAT_RGB_565 = 2 } | Enumerates the pixel formats.| 46| { OHOS_PIXEL_MAP_ALPHA_TYPE_UNKNOWN = 0, OHOS_PIXEL_MAP_ALPHA_TYPE_OPAQUE = 1, OHOS_PIXEL_MAP_ALPHA_TYPE_PREMUL = 2, OHOS_PIXEL_MAP_ALPHA_TYPE_UNPREMUL = 3 } | Enumerates the pixel map alpha types.| 47| { OHOS_PIXEL_MAP_SCALE_MODE_FIT_TARGET_SIZE = 0, OHOS_PIXEL_MAP_SCALE_MODE_CENTER_CROP = 1 } | Enumerates the pixel map scale modes.| 48| { OHOS_PIXEL_MAP_READ_ONLY = 0, OHOS_PIXEL_MAP_EDITABLE = 1 } | Enumerates the pixel map editing types.| 49 50 51### Functions 52 53| Name| Description| 54| -------- | -------- | 55| [OH_GetImageInfo](#oh_getimageinfo) (napi_env env, napi_value value, [OhosPixelMapInfo](_ohos_pixel_map_info.md) \*info) | Obtains the **PixelMap** information and stores the information to the [OhosPixelMapInfo](_ohos_pixel_map_info.md) struct.| 56| [OH_AccessPixels](#oh_accesspixels) (napi_env env, napi_value value, void \*\*addrPtr) | Obtains the memory address of a **PixelMap** object and locks the memory.| 57| [OH_UnAccessPixels](#oh_unaccesspixels) (napi_env env, napi_value value) | Unlocks the memory of a **PixelMap** object. This function is used with [OH_AccessPixels](#oh_accesspixels) in pairs.| 58| [OH_PixelMap_CreatePixelMap](#oh_pixelmap_createpixelmap) (napi_env env, [OhosPixelMapCreateOps](_ohos_pixel_map_create_ops.md) info, void \*buf, size_t len, napi_value \*res) | Creates a **PixelMap** object.| 59| [OH_PixelMap_CreateAlphaPixelMap](#oh_pixelmap_createalphapixelmap) (napi_env env, napi_value source, napi_value \*alpha) | Creates a **PixelMap** object that contains only alpha channel information.| 60| [OH_PixelMap_InitNativePixelMap](#oh_pixelmap_initnativepixelmap) (napi_env env, napi_value source) | Initializes a **PixelMap** object.| 61| [OH_PixelMap_GetBytesNumberPerRow](#oh_pixelmap_getbytesnumberperrow) (const [NativePixelMap](#nativepixelmap) \*native, int32_t \*num) | Obtains the number of bytes per row of a **PixelMap** object.| 62| [OH_PixelMap_GetIsEditable](#oh_pixelmap_getiseditable) (const [NativePixelMap](#nativepixelmap) \*native, int32_t \*[editable](image__pixel__map__napi_8h.md#editable)) | Checks whether a **PixelMap** object is editable.| 63| [OH_PixelMap_IsSupportAlpha](#oh_pixelmap_issupportalpha) (const [NativePixelMap](#nativepixelmap) \*native, int32_t \*alpha) | Checks whether a **PixelMap** object supports alpha channels.| 64| [OH_PixelMap_SetAlphaAble](#oh_pixelmap_setalphaable) (const [NativePixelMap](#nativepixelmap) \*native, int32_t alpha) | Sets an alpha channel for a **PixelMap** object.| 65| [OH_PixelMap_GetDensity](#oh_pixelmap_getdensity) (const [NativePixelMap](#nativepixelmap) \*native, int32_t \*density) | Obtains the pixel density of a **PixelMap** object.| 66| [OH_PixelMap_SetDensity](#oh_pixelmap_setdensity) (const [NativePixelMap](#nativepixelmap) \*native, int32_t density) | Sets the pixel density for a **PixelMap** object.| 67| [OH_PixelMap_SetOpacity](#oh_pixelmap_setopacity) (const [NativePixelMap](#nativepixelmap) \*native, float opacity) | Sets the opacity for a **PixelMap** object.| 68| [OH_PixelMap_Scale](#oh_pixelmap_scale) (const [NativePixelMap](#nativepixelmap) \*native, float x, float y) | Scales a **PixelMap** object.| 69| [OH_PixelMap_Translate](#oh_pixelmap_translate) (const [NativePixelMap](#nativepixelmap) \*native, float x, float y) | Translates a **PixelMap** object.| 70| [OH_PixelMap_Rotate](#oh_pixelmap_rotate) (const [NativePixelMap](#nativepixelmap) \*native, float angle) | Rotates a **PixelMap** object.| 71| [OH_PixelMap_Flip](#oh_pixelmap_flip) (const [NativePixelMap](#nativepixelmap) \*native, int32_t x, int32_t y) | Flips a **PixelMap** object.| 72| [OH_PixelMap_Crop](#oh_pixelmap_crop) (const [NativePixelMap](#nativepixelmap) \*native, int32_t x, int32_t y, int32_t [width](image__pixel__map__napi_8h.md#width), int32_t [height](image__pixel__map__napi_8h.md#height)) | Crops a **PixelMap** object.| 73 74 75## Type Description 76 77 78### NativePixelMap 79 80 81``` 82typedef struct NativePixelMap 83``` 84**Description** 85 86Defines the data type name of the native pixel map. 87 88**Since** 89 909 91 92 93## Enum Description 94 95 96### anonymous enum 97 98 99``` 100anonymous enum 101``` 102**Description** 103 104Enumerates the error codes returned by the functions. 105 106| Value| Description| 107| -------- | -------- | 108| OHOS_IMAGE_RESULT_SUCCESS| Operation success.| 109| OHOS_IMAGE_RESULT_BAD_PARAMETER| Invalid value.| 110 111**Since** 112 1138 114 115### anonymous enum 116 117 118``` 119anonymous enum 120``` 121**Description** 122 123Enumerates the pixel formats. 124 125| Value| Description| 126| -------- | -------- | 127| OHOS_PIXEL_MAP_FORMAT_NONE| Unknown format.| 128| OHOS_PIXEL_MAP_FORMAT_RGBA_8888| 32-bit RGBA, with 8 bits each for R (red), G (green), B (blue), and A (alpha). The data is stored from the most significant bit to the least significant bit.| 129| OHOS_PIXEL_MAP_FORMAT_RGB_565| 16-bit RGB, with 5, 6, and 5 bits for R, G, and B, respectively. The storage sequence is from the most significant bit to the least significant bit.| 130 131**Since** 132 1338 134 135### anonymous enum 136 137 138``` 139anonymous enum 140``` 141**Description** 142 143Enumerates the pixel map alpha types. 144 145| Value| Description| 146| -------- | -------- | 147| OHOS_PIXEL_MAP_ALPHA_TYPE_UNKNOWN| Unknown format.| 148| OHOS_PIXEL_MAP_ALPHA_TYPE_OPAQUE| Opaque format.| 149| OHOS_PIXEL_MAP_ALPHA_TYPE_PREMUL| Premultiplied format.| 150| OHOS_PIXEL_MAP_ALPHA_TYPE_UNPREMUL| Unpremultiplied format.| 151 152**Since** 153 1549 155 156### anonymous enum 157 158 159``` 160anonymous enum 161``` 162**Description** 163 164Enumerates the pixel map scale modes. 165 166| Value| Description| 167| -------- | -------- | 168| OHOS_PIXEL_MAP_SCALE_MODE_FIT_TARGET_SIZE| Adaptation to the target image size.| 169| OHOS_PIXEL_MAP_SCALE_MODE_CENTER_CROP| Cropping the center portion of an image to the target size.| 170 171**Since** 172 1739 174 175 176### anonymous enum 177 178 179``` 180anonymous enum 181``` 182**Description** 183 184Enumerates the pixel map editing types. 185 186| Value| Description| 187| -------- | -------- | 188| OHOS_PIXEL_MAP_READ_ONLY| Read-only.| 189| OHOS_PIXEL_MAP_EDITABLE| Editable.| 190 191**Since** 192 1939 194 195 196## Function Description 197 198 199### OH_AccessPixels() 200 201 202``` 203int32_t OH_AccessPixels (napi_env env, napi_value value, void ** addrPtr ) 204``` 205**Description** 206 207Obtains the memory address of a **PixelMap** object and locks the memory. 208 209After the function is executed successfully, **\*addrPtr** is the address of the memory to be accessed. After the access operation is complete, you must use [OH_UnAccessPixels](#oh_unaccesspixels) to unlock the memory. Otherwise, the resources in the memory cannot be released. After the memory is unlocked, its address cannot be accessed or operated. 210 211**Parameters** 212 213| Name| Description| 214| -------- | -------- | 215| env | Indicates the NAPI environment pointer.| 216| value | Indicates the **PixelMap** object at the application layer.| 217| addrPtr | Indicates the double pointer to the memory address.| 218 219**See** 220 221UnAccessPixels 222 223**Returns** 224 225Returns **OHOS_IMAGE_RESULT_SUCCESS** if the operation is successful; returns an error code otherwise. 226 227**Since** 2288 229 230 231### OH_GetImageInfo() 232 233 234``` 235struct OhosPixelMapCreateOps OH_GetImageInfo (napi_env env, napi_value value, OhosPixelMapInfo * info ) 236``` 237**Description** 238 239Obtains the **PixelMap** information and stores the information to the [OhosPixelMapInfo](_ohos_pixel_map_info.md) struct. 240 241**Parameters** 242 243| Name| Description| 244| -------- | -------- | 245| env | Indicates the NAPI environment pointer.| 246| value | Indicates the **PixelMap** object at the application layer.| 247| info | Indicates the pointer to the object that stores the information obtained. For details, see [OhosPixelMapInfo](_ohos_pixel_map_info.md).| 248 249**Returns** 250 251Returns **0** if the information is obtained and stored successfully; returns an error code otherwise. 252 253**See** 254 255[OhosPixelMapInfo](_ohos_pixel_map_info.md) 256 257**Since** 258 2598 260 261 262### OH_PixelMap_CreateAlphaPixelMap() 263 264 265``` 266int32_t OH_PixelMap_CreateAlphaPixelMap (napi_env env, napi_value source, napi_value * alpha ) 267``` 268**Description** 269 270Creates a **PixelMap** object that contains only alpha channel information. 271 272**Parameters** 273 274| Name| Description| 275| -------- | -------- | 276| env | Indicates the NAPI environment pointer.| 277| source | Indicates the options for setting the **PixelMap** object.| 278| alpha | Indicates the pointer to the alpha channel.| 279 280**Returns** 281 282Returns a **PixelMap** object if the operation is successful; returns an error code otherwise. 283 284**See** 285 286CreateAlphaPixelMap 287 288**Since** 289 2909 291 292 293### OH_PixelMap_CreatePixelMap() 294 295 296``` 297int32_t OH_PixelMap_CreatePixelMap (napi_env env, OhosPixelMapCreateOps info, void * buf, size_t len, napi_value * res ) 298``` 299**Description** 300 301Creates a **PixelMap** object. 302 303**Parameters** 304 305| Name| Description| 306| -------- | -------- | 307| env | Indicates the NAPI environment pointer.| 308| info | Indicates the options for setting the **PixelMap** object.| 309| buf | Indicates the pointer to the buffer of the image.| 310| len | Indicates the image size.| 311| res | Indicates the pointer to the **PixelMap** object at the application layer.| 312 313**Returns** 314 315Returns a **PixelMap** object if the operation is successful; returns an error code otherwise. 316 317**See** 318 319CreatePixelMap 320 321**Since** 322 3239 324 325 326### OH_PixelMap_Crop() 327 328 329``` 330int32_t OH_PixelMap_Crop (const NativePixelMap * native, int32_t x, int32_t y, int32_t width, int32_t height ) 331``` 332**Description** 333 334Crops a **PixelMap** object. 335 336**Parameters** 337 338| Name| Description| 339| -------- | -------- | 340| native | Indicates the pointer to a **NativePixelMap** object.| 341| x | Indicates the x-coordinate of the upper left corner of the target image.| 342| y | Indicates the y-coordinate of the upper left corner of the target image.| 343| width | Indicates the width of the cropped region.| 344| height | Indicates the height of the cropped region.| 345 346**Returns** 347 348Returns **0** if the operation is successful; returns an error code otherwise. 349 350**See** 351 352Crop 353 354**Since** 355 3569 357 358 359### OH_PixelMap_Flip() 360 361 362``` 363int32_t OH_PixelMap_Flip (const NativePixelMap * native, int32_t x, int32_t y ) 364``` 365**Description** 366 367Flips a **PixelMap** object. 368 369**Parameters** 370 371| Name| Description| 372| -------- | -------- | 373| native | Indicates the pointer to a **NativePixelMap** object.| 374| x | Specifies whether to flip around the x axis.| 375| y | Specifies whether to flip around the y axis.| 376 377**Returns** 378 379Returns **0** if the operation is successful; returns an error code otherwise. 380 381**See** 382 383Flip 384 385**Since** 386 3879 388 389 390### OH_PixelMap_GetBytesNumberPerRow() 391 392 393``` 394int32_t OH_PixelMap_GetBytesNumberPerRow (const NativePixelMap * native, int32_t * num ) 395``` 396**Description** 397 398Obtains the number of bytes per row of a **PixelMap** object. 399 400**Parameters** 401 402| Name| Description| 403| -------- | -------- | 404| native | Indicates the pointer to a **NativePixelMap** object.| 405| num | Indicates the pointer to the number of bytes per row of the **PixelMap** object.| 406 407**Returns** 408 409Returns the number of bytes per row of the **PixelMap** object if the operation is successful; returns an error code otherwise. 410 411**See** 412 413GetBytesNumberPerRow 414 415**Since** 416 4179 418 419### OH_PixelMap_GetDensity() 420 421 422``` 423int32_t OH_PixelMap_GetDensity (const NativePixelMap * native, int32_t * density ) 424``` 425**Description** 426 427Obtains the pixel density of a **PixelMap** object. 428 429**Parameters** 430 431| Name| Description| 432| -------- | -------- | 433| native | Indicates the pointer to a **NativePixelMap** object.| 434| density | Indicates the pointer to the pixel density.| 435 436**Returns** 437 438Returns the pixel density if the operation is successful; returns an error code otherwise. 439 440**See** 441 442GetDensity 443 444**Since** 445 4469 447 448 449### OH_PixelMap_GetIsEditable() 450 451 452``` 453int32_t OH_PixelMap_GetIsEditable (const NativePixelMap * native, int32_t * editable ) 454``` 455**Description** 456 457Checks whether a **PixelMap** object is editable. 458 459**Parameters** 460 461| Name| Description| 462| -------- | -------- | 463| native | Indicates the pointer to a **NativePixelMap** object.| 464| editable | Indicates the pointer to the editing type of the **PixelMap** object.| 465 466**Returns** 467 468Returns an enumerated value that indicates the editing type of the **PixelMap** object if the operation is successful; returns an error code otherwise. 469 470**See** 471 472GetIsEditable 473 474**Since** 475 4769 477 478 479### OH_PixelMap_InitNativePixelMap() 480 481 482``` 483NativePixelMap* OH_PixelMap_InitNativePixelMap (napi_env env, napi_value source ) 484``` 485**Description** 486 487Initializes a **PixelMap** object. 488 489**Parameters** 490 491| Name| Description| 492| -------- | -------- | 493| env | Indicates the NAPI environment pointer.| 494| source | Indicates the options for setting the **PixelMap** object.| 495 496**Returns** 497 498Returns a pointer to the **NativePixelMap** object if the operation is successful; returns an error code otherwise. 499 500**See** 501 502InitNativePixelMap 503 504**Since** 505 5069 507 508 509### OH_PixelMap_IsSupportAlpha() 510 511 512``` 513int32_t OH_PixelMap_IsSupportAlpha (const NativePixelMap * native, int32_t * alpha ) 514``` 515**Description** 516 517Checks whether a **PixelMap** object supports alpha channels. 518 519**Parameters** 520 521| Name| Description| 522| -------- | -------- | 523| native | Indicates the pointer to a **NativePixelMap** object.| 524| alpha | Indicates the pointer to the support for alpha channels.| 525 526**Returns** 527 528Returns **0** if the operation is successful; returns an error code otherwise. 529 530**See** 531 532IsSupportAlpha 533 534**Since** 535 5369 537 538 539 540### OH_PixelMap_Rotate() 541 542 543``` 544int32_t OH_PixelMap_Rotate (const NativePixelMap * native, float angle ) 545``` 546**Description** 547 548Rotates a **PixelMap** object. 549 550**Parameters** 551 552| Name| Description| 553| -------- | -------- | 554| native | Indicates the pointer to a **NativePixelMap** object.| 555| angle | Indicates the angle to rotate.| 556 557**Returns** 558 559Returns **0** if the operation is successful; returns an error code otherwise. 560 561**See** 562 563Rotate 564 565**Since** 566 5679 568 569 570### OH_PixelMap_Scale() 571 572 573``` 574int32_t OH_PixelMap_Scale (const NativePixelMap * native, float x, float y ) 575``` 576**Description** 577 578Scales a **PixelMap** object. 579 580**Parameters** 581 582| Name| Description| 583| -------- | -------- | 584| native | Indicates the pointer to a **NativePixelMap** object.| 585| x | Indicates the scaling ratio of the width.| 586| y | Indicates the scaling ratio of the height.| 587 588**Returns** 589 590Returns **0** if the operation is successful; returns an error code otherwise. 591 592**See** 593 594Scale 595 596**Since** 597 5989 599 600 601### OH_PixelMap_SetAlphaAble() 602 603 604``` 605int32_t OH_PixelMap_SetAlphaAble (const NativePixelMap * native, int32_t alpha ) 606``` 607**Description** 608 609Sets an alpha channel for a **PixelMap** object. 610 611**Parameters** 612 613| Name| Description| 614| -------- | -------- | 615| native | Indicates the pointer to a **NativePixelMap** object.| 616| alpha | Indicates the alpha channel to set.| 617 618**Returns** 619 620Returns **0** if the operation is successful; returns an error code otherwise. 621 622**See** 623 624SetAlphaAble 625 626**Since** 627 6289 629 630 631### OH_PixelMap_SetDensity() 632 633 634``` 635int32_t OH_PixelMap_SetDensity (const NativePixelMap * native, int32_t density ) 636``` 637**Description** 638 639Sets the pixel density for a **PixelMap** object. 640 641**Parameters** 642 643| Name| Description| 644| -------- | -------- | 645| native | Indicates the pointer to a **NativePixelMap** object.| 646| density | Indicates the pixel density to set.| 647 648**Returns** 649 650Returns **0** if the operation is successful; returns an error code otherwise. 651 652**See** 653 654GetDensity 655 656**Since** 657 6589 659 660 661### OH_PixelMap_SetOpacity() 662 663 664``` 665int32_t OH_PixelMap_SetOpacity (const NativePixelMap * native, float opacity ) 666``` 667**Description** 668 669Sets the opacity for a **PixelMap** object. 670 671**Parameters** 672 673| Name| Description| 674| -------- | -------- | 675| native | Indicates the pointer to a **NativePixelMap** object.| 676| opacity | Indicates the opacity to set.| 677 678**Returns** 679 680Returns **0** if the operation is successful; returns an error code otherwise. 681 682**See** 683 684SetOpacity 685 686**Since** 687 6889 689 690 691### OH_PixelMap_Translate() 692 693 694``` 695int32_t OH_PixelMap_Translate (const NativePixelMap * native, float x, float y ) 696``` 697**Description** 698 699Translates a **PixelMap** object. 700 701**Parameters** 702 703| Name| Description| 704| -------- | -------- | 705| native | Indicates the pointer to a **NativePixelMap** object.| 706| x | Indicates the horizontal distance to translate.| 707| y | Indicates the vertical distance to translate.| 708 709**Returns** 710 711Returns **0** if the operation is successful; returns an error code otherwise. 712 713**See** 714 715Translate 716 717**Since** 718 7199 720 721 722### OH_UnAccessPixels() 723 724 725``` 726int32_t OH_UnAccessPixels (napi_env env, napi_value value ) 727``` 728**Description** 729 730Unlocks the memory of a **PixelMap** object. This function is used with [OH_AccessPixels](#oh_accesspixels) in pairs. 731 732**Parameters** 733 734| Name| Description| 735| -------- | -------- | 736| env | Indicates the NAPI environment pointer.| 737| value | Indicates the **PixelMap** object at the application layer.| 738 739**Returns** 740 741Returns **OHOS_IMAGE_RESULT_SUCCESS** if the operation is successful; returns an error code otherwise. 742 743**See** 744 745AccessPixels 746 747**Since** 748 7498