Interface (PixelMap)

The PixelMap class provides APIs to read or write image data and obtain image information. Before calling any API in PixelMap, you must use image.createPixelMap 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 × Bytes per pixel.

Since API version 11, PixelMap supports cross-thread calls through Worker. If a PixelMap object is invoked by another thread through Worker, all APIs of the PixelMap object cannot be called in the original thread. Otherwise, error 501 is reported, indicating that the server cannot complete the request.

Before calling any API in PixelMap, you can use image.createPixelMap to pass pixel data to create a PixelMap object, or use ImageSource to decode an image to a PixelMap object.

To develop an atomic service, use ImageSource to create a PixelMap object.

Images occupy a large amount of memory. When you finish using a PixelMap 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 7.

Modules to Import

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

Properties

System capability: SystemCapability.Multimedia.Image.Core

Name	Type	Read Only	Optional	Description
isEditable7+	boolean	Yes	No	Whether the image pixels are editable. true if editable, false otherwise. The value false provides better image rendering and transmission performance. Atomic service API: This API can be used in atomic services since API version 11. Widget capability: This API can be used in ArkTS widgets since API version 12.
isStrideAlignment11+	boolean	Yes	No	Whether the row data of the image is memory aligned. The value true means that the row data is memory-aligned, and there may be blank bytes padded at the end of each row to meet alignment requirements. The value false means that the row data is not memory-aligned, and rows are packed contiguously with no padding bytes at the end.

readPixelsToBuffer⁷⁺

readPixelsToBuffer(dst: ArrayBuffer): Promise<void>

Reads the pixels of this PixelMap object based on the PixelMap's pixel format and writes the data to the buffer. This API uses a promise to return the result.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
dst	ArrayBuffer	Yes	Buffer to which the pixels will be written. The buffer size is obtained by calling getPixelBytesNumber.

Return value

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

Example

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

async function ReadPixelsToBuffer(pixelMap : image.PixelMap) {
  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.
  if (pixelMap != undefined) {
    pixelMap.readPixelsToBuffer(readBuffer).then(() => {
      console.info('Succeeded in reading image pixel data.'); // Called if the condition is met.
    }).catch((error: BusinessError) => {
      console.error(`Failed to read image pixel data. code is ${error.code}, message is ${error.message}`); // Called if no condition is met.
    })
  }
}

readPixelsToBuffer⁷⁺

readPixelsToBuffer(dst: ArrayBuffer, callback: AsyncCallback<void>): void

Reads the pixels of this PixelMap object based on the PixelMap's pixel format and writes the data to the buffer. This API uses an asynchronous callback to return the result.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
dst	ArrayBuffer	Yes	Buffer to which the pixels will be written. The buffer size is obtained by calling getPixelBytesNumber.
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 ReadPixelsToBuffer(pixelMap : image.PixelMap) {
  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.
  if (pixelMap != undefined) {
    pixelMap.readPixelsToBuffer(readBuffer, (error: BusinessError, res: void) => {
      if(error) {
        console.error(`Failed to read image pixel data. code is ${error.code}, message is ${error.message}`); // Called if no condition is met.
        return;
      } else {
        console.info('Succeeded in reading image pixel data.'); // Called if the condition is met.
      }
    })
  }
}

readPixelsToBufferSync¹²⁺

readPixelsToBufferSync(dst: ArrayBuffer): void

Reads the pixels of this PixelMap object based on the PixelMap's pixel format and writes the data to the buffer. This API returns the result synchronously.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
dst	ArrayBuffer	Yes	Buffer to which the pixels will be written. The buffer size is obtained by calling getPixelBytesNumber.

Error codes

For details about the error codes, see Universal Error Codes and Image Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed
501	Resource Unavailable

Example

function ReadPixelsToBufferSync(pixelMap : image.PixelMap) {
  const bufferSize = pixelMap.getPixelBytesNumber();
  const readBuffer = new ArrayBuffer(bufferSize);
  if (pixelMap != undefined) {
    pixelMap.readPixelsToBufferSync(readBuffer);
  }
}

readPixels⁷⁺

readPixels(area: PositionArea): Promise<void>

Reads the pixels in the area specified by PositionArea.region of this PixelMap object in the BGRA_8888 format and writes the data to the PositionArea.pixels buffer. This API uses a promise to return the result.

You can use a formula to calculate the size of the memory to be applied for based on PositionArea.

YUV region calculation formula: region to read (region.size{width * height}) * 1.5 (1 * Y component + 0.25 * U component + 0.25 * V component)

RGBA region calculation formula: region to read (region.size{width * height}) * 4 (1 * R component + 1 * G component + 1 * B component + 1 * A component)

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
area	PositionArea	Yes	Area from which the pixels will be read.

Return value

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

Example

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

async function ReadPixelsRGBA(pixelMap : image.PixelMap) {
  const area: image.PositionArea = {
    pixels: new ArrayBuffer(8), // 8 is the size of the PixelMap buffer to create. The value is calculated as follows: height * width * 4.
    offset: 0,
    stride: 8,
    region: { size: { height: 1, width: 2 }, x: 0, y: 0 }
  };
  if (pixelMap != undefined) {
    pixelMap.readPixels(area).then(() => {
      console.info('Succeeded in reading the image data in the area.'); // Called if the condition is met.
      console.info('RGBA data is ', new Uint8Array(area.pixels));
    }).catch((error: BusinessError) => {
      console.error("Failed to read the image data in the area. code is ", error);// Called if the condition is not met.
    })
  }
}

async function ReadPixelsYUV(pixelMap : image.PixelMap) {
  const area: image.PositionArea = {
    pixels: new ArrayBuffer(6),  // 6 is the size of the PixelMap buffer to create. The value is calculated as follows: height * width * 1.5.
    offset: 0,
    stride: 8,
    region: { size: { height: 2, width: 2 }, x: 0, y: 0 }
  };
  if (pixelMap != undefined) {
    pixelMap.readPixels(area).then(() => {
      console.info('Succeeded in reading the image data in the area.'); // Called if the condition is met.
      console.info('YUV data is ', new Uint8Array(area.pixels));
    }).catch((error: BusinessError) => {
      console.error("Failed to read the image data in the area. code is ", error);// Called if the condition is not met.
    })
  }
}

readPixels⁷⁺

readPixels(area: PositionArea, callback: AsyncCallback<void>): void

Reads the pixels in the area specified by PositionArea.region of this PixelMap object in the BGRA_8888 format and writes the data to the PositionArea.pixels buffer. This API uses an asynchronous callback to return the result.

You can use a formula to calculate the size of the memory to be applied for based on PositionArea.

YUV region calculation formula: region to read (region.size{width * height}) * 1.5 (1 * Y component + 0.25 * U component + 0.25 * V component)

RGBA region calculation formula: region to read (region.size{width * height}) * 4 (1 * R component + 1 * G component + 1 * B component + 1 * A component)

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
area	PositionArea	Yes	Area from which the pixels will be read.
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 ReadPixelsRGBA(pixelMap : image.PixelMap) {
  const area: image.PositionArea = {
    pixels: new ArrayBuffer(8), // 8 is the size of the PixelMap buffer to create. The value is calculated as follows: height * width * 4.
    offset: 0,
    stride: 8,
    region: { size: { height: 1, width: 2 }, x: 0, y: 0 }
  };
  if (pixelMap != undefined) {
    pixelMap.readPixels(area, (error: BusinessError) => {
      if (error) {
        console.error("Failed to read pixelmap from the specified area. code is ", error);
        return;
      } else {
        console.info('Succeeded in reading pixelmap from the specified area.');
        console.info('RGBA data is ', new Uint8Array(area.pixels));
      }
    })
  }
}

async function ReadPixelsYUV(pixelMap : image.PixelMap) {
  const area: image.PositionArea = {
    pixels: new ArrayBuffer(6),  // 6 is the size of the PixelMap buffer to create. The value is calculated as follows: height * width * 1.5.
    offset: 0,
    stride: 8,
    region: { size: { height: 2, width: 2 }, x: 0, y: 0 }
  };
  if (pixelMap != undefined) {
    pixelMap.readPixels(area, (error: BusinessError) => {
      if (error) {
        console.error("Failed to read pixelmap from the specified area. code is ", error);
        return;
      } else {
        console.info('Succeeded in reading pixelmap from the specified area.');
        console.info('YUV data is ', new Uint8Array(area.pixels));
      }
    })
  }
}

readPixelsSync¹²⁺

readPixelsSync(area: PositionArea): void

Reads the pixels in the area specified by PositionArea.region of this PixelMap object in the BGRA_8888 format and writes the data to the PositionArea.pixels buffer. This API returns the result synchronously.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
area	PositionArea	Yes	Area from which the pixels will be read.

