1# Interface (ImageCreator) 2<!--Kit: Image Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @aulight02--> 5<!--SE: @liyang_bryan--> 6<!--TSE: @xchaosioda--> 7 8> **NOTE** 9> 10> - The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. 11> - The initial APIs of this interface are supported since API version 9. 12 13The **ImageCreator** class provides APIs for applications to request an image data area and compile image data. 14 15Before calling any APIs in ImageCreator, you must create an ImageCreator instance. ImageCreator does not support multiple threads. 16 17## Modules to Import 18 19```ts 20import { image } from '@kit.ImageKit'; 21``` 22 23## Properties 24 25**System capability**: SystemCapability.Multimedia.Image.ImageCreator 26 27| Name | Type | Read Only| Optional| Description | 28| -------- | ---------------------------- | ---- | ---- | ------------------ | 29| capacity<sup>9+</sup> | number | Yes | No | Maximum number of images that can be accessed at the same time.| 30| format<sup>9+</sup> | [ImageFormat](arkts-apis-image-e.md#imageformat9) | Yes | No | Image format. | 31 32## dequeueImage<sup>9+</sup> 33 34dequeueImage(callback: AsyncCallback\<Image>): void 35 36Obtains an image buffer from the idle queue and writes image data into it. This API uses an asynchronous callback to return the result. 37 38**System capability**: SystemCapability.Multimedia.Image.ImageCreator 39 40**Parameters** 41 42| Name | Type | Mandatory| Description | 43| ------------- | ---------------------------------------| ---- | -------------------- | 44| callback | AsyncCallback\<[Image](arkts-apis-image-Image.md)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the latest image obtained; otherwise, **err** is an error object. | 45 46**Example** 47 48```ts 49import { BusinessError } from '@kit.BasicServicesKit'; 50 51creator.dequeueImage((err: BusinessError, img: image.Image) => { 52 if (err) { 53 console.error(`Failed to dequeue the Image.code ${err.code},message is ${err.message}`); 54 } else { 55 console.info('Succeeded in dequeuing the Image.'); 56 } 57}); 58``` 59 60## dequeueImage<sup>9+</sup> 61 62dequeueImage(): Promise\<Image> 63 64Obtains an image buffer from the idle queue and writes image data into it. This API uses a promise to return the result. 65 66**System capability**: SystemCapability.Multimedia.Image.ImageCreator 67 68**Return value** 69 70| Type | Description | 71| --------------- | ------------- | 72| Promise\<[Image](arkts-apis-image-Image.md)> | Promise used to return the latest image.| 73 74**Example** 75 76```ts 77import { BusinessError } from '@kit.BasicServicesKit'; 78 79creator.dequeueImage().then((img: image.Image) => { 80 console.info('Succeeded in dequeuing the Image.'); 81}).catch((error: BusinessError) => { 82 console.error(`Failed to dequeue the Image.code ${error.code},message is ${error.message}`); 83}) 84``` 85 86## queueImage<sup>9+</sup> 87 88queueImage(interface: Image, callback: AsyncCallback\<void>): void 89 90Places the drawn image in the queue. This API uses an asynchronous callback to return the result. 91 92**System capability**: SystemCapability.Multimedia.Image.ImageCreator 93 94**Parameters** 95 96| Name | Type | Mandatory| Description | 97| ------------- | -------------------------| ---- | -------------------- | 98| interface | [Image](arkts-apis-image-Image.md) | Yes | Drawn image.| 99| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object. | 100 101**Example** 102 103```ts 104import { BusinessError } from '@kit.BasicServicesKit'; 105 106creator.dequeueImage().then((img: image.Image) => { 107 // Draw the image. 108 img.getComponent(4).then((component : image.Component) => { 109 let bufferArr: Uint8Array = new Uint8Array(component.byteBuffer); 110 for (let i = 0; i < bufferArr.length; i += 4) { 111 bufferArr[i] = 0; //B 112 bufferArr[i + 1] = 0; //G 113 bufferArr[i + 2] = 255; //R 114 bufferArr[i + 3] = 255; //A 115 } 116 }) 117 creator.queueImage(img, (err: BusinessError) => { 118 if (err) { 119 console.error(`Failed to queue the Image.code ${err.code},message is ${err.message}`); 120 } else { 121 console.info('Succeeded in queuing the Image.'); 122 } 123 }) 124}) 125``` 126 127## queueImage<sup>9+</sup> 128 129queueImage(interface: Image): Promise\<void> 130 131Places the drawn image in the queue. This API uses a promise to return the result. 132 133**System capability**: SystemCapability.Multimedia.Image.ImageCreator 134 135**Parameters** 136 137| Name | Type | Mandatory| Description | 138| ------------- | --------| ---- | ------------------- | 139| interface | [Image](arkts-apis-image-Image.md) | Yes | Drawn image.| 140 141**Return value** 142 143| Type | Description | 144| -------------- | ------------- | 145| Promise\<void> | Promise that returns no value.| 146 147**Example** 148 149```ts 150import { BusinessError } from '@kit.BasicServicesKit'; 151 152creator.dequeueImage().then((img: image.Image) => { 153 // Draw the image. 154 img.getComponent(4).then((component: image.Component) => { 155 let bufferArr: Uint8Array = new Uint8Array(component.byteBuffer); 156 for (let i = 0; i < bufferArr.length; i += 4) { 157 bufferArr[i] = 0; //B 158 bufferArr[i + 1] = 0; //G 159 bufferArr[i + 2] = 255; //R 160 bufferArr[i + 3] = 255; //A 161 } 162 }) 163 creator.queueImage(img).then(() => { 164 console.info('Succeeded in queuing the Image.'); 165 }).catch((error: BusinessError) => { 166 console.error(`Failed to queue the Image.code ${error.code},message is ${error.message}`); 167 }) 168}) 169 170``` 171 172## on<sup>9+</sup> 173 174on(type: 'imageRelease', callback: AsyncCallback\<void>): void 175 176Listens for image release events. This API uses an asynchronous callback to return the result. 177 178**System capability**: SystemCapability.Multimedia.Image.ImageCreator 179 180**Parameters** 181 182| Name | Type | Mandatory| Description | 183| ------------- | -------------------------| ---- | -------------------- | 184| type | string | Yes | Type of event, which is **'imageRelease'**.| 185| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object. | 186 187**Example** 188 189```ts 190import { BusinessError } from '@kit.BasicServicesKit'; 191 192creator.on('imageRelease', (err: BusinessError) => { 193 if (err) { 194 console.error(`Failed to get the imageRelease callback.code ${err.code},message is ${err.message}`); 195 } else { 196 console.info('Succeeded in getting imageRelease callback.'); 197 } 198}) 199``` 200 201## off<sup>13+</sup> 202 203off(type: 'imageRelease', callback?: AsyncCallback\<void>): void 204 205Unregisters the callback function that is triggered when the buffer is released. 206 207**System capability**: SystemCapability.Multimedia.Image.ImageCreator 208 209**Parameters** 210 211| Name | Type | Mandatory| Description | 212| ------------- | -------------------------|----|--------------------------------------------| 213| type | string | Yes | Type of event, which is **'imageRelease'**. | 214| callback | AsyncCallback\<void> | No | Callback to unregister.| 215 216**Example** 217 218```ts 219let callbackFunc = ()=>{ 220 // do something. 221} 222creator.on('imageRelease', callbackFunc) 223creator.off('imageRelease', callbackFunc) 224``` 225 226## release<sup>9+</sup> 227 228release(callback: AsyncCallback\<void>): void 229 230Releases this ImageCreator instance. This API uses an asynchronous callback to return the result. 231 232ArkTS supports memory reclamation. Even if the application does not call **release()**, the memory of the ImageCreator object will be released by the system. However, images usually occupy a large amount of memory. Therefore, it is recommended that the application proactively call the API to release the memory when the object is no longer required. 233 234**System capability**: SystemCapability.Multimedia.Image.ImageCreator 235 236**Parameters** 237 238| Name | Type | Mandatory| Description | 239| ------------- | -------------------------| ---- | -------------------- | 240| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 241 242**Example** 243 244```ts 245import { BusinessError } from '@kit.BasicServicesKit'; 246 247creator.release((err: BusinessError) => { 248 if (err) { 249 console.error(`Failed to release the creator.code ${err.code},message is ${err.message}`); 250 } else { 251 console.info('Succeeded in releasing creator.'); 252 } 253}); 254``` 255 256## release<sup>9+</sup> 257 258release(): Promise\<void> 259 260Releases this ImageCreator instance. This API uses a promise to return the result. 261 262ArkTS supports memory reclamation. Even if the application does not call **release()**, the memory of the ImageCreator object will be released by the system. However, images usually occupy a large amount of memory. Therefore, it is recommended that the application proactively call the API to release the memory when the object is no longer required. 263 264**System capability**: SystemCapability.Multimedia.Image.ImageCreator 265 266**Return value** 267 268| Type | Description | 269| -------------- | ------------- | 270| Promise\<void> | Promise that returns no value.| 271 272**Example** 273 274```ts 275import { BusinessError } from '@kit.BasicServicesKit'; 276 277creator.release().then(() => { 278 console.info('Succeeded in releasing creator.'); 279}).catch((error: BusinessError) => { 280 console.error(`Failed to release the creator.code ${error.code},message is ${error.message}`); 281}) 282``` 283