Interface (ImageCreator)

The ImageCreator class, acting as an image producer, is used for writing images into a surface.

Before calling any APIs in ImageCreator, you must use image.createImageCreator to create an ImageCreator instance. ImageCreator does not support multiple threads.

Images occupy a large amount of memory. When you finish using an ImageCreator instance, call release to free the memory promptly. Before releasing the instance, ensure that all asynchronous operations associated with the instance have finished and the instance is no longer needed.

NOTE

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.

The initial APIs of this interface are supported since API version 9.

Modules to Import

import { image } from '@kit.ImageKit';

Properties

System capability: SystemCapability.Multimedia.Image.ImageCreator

Name	Type	Read Only	Optional	Description
capacity⁹⁺	number	Yes	No	Maximum number of images that can be accessed at the same time. This parameter is used only as an expected value. The actual capacity is determined by the device hardware.
format⁹⁺	ImageFormat	Yes	No	Image format.

dequeueImage⁹⁺

dequeueImage(callback: AsyncCallback<Image>): void

Obtains an image buffer from the idle queue and writes image data into it. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.Image.ImageCreator

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<Image>	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.

Example

import { BusinessError } from '@kit.BasicServicesKit';

async function DequeueImage(creator : image.ImageCreator) {
  creator.dequeueImage((err: BusinessError, img: image.Image) => {
    if (err) {
      console.error(`Failed to dequeue the Image.code ${err.code},message is ${err.message}`);
    } else {
      console.info('Succeeded in dequeuing the Image.');
    }
  });
}

dequeueImage⁹⁺

dequeueImage(): Promise<Image>

Obtains an image buffer from the idle queue and writes image data into it. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Image.ImageCreator

Return value

Type	Description
Promise<Image>	Promise used to return the latest image.

Example

import { BusinessError } from '@kit.BasicServicesKit';

async function DequeueImage(creator : image.ImageCreator) {
  creator.dequeueImage().then((img: image.Image) => {
    console.info('Succeeded in dequeuing the Image.');
  }).catch((error: BusinessError) => {
    console.error(`Failed to dequeue the Image.code ${error.code},message is ${error.message}`);
  })
}

queueImage⁹⁺

queueImage(image: Image, callback: AsyncCallback<void>): void

Places the drawn image in the queue. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.Image.ImageCreator

Parameters

Name	Type	Mandatory	Description
image	Image	Yes	Drawn image.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined; otherwise, err is an error object.

Example

import { BusinessError } from '@kit.BasicServicesKit';

async function QueueImage(creator : image.ImageCreator) {
  creator.dequeueImage().then((img: image.Image) => {
    // Draw the image.
    img.getComponent(4).then((component : image.Component) => {
      let bufferArr: Uint8Array = new Uint8Array(component.byteBuffer);
      for (let i = 0; i < bufferArr.length; i += 4) {
        bufferArr[i] = 0; // B
        bufferArr[i + 1] = 0; // G
        bufferArr[i + 2] = 255; // R
        bufferArr[i + 3] = 255; // A
      }
    })
    creator.queueImage(img, (err: BusinessError) => {
      if (err) {
        console.error(`Failed to queue the Image.code ${err.code},message is ${err.message}`);
      } else {
        console.info('Succeeded in queuing the Image.');
      }
    })
  })
}

queueImage⁹⁺

queueImage(image: Image): Promise<void>

Places the drawn image in the queue. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Image.ImageCreator

Parameters

Name	Type	Mandatory	Description
image	Image	Yes	Drawn image.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

import { BusinessError } from '@kit.BasicServicesKit';

async function QueueImage(creator : image.ImageCreator) {
  creator.dequeueImage().then((img: image.Image) => {
    // Draw the image.
    img.getComponent(4).then((component: image.Component) => {
      let bufferArr: Uint8Array = new Uint8Array(component.byteBuffer);
      for (let i = 0; i < bufferArr.length; i += 4) {
        bufferArr[i] = 0; // B
        bufferArr[i + 1] = 0; // G
        bufferArr[i + 2] = 255; // R
        bufferArr[i + 3] = 255; // A
      }
    })
    creator.queueImage(img).then(() => {
      console.info('Succeeded in queuing the Image.');
    }).catch((error: BusinessError) => {
      console.error(`Failed to queue the Image.code ${error.code},message is ${error.message}`);
    })
  })
}

on⁹⁺

on(type: 'imageRelease', callback: AsyncCallback<void>): void

Listens for image release events. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.Image.ImageCreator

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Type of event, which is 'imageRelease'.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined; otherwise, err is an error object.

Example

import { BusinessError } from '@kit.BasicServicesKit';

async function On(creator : image.ImageCreator) {
  creator.on('imageRelease', (err: BusinessError) => {
    if (err) {
      console.error(`Failed to get the imageRelease callback.code ${err.code},message is ${err.message}`);
    } else {
      console.info('Succeeded in getting imageRelease callback.');
    }
  })
}

off¹³⁺

off(type: 'imageRelease', callback?: AsyncCallback<void>): void

Unregisters the callback function that is triggered when the buffer is released. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.Image.ImageCreator

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Type of event, which is 'imageRelease'.
callback	AsyncCallback<void>	No	Callback used to return the result. If the operation is successful, err is null; otherwise, err is an error object.

Example

async function Off(creator : image.ImageCreator) {
  let callbackFunc = ()=>{
      // Implement the callback logic.
  }
  creator.on('imageRelease', callbackFunc)
  creator.off('imageRelease', callbackFunc)
}

release⁹⁺

release(callback: AsyncCallback<void>): void

Releases this ImageCreator instance. This API uses an asynchronous callback to return the result.

Images occupy a large amount of memory. When you finish using an ImageCreator instance, call this API to free the memory promptly.

Before releasing the instance, ensure that all asynchronous operations associated with the instance have finished and the instance is no longer needed.

System capability: SystemCapability.Multimedia.Image.ImageCreator

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined; otherwise, err is an error object.

Example

import { BusinessError } from '@kit.BasicServicesKit';

async function Release(creator : image.ImageCreator) {
  creator.release((err: BusinessError) => {
    if (err) {
      console.error(`Failed to release the creator.code ${err.code},message is ${err.message}`);
    } else {
      console.info('Succeeded in releasing creator.');
    }
  });
}

release⁹⁺

release(): Promise<void>

Releases this ImageCreator instance. This API uses a promise to return the result.

Images occupy a large amount of memory. When you finish using an ImageCreator instance, call this API to free the memory promptly.

Before releasing the instance, ensure that all asynchronous operations associated with the instance have finished and the instance is no longer needed.

System capability: SystemCapability.Multimedia.Image.ImageCreator

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

import { BusinessError } from '@kit.BasicServicesKit';

async function Release(creator : image.ImageCreator) {
  creator.release().then(() => {
    console.info('Succeeded in releasing creator.');
  }).catch((error: BusinessError) => {
    console.error(`Failed to release the creator.code ${error.code},message is ${error.message}`);
  })
}