Error codes

For details about the error codes, see Universal Error Codes and Image Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed
501	Resource Unavailable

Example

function ReadPixelsSync(pixelMap : image.PixelMap) {
  const area : image.PositionArea = {
    pixels: new ArrayBuffer(8),
    offset: 0,
    stride: 8,
    region: { size: { height: 1, width: 2 }, x: 0, y: 0 }
  };
  if (pixelMap != undefined) {
    pixelMap.readPixelsSync(area);
  }
}

writePixels⁷⁺

writePixels(area: PositionArea): Promise<void>

Reads the pixels in the PositionArea.region buffer in the BGRA_8888 format and writes the data to the area specified by PositionArea.pixels in this PixelMap object. This API uses a promise to return the result.

You can use a formula to calculate the size of the memory to be applied for based on PositionArea.

YUV region calculation formula: region to read (region.size{width * height}) * 1.5 (1 * Y component + 0.25 * U component + 0.25 * V component)

RGBA region calculation formula: region to read (region.size{width * height}) * 4 (1 * R component + 1 * G component + 1 * B component + 1 * A component)

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
area	PositionArea	Yes	Area to which the pixels will be written.

Return value

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

Example

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

async function WritePixelsRGBA(pixelMap:image.PixelMap) {
  const area: image.PositionArea = {
    pixels: new ArrayBuffer(8), // 8 is the size of the PixelMap buffer to create. The value is calculated as follows: height * width * 4.
    offset: 0,
    stride: 8,
    region: { size: { height: 1, width: 2 }, x: 0, y: 0 }
  };
  let bufferArr: Uint8Array = new Uint8Array(area.pixels);
  for (let i = 0; i < bufferArr.length; i++) {
    bufferArr[i] = i + 1;
  }
  if (pixelMap != undefined) {
    pixelMap.writePixels(area).then(() => {
      console.info('Succeeded in writing pixelmap into the specified area.');
    }).catch((error: BusinessError) => {
      console.error("Failed to write pixelmap into the specified area. code is ", error);
    })
  }
}

async function WritePixelsYUV(pixelMap:image.PixelMap) {
  const area: image.PositionArea = {
    pixels: new ArrayBuffer(6),  // 6 is the size of the PixelMap buffer to create. The value is calculated as follows: height * width * 1.5.
    offset: 0,
    stride: 8, // This variable is not used by writePixels when the PixelMap is in YUV format.
    region: { size: { height: 2, width: 2 }, x: 0, y: 0 }
  };
  let bufferArr: Uint8Array = new Uint8Array(area.pixels);
  for (let i = 0; i < bufferArr.length; i++) {
    bufferArr[i] = i + 1;
  }
  if (pixelMap != undefined) {
    pixelMap.writePixels(area).then(() => {
      console.info('Succeeded in writing pixelmap into the specified area.');
    }).catch((error: BusinessError) => {
      console.error("Failed to write pixelmap into the specified area. code is ", error);
    })
  }
}

writePixels⁷⁺

writePixels(area: PositionArea, callback: AsyncCallback<void>): void

Reads the pixels in the PositionArea.region buffer in the BGRA_8888 format and writes the data to the area specified by PositionArea.pixels in this PixelMap object. This API uses an asynchronous callback to return the result.

You can use a formula to calculate the size of the memory to be applied for based on PositionArea.

YUV region calculation formula: region to read (region.size{width * height}) * 1.5 (1 * Y component + 0.25 * U component + 0.25 * V component)

RGBA region calculation formula: region to read (region.size{width * height}) * 4 (1 * R component + 1 * G component + 1 * B component + 1 * A component)

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
area	PositionArea	Yes	Area to which the pixels will be written.
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 WritePixelsRGBA(pixelMap:image.PixelMap) {
  const area: image.PositionArea = { pixels: new ArrayBuffer(8), // 8 is the size of the PixelMap buffer to create. The value is calculated as follows: height * width * 4.
    offset: 0,
    stride: 8,
    region: { size: { height: 1, width: 2 }, x: 0, y: 0 }
  };
  let bufferArr: Uint8Array = new Uint8Array(area.pixels);
  for (let i = 0; i < bufferArr.length; i++) {
    bufferArr[i] = i + 1;
  }
  if (pixelMap != undefined) {
    pixelMap.writePixels(area, (error : BusinessError) => {
      if (error) {
        console.error("Failed to write pixelmap into the specified area. code is ", error);
        return;
      } else {
        console.info('Succeeded in writing pixelmap into the specified area.');
      }
    })
  }
}

async function WritePixelsYUV(pixelMap:image.PixelMap) {
  const area: image.PositionArea = { pixels: new ArrayBuffer(6), // 6 is the size of the PixelMap buffer to create. The value is calculated as follows: height * width * 1.5.
    offset: 0,
    stride: 8, // This variable is not used by writePixels when the PixelMap is in YUV format.
    region: { size: { height: 2, width: 2 }, x: 0, y: 0 }
  };
  let bufferArr: Uint8Array = new Uint8Array(area.pixels);
  for (let i = 0; i < bufferArr.length; i++) {
    bufferArr[i] = i + 1;
  }
  if (pixelMap != undefined) {
    pixelMap.writePixels(area, (error : BusinessError) => {
      if (error) {
        console.error("Failed to write pixelmap into the specified area. code is ", error);
        return;
      } else {
        console.info('Succeeded in writing pixelmap into the specified area.');
      }
    })
  }
}

writePixelsSync¹²⁺

writePixelsSync(area: PositionArea): void

Reads the pixels in the PositionArea.region buffer in the BGRA_8888 format and writes the data to the area specified by PositionArea.pixels in this PixelMap object. This API returns the result synchronously.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
area	PositionArea	Yes	Area to which the pixels will be written.

Error codes

For details about the error codes, see Universal Error Codes and Image Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed
501	Resource Unavailable

Example

function WritePixelsSync(pixelMap:image.PixelMap) {
  const area: image.PositionArea = {
    pixels: new ArrayBuffer(8),
    offset: 0,
    stride: 8,
    region: { size: { height: 1, width: 2 }, x: 0, y: 0 }
  };
  let bufferArr: Uint8Array = new Uint8Array(area.pixels);
  for (let i = 0; i < bufferArr.length; i++) {
    bufferArr[i] = i + 1;
  }
  if (pixelMap != undefined) {
    pixelMap.writePixelsSync(area);
  }
}

writeBufferToPixels⁷⁺

writeBufferToPixels(src: ArrayBuffer): Promise<void>

Reads the pixels in the buffer based on the PixelMap's pixel format and writes the data to this PixelMap object. This API uses a promise to return the result.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
src	ArrayBuffer	Yes	Buffer from which the pixels are read. The buffer size is obtained by calling getPixelBytesNumber.

Return value

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

Example

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

async function WriteBufferToPixels(pixelMap:image.PixelMap) {
  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.
  let bufferArr: Uint8Array = new Uint8Array(color);
  for (let i = 0; i < bufferArr.length; i++) {
    bufferArr[i] = i + 1;
  }
  if (pixelMap != undefined) {
    pixelMap.writeBufferToPixels(color).then(() => {
      console.info("Succeeded in writing data from a buffer to a PixelMap.");
    }).catch((error: BusinessError) => {
      console.error(`Failed to write data from a buffer to a PixelMap. code is ${error.code}, message is ${error.message}`);
    })
  }
}

writeBufferToPixels⁷⁺

writeBufferToPixels(src: ArrayBuffer, callback: AsyncCallback<void>): void

Reads the pixels in the buffer based on the PixelMap's pixel format and writes the data to this PixelMap object. This API uses an asynchronous callback to return the result.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
src	ArrayBuffer	Yes	Buffer from which the pixels are read. The buffer size is obtained by calling getPixelBytesNumber.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the pixels in the buffer are successfully written to the PixelMap, err is undefined; otherwise, err is an error object.

Example

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

async function WriteBufferToPixels(pixelMap:image.PixelMap) {
  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.
  let bufferArr: Uint8Array = new Uint8Array(color);
  for (let i = 0; i < bufferArr.length; i++) {
    bufferArr[i] = i + 1;
  }
  if (pixelMap != undefined) {
    pixelMap.writeBufferToPixels(color, (error: BusinessError) => {
      if (error) {
        console.error(`Failed to write data from a buffer to a PixelMap. code is ${error.code}, message is ${error.message}`);
        return;
      } else {
        console.info("Succeeded in writing data from a buffer to a PixelMap.");
      }
    })
  }
}

writeBufferToPixelsSync¹²⁺

