1# Interface (ImageCreator) 2<!--Kit: Image Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @aulight02--> 5<!--Designer: @liyang_bryan--> 6<!--Tester: @xchaosioda--> 7<!--Adviser: @zengyawen--> 8 9> **说明：** 10> 11> - 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 12> - 本Interface首批接口从API version 9开始支持。 13 14图像创建模块，用于请求图像数据区域，并开放给应用编译图像数据的能力。 15在调用以下方法前需要先通过[createImageCreator](arkts-apis-image-f.md#imagecreateimagecreator11)创建ImageCreator实例，ImageCreator不支持多线程。 16 17## 导入模块 18 19```ts 20import { image } from '@kit.ImageKit'; 21``` 22 23## 属性 24 25**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 26 27| 名称 | 类型 | 只读 | 可选 | 说明 | 28| -------- | ---------------------------- | ---- | ---- | ------------------ | 29| capacity<sup>9+</sup> | number | 是 | 否 | 同时访问的图像数。该参数仅作为期望值，实际capacity由设备硬件决定。 | 30| format<sup>9+</sup> | [ImageFormat](arkts-apis-image-e.md#imageformat9) | 是 | 否 | 图像格式。 | 31 32## dequeueImage<sup>9+</sup> 33 34dequeueImage(callback: AsyncCallback\<Image>): void 35 36从空闲队列中获取buffer图片，用于绘制UI内容，并使用callback返回结果。 37 38**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 39 40**参数：** 41 42| 参数名 | 类型 | 必填 | 说明 | 43| ------------- | ---------------------------------------| ---- | -------------------- | 44| callback | AsyncCallback\<[Image](arkts-apis-image-Image.md)> | 是 | 回调函数，当获取最新图片成功，err为undefined，data为获取到的最新图片；否则为错误对象。 | 45 46**示例：** 47 48```ts 49import { BusinessError } from '@kit.BasicServicesKit'; 50 51async function DequeueImage(creator : image.ImageCreator) { 52 creator.dequeueImage((err: BusinessError, img: image.Image) => { 53 if (err) { 54 console.error(`Failed to dequeue the Image.code ${err.code},message is ${err.message}`); 55 } else { 56 console.info('Succeeded in dequeuing the Image.'); 57 } 58 }); 59} 60``` 61 62## dequeueImage<sup>9+</sup> 63 64dequeueImage(): Promise\<Image> 65 66从空闲队列中获取buffer图片，用于绘制UI内容，并使用promise返回结果。 67 68**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 69 70**返回值：** 71 72| 类型 | 说明 | 73| --------------- | ------------- | 74| Promise\<[Image](arkts-apis-image-Image.md)> | Promise对象，返回最新图片。 | 75 76**示例：** 77 78```ts 79import { BusinessError } from '@kit.BasicServicesKit'; 80 81async function DequeueImage(creator : image.ImageCreator) { 82 creator.dequeueImage().then((img: image.Image) => { 83 console.info('Succeeded in dequeuing the Image.'); 84 }).catch((error: BusinessError) => { 85 console.error(`Failed to dequeue the Image.code ${error.code},message is ${error.message}`); 86 }) 87} 88``` 89 90## queueImage<sup>9+</sup> 91 92queueImage(image: Image, callback: AsyncCallback\<void>): void 93 94将绘制好的图片放入队列，并使用callback返回结果。 95 96**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 97 98**参数：** 99 100| 参数名 | 类型 | 必填 | 说明 | 101| ------------- | -------------------------| ---- | -------------------- | 102| image | [Image](arkts-apis-image-Image.md) | 是 | 绘制好的buffer图像。 | 103| callback | AsyncCallback\<void> | 是 | 回调函数，当将图片放入队列成功，err为undefined，否则为错误对象。 | 104 105**示例：** 106 107```ts 108import { BusinessError } from '@kit.BasicServicesKit'; 109 110async function QueueImage(creator : image.ImageCreator) { 111 creator.dequeueImage().then((img: image.Image) => { 112 // 绘制图片。 113 img.getComponent(4).then((component : image.Component) => { 114 let bufferArr: Uint8Array = new Uint8Array(component.byteBuffer); 115 for (let i = 0; i < bufferArr.length; i += 4) { 116 bufferArr[i] = 0; // B 117 bufferArr[i + 1] = 0; // G 118 bufferArr[i + 2] = 255; // R 119 bufferArr[i + 3] = 255; // A 120 } 121 }) 122 creator.queueImage(img, (err: BusinessError) => { 123 if (err) { 124 console.error(`Failed to queue the Image.code ${err.code},message is ${err.message}`); 125 } else { 126 console.info('Succeeded in queuing the Image.'); 127 } 128 }) 129 }) 130} 131``` 132 133## queueImage<sup>9+</sup> 134 135queueImage(image: Image): Promise\<void> 136 137将绘制好的图片放入队列，并使用promise返回结果。 138 139**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 140 141**参数：** 142 143| 参数名 | 类型 | 必填 | 说明 | 144| ------------- | --------| ---- | ------------------- | 145| image | [Image](arkts-apis-image-Image.md) | 是 | 绘制好的buffer图像。 | 146 147**返回值：** 148 149| 类型 | 说明 | 150| -------------- | ------------- | 151| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 152 153**示例：** 154 155```ts 156import { BusinessError } from '@kit.BasicServicesKit'; 157 158async function QueueImage(creator : image.ImageCreator) { 159 creator.dequeueImage().then((img: image.Image) => { 160 // 绘制图片。 161 img.getComponent(4).then((component: image.Component) => { 162 let bufferArr: Uint8Array = new Uint8Array(component.byteBuffer); 163 for (let i = 0; i < bufferArr.length; i += 4) { 164 bufferArr[i] = 0; // B 165 bufferArr[i + 1] = 0; // G 166 bufferArr[i + 2] = 255; // R 167 bufferArr[i + 3] = 255; // A 168 } 169 }) 170 creator.queueImage(img).then(() => { 171 console.info('Succeeded in queuing the Image.'); 172 }).catch((error: BusinessError) => { 173 console.error(`Failed to queue the Image.code ${error.code},message is ${error.message}`); 174 }) 175 }) 176} 177``` 178 179## on<sup>9+</sup> 180 181on(type: 'imageRelease', callback: AsyncCallback\<void>): void 182 183监听imageRelease事件，并使用callback返回结果。 184 185**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 186 187**参数：** 188 189| 参数名 | 类型 | 必填 | 说明 | 190| ------------- | -------------------------| ---- | -------------------- | 191| type | string | 是 | 监听事件类型，如'imageRelease'。 | 192| callback | AsyncCallback\<void> | 是 | 回调函数，当监听事件触发成功，err为undefined，否则为错误对象。 | 193 194**示例：** 195 196```ts 197import { BusinessError } from '@kit.BasicServicesKit'; 198 199async function On(creator : image.ImageCreator) { 200 creator.on('imageRelease', (err: BusinessError) => { 201 if (err) { 202 console.error(`Failed to get the imageRelease callback.code ${err.code},message is ${err.message}`); 203 } else { 204 console.info('Succeeded in getting imageRelease callback.'); 205 } 206 }) 207} 208``` 209 210## off<sup>13+</sup> 211 212off(type: 'imageRelease', callback?: AsyncCallback\<void>): void 213 214释放buffer时，移除注册的回调函数。 215 216**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 217 218**参数：** 219 220| 参数名 | 类型 | 必填 | 说明 | 221| ------------- | -------------------------|----|--------------------------------------------| 222| type | string | 是 | 监听事件类型，如'imageRelease'。 | 223| callback | AsyncCallback\<void> | 否 | 将被移除的回调函数。 | 224 225**示例：** 226 227```ts 228async function Off(creator : image.ImageCreator) { 229 let callbackFunc = ()=>{ 230 // 实现回调函数逻辑。 231 } 232 creator.on('imageRelease', callbackFunc) 233 creator.off('imageRelease', callbackFunc) 234} 235``` 236 237## release<sup>9+</sup> 238 239release(callback: AsyncCallback\<void>): void 240 241释放当前图像，并使用callback返回结果。 242 243ArkTS有内存回收机制，ImageCreator对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 244 245**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 246 247**参数：** 248 249| 参数名 | 类型 | 必填 | 说明 | 250| ------------- | -------------------------| ---- | -------------------- | 251| callback | AsyncCallback\<void> | 是 | 回调函数，当图像释放成功，err为undefined，否则为错误对象。 | 252 253**示例：** 254 255```ts 256import { BusinessError } from '@kit.BasicServicesKit'; 257 258async function Release(creator : image.ImageCreator) { 259 creator.release((err: BusinessError) => { 260 if (err) { 261 console.error(`Failed to release the creator.code ${err.code},message is ${err.message}`); 262 } else { 263 console.info('Succeeded in releasing creator.'); 264 } 265 }); 266} 267``` 268 269## release<sup>9+</sup> 270 271release(): Promise\<void> 272 273释放当前图像，并使用promise返回结果。 274 275ArkTS有内存回收机制，ImageCreator对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 276 277**系统能力：** SystemCapability.Multimedia.Image.ImageCreator 278 279**返回值：** 280 281| 类型 | 说明 | 282| -------------- | ------------- | 283| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 284 285**示例：** 286 287```ts 288import { BusinessError } from '@kit.BasicServicesKit'; 289 290async function Release(creator : image.ImageCreator) { 291 creator.release().then(() => { 292 console.info('Succeeded in releasing creator.'); 293 }).catch((error: BusinessError) => { 294 console.error(`Failed to release the creator.code ${error.code},message is ${error.message}`); 295 }) 296} 297``` 298