1# @ohos.multimedia.sendableImage (Image Processing Based on Sendable Objects) 2<!--Kit: Image Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @aulight02--> 5<!--SE: @liyang_bryan--> 6<!--TSE: @xchaosioda--> 7 8The module provides APIs for image processing based on sendable objects. You can use the APIs to create a PixelMap object with specified properties or read pixels of an image (or even in a region of an image). 9 10> **NOTE** 11> 12> The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version. 13 14## Modules to Import 15 16```ts 17import { sendableImage } from '@kit.ImageKit'; 18``` 19 20## sendableImage.createPixelMap 21 22createPixelMap(colors: ArrayBuffer, options: image.InitializationOptions): Promise\<PixelMap> 23 24Creates a PixelMap object with the default BGRA_8888 format and specified pixel properties. This API uses a promise to return the result. 25 26**System capability**: SystemCapability.Multimedia.Image.Core 27 28**Parameters** 29 30| Name | Type | Mandatory| Description | 31| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- | 32| colors | ArrayBuffer | Yes | Color array in BGRA_8888 format. | 33| options | [image.InitializationOptions](arkts-apis-image-i.md#initializationoptions8) | Yes | Pixel properties, including the alpha type, size, scale mode, pixel format, and editable.| 34 35**Return value** 36 37| Type | Description | 38| -------------------------------- | ----------------------------------------------------------------------- | 39| Promise\<[PixelMap](#pixelmap)> | Promise used to return the PixelMap object.<br>If the size of the created PixelMap exceeds that of the original image, the PixelMap size of the original image is returned.| 40 41**Example** 42 43```ts 44import { image } from '@kit.ImageKit'; 45import { BusinessError } from '@kit.BasicServicesKit'; 46 47async function Demo() { 48 const color: ArrayBuffer = new ArrayBuffer(96); // 96 is the size of the pixel buffer to create. The value is calculated as follows: height * width *4. 49 let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } } 50 sendableImage.createPixelMap(color, opts).then((pixelMap: sendableImage.PixelMap) => { 51 console.info('Succeeded in creating pixelmap.'); 52 }).catch((error: BusinessError) => { 53 console.error(`Failed to create pixelmap. code is ${error.code}, message is ${error.message}`); 54 }) 55} 56``` 57 58## sendableImage.createPixelMapFromParcel 59 60createPixelMapFromParcel(sequence: rpc.MessageSequence): PixelMap 61 62Creates a PixelMap object from a MessageSequence object. 63 64**System capability**: SystemCapability.Multimedia.Image.Core 65 66**Parameters** 67 68| Name | Type | Mandatory| Description | 69| ---------------------- | ----------------------------------------------------- | ---- | ---------------------------------------- | 70| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | Yes | MessageSequence object that stores the PixelMap information. | 71 72**Return value** 73 74| Type | Description | 75| -------------------------------- | --------------------- | 76| [PixelMap](#pixelmap) | PixelMap object. If the operation fails, an error is thrown.| 77 78**Error codes** 79 80For details about the error codes, see [Image Error Codes](errorcode-image.md). 81 82| ID| Error Message| 83| ------- | --------------------------------------------| 84| 62980096 | If the operation failed| 85| 62980097 | If the ipc error| 86| 62980115 | Invalid input parameter| 87| 62980105 | Failed to get the data| 88| 62980177 | Abnormal API environment| 89| 62980178 | Failed to create the PixelMap| 90| 62980179 | Abnormal buffer size| 91| 62980180 | FD mapping failed| 92| 62980246 | Failed to read the PixelMap| 93 94**Example** 95 96```ts 97import { sendableImage } from '@kit.ImageKit'; 98import { image } from '@kit.ImageKit'; 99import { rpc } from '@kit.IPCKit'; 100import { BusinessError } from '@kit.BasicServicesKit'; 101 102class MySequence implements rpc.Parcelable { 103 pixel_map: sendableImage.PixelMap; 104 constructor(conPixelmap: sendableImage.PixelMap) { 105 this.pixel_map = conPixelmap; 106 } 107 marshalling(messageSequence: rpc.MessageSequence) { 108 this.pixel_map.marshalling(messageSequence); 109 return true; 110 } 111 unmarshalling(messageSequence: rpc.MessageSequence) { 112 try { 113 this.pixel_map = sendableImage.createPixelMapFromParcel(messageSequence); 114 } catch(e) { 115 let error = e as BusinessError; 116 console.error(`createPixelMapFromParcel error. code is ${error.code}, message is ${error.message}`); 117 return false; 118 } 119 return true; 120 } 121} 122async function Demo() { 123 const color: ArrayBuffer = new ArrayBuffer(96); 124 let bufferArr: Uint8Array = new Uint8Array(color); 125 for (let i = 0; i < bufferArr.length; i++) { 126 bufferArr[i] = 0x80; 127 } 128 let opts: image.InitializationOptions = { 129 editable: true, 130 pixelFormat: 4, 131 size: { height: 4, width: 6 }, 132 alphaType: 3 133 } 134 let pixelMap: sendableImage.PixelMap | undefined = undefined; 135 await sendableImage.createPixelMap(color, opts).then((srcPixelMap: sendableImage.PixelMap) => { 136 pixelMap = srcPixelMap; 137 }) 138 if (pixelMap != undefined) { 139 // Implement serialization. 140 let parcelable: MySequence = new MySequence(pixelMap); 141 let data: rpc.MessageSequence = rpc.MessageSequence.create(); 142 data.writeParcelable(parcelable); 143 144 // Implement deserialization to obtain data through the RPC. 145 let ret: MySequence = new MySequence(pixelMap); 146 data.readParcelable(ret); 147 148 // Obtain the PixelMap object. 149 let unmarshPixelmap = ret.pixel_map; 150 } 151} 152``` 153 154## sendableImage.createPixelMapFromSurface 155 156createPixelMapFromSurface(surfaceId: string, region: image.Region): Promise\<PixelMap> 157 158Creates a PixelMap object from a surface ID. 159 160**System capability**: SystemCapability.Multimedia.Image.Core 161 162**Parameters** 163 164| Name | Type | Mandatory| Description | 165| ---------------------- | ------------- | ---- | ---------------------------------------- | 166| surfaceId | string | Yes | Surface ID, which is obtained from [XComponent](../apis-arkui/arkui-ts/ts-basic-components-xcomponent.md).| 167| region | [image.Region](../apis-image-kit/arkts-apis-image-i.md#region8) | Yes | Size of the image after cropping. | 168 169**Return value** 170| Type | Description | 171| -------------------------------- | --------------------- | 172| Promise\<[PixelMap](#pixelmap)> | PixelMap object. If the operation fails, an error is thrown.| 173 174**Error codes** 175 176For details about the error codes, see [Image Error Codes](errorcode-image.md). 177 178| ID| Error Message| 179| ------- | --------------------------------------------| 180| 62980115 | Invalid input parameter| 181| 62980105 | Failed to get the data| 182| 62980178 | Failed to create the PixelMap| 183 184**Example** 185 186```ts 187import { image } from '@kit.ImageKit'; 188import { BusinessError } from '@kit.BasicServicesKit'; 189 190async function Demo(surfaceId: string) { 191 let region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 192 sendableImage.createPixelMapFromSurface(surfaceId, region).then(() => { 193 console.info('Succeeded in creating pixelmap from Surface'); 194 }).catch((error: BusinessError) => { 195 console.error(`Failed to create pixelmap. code is ${error.code}, message is ${error.message}`); 196 }); 197} 198``` 199 200## sendableImage.createPixelMapSync 201 202createPixelMapSync(colors: ArrayBuffer, options: image.InitializationOptions): PixelMap 203 204Creates a PixelMap object with the specified pixel properties. This API returns the result synchronously. 205 206**System capability**: SystemCapability.Multimedia.Image.Core 207 208**Parameters** 209 210| Name | Type | Mandatory| Description | 211| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- | 212| colors | ArrayBuffer | Yes | Color array in BGRA_8888 format. | 213| options | [image.InitializationOptions](arkts-apis-image-i.md#initializationoptions8) | Yes | Pixel properties, including the alpha type, size, scale mode, pixel format, and editable.| 214 215**Return value** 216| Type | Description | 217| -------------------------------- | --------------------- | 218| [PixelMap](#pixelmap) | PixelMap object. If the operation fails, an error is thrown.| 219 220**Error codes** 221 222For details about the error codes, see [Image Error Codes](errorcode-image.md). 223 224| ID| Error Message| 225| ------- | --------------------------------------------| 226| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 227 228**Example** 229 230```ts 231import { image } from '@kit.ImageKit'; 232import { BusinessError } from '@kit.BasicServicesKit'; 233 234async function Demo() { 235 const color: ArrayBuffer = new ArrayBuffer(96); // 96 is the size of the pixel buffer to create. The value is calculated as follows: height * width *4. 236 let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } } 237 let pixelMap : sendableImage.PixelMap = sendableImage.createPixelMapSync(color, opts); 238 return pixelMap; 239} 240``` 241 242## sendableImage.convertFromPixelMap 243 244convertFromPixelMap(pixelMap: image.PixelMap): PixelMap 245 246Creates a PixelMap object under **sendableImage** from a PixelMap object under **image**. This API returns the result synchronously. The APIs of the PixelMap object under **image** cannot be called anymore. 247 248**System capability**: SystemCapability.Multimedia.Image.Core 249 250**Parameters** 251 252| Name | Type | Mandatory| Description | 253| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- | 254| pixelMap | [image.PixelMap](arkts-apis-image-PixelMap.md) | Yes | PixelMap object under image.| 255 256**Return value** 257| Type | Description | 258| -------------------------------- | --------------------- | 259| [PixelMap](#pixelmap) | PixelMap object, which is sendable. If the operation fails, an error is thrown.| 260 261**Error codes** 262 263For details about the error codes, see [Image Error Codes](errorcode-image.md). 264 265| ID| Error Message| 266| ------- | --------------------------------------------| 267| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 268| 62980104 | Failed to initialize the internal object.| 269 270**Example** 271 272```ts 273import { image } from '@kit.ImageKit'; 274import { BusinessError } from '@kit.BasicServicesKit'; 275 276async function Demo() { 277 const color: ArrayBuffer = new ArrayBuffer(96); // 96 is the size of the pixel buffer to create. The value is calculated as follows: height * width *4. 278 let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } } 279 let pixelMap : image.PixelMap = image.createPixelMapSync(color, opts); 280 let sendablePixelMap : sendableImage.PixelMap = sendableImage.convertFromPixelMap(pixelMap); 281 return sendablePixelMap; 282} 283``` 284 285## sendableImage.convertToPixelMap 286 287convertToPixelMap(pixelMap: PixelMap): image.PixelMap 288 289Creates a PixelMap object under **image** from a PixelMap object under **sendableImage**. This API returns the result synchronously. The APIs of the PixelMap object under **sendableImage** cannot be called anymore. 290 291**System capability**: SystemCapability.Multimedia.Image.Core 292 293**Parameters** 294 295| Name | Type | Mandatory| Description | 296| ------- | ------------------------------------------------ | ---- | ---------------------------------------------------------------- | 297| pixelMap | [PixelMap](#pixelmap) | Yes | PixelMap object under **sendableImage**.| 298 299**Return value** 300| Type | Description | 301| -------------------------------- | --------------------- | 302| [PixelMap](arkts-apis-image-PixelMap.md) | PixelMap object, which is not sendable. If the operation fails, an error is thrown.| 303 304**Error codes** 305 306For details about the error codes, see [Image Error Codes](errorcode-image.md). 307 308| ID| Error Message| 309| ------- | --------------------------------------------| 310| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 311| 62980104 | Failed to initialize the internal object.| 312 313**Example** 314 315```ts 316import { image } from '@kit.ImageKit'; 317import { BusinessError } from '@kit.BasicServicesKit'; 318 319async function Demo() { 320 const color: ArrayBuffer = new ArrayBuffer(96); // 96 is the size of the pixel buffer to create. The value is calculated as follows: height * width *4. 321 let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } } 322 let sendablePixelMap : sendableImage.PixelMap = sendableImage.createPixelMapSync(color, opts); 323 let pixelMap : image.PixelMap = sendableImage.convertToPixelMap(sendablePixelMap); 324 return pixelMap; 325} 326``` 327 328## PixelMap 329 330Provides APIs to read or write image data and obtain image information. Before calling any API in PixelMap, you must use [createPixelMap](#sendableimagecreatepixelmap) to create a PixelMap object. Currently, the maximum size of a serialized PixelMap is 128 MB. A larger size will cause a display failure. The size is calculated as follows: Width * Height * Number of bytes occupied by each pixel. 331 332The PixelMap object under **sendableImage** supports the **sendable** attribute and sharing of the worker thread. The [Convert](#sendableimageconverttopixelmap) API can be used to convert a PixelMap object in **sendableImage** to a PixelMap object in **image**, and vise versa. After the conversion, the APIs of the original object cannot be called. Otherwise, error 501 is reported. When processing a PixelMap object across threads, you need to consider the multithreaded problem. 333 334Before calling any API in PixelMap, you must use [sendableImage.createPixelMap](#sendableimagecreatepixelmap) to create a PixelMap object. 335 336### Properties 337 338**System capability**: SystemCapability.Multimedia.Image.Core 339 340| Name | Type | Read-Only| Optional| Description | 341| -----------------| ------- | ---- | ---- | -------------------------- | 342| isEditable | boolean | Yes | No | Whether the PixelMap is editable. The value **true** means that the PixelMap is editable, and **false** means the opposite.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 343| isStrideAlignment | boolean | Yes | No | Whether the PixelMap uses DMA memory. The value** true** means that the PixelMap uses DMA memory, and **false** means the opposite. The PixelMap in DMA memory is aligned to 256-byte boundaries, with padding areas at the end of each row.| 344 345### readPixelsToBuffer 346 347readPixelsToBuffer(dst: ArrayBuffer): Promise\<void> 348 349Reads the pixels of this image and writes the data to an ArrayBuffer. This API uses a promise to return the result. If the PixelMap is created in the BGRA_8888 format, the data read is the same as the original data. 350 351**Atomic service API**: This API can be used in atomic services since API version 12. 352 353**System capability**: SystemCapability.Multimedia.Image.Core 354 355**Parameters** 356 357| Name| Type | Mandatory| Description | 358| ------ | ----------- | ---- | ----------------------------------------------------------------------------------------------------- | 359| dst | ArrayBuffer | Yes | Buffer to which the pixels will be written. The buffer size is obtained by calling [getPixelBytesNumber](#getpixelbytesnumber).| 360 361**Return value** 362 363| Type | Description | 364| -------------- | ----------------------------------------------- | 365| Promise\<void> | Promise used to return the result. If the operation fails, an error message is returned.| 366 367**Example** 368 369```ts 370import { BusinessError } from '@kit.BasicServicesKit'; 371import { sendableImage } from '@kit.ImageKit'; 372 373async function Demo(pixelMap : sendableImage.PixelMap) { 374 const readBuffer: ArrayBuffer = new ArrayBuffer(96); // 96 is the size of the pixel buffer to create. The value is calculated as follows: height * width *4. 375 if (pixelMap != undefined) { 376 pixelMap.readPixelsToBuffer(readBuffer).then(() => { 377 console.info('Succeeded in reading image pixel data.'); // Called if the condition is met. 378 }).catch((error: BusinessError) => { 379 console.error(`Failed to read image pixel data. code is ${error.code}, message is ${error.message}`); // Called if no condition is met. 380 }) 381 } 382} 383``` 384 385### readPixelsToBufferSync 386 387readPixelsToBufferSync(dst: ArrayBuffer): void 388 389Reads the pixels of this image and writes the data to an ArrayBuffer. This API returns the result synchronously. 390 391**Atomic service API**: This API can be used in atomic services since API version 12. 392 393**System capability**: SystemCapability.Multimedia.Image.Core 394 395**Parameters** 396 397| Name | Type | Mandatory| Description | 398| -------- | -------------------- | ---- | ----------------------------------------------------------------------------------------------------- | 399| dst | ArrayBuffer | Yes | Buffer to which the pixels will be written. The buffer size is obtained by calling [getPixelBytesNumber](#getpixelbytesnumber).| 400 401**Error codes** 402 403For details about the error codes, see [Image Error Codes](errorcode-image.md). 404 405| ID| Error Message| 406| ------- | --------------------------------------------| 407| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 408| 501 | Resource Unavailable. | 409 410**Example** 411 412```ts 413import { BusinessError } from '@kit.BasicServicesKit'; 414import { sendableImage } from '@kit.ImageKit'; 415 416async function Demo(pixelMap: sendableImage.PixelMap) { 417 const bufferSize = pixelMap.getPixelBytesNumber(); 418 const readBuffer: ArrayBuffer = new ArrayBuffer(bufferSize); 419 if (pixelMap != undefined) { 420 pixelMap.readPixelsToBufferSync(readBuffer); 421 } 422} 423``` 424 425### readPixels 426 427readPixels(area: image.PositionArea): Promise\<void> 428 429Reads the pixels in an area. This API uses a promise to return the result. 430 431**Atomic service API**: This API can be used in atomic services since API version 12. 432 433**System capability**: SystemCapability.Multimedia.Image.Core 434 435**Parameters** 436 437| Name| Type | Mandatory| Description | 438| ------ | ------------------------------ | ---- | ------------------------ | 439| area | [image.PositionArea](arkts-apis-image-i.md#positionarea7) | Yes | Area from which the pixels will be read.| 440 441**Return value** 442 443| Type | Description | 444| :------------- | :-------------------------------------------------- | 445| Promise\<void> | Promise used to return the result. If the operation fails, an error message is returned.| 446 447**Example** 448 449```ts 450import { image } from '@kit.ImageKit'; 451import { BusinessError } from '@kit.BasicServicesKit'; 452 453async function Demo() { 454 const area: image.PositionArea = { 455 pixels: new ArrayBuffer(8), 456 offset: 0, 457 stride: 8, 458 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 459 }; 460 if (pixelMap != undefined) { 461 pixelMap.readPixels(area).then(() => { 462 console.info('Succeeded in reading the image data in the area.'); // Called if the condition is met. 463 }).catch((error: BusinessError) => { 464 console.error(`Failed to read the image data in the area. code is ${error.code}, message is ${error.message}`); // Called if no condition is met. 465 }) 466 } 467} 468``` 469 470### readPixelsSync 471 472readPixelsSync(area: image.PositionArea): void 473 474Reads the pixels in an area. This API returns the result synchronously. 475 476**Atomic service API**: This API can be used in atomic services since API version 12. 477 478**System capability**: SystemCapability.Multimedia.Image.Core 479 480**Parameters** 481 482| Name| Type | Mandatory| Description | 483| ------ | ------------------------------ | ---- | ------------------------ | 484| area | [image.PositionArea](arkts-apis-image-i.md#positionarea7) | Yes | Area from which the pixels will be read.| 485 486**Error codes** 487 488For details about the error codes, see [Image Error Codes](errorcode-image.md). 489 490| ID| Error Message| 491| ------- | --------------------------------------------| 492| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 493| 501 | Resource Unavailable. | 494 495**Example** 496 497```ts 498import { image } from '@kit.ImageKit'; 499import { BusinessError } from '@kit.BasicServicesKit'; 500 501async function Demo() { 502 const area : image.PositionArea = { 503 pixels: new ArrayBuffer(8), 504 offset: 0, 505 stride: 8, 506 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 507 }; 508 if (pixelMap != undefined) { 509 pixelMap.readPixelsSync(area); 510 } 511} 512``` 513 514### writePixels 515 516writePixels(area: image.PositionArea): Promise\<void> 517 518Writes the pixels to an area. This API uses a promise to return the result. 519 520**Atomic service API**: This API can be used in atomic services since API version 12. 521 522**System capability**: SystemCapability.Multimedia.Image.Core 523 524**Parameters** 525 526| Name| Type | Mandatory| Description | 527| ------ | ------------------------------ | ---- | -------------------- | 528| area | [image.PositionArea](arkts-apis-image-i.md#positionarea7) | Yes | Area to which the pixels will be written.| 529 530**Return value** 531 532| Type | Description | 533| :------------- | :-------------------------------------------------- | 534| Promise\<void> | Promise used to return the result. If the operation fails, an error message is returned.| 535 536**Example** 537 538```ts 539import { image } from '@kit.ImageKit'; 540import { BusinessError } from '@kit.BasicServicesKit'; 541 542async function Demo() { 543 const area: image.PositionArea = { 544 pixels: new ArrayBuffer(8), 545 offset: 0, 546 stride: 8, 547 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 548 }; 549 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 550 for (let i = 0; i < bufferArr.length; i++) { 551 bufferArr[i] = i + 1; 552 } 553 if (pixelMap != undefined) { 554 pixelMap.writePixels(area).then(() => { 555 console.info('Succeeded to write pixelmap into the specified area.'); 556 }).catch((error: BusinessError) => { 557 console.error(`Failed to write pixelmap into the specified area. code is ${error.code}, message is ${error.message}`); 558 }) 559 } 560} 561``` 562 563### writePixelsSync 564 565writePixelsSync(area: image.PositionArea): void 566 567Writes the pixels to an area. This API returns the result synchronously. 568 569**Atomic service API**: This API can be used in atomic services since API version 12. 570 571**System capability**: SystemCapability.Multimedia.Image.Core 572 573**Parameters** 574 575| Name| Type | Mandatory| Description | 576| ------ | ------------------------------ | ---- | -------------------- | 577| area | [image.PositionArea](arkts-apis-image-i.md#positionarea7) | Yes | Area to which the pixels will be written.| 578 579**Error codes** 580 581For details about the error codes, see [Image Error Codes](errorcode-image.md). 582 583| ID| Error Message| 584| ------- | --------------------------------------------| 585| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 586| 501 | Resource Unavailable. | 587 588**Example** 589 590```ts 591import { image } from '@kit.ImageKit'; 592import { BusinessError } from '@kit.BasicServicesKit'; 593 594async function Demo() { 595 const area: image.PositionArea = { 596 pixels: new ArrayBuffer(8), 597 offset: 0, 598 stride: 8, 599 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 600 }; 601 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 602 for (let i = 0; i < bufferArr.length; i++) { 603 bufferArr[i] = i + 1; 604 } 605 if (pixelMap != undefined) { 606 pixelMap.writePixelsSync(area); 607 } 608} 609``` 610 611### writeBufferToPixels 612 613writeBufferToPixels(src: ArrayBuffer): Promise\<void> 614 615Reads image data in an ArrayBuffer and writes the data to a PixelMap object. This API uses a promise to return the result. 616 617**Atomic service API**: This API can be used in atomic services since API version 12. 618 619**System capability**: SystemCapability.Multimedia.Image.Core 620 621**Parameters** 622 623| Name| Type | Mandatory| Description | 624| ------ | ----------- | ---- | -------------- | 625| src | ArrayBuffer | Yes | Buffer from which the image data will be read.| 626 627**Return value** 628 629| Type | Description | 630| -------------- | ----------------------------------------------- | 631| Promise\<void> | Promise used to return the result. If the operation fails, an error message is returned.| 632 633**Example** 634 635```ts 636import { BusinessError } from '@kit.BasicServicesKit'; 637 638async function Demo() { 639 const color: ArrayBuffer = new ArrayBuffer(96); // 96 is the size of the pixel buffer to create. The value is calculated as follows: height * width *4. 640 let bufferArr: Uint8Array = new Uint8Array(color); 641 for (let i = 0; i < bufferArr.length; i++) { 642 bufferArr[i] = i + 1; 643 } 644 if (pixelMap != undefined) { 645 pixelMap.writeBufferToPixels(color).then(() => { 646 console.info("Succeeded in writing data from a buffer to a PixelMap."); 647 }).catch((error: BusinessError) => { 648 console.error(`Failed to write data from a buffer to a PixelMap. code is ${error.code}, message is ${error.message}`); 649 }) 650 } 651} 652``` 653 654### writeBufferToPixelsSync 655 656writeBufferToPixelsSync(src: ArrayBuffer): void 657 658Reads image data in an ArrayBuffer and writes the data to a PixelMap object. This API returns the result synchronously. 659 660**Atomic service API**: This API can be used in atomic services since API version 12. 661 662**System capability**: SystemCapability.Multimedia.Image.Core 663 664**Parameters** 665 666| Name| Type | Mandatory| Description | 667| ------ | ----------- | ---- | -------------- | 668| src | ArrayBuffer | Yes | Buffer from which the image data will be read.| 669 670**Error codes** 671 672For details about the error codes, see [Image Error Codes](errorcode-image.md). 673 674| ID| Error Message| 675| ------- | --------------------------------------------| 676| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 677| 501 | Resource Unavailable. | 678 679**Example** 680 681```ts 682import { BusinessError } from '@kit.BasicServicesKit'; 683 684async function Demo(pixelMap: sendableImage.PixelMap) { 685 const bufferSize = pixelMap.getPixelBytesNumber(); 686 const color : ArrayBuffer = new ArrayBuffer(bufferSize); 687 let bufferArr : Uint8Array = new Uint8Array(color); 688 for (let i = 0; i < bufferArr.length; i++) { 689 bufferArr[i] = i + 1; 690 } 691 if (pixelMap != undefined) { 692 pixelMap.writeBufferToPixelsSync(color); 693 } 694} 695``` 696 697### getImageInfo 698 699getImageInfo(): Promise\<image.ImageInfo> 700 701Obtains the image information. This API uses a promise to return the result. 702 703**Atomic service API**: This API can be used in atomic services since API version 12. 704 705**System capability**: SystemCapability.Multimedia.Image.Core 706 707**Return value** 708 709| Type | Description | 710| --------------------------------- | ----------------------------------------------------------- | 711| Promise\<[ImageInfo](arkts-apis-image-i.md#imageinfo)> | Promise used to return the image information. If the operation fails, an error message is returned.| 712 713**Example** 714 715```ts 716import { image } from '@kit.ImageKit'; 717import { BusinessError } from '@kit.BasicServicesKit'; 718 719async function Demo() { 720 if (pixelMap != undefined) { 721 pixelMap.getImageInfo().then((imageInfo: image.ImageInfo) => { 722 if (imageInfo != undefined) { 723 console.info("Succeeded in obtaining the image pixel map information."+ imageInfo.size.height); 724 } 725 }).catch((error: BusinessError) => { 726 console.error(`Failed to obtain the image pixel map information. code is ${error.code}, message is ${error.message}`); 727 }) 728 } 729} 730``` 731 732### getImageInfoSync 733 734getImageInfoSync(): image.ImageInfo 735 736Obtains the image information. This API returns the result synchronously. 737 738**Atomic service API**: This API can be used in atomic services since API version 12. 739 740**System capability**: SystemCapability.Multimedia.Image.ImageSource 741 742**Return value** 743 744| Type | Description | 745| --------------------------------- | ----------------------------------------------------------- | 746| [ImageInfo](arkts-apis-image-i.md#imageinfo) | Image information. | 747 748**Error codes** 749 750For details about the error codes, see [Image Error Codes](errorcode-image.md). 751 752| ID| Error Message| 753| ------- | --------------------------------------------| 754| 501 | Resource Unavailable | 755 756**Example** 757 758```ts 759import { image } from '@kit.ImageKit'; 760import { BusinessError } from '@kit.BasicServicesKit'; 761 762async function Demo() { 763 if (pixelMap != undefined) { 764 let imageInfo : image.ImageInfo = pixelMap.getImageInfoSync(); 765 } 766} 767``` 768 769### getBytesNumberPerRow 770 771getBytesNumberPerRow(): number 772 773Obtains the number of bytes per row of this image. 774 775**Atomic service API**: This API can be used in atomic services since API version 12. 776 777**System capability**: SystemCapability.Multimedia.Image.Core 778 779**Return value** 780 781| Type | Description | 782| ------ | -------------------- | 783| number | Number of bytes per row.| 784 785**Example** 786 787```ts 788let rowCount: number = pixelMap.getBytesNumberPerRow(); 789``` 790 791### getPixelBytesNumber 792 793getPixelBytesNumber(): number 794 795Obtains the total number of bytes of this image. 796 797**Atomic service API**: This API can be used in atomic services since API version 12. 798 799**System capability**: SystemCapability.Multimedia.Image.Core 800 801**Return value** 802 803| Type | Description | 804| ------ | -------------------- | 805| number | Total number of bytes.| 806 807**Example** 808 809```ts 810let pixelBytesNumber: number = pixelMap.getPixelBytesNumber(); 811``` 812 813### getDensity 814 815getDensity():number 816 817Obtains the pixel density of this image. 818 819**Atomic service API**: This API can be used in atomic services since API version 12. 820 821**System capability**: SystemCapability.Multimedia.Image.Core 822 823**Return value** 824 825| Type | Description | 826| ------ | --------------- | 827| number | Pixel density, in ppi.| 828 829**Example** 830 831```ts 832let getDensity: number = pixelMap.getDensity(); 833``` 834 835### opacity 836 837opacity(rate: number): Promise\<void> 838 839Sets an opacity rate for this image. This API uses a promise to return the result. 840 841**Atomic service API**: This API can be used in atomic services since API version 12. 842 843**System capability**: SystemCapability.Multimedia.Image.Core 844 845**Parameters** 846 847| Name| Type | Mandatory| Description | 848| ------ | ------ | ---- | --------------------------- | 849| rate | number | Yes | Opacity rate. The value range is (0,1].| 850 851**Return value** 852 853| Type | Description | 854| -------------- | ----------------------------------------------- | 855| Promise\<void> | Promise used to return the result. If the operation fails, an error message is returned.| 856 857**Example** 858 859```ts 860import { BusinessError } from '@kit.BasicServicesKit'; 861 862async function Demo() { 863 let rate: number = 0.5; 864 if (pixelMap != undefined) { 865 pixelMap.opacity(rate).then(() => { 866 console.info('Succeeded in setting opacity.'); 867 }).catch((err: BusinessError) => { 868 console.error(`Failed to set opacity. code is ${err.code}, message is ${err.message}`); 869 }) 870 } 871} 872``` 873 874### opacitySync 875 876opacitySync(rate: number): void 877 878Sets the opacity rate for this PixelMap and initializes the PixelMap. 879 880**Atomic service API**: This API can be used in atomic services since API version 12. 881 882**System capability**: SystemCapability.Multimedia.Image.Core 883 884**Parameters** 885 886| Name | Type | Mandatory| Description | 887| -------- | -------------------- | ---- | ------------------------------ | 888| rate | number | Yes | Opacity rate. The value range is (0,1]. | 889 890**Error codes** 891 892For details about the error codes, see [Image Error Codes](errorcode-image.md). 893 894| ID| Error Message| 895| ------- | --------------------------------------------| 896| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 897| 501 | Resource Unavailable. | 898 899**Example** 900 901```ts 902import { BusinessError } from '@kit.BasicServicesKit'; 903 904async function Demo() { 905 let rate : number = 0.5; 906 if (pixelMap != undefined) { 907 pixelMap.opacitySync(rate); 908 } 909} 910``` 911 912### createAlphaPixelmap 913 914createAlphaPixelmap(): Promise\<PixelMap> 915 916Creates a PixelMap object that contains only the alpha channel information. This object can be used for the shadow effect. This API uses a promise to return the result. 917 918**Atomic service API**: This API can be used in atomic services since API version 12. 919 920**System capability**: SystemCapability.Multimedia.Image.Core 921 922**Return value** 923 924| Type | Description | 925| -------------------------------- | --------------------------- | 926| Promise\<[PixelMap](#pixelmap)> | Promise used to return the PixelMap object.| 927 928**Example** 929 930```ts 931import { BusinessError } from '@kit.BasicServicesKit'; 932 933async function Demo() { 934 if (pixelMap != undefined) { 935 pixelMap.createAlphaPixelmap().then((alphaPixelMap: sendableImage.PixelMap) => { 936 console.info('Succeeded in creating alpha pixelmap.'); 937 }).catch((error: BusinessError) => { 938 console.error(`Failed to create alpha pixelmap. code is ${error.code}, message is ${error.message}`); 939 }) 940 } 941} 942``` 943 944### createAlphaPixelmapSync 945 946createAlphaPixelmapSync(): PixelMap 947 948Creates a PixelMap object that contains only the alpha channel information. This object can be used for the shadow effect. This API returns the result synchronously. 949 950**Atomic service API**: This API can be used in atomic services since API version 12. 951 952**System capability**: SystemCapability.Multimedia.Image.Core 953 954**Return value** 955 956| Type | Description | 957| -------------------------------- | --------------------- | 958| [PixelMap](#pixelmap) | PixelMap object. If the operation fails, an error is thrown.| 959 960**Error codes** 961 962For details about the error codes, see [Image Error Codes](errorcode-image.md). 963 964| ID| Error Message| 965| ------- | --------------------------------------------| 966| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 967| 501 | Resource Unavailable. | 968 969**Example** 970 971```ts 972import { BusinessError } from '@kit.BasicServicesKit'; 973import { sendableImage } from '@kit.ImageKit'; 974 975async function Demo(pixelMap : sendableImage.PixelMap) { 976 let resPixelMap : sendableImage.PixelMap = pixelMap.createAlphaPixelmapSync(); 977 return resPixelMap; 978} 979``` 980 981### scale 982 983scale(x: number, y: number): Promise\<void> 984 985Scales this image based on a given width and height. This API uses a promise to return the result. 986 987**Atomic service API**: This API can be used in atomic services since API version 12. 988 989**System capability**: SystemCapability.Multimedia.Image.Core 990 991**Parameters** 992 993| Name| Type | Mandatory| Description | 994| ------ | ------ | ---- | ------------------------------- | 995| x | number | Yes | Scale factor of the width.| 996| y | number | Yes | Scale factor of the height.| 997 998**Return value** 999 1000| Type | Description | 1001| -------------- | --------------------------- | 1002| Promise\<void> | Promise used to return the result.| 1003 1004**Example** 1005 1006```ts 1007import { BusinessError } from '@kit.BasicServicesKit'; 1008 1009async function Demo() { 1010 let scaleX: number = 2.0; 1011 let scaleY: number = 1.0; 1012 if (pixelMap != undefined) { 1013 pixelMap.scale(scaleX, scaleY).then(() => { 1014 console.info('Succeeded in scaling pixelmap.'); 1015 }).catch((err: BusinessError) => { 1016 console.error(`Failed to scale pixelmap. code is ${err.code}, message is ${err.message}`); 1017 1018 }) 1019 } 1020} 1021``` 1022 1023### scaleSync 1024 1025scaleSync(x: number, y: number): void 1026 1027Scales this image based on a given width and height. This API returns the result synchronously. 1028 1029**Atomic service API**: This API can be used in atomic services since API version 12. 1030 1031**System capability**: SystemCapability.Multimedia.Image.Core 1032 1033**Parameters** 1034 1035| Name| Type | Mandatory| Description | 1036| ------ | ------ | ---- | ------------------------------- | 1037| x | number | Yes | Scale factor of the width.| 1038| y | number | Yes | Scale factor of the height.| 1039 1040**Error codes** 1041 1042For details about the error codes, see [Image Error Codes](errorcode-image.md). 1043 1044| ID| Error Message| 1045| ------- | --------------------------------------------| 1046| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1047| 501 | Resource Unavailable. | 1048 1049**Example** 1050 1051```ts 1052import { BusinessError } from '@kit.BasicServicesKit'; 1053 1054async function Demo() { 1055 let scaleX: number = 2.0; 1056 let scaleY: number = 1.0; 1057 if (pixelMap != undefined) { 1058 pixelMap.scaleSync(scaleX, scaleY); 1059 } 1060} 1061``` 1062 1063### translate 1064 1065translate(x: number, y: number): Promise\<void> 1066 1067Translates this image based on given coordinates. This API uses a promise to return the result. 1068 1069**Atomic service API**: This API can be used in atomic services since API version 12. 1070 1071**System capability**: SystemCapability.Multimedia.Image.Core 1072 1073**Parameters** 1074 1075| Name| Type | Mandatory| Description | 1076| ------ | ------ | ---- | ----------- | 1077| x | number | Yes | X coordinate, in px.| 1078| y | number | Yes | Y coordinate, in px.| 1079 1080**Return value** 1081 1082| Type | Description | 1083| -------------- | --------------------------- | 1084| Promise\<void> | Promise used to return the result.| 1085 1086**Example** 1087 1088```ts 1089import { BusinessError } from '@kit.BasicServicesKit'; 1090 1091async function Demo() { 1092 let translateX: number = 50.0; 1093 let translateY: number = 10.0; 1094 if (pixelMap != undefined) { 1095 pixelMap.translate(translateX, translateY).then(() => { 1096 console.info('Succeeded in translating pixelmap.'); 1097 }).catch((err: BusinessError) => { 1098 console.error(`Failed to translate pixelmap. code is ${err.code}, message is ${err.message}`); 1099 }) 1100 } 1101} 1102``` 1103 1104### translateSync 1105 1106translateSync(x: number, y: number): void 1107 1108Translates this image based on given coordinates. This API returns the result synchronously. 1109 1110**Atomic service API**: This API can be used in atomic services since API version 12. 1111 1112**System capability**: SystemCapability.Multimedia.Image.Core 1113 1114**Parameters** 1115 1116| Name | Type | Mandatory| Description | 1117| -------- | -------------------- | ---- | ------------------------------- | 1118| x | number | Yes | Scale factor of the width.| 1119| y | number | Yes | Scale factor of the height.| 1120 1121**Error codes** 1122 1123For details about the error codes, see [Image Error Codes](errorcode-image.md). 1124 1125| ID| Error Message| 1126| ------- | --------------------------------------------| 1127| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1128| 501 | Resource Unavailable. | 1129 1130**Example** 1131 1132```ts 1133import { BusinessError } from '@kit.BasicServicesKit'; 1134 1135async function Demo() { 1136 let translateX : number = 50.0; 1137 let translateY : number = 10.0; 1138 if (pixelMap != undefined) { 1139 pixelMap.translateSync(translateX, translateY); 1140 } 1141} 1142``` 1143 1144### rotate 1145 1146rotate(angle: number): Promise\<void> 1147 1148Rotates this image based on a given angle. This API uses a promise to return the result. 1149 1150**Atomic service API**: This API can be used in atomic services since API version 12. 1151 1152**System capability**: SystemCapability.Multimedia.Image.Core 1153 1154**Parameters** 1155 1156| Name| Type | Mandatory| Description | 1157| ------ | ------ | ---- | ----------------------------- | 1158| angle | number | Yes | Angle to rotate. | 1159 1160**Return value** 1161 1162| Type | Description | 1163| -------------- | --------------------------- | 1164| Promise\<void> | Promise used to return the result.| 1165 1166**Example** 1167 1168```ts 1169import { BusinessError } from '@kit.BasicServicesKit'; 1170 1171async function Demo() { 1172 let angle: number = 90.0; 1173 if (pixelMap != undefined) { 1174 pixelMap.rotate(angle).then(() => { 1175 console.info('Succeeded in rotating pixelmap.'); 1176 }).catch((err: BusinessError) => { 1177 console.error(`Failed to rotate pixelmap. code is ${err.code}, message is ${err.message}`); 1178 }) 1179 } 1180} 1181``` 1182 1183### rotateSync 1184 1185rotateSync(angle: number): void 1186 1187Rotates this image based on a given angle. This API returns the result synchronously. 1188 1189**Atomic service API**: This API can be used in atomic services since API version 12. 1190 1191**System capability**: SystemCapability.Multimedia.Image.Core 1192 1193**Parameters** 1194 1195| Name | Type | Mandatory| Description | 1196| -------- | -------------------- | ---- | ----------------------------- | 1197| angle | number | Yes | Angle to rotate. | 1198 1199**Error codes** 1200 1201For details about the error codes, see [Image Error Codes](errorcode-image.md). 1202 1203| ID| Error Message| 1204| ------- | --------------------------------------------| 1205| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1206| 501 | Resource Unavailable. | 1207 1208**Example** 1209 1210```ts 1211import { BusinessError } from '@kit.BasicServicesKit'; 1212 1213async function Demo() { 1214 let angle : number = 90.0; 1215 if (pixelMap != undefined) { 1216 pixelMap.rotateSync(angle); 1217 } 1218} 1219``` 1220 1221### flip 1222 1223flip(horizontal: boolean, vertical: boolean): Promise\<void> 1224 1225Flips this image horizontally or vertically, or both. This API uses a promise to return the result. 1226 1227**Atomic service API**: This API can be used in atomic services since API version 12. 1228 1229**System capability**: SystemCapability.Multimedia.Image.Core 1230 1231**Parameters** 1232 1233| Name | Type | Mandatory| Description | 1234| ---------- | ------- | ---- | --------- | 1235| horizontal | boolean | Yes | Whether to flip the image horizontally. The value **true** means to flip the image horizontally, and **false** means the opposite. | 1236| vertical | boolean | Yes | Whether to flip the image vertically. The value **true** means to flip the image vertically, and **false** means the opposite. | 1237 1238**Return value** 1239 1240| Type | Description | 1241| -------------- | --------------------------- | 1242| Promise\<void> | Promise used to return the result.| 1243 1244**Example** 1245 1246```ts 1247import { BusinessError } from '@kit.BasicServicesKit'; 1248 1249async function Demo() { 1250 let horizontal: boolean = true; 1251 let vertical: boolean = false; 1252 if (pixelMap != undefined) { 1253 pixelMap.flip(horizontal, vertical).then(() => { 1254 console.info('Succeeded in flipping pixelmap.'); 1255 }).catch((err: BusinessError) => { 1256 console.error(`Failed to flip pixelmap. code is ${err.code}, message is ${err.message}`); 1257 1258 }) 1259 } 1260} 1261``` 1262 1263### flipSync 1264 1265flipSync(horizontal: boolean, vertical: boolean): void 1266 1267Flips this image horizontally or vertically, or both. This API returns the result synchronously. 1268 1269**Atomic service API**: This API can be used in atomic services since API version 12. 1270 1271**System capability**: SystemCapability.Multimedia.Image.Core 1272 1273**Parameters** 1274 1275| Name | Type | Mandatory| Description | 1276| ---------- | -------------------- | ---- | ----------------------------- | 1277| horizontal | boolean | Yes | Whether to flip the image horizontally. The value **true** means to flip the image horizontally, and **false** means the opposite. | 1278| vertical | boolean | Yes | Whether to flip the image vertically. The value **true** means to flip the image vertically, and **false** means the opposite. | 1279 1280**Error codes** 1281 1282For details about the error codes, see [Image Error Codes](errorcode-image.md). 1283 1284| ID| Error Message| 1285| ------- | --------------------------------------------| 1286| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1287| 501 | Resource Unavailable. | 1288 1289**Example** 1290 1291```ts 1292import { BusinessError } from '@kit.BasicServicesKit'; 1293 1294async function Demo() { 1295 let horizontal : boolean = true; 1296 let vertical : boolean = false; 1297 if (pixelMap != undefined) { 1298 pixelMap.flipSync(horizontal, vertical); 1299 } 1300} 1301``` 1302 1303### crop 1304 1305crop(region: image.Region): Promise\<void> 1306 1307Crops this image based on a given size. This API uses a promise to return the result. 1308 1309**Atomic service API**: This API can be used in atomic services since API version 12. 1310 1311**System capability**: SystemCapability.Multimedia.Image.Core 1312 1313**Parameters** 1314 1315| Name| Type | Mandatory| Description | 1316| ------ | ------------------ | ---- | ----------- | 1317| region | [Region](../apis-image-kit/arkts-apis-image-i.md#region8) | Yes | Size of the image after cropping.| 1318 1319**Return value** 1320 1321| Type | Description | 1322| -------------- | --------------------------- | 1323| Promise\<void> | Promise used to return the result.| 1324 1325**Example** 1326 1327```ts 1328import { image } from '@kit.ImageKit'; 1329import { BusinessError } from '@kit.BasicServicesKit'; 1330 1331async function Demo() { 1332 let region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 1333 if (pixelMap != undefined) { 1334 pixelMap.crop(region).then(() => { 1335 console.info('Succeeded in cropping pixelmap.'); 1336 }).catch((err: BusinessError) => { 1337 console.error(`Failed to crop pixelmap. code is ${err.code}, message is ${err.message}`); 1338 1339 }); 1340 } 1341} 1342``` 1343 1344### cropSync 1345 1346cropSync(region: image.Region): void 1347 1348Crops this image based on a given size. This API returns the result synchronously. 1349 1350**Atomic service API**: This API can be used in atomic services since API version 12. 1351 1352**System capability**: SystemCapability.Multimedia.Image.Core 1353 1354**Parameters** 1355 1356| Name | Type | Mandatory| Description | 1357| -------- | -------------------- | ---- | ----------------------------- | 1358| region | [Region](../apis-image-kit/arkts-apis-image-i.md#region8) | Yes | Size of the image after cropping. | 1359 1360**Error codes** 1361 1362For details about the error codes, see [Image Error Codes](errorcode-image.md). 1363 1364| ID| Error Message| 1365| ------- | --------------------------------------------| 1366| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1367| 501 | Resource Unavailable. | 1368 1369**Example** 1370 1371```ts 1372import { image } from '@kit.ImageKit'; 1373import { BusinessError } from '@kit.BasicServicesKit'; 1374 1375async function Demo() { 1376 let region : image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 1377 if (pixelMap != undefined) { 1378 pixelMap.cropSync(region); 1379 } 1380} 1381``` 1382 1383### getColorSpace 1384 1385getColorSpace(): colorSpaceManager.ColorSpaceManager 1386 1387Obtains the color space of this image. 1388 1389**System capability**: SystemCapability.Multimedia.Image.Core 1390 1391**Return value** 1392 1393| Type | Description | 1394| ----------------------------------- | ---------------- | 1395| [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | Color space.| 1396 1397**Error codes** 1398 1399For details about the error codes, see [Image Error Codes](errorcode-image.md). 1400 1401| ID| Error Message| 1402| ------- | --------------------------------------------| 1403| 62980101| If the image data abnormal. | 1404| 62980103| If the image data unsupport. | 1405| 62980115| If the image parameter invalid. | 1406 1407**Example** 1408 1409```ts 1410async function Demo() { 1411 if (pixelMap != undefined) { 1412 let csm = pixelMap.getColorSpace(); 1413 } 1414} 1415``` 1416 1417### setColorSpace 1418 1419setColorSpace(colorSpace: colorSpaceManager.ColorSpaceManager): void 1420 1421Sets the color space for this image. 1422 1423**System capability**: SystemCapability.Multimedia.Image.Core 1424 1425**Parameters** 1426 1427| Name | Type | Mandatory| Description | 1428| ---------- | ----------------------------------- | ---- | --------------- | 1429| colorSpace | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | Yes | Color space.| 1430 1431**Error codes** 1432 1433For details about the error codes, see [Image Error Codes](errorcode-image.md). 1434 1435| ID| Error Message| 1436| ------- | --------------------------------------------| 1437| 62980111| If the operation invalid. | 1438| 62980115| If the image parameter invalid. | 1439 1440**Example** 1441 1442```ts 1443import { colorSpaceManager } from '@kit.ArkGraphics2D'; 1444async function Demo() { 1445 let colorSpaceName = colorSpaceManager.ColorSpace.SRGB; 1446 let csm: colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceName); 1447 if (pixelMap != undefined) { 1448 pixelMap.setColorSpace(csm); 1449 } 1450} 1451``` 1452 1453### applyColorSpace 1454 1455applyColorSpace(targetColorSpace: colorSpaceManager.ColorSpaceManager): Promise\<void> 1456 1457Performs Color Space Converters (CSC) on the image pixel color based on a given color space. This API uses a promise to return the result. 1458 1459**System capability**: SystemCapability.Multimedia.Image.Core 1460 1461**Parameters** 1462 1463| Name| Type | Mandatory| Description | 1464| ------ | ------------------ | ---- | ----------- | 1465| targetColorSpace | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | Yes | Target color space. SRGB, DCI_P3, DISPLAY_P3, and ADOBE_RGB_1998 are supported.| 1466 1467**Return value** 1468 1469| Type | Description | 1470| -------------- | --------------------------- | 1471| Promise\<void> | Promise used to return the result.| 1472 1473**Error codes** 1474 1475For details about the error codes, see [Image Error Codes](errorcode-image.md). 1476 1477| ID| Error Message| 1478| ------- | ------------------------------------------| 1479| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1480| 62980104| Failed to initialize the internal object. | 1481| 62980108| Failed to convert the color space. | 1482| 62980115| Invalid image parameter. | 1483 1484**Example** 1485 1486```ts 1487import { sendableImage } from '@kit.ImageKit'; 1488import { colorSpaceManager } from '@kit.ArkGraphics2D'; 1489import { BusinessError } from '@kit.BasicServicesKit'; 1490 1491async function Demo(pixelMap : sendableImage.PixelMap) { 1492 let colorSpaceName = colorSpaceManager.ColorSpace.SRGB; 1493 let targetColorSpace: colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceName); 1494 pixelMap.applyColorSpace(targetColorSpace).then(() => { 1495 console.info('Succeeded in applying color space for pixelmap object.'); 1496 }).catch((error: BusinessError) => { 1497 console.error(`Failed to apply color space for pixelmap object. code is ${error.code}, message is ${error.message}`); 1498 }) 1499} 1500``` 1501 1502### marshalling 1503 1504marshalling(sequence: rpc.MessageSequence): void 1505 1506Marshals this PixelMap object and writes it to a MessageSequence object. 1507 1508**System capability**: SystemCapability.Multimedia.Image.Core 1509 1510**Parameters** 1511 1512| Name | Type | Mandatory| Description | 1513| ---------------------- | ------------------------------------------------------ | ---- | ---------------------------------------- | 1514| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | Yes | MessageSequence object. | 1515 1516**Error codes** 1517 1518For details about the error codes, see [Image Error Codes](errorcode-image.md). 1519 1520| ID| Error Message| 1521| ------- | --------------------------------------------| 1522| 62980115 | Invalid image parameter. | 1523| 62980097 | IPC error. | 1524 1525**Example** 1526```ts 1527import { sendableImage } from '@kit.ImageKit'; 1528import { image } from '@kit.ImageKit'; 1529import { rpc } from '@kit.IPCKit'; 1530 1531class MySequence implements rpc.Parcelable { 1532 pixel_map: sendableImage.PixelMap; 1533 constructor(conPixelMap : sendableImage.PixelMap) { 1534 this.pixel_map = conPixelMap; 1535 } 1536 marshalling(messageSequence : rpc.MessageSequence) { 1537 this.pixel_map.marshalling(messageSequence); 1538 console.info('marshalling'); 1539 return true; 1540 } 1541 unmarshalling(messageSequence : rpc.MessageSequence) { 1542 sendableImage.createPixelMap(new ArrayBuffer(96), {size: { height:4, width: 6}}).then((pixelParcel: sendableImage.PixelMap) => { 1543 pixelParcel.unmarshalling(messageSequence).then(async (pixelMap: sendableImage.PixelMap) => { 1544 this.pixel_map = pixelMap; 1545 pixelMap.getImageInfo().then((imageInfo: image.ImageInfo) => { 1546 console.info("unmarshalling information h:" + imageInfo.size.height + "w:" + imageInfo.size.width); 1547 }) 1548 }) 1549 }); 1550 return true; 1551 } 1552} 1553async function Demo() { 1554 const color: ArrayBuffer = new ArrayBuffer(96); 1555 let bufferArr: Uint8Array = new Uint8Array(color); 1556 for (let i = 0; i < bufferArr.length; i++) { 1557 bufferArr[i] = 0x80; 1558 } 1559 let opts: image.InitializationOptions = { 1560 editable: true, 1561 pixelFormat: 4, 1562 size: { height: 4, width: 6 }, 1563 alphaType: 3 1564 } 1565 let pixelMap: sendableImage.PixelMap | undefined = undefined; 1566 await sendableImage.createPixelMap(color, opts).then((srcPixelMap: sendableImage.PixelMap) => { 1567 pixelMap = srcPixelMap; 1568 }) 1569 if (pixelMap != undefined) { 1570 // Implement serialization. 1571 let parcelable: MySequence = new MySequence(pixelMap); 1572 let data: rpc.MessageSequence = rpc.MessageSequence.create(); 1573 data.writeParcelable(parcelable); 1574 1575 // Implement deserialization to obtain data through the RPC. 1576 let ret: MySequence = new MySequence(pixelMap); 1577 data.readParcelable(ret); 1578 } 1579} 1580``` 1581 1582### unmarshalling 1583 1584unmarshalling(sequence: rpc.MessageSequence): Promise\<PixelMap> 1585 1586Unmarshals a MessageSequence object to obtain a PixelMap object. 1587To create a PixelMap object in synchronous mode, use [createPixelMapFromParcel](#sendableimagecreatepixelmapfromparcel). 1588 1589**System capability**: SystemCapability.Multimedia.Image.Core 1590 1591**Parameters** 1592 1593| Name | Type | Mandatory| Description | 1594| ---------------------- | ----------------------------------------------------- | ---- | ---------------------------------------- | 1595| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | Yes | MessageSequence object that stores the PixelMap information. | 1596 1597**Return value** 1598 1599| Type | Description | 1600| -------------------------------- | --------------------- | 1601| Promise\<[PixelMap](#pixelmap)> | Promise used to return the result. If the operation fails, an error message is returned.| 1602 1603**Error codes** 1604 1605For details about the error codes, see [Image Error Codes](errorcode-image.md). 1606 1607| ID| Error Message| 1608| ------- | --------------------------------------------| 1609| 62980115 | Invalid image parameter. | 1610| 62980097 | IPC error. | 1611| 62980096 | The operation failed. | 1612 1613**Example** 1614 1615```ts 1616import { sendableImage } from '@kit.ImageKit'; 1617import { image } from '@kit.ImageKit'; 1618import { rpc } from '@kit.IPCKit'; 1619 1620class MySequence implements rpc.Parcelable { 1621 pixel_map: sendableImage.PixelMap; 1622 constructor(conPixelMap: sendableImage.PixelMap) { 1623 this.pixel_map = conPixelMap; 1624 } 1625 marshalling(messageSequence: rpc.MessageSequence) { 1626 this.pixel_map.marshalling(messageSequence); 1627 console.info('marshalling'); 1628 return true; 1629 } 1630 unmarshalling(messageSequence: rpc.MessageSequence) { 1631 sendableImage.createPixelMap(new ArrayBuffer(96), {size: { height:4, width: 6}}).then((pixelParcel : sendableImage.PixelMap) => { 1632 pixelParcel.unmarshalling(messageSequence).then(async (pixelMap : sendableImage.PixelMap) => { 1633 this.pixel_map = pixelMap; 1634 pixelMap.getImageInfo().then((imageInfo : image.ImageInfo) => { 1635 console.info("unmarshalling information h:" + imageInfo.size.height + "w:" + imageInfo.size.width); 1636 }) 1637 }) 1638 }); 1639 return true; 1640 } 1641} 1642async function Demo() { 1643 const color: ArrayBuffer = new ArrayBuffer(96); 1644 let bufferArr: Uint8Array = new Uint8Array(color); 1645 for (let i = 0; i < bufferArr.length; i++) { 1646 bufferArr[i] = 0x80; 1647 } 1648 let opts: image.InitializationOptions = { 1649 editable: true, 1650 pixelFormat: 4, 1651 size: { height: 4, width: 6 }, 1652 alphaType: 3 1653 } 1654 let pixelMap: sendableImage.PixelMap | undefined = undefined; 1655 await sendableImage.createPixelMap(color, opts).then((srcPixelMap : sendableImage.PixelMap) => { 1656 pixelMap = srcPixelMap; 1657 }) 1658 if (pixelMap != undefined) { 1659 // Implement serialization. 1660 let parcelable: MySequence = new MySequence(pixelMap); 1661 let data : rpc.MessageSequence = rpc.MessageSequence.create(); 1662 data.writeParcelable(parcelable); 1663 1664 // Implement deserialization to obtain data through the RPC. 1665 let ret : MySequence = new MySequence(pixelMap); 1666 data.readParcelable(ret); 1667 } 1668} 1669``` 1670 1671### release 1672 1673release():Promise\<void> 1674 1675Releases this PixelMap object. This API uses a promise to return the result. 1676 1677**Atomic service API**: This API can be used in atomic services since API version 12. 1678 1679**System capability**: SystemCapability.Multimedia.Image.Core 1680 1681**Return value** 1682 1683| Type | Description | 1684| -------------- | ------------------------------- | 1685| Promise\<void> | Promise used to return the result.| 1686 1687**Example** 1688 1689```ts 1690import { BusinessError } from '@kit.BasicServicesKit'; 1691import { sendableImage } from '@kit.ImageKit'; 1692 1693async function Demo(pixelMap: sendableImage.PixelMap) { 1694 if (pixelMap != undefined) { 1695 await pixelMap.release().then(() => { 1696 console.info('Succeeded in releasing pixelmap object.'); 1697 }).catch((error: BusinessError) => { 1698 console.error(`Failed to release pixelmap object. code is ${error.code}, message is ${error.message}`); 1699 }) 1700 } 1701} 1702``` 1703 1704## Size 1705 1706Describes the size of an image. 1707It inherits from [lang.ISendable](../../arkts-utils/arkts-sendable.md#isendable). 1708 1709**Widget capability**: This API can be used in ArkTS widgets since API version 12. 1710 1711**Atomic service API**: This API can be used in atomic services since API version 12. 1712 1713**System capability**: SystemCapability.Multimedia.Image.Core 1714 1715| Name | Type | Read-Only| Optional| Description | 1716| ------ | ------ | ---- | ---- | -------------- | 1717| height | number | No | No | Height of the output image, in px.| 1718| width | number | No | No | Width of the output image, in px.| 1719 1720## Region 1721 1722Describes the region information. 1723It inherits from [lang.ISendable](../../arkts-utils/arkts-sendable.md#isendable). 1724 1725**Widget capability**: This API can be used in ArkTS widgets since API version 12. 1726 1727**Atomic service API**: This API can be used in atomic services since API version 12. 1728 1729**System capability**: SystemCapability.Multimedia.Image.Core 1730 1731| Name| Type | Read-Only| Optional| Description | 1732| ---- | ------------- | ---- | ---- | ------------ | 1733| size | [Size](#size) | No | No | Region size. | 1734| x | number | No | No | X coordinate, in px.| 1735| y | number | No | No | Y coordinate, in px.| 1736 1737## sendableImage.createImageSource 1738 1739createImageSource(uri: string): ImageSource 1740 1741Creates an ImageSource instance based on a given URI. 1742 1743 1744**Atomic service API**: This API can be used in atomic services since API version 12. 1745 1746**System capability**: SystemCapability.Multimedia.Image.ImageSource 1747 1748**Parameters** 1749 1750| Name| Type | Mandatory| Description | 1751| ------ | ------ | ---- | ---------------------------------- | 1752| uri | string | Yes | Image path. Currently, only the application sandbox path is supported.<br>The following formats are supported: .jpg, .png, .gif, .bmp, .webp, .dng [SVG](arkts-apis-image-f.md#svg-tags), and ico.| 1753 1754**Return value** 1755 1756| Type | Description | 1757| --------------------------- | -------------------------------------------- | 1758| [ImageSource](#imagesource) | ImageSource instance. If the operation fails, undefined is returned.| 1759 1760**Example** 1761 1762<!--code_no_check--> 1763```ts 1764import { common } from '@kit.AbilityKit'; 1765 1766// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 1767let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1768const path: string = context.cacheDir + "/test.jpg"; 1769const sendableImageSourceApi: sendableImage.ImageSource = sendableImage.createImageSource(path); 1770``` 1771 1772## sendableImage.createImageSource 1773 1774createImageSource(fd: number): ImageSource 1775 1776Creates an ImageSource instance based on a given file descriptor. 1777 1778**Atomic service API**: This API can be used in atomic services since API version 12. 1779 1780**System capability**: SystemCapability.Multimedia.Image.ImageSource 1781 1782**Parameters** 1783 1784| Name| Type | Mandatory| Description | 1785| ------ | ------ | ---- | ------------- | 1786| fd | number | Yes | File descriptor.| 1787 1788**Return value** 1789 1790| Type | Description | 1791| --------------------------- | -------------------------------------------- | 1792| [ImageSource](#imagesource) | ImageSource instance. If the operation fails, undefined is returned.| 1793 1794**Example** 1795 1796<!--code_no_check--> 1797```ts 1798import { common } from '@kit.AbilityKit'; 1799import { fileIo as fs } from '@kit.CoreFileKit'; 1800 1801// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 1802let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1803const path: string = context.cacheDir + "/test.jpg"; 1804let file = fs.openSync(path, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 1805const sendableImageSourceApi: sendableImage.ImageSource = sendableImage.createImageSource(file.fd); 1806``` 1807 1808## sendableImage.createImageSource 1809 1810createImageSource(buf: ArrayBuffer): ImageSource 1811 1812Creates an ImageSource instance based on buffers. 1813 1814**Widget capability**: This API can be used in ArkTS widgets since API version 12. 1815 1816**Atomic service API**: This API can be used in atomic services since API version 12. 1817 1818**System capability**: SystemCapability.Multimedia.Image.ImageSource 1819 1820**Parameters** 1821 1822| Name| Type | Mandatory| Description | 1823| ------ | ----------- | ---- | ---------------- | 1824| buf | ArrayBuffer | Yes | Array of image buffers.| 1825 1826**Return value** 1827 1828| Type | Description | 1829| --------------------------- | -------------------------------------------- | 1830| [ImageSource](#imagesource) | ImageSource instance. If the operation fails, undefined is returned.| 1831 1832 1833**Example** 1834 1835```ts 1836const buf: ArrayBuffer = new ArrayBuffer(96); // 96 is the size of the pixel buffer to create. The value is calculated as follows: height * width *4. 1837const sendableImageSourceApi: sendableImage.ImageSource = sendableImage.createImageSource(buf); 1838``` 1839 1840## sendableImage.createImageReceiver 1841 1842createImageReceiver(size: image.Size, format: image.ImageFormat, capacity: number): ImageReceiver 1843 1844Creates an ImageReceiver instance based on the specified image size, format, and capacity. 1845 1846**System capability**: SystemCapability.Multimedia.Image.ImageReceiver 1847 1848**Parameters** 1849 1850| Name | Type | Mandatory| Description | 1851| -------- | ------ | ---- | ---------------------- | 1852| size | [image.Size](./arkts-apis-image-i.md#size) | Yes | Default size of the image. | 1853| format | [image.ImageFormat](./arkts-apis-image-e.md#imageformat9) | Yes | Image format, which is a constant of **image.ImageFormat**. (Currently, only **ImageFormat:JPEG** is supported.) | 1854| capacity | number | Yes | Maximum number of images that can be accessed at the same time.| 1855 1856**Return value** 1857 1858| Type | Description | 1859| -------------------------------- | --------------------------------------- | 1860| [ImageReceiver](#imagereceiver) | ImageReceiver instance.| 1861 1862**Error codes** 1863 1864For details about the error codes, see [Image Error Codes](errorcode-image.md). 1865 1866| ID| Error Message| 1867| ------- | --------------------------------------------| 1868| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1869 1870**Example** 1871 1872```ts 1873import { image } from '@kit.ImageKit'; 1874 1875let size: image.Size = { 1876 height: 8192, 1877 width: 8 1878} 1879let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8); 1880``` 1881 1882## ImageSource 1883 1884Provides APIs to obtain image information. Before calling any API in ImageSource, you must use [createImageSource](#sendableimagecreateimagesource) to create an ImageSource instance. 1885 1886 1887### createPixelMap 1888 1889createPixelMap(options?: image.DecodingOptions): Promise\<PixelMap> 1890 1891Creates a PixelMap object based on decoding options. This API uses a promise to return the result. 1892 1893**Widget capability**: This API can be used in ArkTS widgets since API version 12. 1894 1895**Atomic service API**: This API can be used in atomic services since API version 12. 1896 1897**System capability**: SystemCapability.Multimedia.Image.ImageSource 1898 1899**Parameters** 1900 1901| Name | Type | Mandatory| Description | 1902| ------- | ------------------------------------ | ---- | ---------- | 1903| options | [image.DecodingOptions](./arkts-apis-image-i.md#decodingoptions7) | No | Decoding options.| 1904 1905**Return value** 1906 1907| Type | Description | 1908| -------------------------------- | --------------------- | 1909| Promise\<[PixelMap]> | Promise used to return the PixelMap object.| 1910 1911**Example** 1912 1913<!--code_no_check--> 1914```ts 1915import { common } from '@kit.AbilityKit'; 1916import { BusinessError } from '@kit.BasicServicesKit'; 1917 1918// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 1919let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1920const path: string = context.cacheDir + "/test.jpg"; 1921const sendableImageSourceApi: sendableImage.ImageSource = sendableImage.createImageSource(path); 1922sendableImageSourceApi.createPixelMap().then((pixelMap: sendableImage.PixelMap) => { 1923 console.info('Succeeded in creating pixelMap object through image decoding parameters.'); 1924}).catch((error: BusinessError) => { 1925 console.error(`Failed to create pixelMap object through image decoding parameters. code ${error.code}, message is ${error.message}`); 1926}) 1927``` 1928 1929### release 1930 1931release(): Promise\<void> 1932 1933Releases this ImageSource instance. This API uses a promise to return the result. The thread that runs **release** is insecure. 1934 1935**System capability**: SystemCapability.Multimedia.Image.ImageSource 1936 1937**Return value** 1938 1939| Type | Description | 1940| -------------- | --------------------------- | 1941| Promise\<void> | Promise used to return the result.| 1942 1943**Example** 1944 1945<!--code_no_check--> 1946```ts 1947import { common } from '@kit.AbilityKit'; 1948import { BusinessError } from '@kit.BasicServicesKit'; 1949 1950// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. 1951let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1952const path: string = context.cacheDir + "/test.jpg"; 1953const sendableImageSourceApi: sendableImage.ImageSource = sendableImage.createImageSource(path); 1954sendableImageSourceApi.release().then(() => { 1955 console.info('Succeeded in releasing the image source instance.'); 1956}).catch((error: BusinessError) => { 1957 console.error(`Failed to release the image source instance. code ${error.code}, message is ${error.message}`); 1958}) 1959``` 1960 1961## Image 1962 1963Provides APIs for basic image operations, including obtaining image information and reading and writing image data. An Image instance is returned when [readNextImage](#readnextimage) and [readLatestImage](#readlatestimage) are called. This class inherits from [lang.ISendable](../../arkts-utils/arkts-sendable.md#isendable). 1964 1965### Properties 1966 1967**System capability**: SystemCapability.Multimedia.Image.Core 1968 1969| Name | Type | Read-Only| Optional| Description | 1970| -------- | ------------------ | ---- | ---- | -------------------------------------------------- | 1971| clipRect | [Region](#region) | No | No | Image area to be cropped. | 1972| size | [Size](#size) | Yes | No | Image size. If the image object stores the camera preview stream data (YUV image data), the width and height in **size** obtained correspond to those of the YUV image. If the image object stores the camera photo stream data (JPEG image data, which is already encoded), the width in **size** obtained is the JPEG data size, and the height is 1. The type of data stored in the image object depends on whether the application passes the surface ID in the receiver to a previewOutput or captureOutput object of the camera. For details about the best practices of camera preview and photo capture, see [Dual-Channel Preview (ArkTS)](../../media/camera/camera-dual-channel-preview.md) and [Photo Capture Sample (ArkTS)](../../media/camera/camera-shooting-case.md). | 1973| format | number | Yes | No | Image format. For details, see [OH_NativeBuffer_Format](../apis-arkgraphics2d/capi-native-buffer-h.md#oh_nativebuffer_format).| 1974| timestamp<sup>12+</sup> | number | Yes | No | Image timestamp. Timestamps, measured in nanoseconds, are usually monotonically increasing. The specific meaning and baseline of these timestamps are determined by the image producer, which is the camera in the camera preview and photo scenarios. As a result, images from different producers may carry timestamps with distinct meanings and baselines, making direct comparison between them infeasible. To obtain the generation time of a photo, you can use [getImageProperty](arkts-apis-image-ImageSource.md#getimageproperty11) to read the related EXIF information.| 1975 1976### getComponent 1977 1978getComponent(componentType: image.ComponentType): Promise\<image.Component> 1979 1980Obtains the component buffer from the Image instance based on the color component type. This API uses a promise to return the result. The thread that runs **getComponent** is insecure. 1981 1982**System capability**: SystemCapability.Multimedia.Image.Core 1983 1984**Parameters** 1985 1986| Name | Type | Mandatory| Description | 1987| ------------- | -------------------------------- | ---- | ---------------- | 1988| componentType | [image.ComponentType](./arkts-apis-image-e.md#componenttype9) | Yes | Color component type of the image.| 1989 1990**Return value** 1991 1992| Type | Description | 1993| --------------------------------- | --------------------------------- | 1994| Promise<[image.Component](./arkts-apis-image-i.md#component9)> | Promise used to return the component buffer.| 1995 1996**Example** 1997 1998```ts 1999import { BusinessError } from '@kit.BasicServicesKit'; 2000import { image } from '@kit.ImageKit'; 2001 2002async function Demo() { 2003 let size: image.Size = { 2004 height: 8192, 2005 width: 8 2006 } 2007 let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8); 2008 let img = await receiver.readNextImage(); 2009 img.getComponent(4).then((component: image.Component) => { 2010 console.info('getComponent succeeded.'); 2011 }).catch((error: BusinessError) => { 2012 console.error(`getComponent failed code ${error.code}, message is ${error.message}`); 2013 }) 2014} 2015``` 2016 2017### release 2018 2019release(): Promise\<void> 2020 2021Releases this Image instance. This API uses a promise to return the result. 2022 2023The corresponding resources must be released before another image arrives. The thread that runs **release** is insecure. 2024 2025 2026**System capability**: SystemCapability.Multimedia.Image.Core 2027 2028**Return value** 2029 2030| Type | Description | 2031| -------------- | --------------------- | 2032| Promise\<void> | Promise used to return the result.| 2033 2034**Example** 2035 2036```ts 2037import { BusinessError } from '@kit.BasicServicesKit'; 2038import { image } from '@kit.ImageKit'; 2039 2040async function Demo() { 2041 let size: image.Size = { 2042 height: 8192, 2043 width: 8 2044 } 2045 let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8); 2046 let img = await receiver.readNextImage(); 2047 img.release().then(() => { 2048 console.info('release succeeded.'); 2049 }).catch((error: BusinessError) => { 2050 console.error(`release failed. code ${error.code}, message is ${error.message}`); 2051 }) 2052} 2053``` 2054 2055## ImageReceiver 2056 2057You can use the **ImageReceiver** class to obtain the surface ID of a component, read the latest image or the next image, and release ImageReceiver instances. 2058 2059Before calling any APIs in ImageReceiver, you must create an ImageReceiver instance. 2060 2061### Properties 2062 2063**System capability**: SystemCapability.Multimedia.Image.ImageReceiver 2064 2065| Name | Type | Read-Only| Optional| Description | 2066| -------- | ---------------------------- | ---- | ---- | ------------------ | 2067| size | [image.Size](./arkts-apis-image-i.md#size) | Yes | No | Image size. | 2068| capacity | number | Yes | No | Maximum number of images that can be accessed at the same time.| 2069| format | [image.ImageFormat](./arkts-apis-image-e.md#imageformat9) | Yes | No | Image format. | 2070 2071### getReceivingSurfaceId 2072 2073getReceivingSurfaceId(): Promise\<string> 2074 2075Obtains a surface ID for the camera or other components. This API uses a promise to return the result. 2076 2077**System capability**: SystemCapability.Multimedia.Image.ImageReceiver 2078 2079**Return value** 2080 2081| Type | Description | 2082| ---------------- | -------------------- | 2083| Promise\<string> | Promise used to return the surface ID.| 2084 2085**Example** 2086 2087```ts 2088import { BusinessError } from '@kit.BasicServicesKit'; 2089import { image } from '@kit.ImageKit'; 2090 2091let size: image.Size = { 2092 height: 8192, 2093 width: 8 2094} 2095let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8); 2096receiver.getReceivingSurfaceId().then((id: string) => { 2097 console.info('Succeeded in getting the ReceivingSurfaceId.'); 2098}).catch((error: BusinessError) => { 2099 console.error(`Failed to get the ReceivingSurfaceId.code ${error.code}, message is ${error.message}`); 2100}) 2101``` 2102 2103### readLatestImage 2104 2105readLatestImage(): Promise\<Image> 2106 2107Reads the latest image from the ImageReceiver instance. This API uses a promise to return the result. 2108 2109This API can be called to receive data only after the [on](#on) callback is triggered. When the [Image](#image) object returned by this API is no longer needed, call [release](#release-2) to release the object. New data can be received only after the release. 2110 2111**System capability**: SystemCapability.Multimedia.Image.ImageReceiver 2112 2113**Return value** 2114 2115| Type | Description | 2116| ------------------------- | ------------------ | 2117| Promise<[Image](#image)> | Promise used to return the latest image.| 2118 2119**Example** 2120 2121```ts 2122import { BusinessError } from '@kit.BasicServicesKit'; 2123import { image } from '@kit.ImageKit'; 2124 2125let size: image.Size = { 2126 height: 8192, 2127 width: 8 2128} 2129let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8); 2130receiver.readLatestImage().then((img: image.Image) => { 2131 console.info('readLatestImage succeeded.'); 2132}).catch((error: BusinessError) => { 2133 console.error(`readLatestImage failed. code ${error.code}, message is ${error.message}`); 2134}) 2135``` 2136 2137### readNextImage 2138 2139readNextImage(): Promise\<Image> 2140 2141Reads the next image from the ImageReceiver instance. This API uses a promise to return the result. 2142 2143This API can be called to receive data only after the [on](#on) callback is triggered. When the [Image](#image) object returned by this API is no longer needed, call [release](#release-2) to release the object. New data can be received only after the release. 2144 2145**System capability**: SystemCapability.Multimedia.Image.ImageReceiver 2146 2147**Return value** 2148 2149| Type | Description | 2150| ------------------------- | -------------------- | 2151| Promise<[Image](#image)> | Promise used to return the next image.| 2152 2153**Example** 2154 2155```ts 2156import { BusinessError } from '@kit.BasicServicesKit'; 2157import { image } from '@kit.ImageKit'; 2158 2159let size: image.Size = { 2160 height: 8192, 2161 width: 8 2162} 2163let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8); 2164receiver.readNextImage().then((img: image.Image) => { 2165 console.info('readNextImage succeeded.'); 2166}).catch((error: BusinessError) => { 2167 console.error(`readNextImage failed. code ${error.code}, message is ${error.message}`); 2168}) 2169``` 2170 2171### on 2172 2173on(type: 'imageArrival', callback: AsyncCallback\<void>): void 2174 2175Listens for image arrival events. 2176 2177**System capability**: SystemCapability.Multimedia.Image.ImageReceiver 2178 2179**Parameters** 2180 2181| Name | Type | Mandatory| Description | 2182| -------- | -------------------- | ---- | ------------------------------------------------------ | 2183| type | string | Yes | Type of event to listen for. The value is fixed at **'imageArrival'**, which is triggered when an image is received.| 2184| callback | AsyncCallback\<void> | Yes | Callback invoked for the event. | 2185 2186**Example** 2187 2188```ts 2189import { BusinessError } from '@kit.BasicServicesKit'; 2190import { image } from '@kit.ImageKit'; 2191 2192let size: image.Size = { 2193 height: 8192, 2194 width: 8 2195} 2196let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8); 2197receiver.on('imageArrival', () => { 2198 // image arrival, do something. 2199}) 2200``` 2201 2202### release 2203 2204release(): Promise\<void> 2205 2206Releases this ImageReceiver instance. This API uses a promise to return the result. The thread that runs **release** is insecure. 2207 2208**System capability**: SystemCapability.Multimedia.Image.ImageReceiver 2209 2210**Return value** 2211 2212| Type | Description | 2213| -------------- | ------------------ | 2214| Promise\<void> | Promise used to return the result.| 2215 2216**Example** 2217 2218```ts 2219import { BusinessError } from '@kit.BasicServicesKit'; 2220import { image } from '@kit.ImageKit'; 2221 2222let size: image.Size = { 2223 height: 8192, 2224 width: 8 2225} 2226let receiver: sendableImage.ImageReceiver = sendableImage.createImageReceiver(size, image.ImageFormat.JPEG, 8); 2227receiver.release().then(() => { 2228 console.info('release succeeded.'); 2229}).catch((error: BusinessError) => { 2230 console.error(`release failed. code ${error.code}, message is ${error.message}`); 2231}) 2232``` 2233 2234<!--no_check-->