writeBufferToPixelsSync(src: ArrayBuffer): void

Reads the pixels in the buffer based on the PixelMap's pixel format and writes the data to this PixelMap object. This API returns the result synchronously.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
src	ArrayBuffer	Yes	Buffer from which the pixels are read. The buffer size is obtained by calling getPixelBytesNumber.

Error codes

For details about the error codes, see Universal Error Codes and Image Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed
501	Resource Unavailable

Example

function WriteBufferToPixelsSync(pixelMap:image.PixelMap) {
  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.
  let bufferArr : Uint8Array = new Uint8Array(color);
  for (let i = 0; i < bufferArr.length; i++) {
    bufferArr[i] = i + 1;
  }
  if (pixelMap != undefined) {
    pixelMap.writeBufferToPixelsSync(color);
  }
}

getImageInfo⁷⁺

getImageInfo(): Promise<ImageInfo>

Obtains the image information of a PixelMap. This API uses a promise to return the result.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Return value

Type	Description
Promise<ImageInfo>	Promise used to return the image information.

Example

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

async function GetImageInfo(pixelMap: image.PixelMap) {
  if (pixelMap != undefined) {
    pixelMap.getImageInfo().then((imageInfo: image.ImageInfo) => {
      if (imageInfo != undefined) {
        console.info(`Succeeded in obtaining the image pixel map information ${imageInfo.size.height}`);
      }
    }).catch((error: BusinessError) => {
      console.error(`Failed to obtain the image pixel map information. code is ${error.code}, message is ${error.message}`);
    })
  }
}

getImageInfo⁷⁺

getImageInfo(callback: AsyncCallback<ImageInfo>): void

Obtains the image information. This API uses an asynchronous callback to return the result.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

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

Example

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

function GetImageInfoSync(pixelMap : image.PixelMap){
  if (pixelMap != undefined) {
    pixelMap.getImageInfo((error: BusinessError, imageInfo: image.ImageInfo) => {
      if (error) {
        console.error(`Failed to obtain the image pixel map information. code is ${error.code}, message is ${error.message}`);
        return;
      } else {
        console.info(`Succeeded in obtaining the image pixel map information ${imageInfo.size.height}`);
      }
    })
  }
}

getImageInfoSync¹²⁺

getImageInfoSync(): ImageInfo

Obtains the image information. This API returns the result synchronously.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.Image.ImageSource

Return value

Type	Description
ImageInfo	Image information.

Error codes

For details about the error codes, see Image Error Codes.

ID	Error Message
501	Resource Unavailable

Example

function GetImageInfoSync(pixelMap:image.PixelMap) {
  if (pixelMap != undefined) {
    let imageInfo : image.ImageInfo = pixelMap.getImageInfoSync();
    return imageInfo;
  }
  return undefined;
}

getBytesNumberPerRow⁷⁺

getBytesNumberPerRow(): number

Obtains the number of bytes per row of this image. Unit: bytes.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Return value

Type	Description
number	Number of bytes per row.

Example

function GetBytesNumberPerRow(pixelMap: image.PixelMap) {
  let rowCount: number = pixelMap.getBytesNumberPerRow();
}

getPixelBytesNumber⁷⁺

getPixelBytesNumber(): number

Obtains the total number of bytes of this image. Unit: bytes.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Return value

Type	Description
number	Total number of bytes.

Example

function GetPixelBytesNumber(pixelMap: image.PixelMap) {
  let pixelBytesNumber: number = pixelMap.getPixelBytesNumber();
}

getDensity⁹⁺

getDensity():number

Obtains the pixel density of this image. Unit: ppi (pixels/inch)

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Return value

Type	Description
number	Pixel density, in ppi.

Example

function GetDensity(pixelMap: image.PixelMap) {
  let getDensity: number = pixelMap.getDensity();
}

opacity⁹⁺

opacity(rate: number, callback: AsyncCallback<void>): void

Sets an opacity rate for this image. This API uses an asynchronous callback to return the result. It is invalid for YUV images.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
rate	number	Yes	Opacity rate. The value range is (0,1].
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 Opacity(pixelMap:image.PixelMap) {
  let rate: number = 0.5;
  if (pixelMap != undefined) {
    pixelMap.opacity(rate, (err: BusinessError) => {
      if (err) {
        console.error(`Failed to set opacity. code is ${err.code}, message is ${err.message}`);
        return;
      } else {
        console.info("Succeeded in setting opacity.");
      }
    })
  }
}

opacity⁹⁺

opacity(rate: number): Promise<void>

Sets an opacity rate for this image. It is invalid for YUV images. This API uses a promise to return the result.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
rate	number	Yes	Opacity rate. The value range is (0,1].

Return value

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

Example

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

async function Opacity(pixelMap:image.PixelMap) {
  let rate: number = 0.5;
  if (pixelMap != undefined) {
    pixelMap.opacity(rate).then(() => {
      console.info('Succeeded in setting opacity.');
    }).catch((err: BusinessError) => {
      console.error(`Failed to set opacity. code is ${err.code}, message is ${err.message}`);
    })
  }
}

opacitySync¹²⁺

opacitySync(rate: number): void

Sets an opacity rate for this image. This API returns the result synchronously. It is invalid for YUV images.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
rate	number	Yes	Opacity rate. The value range is (0,1].

Error codes

For details about the error codes, see Universal Error Codes and Image Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed
501	Resource Unavailable

Example

function OpacitySync(pixelMap:image.PixelMap) {
  let rate : number = 0.5;
  if (pixelMap != undefined) {
    pixelMap.opacitySync(rate);
  }
}

createAlphaPixelmap⁹⁺

createAlphaPixelmap(): Promise<PixelMap>

Creates a PixelMap object that contains only the alpha channel information based on the alpha channel information. This object is not editable and can be used for the shadow effect. The YUV format is not supported by this API. This API uses a promise to return the result.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Return value

Type	Description
Promise<PixelMap>	Promise used to return the PixelMap object.

Example

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

async function CreateAlphaPixelmap(pixelMap:image.PixelMap) {
  if (pixelMap != undefined) {
    pixelMap.createAlphaPixelmap().then((alphaPixelMap: image.PixelMap) => {
      console.info('Succeeded in creating alpha pixelmap.');
    }).catch((error: BusinessError) => {
      console.error(`Failed to create alpha pixelmap. code is ${error.code}, message is ${error.message}`);
    })
  }
}

createAlphaPixelmap⁹⁺

createAlphaPixelmap(callback: AsyncCallback<PixelMap>): void

Creates a PixelMap object that contains only the alpha channel information based on the alpha channel information. This object is not editable and can be used for the shadow effect. The YUV format is not supported by this API. This API returns the result asynchronously through a callback.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

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

Example

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

async function CreateAlphaPixelmap(pixelMap:image.PixelMap) {
  if (pixelMap != undefined) {
    pixelMap.createAlphaPixelmap((err: BusinessError, alphaPixelMap: image.PixelMap) => {
      if (alphaPixelMap == undefined) {
        console.error(`Failed to obtain new pixel map. code is ${err.code}, message is ${err.message}`);
        return;
      } else {
        console.info('Succeeded in obtaining new pixel map.');
      }
    })
  }
}

createAlphaPixelmapSync¹²⁺

createAlphaPixelmapSync(): PixelMap

Creates a PixelMap object that contains only the alpha channel information based on the alpha channel information. This object is not editable and can be used for the shadow effect. The YUV format is not supported by this API. This API returns a PixelMap object synchronously.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.Image.Core

Return value

Type	Description
PixelMap	PixelMap object. If the operation fails, an error is thrown.

Error codes

For details about the error codes, see Universal Error Codes and Image Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1.Parameter verification failed
501	Resource Unavailable

Example

function CreateAlphaPixelmapSync(pixelMap:image.PixelMap) {
  if (pixelMap != undefined) {
    let pixelmap : image.PixelMap = pixelMap.createAlphaPixelmapSync();
    return pixelmap;
  }
  return undefined;
}

scale⁹⁺

scale(x: number, y: number, callback: AsyncCallback<void>): void

Scales this image based on the scale factors of the width and height. This API uses an asynchronous callback to return the result.

NOTE

1. You are advised to set the scale factors to non-negative numbers to avoid a flipping effect.
2. Scale factors of the width and height = Width and height of the resized image/Width and height of the original image

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
x	number	Yes	Scale factor of the width.
y	number	Yes	Scale factor of the height.
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 Scale(pixelMap:image.PixelMap) {
  let scaleX: number = 2.0;
  let scaleY: number = 1.0;
  if (pixelMap != undefined) {
    pixelMap.scale(scaleX, scaleY, (err: BusinessError) => {
      if (err) {
        console.error(`Failed to scale pixelmap. code is ${err.code}, message is ${err.message}`);
        return;
      } else {
        console.info("Succeeded in scaling pixelmap.");
      }
    })
  }
}

scale⁹⁺

scale(x: number, y: number): Promise<void>

Scales this image based on the scale factors of the width and height. This API uses a promise to return the result.

NOTE

1. You are advised to set the scale factors to non-negative numbers to avoid a flipping effect.
2. Scale factors of the width and height = Width and height of the resized image/Width and height of the original image

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
x	number	Yes	Scale factor of the width.
y	number	Yes	Scale factor of the height.

Return value

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

Example

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

async function Scale(pixelMap:image.PixelMap) {
  let scaleX: number = 2.0;
  let scaleY: number = 1.0;
  if (pixelMap != undefined) {
    pixelMap.scale(scaleX, scaleY).then(() => {
      console.info('Succeeded in scaling pixelmap.');
    }).catch((err: BusinessError) => {
      console.error(`Failed to scale pixelmap. code is ${err.code}, message is ${err.message}`);
    })
  }
}

scaleSync¹²⁺

scaleSync(x: number, y: number): void

Scales this image based on the scale factors of the width and height. This API returns the result synchronously.

NOTE

1. You are advised to set the scale factors to non-negative numbers to avoid a flipping effect.
2. Scale factors of the width and height = Width and height of the resized image/Width and height of the original image

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
x	number	Yes	Scale factor of the width.
y	number	Yes	Scale factor of the height.

Error codes

For details about the error codes, see Universal Error Codes and Image Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed
501	Resource Unavailable

Example

function ScaleSync(pixelMap: image.PixelMap) {
  let scaleX: number = 2.0;
  let scaleY: number = 1.0;
  if (pixelMap != undefined) {
    pixelMap.scaleSync(scaleX, scaleY);
  }
}

scale¹²⁺

scale(x: number, y: number, level: AntiAliasingLevel): Promise<void>

Scales this image based on the specified anti-aliasing level and the scale factors for the width and height. This API uses a promise to return the result.

NOTE

1. You are advised to set the scale factors to non-negative numbers to avoid a flipping effect.
2. Scale factors of the width and height = Width and height of the resized image/Width and height of the original image

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
x	number	Yes	Scale factor of the width.
y	number	Yes	Scale factor of the height.
level	AntiAliasingLevel	Yes	Anti-aliasing level.

Return value

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

Error codes

For details about the error codes, see Universal Error Codes and Image Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed
501	Resource Unavailable

Example

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

function ScaleSync(pixelMap:image.PixelMap) {
  let scaleX: number = 2.0;
  let scaleY: number = 1.0;
  if (pixelMap != undefined) {
    pixelMap.scale(scaleX, scaleY, image.AntiAliasingLevel.LOW).then(() => {
      console.info('Succeeded in scaling pixelmap.');
    }).catch((err: BusinessError) => {
      console.error(`Failed to scale pixelmap. code is ${err.code}, message is ${err.message}`);
    })
  }
}

scaleSync¹²⁺

scaleSync(x: number, y: number, level: AntiAliasingLevel): void

Scales this image based on the specified anti-aliasing level and the scale factors for the width and height. This API returns the result synchronously.

NOTE

1. You are advised to set the scale factors to non-negative numbers to avoid a flipping effect.
2. Scale factors of the width and height = Width and height of the resized image/Width and height of the original image

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
x	number	Yes	Scale factor of the width.
y	number	Yes	Scale factor of the height.
level	AntiAliasingLevel	Yes	Anti-aliasing level.

Error codes

For details about the error codes, see Universal Error Codes and Image Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed
501	Resource Unavailable

Example

function ScaleSync(pixelMap: image.PixelMap) {
  let scaleX: number = 2.0;
  let scaleY: number = 1.0;
  if (pixelMap != undefined) {
    pixelMap.scaleSync(scaleX, scaleY, image.AntiAliasingLevel.LOW);
  }
}

createScaledPixelMap¹⁸⁺

createScaledPixelMap(x: number, y: number, level?: AntiAliasingLevel): Promise<PixelMap>

Creates an image that has been resized based on the specified anti-aliasing level and the scale factors of the width and height. The generated PixelMap is not editable. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
x	number	Yes	Scale factor of the width.
y	number	Yes	Scale factor of the height.
level	AntiAliasingLevel	No	Anti-aliasing level. The default value is AntiAliasingLevel.NONE.

Return value

Type	Description
Promise<PixelMap>	Promise used to return the PixelMap object.

Error codes

For details about the error codes, see Universal Error Codes and Image Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed
501	Resource Unavailable

Example

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

async function CreateScaledPixelMap(pixelMap:image.PixelMap) {
  let scaleX: number = 2.0;
  let scaleY: number = 1.0;
  if (pixelMap != undefined) {
      pixelMap.createScaledPixelMap(scaleX, scaleY, image.AntiAliasingLevel.LOW).then((scaledPixelMap: image.PixelMap) => {
      console.info('Succeeded in creating scaledPixelMap.');
    }).catch((error: BusinessError) => {
      console.error(`Failed to create scaledPixelMap. Error code is ${error.code}, error message is ${error.message}`);
    })
  }
}

createScaledPixelMapSync¹⁸⁺

createScaledPixelMapSync(x: number, y: number, level?: AntiAliasingLevel): PixelMap

Creates an image that has been resized based on the specified anti-aliasing level and the scale factors of the width and height. The generated PixelMap is not editable. This API returns the result synchronously.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
x	number	Yes	Scale factor of the width.
y	number	Yes	Scale factor of the height.
level	AntiAliasingLevel	No	Anti-aliasing level. The default value is AntiAliasingLevel.NONE.

Return value

Type	Description
PixelMap	PixelMap object. If the operation fails, an error is thrown.

Error codes

For details about the error codes, see Universal Error Codes and Image Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed
501	Resource Unavailable

Example

function CreateScaledPixelMapSync(pixelMap:image.PixelMap) {
  let scaleX: number = 2.0;
  let scaleY: number = 1.0;
  if (pixelMap != undefined) {
    let scaledPixelMap = pixelMap.createScaledPixelMapSync(scaleX, scaleY, image.AntiAliasingLevel.LOW);
  }
}

createCroppedAndScaledPixelMap²²⁺

createCroppedAndScaledPixelMap(region: Region, x: number, y: number, level?: AntiAliasingLevel): Promise<PixelMap>

Creates an image that has been cropped and resized based on the specified cropping area, scale factors of the width and height, and anti-aliasing level. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
region	Region	Yes	Area to crop. It must be within the original image's dimension (in pixels).
x	number	Yes	Scale factor of the width. It must not be 0.
y	number	Yes	Scale factor of the height. It must not be 0.
level	AntiAliasingLevel	No	Anti-aliasing level. The default value is AntiAliasingLevel.NONE.

Return value

Type	Description
Promise<PixelMap>	Promise used to return the PixelMap object.

Error codes

For details about the error codes, see Image Error Codes.

ID	Error Message
7600201	The PixelMap has been released.
7600204	Invalid region.
7600205	Unsupported memory format or pixel format.
7600301	Memory alloc failed.

Example

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

function DemoCreateCroppedAndScaledPixelMap(pixelMap: PixelMap) {
  const imageInfo = pixelMap.getImageInfoSync();
  const region: image.Region = {
    size: { width: imageInfo.size.width / 2, height: imageInfo.size.height / 2 },
    x: imageInfo.size.width / 4,
    y: imageInfo.size.height / 4
  };
  const scaleX: number = 2.0;
  const scaleY: number = 2.0;
  pixelMap.createCroppedAndScaledPixelMap(region, scaleX, scaleY, image.AntiAliasingLevel.HIGH)
    .then((croppedAndScaled: PixelMap) => {
      console.info('PixelMap crop and scale succeeded.');
    })
    .catch((error: BusinessError) => {
      console.error(`PixelMap crop and scale failed. Error code: ${error.code}, message: ${error.message}`);
    });
}

createCroppedAndScaledPixelMapSync²²⁺

createCroppedAndScaledPixelMapSync(region: Region, x: number, y: number, level?: AntiAliasingLevel): PixelMap

Creates an image that has been cropped and resized based on the specified cropping area, scale factors of the width and height, and anti-aliasing level. This API returns the result synchronously.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
region	Region	Yes	Area to crop. It must be within the original image's dimension (in pixels).
x	number	Yes	Scale factor of the width. It must not be 0.
y	number	Yes	Scale factor of the height. It must not be 0.
level	AntiAliasingLevel	No	Anti-aliasing level. The default value is AntiAliasingLevel.NONE.

Return value

Type	Description
PixelMap	PixelMap object. If the operation fails, an error is thrown.

Error codes

For details about the error codes, see Image Error Codes.

ID	Error Message
7600201	The PixelMap has been released.
7600204	Invalid region.
7600205	Unsupported memory format or pixel format.
7600301	Memory alloc failed.

Example

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

function DemoCreateCroppedAndScaledPixelMapSync(pixelMap: PixelMap) {
  const imageInfo = pixelMap.getImageInfoSync();
  const region: image.Region = {
    size: { width: imageInfo.size.width / 2, height: imageInfo.size.height / 2 },
    x: imageInfo.size.width / 4,
    y: imageInfo.size.height / 4
  };
  const scaleX: number = 2.0;
  const scaleY: number = 2.0;
  try {
    const croppedAndScaled = pixelMap.createCroppedAndScaledPixelMapSync(region, scaleX, scaleY, image.AntiAliasingLevel.HIGH);
  } catch (e) {
    const error = e as BusinessError;
    console.error(`PixelMap crop and scale failed. Error code: ${error.code}, message: ${error.message}`);
  }
}

clone¹⁸⁺

clone(): Promise<PixelMap>

Copies this PixelMap object. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Image.Core

Return value

Type	Description
Promise<PixelMap>	Promise used to return the PixelMap object.

Error codes

For details about the error codes, see Image Error Codes.

ID	Error Message
501	Resource unavailable.
62980102	Image malloc abnormal. This status code is thrown when an error occurs during the process of copying data.
62980103	Image YUV And ASTC types are not supported.
62980104	Image initialization abnormal. This status code is thrown when an error occurs during the process of creating empty pixelmap.
62980106	The image data is too large. This status code is thrown when an error occurs during the process of checking size.

Example

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

async function Clone(pixelMap:image.PixelMap) {
  if (pixelMap != undefined) {
    pixelMap.clone().then((clonePixelMap: image.PixelMap) => {
      console.info('Succeeded clone pixelmap.');
    }).catch((error: BusinessError) => {
      console.error(`Failed to clone pixelmap. code is ${error.code}, message is ${error.message}`);
    })
  }
}

cloneSync¹⁸⁺

cloneSync(): PixelMap

Copies this PixelMap object. This API returns the result synchronously.

System capability: SystemCapability.Multimedia.Image.Core

Return value

Type	Description
PixelMap	PixelMap object. If the operation fails, an error is thrown.

Error codes

For details about the error codes, see Image Error Codes.

ID	Error Message
501	Resource unavailable.
62980102	Image malloc abnormal. This status code is thrown when an error occurs during the process of copying data.
62980103	Image YUV And ASTC types are not supported.
62980104	Image initialization abnormal. This status code is thrown when an error occurs during the process of creating empty pixelmap.
62980106	The image data is too large. This status code is thrown when an error occurs during the process of checking size.

Example

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

function CloneSync(pixelMap: image.PixelMap) {
  if (pixelMap != undefined) {
    try {
      let clonedPixelMap:image.PixelMap = pixelMap.cloneSync();
    } catch(e) {
      let error = e as BusinessError;
      console.error(`clone pixelmap error. code is ${error.code}, message is ${error.message}`);
    }
  }
}

translate⁹⁺

translate(x: number, y: number, callback: AsyncCallback<void>): void

Translates this image based on given coordinates. This API uses an asynchronous callback to return the result.

The size of the translated image is changed to width+X and height+Y. It is recommended that the new width and height not exceed the width and height of the screen.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
x	number	Yes	X coordinate to translate, in px.
y	number	Yes	Y coordinate to translate, in px.
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 Translate(pixelMap:image.PixelMap) {
  let translateX: number = 50.0;
  let translateY: number = 10.0;
  if (pixelMap != undefined) {
    pixelMap.translate(translateX, translateY, (err: BusinessError) => {
      if (err) {
        console.error(`Failed to translate pixelmap. code is ${err.code}, message is ${err.message}`);
        return;
      } else {
        console.info("Succeeded in translating pixelmap.");
      }
    })
  }
}

translate⁹⁺

translate(x: number, y: number): Promise<void>

Translates a PixelMap based on given coordinates. This API uses a promise to return the result.

The size of the translated image is changed to width+X and height+Y. It is recommended that the new width and height not exceed the width and height of the screen.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
x	number	Yes	X coordinate to translate, in px.
y	number	Yes	Y coordinate to translate, in px.

Return value

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

Example

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

async function Translate(pixelMap:image.PixelMap) {
  let translateX: number = 50.0;
  let translateY: number = 10.0;
  if (pixelMap != undefined) {
    pixelMap.translate(translateX, translateY).then(() => {
      console.info('Succeeded in translating pixelmap.');
    }).catch((err: BusinessError) => {
      console.error(`Failed to translate pixelmap. code is ${err.code}, message is ${err.message}`);
    })
  }
}

translateSync¹²⁺

translateSync(x: number, y: number): void

Translates this image based on given coordinates. This API returns the result synchronously.

The size of the translated image is changed to width+X and height+Y. It is recommended that the new width and height not exceed the width and height of the screen.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
x	number	Yes	X coordinate to translate, in px.
y	number	Yes	Y coordinate to translate, in px.

Error codes

For details about the error codes, see Universal Error Codes and Image Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed
501	Resource Unavailable

Example

function TranslateSync(pixelMap:image.PixelMap) {
  let translateX : number = 50.0;
  let translateY : number = 10.0;
  if (pixelMap != undefined) {
    pixelMap.translateSync(translateX, translateY);
  }
}

rotate⁹⁺

rotate(angle: number, callback: AsyncCallback<void>): void

Rotates this image based on a given angle. This API uses an asynchronous callback to return the result.

NOTE

1. The allowable range for image rotation angles is [0, 360]. Angles outside this range are automatically adjusted according to the 360-degree cycle. For example, an angle of -100 degrees will produce the same result as 260 degrees.
2. If the rotation angle is not an integer multiple of 90 degrees, the image size will change after rotation.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
angle	number	Yes	Angle to rotate. Unit: degrees.
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 Rotate(pixelMap:image.PixelMap) {
  let angle: number = 90.0;
  if (pixelMap != undefined) {
    pixelMap.rotate(angle, (err: BusinessError) => {
      if (err) {
        console.error(`Failed to rotate pixelmap. code is ${err.code}, message is ${err.message}`);
        return;
      } else {
        console.info("Succeeded in rotating pixelmap.");
      }
    })
  }
}

rotate⁹⁺

rotate(angle: number): Promise<void>

Rotates a PixelMap based on a given angle. This API uses a promise to return the result.

NOTE

1. The allowable range for image rotation angles is [0, 360]. Angles outside this range are automatically adjusted according to the 360-degree cycle. For example, an angle of -100 degrees will produce the same result as 260 degrees.
2. If the rotation angle is not an integer multiple of 90 degrees, the image size will change after rotation.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
angle	number	Yes	Angle to rotate. Unit: degrees.

Return value

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

Example

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

async function Rotate(pixelMap:image.PixelMap) {
  let angle: number = 90.0;
  if (pixelMap != undefined) {
    pixelMap.rotate(angle).then(() => {
      console.info('Succeeded in rotating pixelmap.');
    }).catch((err: BusinessError) => {
      console.error(`Failed to rotate pixelmap. code is ${err.code}, message is ${err.message}`);
    })
  }
}

rotateSync¹²⁺

rotateSync(angle: number): void

Rotates this image based on a given angle. This API returns the result synchronously.

NOTE

1. The allowable range for image rotation angles is [0, 360]. Angles outside this range are automatically adjusted according to the 360-degree cycle. For example, an angle of -100 degrees will produce the same result as 260 degrees.
2. If the rotation angle is not an integer multiple of 90 degrees, the image size will change after rotation.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
angle	number	Yes	Angle to rotate. Unit: degrees.

Error codes

For details about the error codes, see Universal Error Codes and Image Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed
501	Resource Unavailable

Example

function RotateSync(pixelMap: image.PixelMap) {
  let angle : number = 90.0;
  if (pixelMap != undefined) {
    pixelMap.rotateSync(angle);
  }
}

flip⁹⁺

flip(horizontal: boolean, vertical: boolean, callback: AsyncCallback<void>): void

Flips this image horizontally or vertically, or both. This API uses an asynchronous callback to return the result.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
horizontal	boolean	Yes	Whether to flip the image horizontally. true to flip the image horizontally, false otherwise.
vertical	boolean	Yes	Whether to flip the image vertically. true to flip the image vertically, false otherwise.
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 Flip(pixelMap:image.PixelMap) {
  let horizontal: boolean = true;
  let vertical: boolean = false;
  if (pixelMap != undefined) {
    pixelMap.flip(horizontal, vertical, (err: BusinessError) => {
      if (err) {
        console.error(`Failed to flip pixelmap. code is ${err.code}, message is ${err.message}`);
        return;
      } else {
        console.info("Succeeded in flipping pixelmap.");
      }
    })
  }
}

flip⁹⁺

flip(horizontal: boolean, vertical: boolean): Promise<void>

Flips a PixelMap based on a given angle. This API uses a promise to return the result.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
horizontal	boolean	Yes	Whether to flip the image horizontally. true to flip the image horizontally, false otherwise.
vertical	boolean	Yes	Whether to flip the image vertically. true to flip the image vertically, false otherwise.

Return value

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

Example

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

async function Flip(pixelMap:image.PixelMap) {
  let horizontal: boolean = true;
  let vertical: boolean = false;
  if (pixelMap != undefined) {
    pixelMap.flip(horizontal, vertical).then(() => {
      console.info('Succeeded in flipping pixelmap.');
    }).catch((err: BusinessError) => {
      console.error(`Failed to flip pixelmap. code is ${err.code}, message is ${err.message}`);
    })
  }
}

flipSync¹²⁺

flipSync(horizontal: boolean, vertical: boolean): void

Flips this image horizontally or vertically, or both. This API returns the result synchronously.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
horizontal	boolean	Yes	Whether to flip the image horizontally. true to flip the image horizontally, false otherwise.
vertical	boolean	Yes	Whether to flip the image vertically. true to flip the image vertically, false otherwise.

Error codes

For details about the error codes, see Universal Error Codes and Image Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed
501	Resource Unavailable

Example

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

function FlipSync(pixelMap:image.PixelMap) {
  let horizontal : boolean = true;
  let vertical : boolean = false;
  if (pixelMap != undefined) {
    pixelMap.flipSync(horizontal, vertical);
  }
}

crop⁹⁺

crop(region: Region, callback: AsyncCallback<void>): void

Crops this image based on a given size. This API uses an asynchronous callback to return the result.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
region	Region	Yes	Size of the image after cropping. The value cannot exceed the width or height of the 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 Crop(pixelMap:image.PixelMap) {
  let region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } };
  if (pixelMap != undefined) {
    pixelMap.crop(region, (err: BusinessError) => {
      if (err) {
        console.error(`Failed to crop pixelmap. code is ${err.code}, message is ${err.message}`);
        return;
      } else {
        console.info("Succeeded in cropping pixelmap.");
      }
    })
  }
}

crop⁹⁺

crop(region: Region): Promise<void>

Crops a PixelMap based on a given size. This API uses a promise to return the result.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
region	Region	Yes	Size of the image after cropping. The value cannot exceed the width or height of the image.

Return value

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

Example

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

async function Crop(pixelMap:image.PixelMap) {
  let region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } };
  if (pixelMap != undefined) {
    pixelMap.crop(region).then(() => {
      console.info('Succeeded in cropping pixelmap.');
    }).catch((err: BusinessError) => {
      console.error(`Failed to crop pixelmap. code is ${err.code}, message is ${err.message}`);

    });
  }
}

cropSync¹²⁺

cropSync(region: Region): void

Crops this image based on a given size. This API returns the result synchronously.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
region	Region	Yes	Size of the image after cropping. The value cannot exceed the width or height of the image.

Error codes

For details about the error codes, see Universal Error Codes and Image Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed
501	Resource Unavailable

Example

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

function CropSync(pixelMap:image.PixelMap) {
  let region : image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } };
  if (pixelMap != undefined) {
    pixelMap.cropSync(region);
  }
}

getColorSpace¹⁰⁺

getColorSpace(): colorSpaceManager.ColorSpaceManager

Obtains the color space of this image.

System capability: SystemCapability.Multimedia.Image.Core

Return value

Type	Description
colorSpaceManager.ColorSpaceManager	Color space obtained.

Error codes

For details about the error codes, see Image Error Codes.

ID	Error Message
62980101	The image data is abnormal.
62980103	The image data is not supported.
62980115	Invalid image parameter.

Example

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

function GetColorSpace(pixelMap:image.PixelMap) {
  if (pixelMap != undefined) {
    let csm = pixelMap.getColorSpace();
  }
}

setColorSpace¹⁰⁺

setColorSpace(colorSpace: colorSpaceManager.ColorSpaceManager): void

Sets the color space for this image.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
colorSpace	colorSpaceManager.ColorSpaceManager	Yes	Color space to set.

Error codes

For details about the error codes, see Image Error Codes.

ID	Error Message
62980111	The image source data is incomplete.
62980115	If the image parameter invalid.

Example

import { colorSpaceManager } from '@kit.ArkGraphics2D';

function SetColorSpace(pixelMap:image.PixelMap) {
  let colorSpaceName = colorSpaceManager.ColorSpace.SRGB; // The colorSpaceManager.ColorSpace object is supported only on 2-in-1 devices/PCs.
  let csm: colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceName);
  if (pixelMap != undefined) {
    pixelMap.setColorSpace(csm);
  }
}

applyColorSpace¹¹⁺

applyColorSpace(targetColorSpace: colorSpaceManager.ColorSpaceManager, callback: AsyncCallback<void>): void

Performs color space conversion (CSC) on the image pixel color based on a given color space. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
targetColorSpace	colorSpaceManager.ColorSpaceManager	Yes	Target color space. SRGB, DCI_P3, DISPLAY_P3, and ADOBE_RGB_1998 are supported.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Image Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed
62980104	Failed to initialize the internal object.
62980108	Failed to convert the color space.
62980115	Invalid image parameter.

Example

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

function ApplyColorSpace(pixelMap:image.PixelMap) {
  let colorSpaceName = colorSpaceManager.ColorSpace.SRGB; // The colorSpaceManager.ColorSpace object is supported only on 2-in-1 devices/PCs.
  let targetColorSpace: colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceName);
  if (pixelMap != undefined) {
    try {
      pixelMap.applyColorSpace(targetColorSpace, (error: BusinessError) => {
        if (error) {
          console.error(`ApplyColorSpace failed. code is ${error.code}, message is ${error.message}`);
          return;
        } else {
          console.info("Succeeded ApplyColorSpace.");
        }
      });
    } catch (error) {
      console.error(`Failed to apply color space for pixelmap object, error code is ${error}`);
      return;
    }
    console.info('Succeeded in applying color space for pixelmap object.');
  }
}

applyColorSpace¹¹⁺

applyColorSpace(targetColorSpace: colorSpaceManager.ColorSpaceManager): Promise<void>

Performs Color Space Converters (CSC) on the image pixel color based on a given color space. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
targetColorSpace	colorSpaceManager.ColorSpaceManager	Yes	Target color space. SRGB, DCI_P3, DISPLAY_P3, and ADOBE_RGB_1998 are supported.

Return value

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

Error codes

For details about the error codes, see Universal Error Codes and Image Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed
62980104	Failed to initialize the internal object.
62980108	Failed to convert the color space.
62980115	Invalid image parameter.

Example

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

function ApplyColorSpace(pixelMap:image.PixelMap) {
  let colorSpaceName = colorSpaceManager.ColorSpace.SRGB; // The colorSpaceManager.ColorSpace object is supported only on 2-in-1 devices/PCs.
  let targetColorSpace: colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceName);
  if (pixelMap != undefined) {
      pixelMap.applyColorSpace(targetColorSpace).then(() => {
      console.info('Succeeded in applying color space for pixelmap object.');
    }).catch((error: BusinessError) => {
      console.error(`Failed to apply color space for pixelmap object, error code is ${error}`);
      return;
    });
  }
}

toSdr¹²⁺

toSdr(): Promise<void>

Converts a PixelMap from the HDR format to the SDR format. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Image.Core

Return value

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

Error codes

For details about the error codes, see Image Error Codes.

ID	Error Message
62980137	Invalid image operation.

Example

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

async function ToSdr(context: Context) {
  // Replace app.media.startIcon with a local HDR image.
  let img = context.resourceManager.getMediaContentSync($r('app.media.startIcon').id);
  let imageSource = image.createImageSource(img.buffer.slice(0));
  let decodingOptions: image.DecodingOptions = {
    desiredDynamicRange: image.DecodingDynamicRange.AUTO
  };
  let pixelmap = imageSource.createPixelMapSync(decodingOptions);
  if (pixelmap != undefined) {
    console.info('Succeeded in creating pixelMap object.');
    pixelmap.toSdr().then(() => {
      let imageInfo = pixelmap.getImageInfoSync();
      console.info("after toSdr ,imageInfo isHdr:" + imageInfo.isHdr);
    }).catch((err: BusinessError) => {
      console.error(`Failed to set sdr. code is ${err.code}, message is ${err.message}`);
    });
  } else {
    console.error('Failed to create pixelMap.');
  }
}

getMetadata¹²⁺

getMetadata(key: HdrMetadataKey): HdrMetadataValue

Obtains the value of the metadata with a given key in this PixelMap.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
key	HdrMetadataKey	Yes	Key of the HDR metadata.

Return value

Type	Description
HdrMetadataValue	Value of the metadata with the given key.

Error codes

For details about the error codes, see Universal Error Codes and Image Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
501	Resource unavailable.
62980173	The DMA memory does not exist.
62980302	Memory copy failed. Possibly caused by invalid metadata value.

Example

async function GetMetadata(context: Context) {
  // Replace app.media.startIcon with a local HDR image.
  let img = context.resourceManager.getMediaContentSync($r('app.media.startIcon').id);
  let imageSource = image.createImageSource(img.buffer.slice(0));
  let decodingOptions: image.DecodingOptions = {
    desiredDynamicRange: image.DecodingDynamicRange.AUTO
  };
  let pixelmap = imageSource.createPixelMapSync(decodingOptions);
  if (pixelmap != undefined) {
    console.info('Succeeded in creating pixelMap object.');
    try {
      let staticMetadata = pixelmap.getMetadata(image.HdrMetadataKey.HDR_STATIC_METADATA);
      console.info(`getMetadata:${staticMetadata}`);
    } catch (e) {
      console.error('pixelmap create failed' + e);
    }
  } else {
    console.error('Failed to create pixelMap.');
  }
}

setMetadata¹²⁺

setMetadata(key: HdrMetadataKey, value: HdrMetadataValue): Promise<void>

Sets the value for the metadata with a given key in this PixelMap. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
key	HdrMetadataKey	Yes	Key of the HDR metadata.
value	HdrMetadataValue	Yes	Value of the metadata.

Return value

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

Error codes

For details about the error codes, see Universal Error Codes and Image Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
501	Resource unavailable.
62980173	The DMA memory does not exist.
62980302	Memory copy failed. Possibly caused by invalid metadata value.

Example

For details about how to create a PixelMap with DMA_ALLOC memory, see Default Memory Allocation Mode.

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

function SetMetadata(pixelMap: image.PixelMap) { // The input parameter pixelMap must be of the DMA_ALLOC memory type. For details about how to create a PixelMap with DMA_ALLOC memory, see the preceding link.
  let staticMetadata: image.HdrStaticMetadata = {
    displayPrimariesX: [1.1, 1.1, 1.1],
    displayPrimariesY: [1.2, 1.2, 1.2],
    whitePointX: 1.1,
    whitePointY: 1.2,
    maxLuminance: 2.1,
    minLuminance: 1.0,
    maxContentLightLevel: 2.1,
    maxFrameAverageLightLevel: 2.1,
  };
  pixelMap.setMetadata(image.HdrMetadataKey.HDR_STATIC_METADATA, staticMetadata).then(() => {
    console.info('Succeeded in setting pixelMap metadata.');
  }).catch((error: BusinessError) => {
    console.error("Failed to set the metadata.code ", error);
  })
}

setTransferDetached¹²⁺

setTransferDetached(detached: boolean): void

Sets whether to detach from the original thread when this PixelMap is transmitted across threads. This API applies to the scenario where the PixelMap needs to be released immediately.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
detached	boolean	Yes	Whether to detach from the original thread. true to detach, false otherwise.

Error codes

For details about the error codes, see Image Error Codes.

ID	Error Message
501	Resource Unavailable

Example

import { common } from '@kit.AbilityKit';
import { taskpool } from '@kit.ArkTS';

@Concurrent
// Child thread method.
async function loadPixelMap(rawFileDescriptor: number): Promise<PixelMap> {
  // Create an ImageSource instance.
  const imageSource = image.createImageSource(rawFileDescriptor);
  // Create a pixelMap.
  const pixelMap = imageSource.createPixelMapSync();
  // Release the ImageSource instance.
  imageSource.release();
  // Disconnect the reference of the original thread after the cross-thread transfer of the pixelMap is complete.
  pixelMap.setTransferDetached(true);
  // Return the pixelMap to the main thread.
  return pixelMap;
}

@Entry
@Component
struct Demo {
  @State pixelMap: PixelMap|undefined = undefined;
  // Main thread method.
  private loadImageFromThread(): void {
    let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
    const resourceMgr = context.resourceManager;
    // 'example.jpg' is only an example. Replace it with the actual one in use. Otherwise, the imageSource instance fails to be created, and subsequent operations cannot be performed.
    resourceMgr.getRawFd('example.jpg').then(rawFileDescriptor => {
      taskpool.execute(loadPixelMap, rawFileDescriptor).then(pixelMap => {
        if (pixelMap) {
          this.pixelMap = pixelMap as PixelMap;
          console.info('Succeeded in creating pixelMap.');
          // The main thread releases the pixelMap. Because setTransferDetached has been called when the child thread returns pixelMap, the pixelMap can be released immediately.
          this.pixelMap.release();
        } else {
          console.error('Failed to create pixelMap.');
        }
      });
    });
  }
  build() {
    // ...
  }
}

marshalling¹⁰⁺

marshalling(sequence: rpc.MessageSequence): void

Marshals this PixelMap object and writes it to a MessageSequence object.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
sequence	rpc.MessageSequence	Yes	MessageSequence object.

Error codes

For details about the error codes, see Image Error Codes.

ID	Error Message
62980115	Invalid image parameter.
62980097	IPC error. Possible cause: 1.IPC communication failed. 2. Image upload exception. 3. Decode process exception. 4. Insufficient memory.

Example

import { rpc } from '@kit.IPCKit';

class MySequence implements rpc.Parcelable {
  pixel_map: image.PixelMap;
  constructor(conPixelMap : image.PixelMap) {
    this.pixel_map = conPixelMap;
  }
  marshalling(messageSequence : rpc.MessageSequence) {
    this.pixel_map.marshalling(messageSequence);
    console.info('marshalling');
    return true;
  }
  unmarshalling(messageSequence : rpc.MessageSequence) {
    image.createPixelMap(new ArrayBuffer(96), {size: { height:4, width: 6}}).then((pixelParcel: image.PixelMap) => {
      pixelParcel.unmarshalling(messageSequence).then(async (pixelMap: image.PixelMap) => {
        this.pixel_map = pixelMap;
        pixelMap.getImageInfo().then((imageInfo: image.ImageInfo) => {
          console.info(`unmarshalling information h: ${imageInfo.size.height} w: ${imageInfo.size.width}`);
        })
      })
    });
    return true;
  }
}
async function Marshalling() {
  const color: ArrayBuffer = new ArrayBuffer(96);
  let bufferArr: Uint8Array = new Uint8Array(color);
  for (let i = 0; i < bufferArr.length; i++) {
    bufferArr[i] = 0x80;
  }
  let opts: image.InitializationOptions = {
    editable: true,
    pixelFormat: image.PixelMapFormat.BGRA_8888,
    size: { height: 4, width: 6 },
    alphaType: image.AlphaType.UNPREMUL
  }
  let pixelMap: image.PixelMap|undefined = undefined;
  await image.createPixelMap(color, opts).then((srcPixelMap: image.PixelMap) => {
    pixelMap = srcPixelMap;
  })
  if (pixelMap != undefined) {
    // Implement serialization.
    let parcelable: MySequence = new MySequence(pixelMap);
    let data: rpc.MessageSequence = rpc.MessageSequence.create();
    data.writeParcelable(parcelable);

    // Implement deserialization to obtain data through the RPC.
    let ret: MySequence = new MySequence(pixelMap);
    data.readParcelable(ret);
  }
}

unmarshalling¹⁰⁺

unmarshalling(sequence: rpc.MessageSequence): Promise<PixelMap>

Unmarshals a MessageSequence object to obtain a PixelMap object. To create a PixelMap object in synchronous mode, use createPixelMapFromParcel.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
sequence	rpc.MessageSequence	Yes	MessageSequence object that stores the PixelMap information.

Return value

Type	Description
Promise<PixelMap>	Promise used to return the PixelMap object.

Error codes

For details about the error codes, see Image Error Codes.

ID	Error Message
62980115	Invalid image parameter.
62980097	IPC error. Possible cause: 1.IPC communication failed. 2. Image upload exception. 3. Decode process exception. 4. Insufficient memory.
62980096	The operation failed. Possible cause: 1.Image upload exception. 2. Decoding process exception. 3. Insufficient memory.

Example

import { rpc } from '@kit.IPCKit';

class MySequence implements rpc.Parcelable {
  pixel_map: image.PixelMap;
  constructor(conPixelMap: image.PixelMap) {
    this.pixel_map = conPixelMap;
  }
  marshalling(messageSequence: rpc.MessageSequence) {
    this.pixel_map.marshalling(messageSequence);
    console.info('marshalling');
    return true;
  }
  unmarshalling(messageSequence: rpc.MessageSequence) {
    image.createPixelMap(new ArrayBuffer(96), {size: { height:4, width: 6}}).then((pixelParcel : image.PixelMap) => {
      pixelParcel.unmarshalling(messageSequence).then(async (pixelMap : image.PixelMap) => {
        this.pixel_map = pixelMap;
        pixelMap.getImageInfo().then((imageInfo : image.ImageInfo) => {
          console.info(`unmarshalling information h: ${imageInfo.size.height} w: ${imageInfo.size.width}`);
        })
      })
    });
    return true;
  }
}
async function Unmarshalling() {
  const color: ArrayBuffer = new ArrayBuffer(96);
  let bufferArr: Uint8Array = new Uint8Array(color);
  for (let i = 0; i < bufferArr.length; i++) {
    bufferArr[i] = 0x80;
  }
  let opts: image.InitializationOptions = {
    editable: true,
    pixelFormat: image.PixelMapFormat.BGRA_8888,
    size: { height: 4, width: 6 },
    alphaType: image.AlphaType.UNPREMUL
  }
  let pixelMap: image.PixelMap|undefined = undefined;
  await image.createPixelMap(color, opts).then((srcPixelMap : image.PixelMap) => {
    pixelMap = srcPixelMap;
  })
  if (pixelMap != undefined) {
    // Implement serialization.
    let parcelable: MySequence = new MySequence(pixelMap);
    let data : rpc.MessageSequence = rpc.MessageSequence.create();
    data.writeParcelable(parcelable);

    // Implement deserialization to obtain data through the RPC.
    let ret : MySequence = new MySequence(pixelMap);
    data.readParcelable(ret);
  }
}

release⁷⁺

release(): Promise<void>

Releases this PixelMap instance. After the release, any attempt to access the internal data of this object will fail. This API uses a promise to return the result.

Images occupy a large amount of memory. When you finish using a PixelMap 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.

NOTE

Release occurs when an ArkTS object relinquishes control over its associated native object. The memory occupied by the native object is reclaimed only after all managing ArkTS objects have relinquished their control.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

Return value

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

Example

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

async function Release(pixelMap:image.PixelMap) {
  if (pixelMap != undefined) {
    await pixelMap.release().then(() => {
      console.info('Succeeded in releasing pixelmap object.');
    }).catch((error: BusinessError) => {
      console.error(`Failed to release pixelmap object. code is ${error.code}, message is ${error.message}`);
    })
  }
}

release⁷⁺

release(callback: AsyncCallback<void>): void

Releases this PixelMap instance. After the release, any attempt to access the internal data of this object will fail. This API uses an asynchronous callback to return the result.

Images occupy a large amount of memory. When you finish using a PixelMap 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.

NOTE

Release occurs when an ArkTS object relinquishes control over its associated native object. The memory occupied by the native object is reclaimed only after all managing ArkTS objects have relinquished their control.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Image.Core

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(pixelMap:image.PixelMap) {
  if (pixelMap != undefined) {
    pixelMap.release((err: BusinessError) => {
      if (err) {
        console.error(`Failed to release pixelmap object. code is ${err.code}, message is ${err.message}`);
        return;
      } else {
        console.info('Succeeded in releasing pixelmap object.');
      }
    })
  }
}

convertPixelFormat¹²⁺

convertPixelFormat(targetPixelFormat: PixelMapFormat): Promise<void>

Converts between YUV and RGB formats. This API uses a promise to return the result.

Conversion between NV12/NV21 and RGB888/RGBA8888/RGB565/BGRA8888/RGBAF16 and conversion between YCRCB_P010/YCBCR_P010 and RGBA1010102 are supported.

Since API version 18, this API can be used for conversion from ASTC_4x4 to RGBA_8888.

NOTE Call this API to convert the format from ASTC_4x4 to RGBA_8888 only when you need to access pixels of images in ASTC_4x4 format. The conversion from ASTC_4x4 to RGBA_8888 is slow and is not recommended in other cases.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
targetPixelFormat	PixelMapFormat	Yes	Target pixel format. Currently, only conversion between NV12/NV21 and RGB888/RGBA8888/RGB565/BGRA8888/RGBAF16, conversion between YCRCB_P010/YCBCR_P010 and RGBA1010102, and conversion from ASTC_4x4 to RGBA_8888 are supported.

Return value

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

Error codes

For details about the error codes, see Image Error Codes.

ID	Error Message
62980111	The image source data is incomplete.
62980115	Invalid input parameter.
62980178	Failed to create the pixelmap.
62980274	The conversion failed
62980276	The type to be converted is an unsupported target pixel format

Example

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

async function ConvertPixelFormat(pixelMap: image.PixelMap) {
  if (pixelMap != undefined) {
    // Set the target pixel format to NV12.
    let targetPixelFormat = image.PixelMapFormat.NV12;
    pixelMap.convertPixelFormat(targetPixelFormat).then(() => {
      // The pixelMap is converted to the NV12 format.
      console.info('PixelMapFormat convert Succeeded');
    }).catch((error: BusinessError) => {
      // The pixelMap fails to be converted to the NV12 format.
      console.error(`PixelMapFormat convert Failed. code is ${error.code}, message is ${error.message}`);
    })
  }
}

setMemoryNameSync¹³⁺

setMemoryNameSync(name: string): void

Sets a memory name for this PixelMap.

System capability: SystemCapability.Multimedia.Image.Core

Parameters

Name	Type	Mandatory	Description
name	string	Yes	Memory name, which can be set only for a PixelMap with the DMA or ASHMEM memory format. The name length for DMA memory settings should be within the range of 1 to 255 bytes. For ASHMEM memory settings, the name length should be within the range of 1 to 244 bytes.

Error codes

For details about the error codes, see Universal Error Codes and Image Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1.The length of the input parameter is too long. 2.Parameter verification failed.
501	Resource unavailable.
62980286	Memory format not supported.

Example

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

function SetMemoryNameSync(pixelMap:image.PixelMap) {
  if (pixelMap != undefined) {
    try {
      pixelMap.setMemoryNameSync("PixelMapName Test");
    } catch(e) {
      let error = e as BusinessError;
      console.error(`setMemoryNameSync error. code is ${error.code}, message is ${error.message}`);
    }
  }
}

getUniqueId²²⁺

getUniqueId(): number

Obtains the unique ID of this PixelMap.

System capability: SystemCapability.Multimedia.Image.Core

Return value

Type	Description
number	Unique ID. The value is a positive integer.

Error codes

For details about the error codes, see Image Error Codes.

ID	Error Message
7600201	The PixelMap has been released.

Example

function DemoGetUniqueId(pixelMap: PixelMap) {
  const uniqueId: number = pixelMap.getUniqueId();
}

isReleased²²⁺

isReleased(): boolean

Checks whether this PixelMap object is released. If released, any attempt to access the internal data of this object will fail.

NOTE

Release occurs when an ArkTS object relinquishes control over its associated native object. The memory occupied by the native object is reclaimed only after all managing ArkTS objects have relinquished their control.

System capability: SystemCapability.Multimedia.Image.Core

Return value

Type	Description
boolean	Check result for whether the PixelMap object is released. true if released; false otherwise.

Example

async function DemoIsReleased(pixelMap: PixelMap) { // Unreleased PixelMap.
  pixelMap.isReleased(); // Return false.
  await pixelMap.release();
  pixelMap.isReleased(); // Return true.
}

你可能感兴趣的鸿蒙文章

openharmony 鸿蒙 capi-image-nativemodule-oh-pixelmap-hdrmetadatavalue

openharmony 鸿蒙 capi-image-imagepacker-opts-

openharmony 鸿蒙 capi-image-nativemodule-image-region

openharmony 鸿蒙 capi-image-imagepacker-native-

openharmony 鸿蒙 capi-image-imagenative-

openharmony 鸿蒙 capi-image-processing-h

openharmony 鸿蒙 capi-image-ohosimagesourcesupportedformat

openharmony 鸿蒙 capi-image-nativemodule-image-size

openharmony 鸿蒙 capi-image-mdk-h

openharmony 鸿蒙 capi-image-ohosimagesourcedelaytimelist