1# Interface (PixelMap) 2<!--Kit: Image Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @yaozhupeng--> 5<!--Designer: @yaozhupeng--> 6<!--Tester: @zhaoxiaoguang2--> 7<!--Adviser: @zengyawen--> 8 9> **说明：** 10> 11> - 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 12> - 本Interface首批接口从API version 7开始支持。 13 14图像像素类，用于读取或写入图像数据以及获取图像信息。在调用PixelMap的方法前，需要先通过[createPixelMap](arkts-apis-image-f.md#imagecreatepixelmap8)创建一个PixelMap实例。目前pixelmap序列化大小最大128MB，超过会送显失败。大小计算方式为(宽\*高\*每像素占用字节数)。 15 16从API version 11开始，PixelMap支持通过worker跨线程调用。当PixelMap通过[Worker](../apis-arkts/js-apis-worker.md)跨线程后，原线程的PixelMap的所有接口均不能调用，否则将报错501 服务器不具备完成请求的功能。 17 18在调用PixelMap的方法前，需要先通过[image.createPixelMap](arkts-apis-image-f.md#imagecreatepixelmap8)构建一个PixelMap对象。 19 20开发原子化服务请通过[ImageSource](arkts-apis-image-ImageSource.md)构建PixelMap对象。 21 22## 导入模块 23 24```ts 25import { image } from '@kit.ImageKit'; 26``` 27 28## 属性 29 30**系统能力：** SystemCapability.Multimedia.Image.Core 31 32| 名称 | 类型 | 只读 | 可选 | 说明 | 33| -----------------| ------- | ---- | ---- | -------------------------- | 34| isEditable<sup>7+</sup> | boolean | 是 | 否 | true表示图像像素可被编辑，false表示不可被编辑。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 <br>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 | 35| isStrideAlignment<sup>11+</sup> | boolean | 是 | 否 | true表示图像内存为DMA内存，false表示非DMA内存。 | 36 37## readPixelsToBuffer<sup>7+</sup> 38 39readPixelsToBuffer(dst: ArrayBuffer): Promise\<void> 40 41按照PixelMap的像素格式，读取PixelMap的图像像素数据，并写入缓冲区中，使用Promise形式返回。 42 43**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 44 45**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 46 47**系统能力：** SystemCapability.Multimedia.Image.Core 48 49**参数：** 50 51| 参数名 | 类型 | 必填 | 说明 | 52| ------ | ----------- | ---- | ----------------------------------------------------------------------------------------------------- | 53| dst | ArrayBuffer | 是 | 缓冲区，函数执行结束后获取的图像像素数据写入到该内存区域内。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 54 55**返回值：** 56 57| 类型 | 说明 | 58| -------------- | ----------------------------------------------- | 59| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 60 61**示例：** 62 63```ts 64import { BusinessError } from '@kit.BasicServicesKit'; 65 66async function ReadPixelsToBuffer(pixelMap : image.PixelMap) { 67 const readBuffer: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 68 if (pixelMap != undefined) { 69 pixelMap.readPixelsToBuffer(readBuffer).then(() => { 70 console.info('Succeeded in reading image pixel data.'); // 符合条件则进入。 71 }).catch((error: BusinessError) => { 72 console.error(`Failed to read image pixel data. code is ${error.code}, message is ${error.message}`);// 不符合条件则进入。 73 }) 74 } 75} 76``` 77 78## readPixelsToBuffer<sup>7+</sup> 79 80readPixelsToBuffer(dst: ArrayBuffer, callback: AsyncCallback\<void>): void 81 82按照PixelMap的像素格式，读取PixelMap的图像像素数据，并写入缓冲区中，使用callback形式返回。 83 84**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 85 86**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 87 88**系统能力：** SystemCapability.Multimedia.Image.Core 89 90**参数：** 91 92| 参数名 | 类型 | 必填 | 说明 | 93| -------- | -------------------- | ---- | ----------------------------------------------------------------------------------------------------- | 94| dst | ArrayBuffer | 是 | 缓冲区，函数执行结束后获取的图像像素数据写入到该内存区域内。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 95| callback | AsyncCallback\<void> | 是 | 回调函数。当读取像素数据到ArrayBuffer成功，err为undefined，否则为错误对象。 | 96 97**示例：** 98 99```ts 100import { BusinessError } from '@kit.BasicServicesKit'; 101 102async function ReadPixelsToBuffer(pixelMap : image.PixelMap) { 103 const readBuffer: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 104 if (pixelMap != undefined) { 105 pixelMap.readPixelsToBuffer(readBuffer, (error: BusinessError, res: void) => { 106 if(error) { 107 console.error(`Failed to read image pixel data. code is ${error.code}, message is ${error.message}`);// 不符合条件则进入。 108 return; 109 } else { 110 console.info('Succeeded in reading image pixel data.'); // 符合条件则进入。 111 } 112 }) 113 } 114} 115``` 116 117## readPixelsToBufferSync<sup>12+</sup> 118 119readPixelsToBufferSync(dst: ArrayBuffer): void 120 121按照PixelMap的像素格式，读取PixelMap的图像像素数据，并写入缓冲区中，同步返回结果。 122 123**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 124 125**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 126 127**系统能力：** SystemCapability.Multimedia.Image.Core 128 129**参数：** 130 131| 参数名 | 类型 | 必填 | 说明 | 132| -------- | -------------------- | ---- | ----------------------------------------------------------------------------------------------------- | 133| dst | ArrayBuffer | 是 | 缓冲区，函数执行结束后获取的图像像素数据写入到该内存区域内。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 134 135**错误码：** 136 137以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 138 139| 错误码ID | 错误信息 | 140| ------- | --------------------------------------------| 141| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 142| 501 | Resource Unavailable | 143 144**示例：** 145 146```ts 147function ReadPixelsToBufferSync(pixelMap : image.PixelMap) { 148 const bufferSize = pixelMap.getPixelBytesNumber(); 149 const readBuffer = new ArrayBuffer(bufferSize); 150 if (pixelMap != undefined) { 151 pixelMap.readPixelsToBufferSync(readBuffer); 152 } 153} 154``` 155 156## readPixels<sup>7+</sup> 157 158readPixels(area: PositionArea): Promise\<void> 159 160固定按照BGRA_8888格式，读取PixelMap指定区域内的图像像素数据，并写入[PositionArea](arkts-apis-image-i.md#positionarea7).pixels缓冲区中，该区域由[PositionArea](arkts-apis-image-i.md#positionarea7).region指定，使用Promise形式返回。 161 162可用公式计算PositionArea需要申请的内存大小。 163 164YUV的区域计算公式：读取区域（region.size{width * height}）* 1.5 （1倍的Y分量+0.25倍U分量+0.25倍V分量） 165 166RGBA的区域计算公式：读取区域（region.size{width * height}）* 4 （1倍的R分量+1倍G分量+1倍B分量+1倍A分量） 167 168**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 169 170**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 171 172**系统能力：** SystemCapability.Multimedia.Image.Core 173 174**参数：** 175 176| 参数名 | 类型 | 必填 | 说明 | 177| ------ | ------------------------------ | ---- | ------------------------ | 178| area | [PositionArea](arkts-apis-image-i.md#positionarea7) | 是 | 区域大小，根据区域读取。 | 179 180**返回值：** 181 182| 类型 | 说明 | 183| :------------- | :-------------------------------------------------- | 184| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 185 186**示例：** 187 188```ts 189import { BusinessError } from '@kit.BasicServicesKit'; 190 191async function ReadPixelsRGBA(pixelMap : image.PixelMap) { 192 const area: image.PositionArea = { 193 pixels: new ArrayBuffer(8), // 8为需要创建的像素buffer大小，取值为：height * width *4。 194 offset: 0, 195 stride: 8, 196 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 197 }; 198 if (pixelMap != undefined) { 199 pixelMap.readPixels(area).then(() => { 200 console.info('Succeeded in reading the image data in the area.'); // 符合条件则进入。 201 console.info('RGBA data is ', new Uint8Array(area.pixels)); 202 }).catch((error: BusinessError) => { 203 console.error(`Failed to read the image data in the area. code is ${error.code}, message is ${error.message}`);// 不符合条件则进入。 204 }) 205 } 206} 207 208async function ReadPixelsYUV(pixelMap : image.PixelMap) { 209 const area: image.PositionArea = { 210 pixels: new ArrayBuffer(6), // 6为需要创建的像素buffer大小，取值为：height * width *1.5。 211 offset: 0, 212 stride: 8, 213 region: { size: { height: 2, width: 2 }, x: 0, y: 0 } 214 }; 215 if (pixelMap != undefined) { 216 pixelMap.readPixels(area).then(() => { 217 console.info('Succeeded in reading the image data in the area.'); // 符合条件则进入。 218 console.info('YUV data is ', new Uint8Array(area.pixels)); 219 }).catch((error: BusinessError) => { 220 console.error(`Failed to read the image data in the area. code is ${error.code}, message is ${error.message}`);// 不符合条件则进入。 221 }) 222 } 223} 224``` 225 226## readPixels<sup>7+</sup> 227 228readPixels(area: PositionArea, callback: AsyncCallback\<void>): void 229 230固定按照BGRA_8888格式，读取PixelMap指定区域内的图像像素数据，并写入[PositionArea](arkts-apis-image-i.md#positionarea7).pixels缓冲区中，该区域由[PositionArea](arkts-apis-image-i.md#positionarea7).region指定，使用callback形式返回。 231 232可用公式计算PositionArea需要申请的内存大小。 233 234YUV的区域计算公式：读取区域（region.size{width * height}）* 1.5 （1倍的Y分量+0.25倍U分量+0.25倍V分量） 235 236RGBA的区域计算公式：读取区域（region.size{width * height}）* 4 （1倍的R分量+1倍G分量+1倍B分量+1倍A分量） 237 238**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 239 240**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 241 242**系统能力：** SystemCapability.Multimedia.Image.Core 243 244**参数：** 245 246| 参数名 | 类型 | 必填 | 说明 | 247| -------- | ------------------------------ | ---- | ------------------------------ | 248| area | [PositionArea](arkts-apis-image-i.md#positionarea7) | 是 | 区域大小，根据区域读取。 | 249| callback | AsyncCallback\<void> | 是 | 回调函数。当读取区域内的图片数据成功，err为undefined，否则为错误对象。 | 250 251**示例：** 252 253```ts 254import { BusinessError } from '@kit.BasicServicesKit'; 255 256async function ReadPixelsRGBA(pixelMap : image.PixelMap) { 257 const area: image.PositionArea = { 258 pixels: new ArrayBuffer(8), // 8为需要创建的像素buffer大小，取值为：height * width *4。 259 offset: 0, 260 stride: 8, 261 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 262 }; 263 if (pixelMap != undefined) { 264 pixelMap.readPixels(area, (error: BusinessError) => { 265 if (error) { 266 console.error(`Failed to read pixelmap from the specified area. code is ${error.code}, message is ${error.message}`); 267 return; 268 } else { 269 console.info('Succeeded in reading pixelmap from the specified area.'); 270 console.info('RGBA data is ', new Uint8Array(area.pixels)); 271 } 272 }) 273 } 274} 275 276async function ReadPixelsYUV(pixelMap : image.PixelMap) { 277 const area: image.PositionArea = { 278 pixels: new ArrayBuffer(6), // 6为需要创建的像素buffer大小，取值为：height * width *1.5。 279 offset: 0, 280 stride: 8, 281 region: { size: { height: 2, width: 2 }, x: 0, y: 0 } 282 }; 283 if (pixelMap != undefined) { 284 pixelMap.readPixels(area, (error: BusinessError) => { 285 if (error) { 286 console.error(`Failed to read pixelmap from the specified area. code is ${error.code}, message is ${error.message}`); 287 return; 288 } else { 289 console.info('Succeeded in reading pixelmap from the specified area.'); 290 console.info('YUV data is ', new Uint8Array(area.pixels)); 291 } 292 }) 293 } 294} 295``` 296 297## readPixelsSync<sup>12+</sup> 298 299readPixelsSync(area: PositionArea): void 300 301固定按照BGRA_8888格式，读取PixelMap指定区域内的图像像素数据，并写入[PositionArea](arkts-apis-image-i.md#positionarea7).pixels缓冲区中，该区域由[PositionArea](arkts-apis-image-i.md#positionarea7).region指定，同步返回结果。 302 303**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 304 305**系统能力：** SystemCapability.Multimedia.Image.Core 306 307**参数：** 308 309| 参数名 | 类型 | 必填 | 说明 | 310| ------ | ------------------------------ | ---- | ------------------------ | 311| area | [PositionArea](arkts-apis-image-i.md#positionarea7) | 是 | 区域大小，根据区域读取。 | 312 313**错误码：** 314 315以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 316 317| 错误码ID | 错误信息 | 318| ------- | --------------------------------------------| 319| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 320| 501 | Resource Unavailable | 321 322**示例：** 323 324```ts 325function ReadPixelsSync(pixelMap : image.PixelMap) { 326 const area : image.PositionArea = { 327 pixels: new ArrayBuffer(8), 328 offset: 0, 329 stride: 8, 330 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 331 }; 332 if (pixelMap != undefined) { 333 pixelMap.readPixelsSync(area); 334 } 335} 336``` 337 338## writePixels<sup>7+</sup> 339 340writePixels(area: PositionArea): Promise\<void> 341 342固定按照BGRA_8888格式，读取[PositionArea](arkts-apis-image-i.md#positionarea7).pixels缓冲区中的图像像素数据，并写入PixelMap指定区域内，该区域由[PositionArea](arkts-apis-image-i.md#positionarea7).region指定，使用Promise形式返回。 343 344可用公式计算PositionArea需要申请的内存大小。 345 346YUV的区域计算公式：读取区域（region.size{width * height}）* 1.5 （1倍的Y分量+0.25倍U分量+0.25倍V分量） 347 348RGBA的区域计算公式：读取区域（region.size{width * height}）* 4 （1倍的R分量+1倍G分量+1倍B分量+1倍A分量） 349 350**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 351 352**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 353 354**系统能力：** SystemCapability.Multimedia.Image.Core 355 356**参数：** 357 358| 参数名 | 类型 | 必填 | 说明 | 359| ------ | ------------------------------ | ---- | -------------------- | 360| area | [PositionArea](arkts-apis-image-i.md#positionarea7) | 是 | 区域，根据区域写入。 | 361 362**返回值：** 363 364| 类型 | 说明 | 365| :------------- | :-------------------------------------------------- | 366| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 367 368**示例：** 369 370```ts 371import { BusinessError } from '@kit.BasicServicesKit'; 372 373async function WritePixelsRGBA(pixelMap:image.PixelMap) { 374 const area: image.PositionArea = { 375 pixels: new ArrayBuffer(8), // 8为需要创建的像素buffer大小，取值为：height * width *4。 376 offset: 0, 377 stride: 8, 378 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 379 }; 380 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 381 for (let i = 0; i < bufferArr.length; i++) { 382 bufferArr[i] = i + 1; 383 } 384 if (pixelMap != undefined) { 385 pixelMap.writePixels(area).then(() => { 386 console.info('Succeeded in writing pixelmap into the specified area.'); 387 }).catch((error: BusinessError) => { 388 console.error(`Failed to write pixelmap into the specified area. code is ${error.code}, message is ${error.message}`); 389 }) 390 } 391} 392 393async function WritePixelsYUV(pixelMap:image.PixelMap) { 394 const area: image.PositionArea = { 395 pixels: new ArrayBuffer(6), // 6为需要创建的像素buffer大小，取值为：height * width *1.5。 396 offset: 0, 397 stride: 8, // PixelMap为yuv格式时，writePixels函数不使用该变量。 398 region: { size: { height: 2, width: 2 }, x: 0, y: 0 } 399 }; 400 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 401 for (let i = 0; i < bufferArr.length; i++) { 402 bufferArr[i] = i + 1; 403 } 404 if (pixelMap != undefined) { 405 pixelMap.writePixels(area).then(() => { 406 console.info('Succeeded in writing pixelmap into the specified area.'); 407 }).catch((error: BusinessError) => { 408 console.error(`Failed to write pixelmap into the specified area. code is ${error.code}, message is ${error.message}`); 409 }) 410 } 411} 412``` 413 414## writePixels<sup>7+</sup> 415 416writePixels(area: PositionArea, callback: AsyncCallback\<void>): void 417 418固定按照BGRA_8888格式，读取[PositionArea](arkts-apis-image-i.md#positionarea7).pixels缓冲区中的图像像素数据，并写入PixelMap指定区域内，该区域由[PositionArea](arkts-apis-image-i.md#positionarea7).region指定，使用callback形式返回。 419 420可用公式计算PositionArea需要申请的内存大小。 421 422YUV的区域计算公式：读取区域（region.size{width * height}）* 1.5 （1倍的Y分量+0.25倍U分量+0.25倍V分量） 423 424RGBA的区域计算公式：读取区域（region.size{width * height}）* 4 （1倍的R分量+1倍G分量+1倍B分量+1倍A分量） 425 426**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 427 428**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 429 430**系统能力：** SystemCapability.Multimedia.Image.Core 431 432**参数：** 433 434| 参数名 | 类型 | 必填 | 说明 | 435| --------- | ------------------------------ | ---- | ------------------------------ | 436| area | [PositionArea](arkts-apis-image-i.md#positionarea7) | 是 | 区域，根据区域写入。 | 437| callback | AsyncCallback\<void> | 是 | 回调函数，当写入成功，err为undefined，否则为错误对象。 | 438 439**示例：** 440 441```ts 442import { BusinessError } from '@kit.BasicServicesKit'; 443 444async function WritePixelsRGBA(pixelMap:image.PixelMap) { 445 const area: image.PositionArea = { pixels: new ArrayBuffer(8), // 8为需要创建的像素buffer大小，取值为：height * width *4。 446 offset: 0, 447 stride: 8, 448 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 449 }; 450 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 451 for (let i = 0; i < bufferArr.length; i++) { 452 bufferArr[i] = i + 1; 453 } 454 if (pixelMap != undefined) { 455 pixelMap.writePixels(area, (error : BusinessError) => { 456 if (error) { 457 console.error(`Failed to write pixelmap into the specified area. code is ${error.code}, message is ${error.message}`); 458 return; 459 } else { 460 console.info('Succeeded in writing pixelmap into the specified area.'); 461 } 462 }) 463 } 464} 465 466async function WritePixelsYUV(pixelMap:image.PixelMap) { 467 const area: image.PositionArea = { pixels: new ArrayBuffer(6), // 6为需要创建的像素buffer大小，取值为：height * width *1.5。 468 offset: 0, 469 stride: 8, // PixelMap为yuv格式时，writePixels函数不使用该变量。 470 region: { size: { height: 2, width: 2 }, x: 0, y: 0 } 471 }; 472 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 473 for (let i = 0; i < bufferArr.length; i++) { 474 bufferArr[i] = i + 1; 475 } 476 if (pixelMap != undefined) { 477 pixelMap.writePixels(area, (error : BusinessError) => { 478 if (error) { 479 console.error(`Failed to write pixelmap into the specified area. code is ${error.code}, message is ${error.message}`); 480 return; 481 } else { 482 console.info('Succeeded in writing pixelmap into the specified area.'); 483 } 484 }) 485 } 486} 487``` 488 489## writePixelsSync<sup>12+</sup> 490 491writePixelsSync(area: PositionArea): void 492 493固定按照BGRA_8888格式，读取[PositionArea](arkts-apis-image-i.md#positionarea7).pixels缓冲区中的图像像素数据，并写入PixelMap指定区域内，该区域由[PositionArea](arkts-apis-image-i.md#positionarea7).region指定，同步返回结果。 494 495**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 496 497**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 498 499**系统能力：** SystemCapability.Multimedia.Image.Core 500 501**参数：** 502 503| 参数名 | 类型 | 必填 | 说明 | 504| ------ | ------------------------------ | ---- | -------------------- | 505| area | [PositionArea](arkts-apis-image-i.md#positionarea7) | 是 | 区域，根据区域写入。 | 506 507**错误码：** 508 509以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 510 511| 错误码ID | 错误信息 | 512| ------- | --------------------------------------------| 513| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 514| 501 | Resource Unavailable | 515 516**示例：** 517 518```ts 519function WritePixelsSync(pixelMap:image.PixelMap) { 520 const area: image.PositionArea = { 521 pixels: new ArrayBuffer(8), 522 offset: 0, 523 stride: 8, 524 region: { size: { height: 1, width: 2 }, x: 0, y: 0 } 525 }; 526 let bufferArr: Uint8Array = new Uint8Array(area.pixels); 527 for (let i = 0; i < bufferArr.length; i++) { 528 bufferArr[i] = i + 1; 529 } 530 if (pixelMap != undefined) { 531 pixelMap.writePixelsSync(area); 532 } 533} 534``` 535 536## writeBufferToPixels<sup>7+</sup> 537 538writeBufferToPixels(src: ArrayBuffer): Promise\<void> 539 540按照PixelMap的像素格式，读取缓冲区中的图像像素数据，并写入PixelMap，使用Promise形式返回。 541 542**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 543 544**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 545 546**系统能力：** SystemCapability.Multimedia.Image.Core 547 548**参数：** 549 550| 参数名 | 类型 | 必填 | 说明 | 551| ------ | ----------- | ---- | -------------- | 552| src | ArrayBuffer | 是 | 缓冲区，函数执行时会将该缓冲区中的图像像素数据写入到PixelMap。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 553 554**返回值：** 555 556| 类型 | 说明 | 557| -------------- | ----------------------------------------------- | 558| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 559 560**示例：** 561 562```ts 563import { BusinessError } from '@kit.BasicServicesKit'; 564 565async function WriteBufferToPixels(pixelMap:image.PixelMap) { 566 const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 567 let bufferArr: Uint8Array = new Uint8Array(color); 568 for (let i = 0; i < bufferArr.length; i++) { 569 bufferArr[i] = i + 1; 570 } 571 if (pixelMap != undefined) { 572 pixelMap.writeBufferToPixels(color).then(() => { 573 console.info("Succeeded in writing data from a buffer to a PixelMap."); 574 }).catch((error: BusinessError) => { 575 console.error(`Failed to write data from a buffer to a PixelMap. code is ${error.code}, message is ${error.message}`); 576 }) 577 } 578} 579``` 580 581## writeBufferToPixels<sup>7+</sup> 582 583writeBufferToPixels(src: ArrayBuffer, callback: AsyncCallback\<void>): void 584 585按照PixelMap的像素格式，读取缓冲区中的图像像素数据，并写入PixelMap，使用callback形式返回。 586 587**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 588 589**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 590 591**系统能力：** SystemCapability.Multimedia.Image.Core 592 593**参数：** 594 595| 参数名 | 类型 | 必填 | 说明 | 596| -------- | -------------------- | ---- | ------------------------------ | 597| src | ArrayBuffer | 是 | 缓冲区，函数执行时会将该缓冲区中的图像像素数据写入到PixelMap。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 598| callback | AsyncCallback\<void> | 是 | 回调函数。当缓冲区中的图像像素数据写入PixelMap成功，err为undefined，否则为错误对象。 | 599 600**示例：** 601 602```ts 603import { BusinessError } from '@kit.BasicServicesKit'; 604 605async function WriteBufferToPixels(pixelMap:image.PixelMap) { 606 const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 607 let bufferArr: Uint8Array = new Uint8Array(color); 608 for (let i = 0; i < bufferArr.length; i++) { 609 bufferArr[i] = i + 1; 610 } 611 if (pixelMap != undefined) { 612 pixelMap.writeBufferToPixels(color, (error: BusinessError) => { 613 if (error) { 614 console.error(`Failed to write data from a buffer to a PixelMap. code is ${error.code}, message is ${error.message}`); 615 return; 616 } else { 617 console.info("Succeeded in writing data from a buffer to a PixelMap."); 618 } 619 }) 620 } 621} 622``` 623 624## writeBufferToPixelsSync<sup>12+</sup> 625 626writeBufferToPixelsSync(src: ArrayBuffer): void 627 628按照PixelMap的像素格式，读取缓冲区中的图像像素数据，并写入PixelMap，同步返回结果。 629 630**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 631 632**系统能力：** SystemCapability.Multimedia.Image.Core 633 634**参数：** 635 636| 参数名 | 类型 | 必填 | 说明 | 637| ------ | ----------- | ---- | -------------- | 638| src | ArrayBuffer | 是 | 缓冲区，函数执行时会将该缓冲区中的图像像素数据写入到PixelMap。缓冲区大小由[getPixelBytesNumber](#getpixelbytesnumber7)接口获取。 | 639 640**错误码：** 641 642以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 643 644| 错误码ID | 错误信息 | 645| ------- | --------------------------------------------| 646| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 647| 501 | Resource Unavailable | 648 649**示例：** 650 651```ts 652function WriteBufferToPixelsSync(pixelMap:image.PixelMap) { 653 const color : ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 654 let bufferArr : Uint8Array = new Uint8Array(color); 655 for (let i = 0; i < bufferArr.length; i++) { 656 bufferArr[i] = i + 1; 657 } 658 if (pixelMap != undefined) { 659 pixelMap.writeBufferToPixelsSync(color); 660 } 661} 662``` 663 664 665## getImageInfo<sup>7+</sup> 666 667getImageInfo(): Promise\<ImageInfo> 668 669获取图像像素信息，使用Promise形式返回获取的图像像素信息。 670 671**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 672 673**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 674 675**系统能力：** SystemCapability.Multimedia.Image.Core 676 677**返回值：** 678 679| 类型 | 说明 | 680| --------------------------------- | ----------------------------------------------------------- | 681| Promise\<[ImageInfo](arkts-apis-image-i.md#imageinfo)> | Promise对象，返回图像像素信息。 | 682 683**示例：** 684 685```ts 686import { BusinessError } from '@kit.BasicServicesKit'; 687 688async function GetImageInfo(pixelMap: image.PixelMap) { 689 if (pixelMap != undefined) { 690 pixelMap.getImageInfo().then((imageInfo: image.ImageInfo) => { 691 if (imageInfo != undefined) { 692 console.info(`Succeeded in obtaining the image pixel map information ${imageInfo.size.height}`); 693 } 694 }).catch((error: BusinessError) => { 695 console.error(`Failed to obtain the image pixel map information. code is ${error.code}, message is ${error.message}`); 696 }) 697 } 698} 699``` 700 701## getImageInfo<sup>7+</sup> 702 703getImageInfo(callback: AsyncCallback\<ImageInfo>): void 704 705获取图像像素信息，使用callback形式返回获取的图像像素信息。 706 707**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 708 709**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 710 711**系统能力：** SystemCapability.Multimedia.Image.Core 712 713**参数：** 714 715| 参数名 | 类型 | 必填 | 说明 | 716| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 717| callback | AsyncCallback\<[ImageInfo](arkts-apis-image-i.md#imageinfo)> | 是 | 回调函数。当获取图像像素信息成功，err为undefined，data为获取到的图像像素信息；否则为错误对象。 | 718 719**示例:** 720 721```ts 722import { BusinessError } from '@kit.BasicServicesKit'; 723 724function GetImageInfoSync(pixelMap : image.PixelMap){ 725 if (pixelMap != undefined) { 726 pixelMap.getImageInfo((error: BusinessError, imageInfo: image.ImageInfo) => { 727 if (error) { 728 console.error(`Failed to obtain the image pixel map information. code is ${error.code}, message is ${error.message}`); 729 return; 730 } else { 731 console.info(`Succeeded in obtaining the image pixel map information ${imageInfo.size.height}`); 732 } 733 }) 734 } 735} 736``` 737 738## getImageInfoSync<sup>12+</sup> 739 740getImageInfoSync(): ImageInfo 741 742以同步方法获取图像像素信息。 743 744**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 745 746**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 747 748**系统能力：** SystemCapability.Multimedia.Image.ImageSource 749 750**返回值：** 751 752| 类型 | 说明 | 753| --------------------------------- | ----------------------------------------------------------- | 754| [ImageInfo](arkts-apis-image-i.md#imageinfo) | 图像像素信息。 | 755 756**错误码：** 757 758以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 759 760| 错误码ID | 错误信息 | 761| ------- | --------------------------------------------| 762| 501 | Resource Unavailable | 763 764**示例：** 765 766```ts 767function GetImageInfoSync(pixelMap:image.PixelMap) { 768 if (pixelMap != undefined) { 769 let imageInfo : image.ImageInfo = pixelMap.getImageInfoSync(); 770 return imageInfo; 771 } 772 return undefined; 773} 774``` 775 776## getBytesNumberPerRow<sup>7+</sup> 777 778getBytesNumberPerRow(): number 779 780获取图像像素每行字节数。 781 782**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 783 784**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 785 786**系统能力：** SystemCapability.Multimedia.Image.Core 787 788**返回值：** 789 790| 类型 | 说明 | 791| ------ | -------------------- | 792| number | 图像像素的行字节数。 | 793 794**示例：** 795 796```ts 797function GetBytesNumberPerRow(pixelMap: image.PixelMap) { 798 let rowCount: number = pixelMap.getBytesNumberPerRow(); 799} 800``` 801 802## getPixelBytesNumber<sup>7+</sup> 803 804getPixelBytesNumber(): number 805 806获取图像像素的总字节数。 807 808**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 809 810**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 811 812**系统能力：** SystemCapability.Multimedia.Image.Core 813 814**返回值：** 815 816| 类型 | 说明 | 817| ------ | -------------------- | 818| number | 图像像素的总字节数。 | 819 820**示例：** 821 822```ts 823function GetPixelBytesNumber(pixelMap: image.PixelMap) { 824 let pixelBytesNumber: number = pixelMap.getPixelBytesNumber(); 825} 826``` 827 828## getDensity<sup>9+</sup> 829 830getDensity():number 831 832获取当前图像像素的密度。 833 834**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 835 836**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 837 838**系统能力：** SystemCapability.Multimedia.Image.Core 839 840**返回值：** 841 842| 类型 | 说明 | 843| ------ | --------------- | 844| number | 图像像素的密度，单位为ppi。| 845 846**示例：** 847 848```ts 849function GetDensity(pixelMap: image.PixelMap) { 850 let getDensity: number = pixelMap.getDensity(); 851} 852``` 853 854## opacity<sup>9+</sup> 855 856opacity(rate: number, callback: AsyncCallback\<void>): void 857 858通过设置透明比率来让PixelMap达到对应的透明效果，yuv图片不支持设置透明度，使用callback形式返回。 859 860**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 861 862**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 863 864**系统能力：** SystemCapability.Multimedia.Image.Core 865 866**参数：** 867 868| 参数名 | 类型 | 必填 | 说明 | 869| -------- | -------------------- | ---- | ------------------------------ | 870| rate | number | 是 | 透明比率的值，取值范围是(0,1]。 | 871| callback | AsyncCallback\<void> | 是 | 回调函数。当设置透明比率成功，err为undefined，否则为错误对象。 | 872 873**示例：** 874 875```ts 876import { BusinessError } from '@kit.BasicServicesKit'; 877 878async function Opacity(pixelMap:image.PixelMap) { 879 let rate: number = 0.5; 880 if (pixelMap != undefined) { 881 pixelMap.opacity(rate, (err: BusinessError) => { 882 if (err) { 883 console.error(`Failed to set opacity. code is ${err.code}, message is ${err.message}`); 884 return; 885 } else { 886 console.info("Succeeded in setting opacity."); 887 } 888 }) 889 } 890} 891``` 892 893## opacity<sup>9+</sup> 894 895opacity(rate: number): Promise\<void> 896 897通过设置透明比率来让PixelMap达到对应的透明效果，yuv图片不支持设置透明度，使用Promise形式返回。 898 899**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 900 901**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 902 903**系统能力：** SystemCapability.Multimedia.Image.Core 904 905**参数：** 906 907| 参数名 | 类型 | 必填 | 说明 | 908| ------ | ------ | ---- | --------------------------- | 909| rate | number | 是 | 透明比率的值，取值范围是(0,1]。| 910 911**返回值：** 912 913| 类型 | 说明 | 914| -------------- | ----------------------------------------------- | 915| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 916 917**示例：** 918 919```ts 920import { BusinessError } from '@kit.BasicServicesKit'; 921 922async function Opacity(pixelMap:image.PixelMap) { 923 let rate: number = 0.5; 924 if (pixelMap != undefined) { 925 pixelMap.opacity(rate).then(() => { 926 console.info('Succeeded in setting opacity.'); 927 }).catch((err: BusinessError) => { 928 console.error(`Failed to set opacity. code is ${err.code}, message is ${err.message}`); 929 }) 930 } 931} 932``` 933 934## opacitySync<sup>12+</sup> 935 936opacitySync(rate: number): void 937 938设置PixelMap的透明比率，yuv图片不支持设置透明度，初始化PixelMap并同步返回结果。 939 940**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 941 942**系统能力：** SystemCapability.Multimedia.Image.Core 943 944**参数：** 945 946| 参数名 | 类型 | 必填 | 说明 | 947| -------- | -------------------- | ---- | ------------------------------ | 948| rate | number | 是 | 透明比率的值，取值范围是(0,1]。 | 949 950**错误码：** 951 952以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 953 954| 错误码ID | 错误信息 | 955| ------- | --------------------------------------------| 956| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 957| 501 | Resource Unavailable | 958 959**示例：** 960 961```ts 962function OpacitySync(pixelMap:image.PixelMap) { 963 let rate : number = 0.5; 964 if (pixelMap != undefined) { 965 pixelMap.opacitySync(rate); 966 } 967} 968``` 969 970## createAlphaPixelmap<sup>9+</sup> 971 972createAlphaPixelmap(): Promise\<PixelMap> 973 974根据Alpha通道的信息，来生成一个仅包含Alpha通道信息的pixelmap，可用于阴影效果，yuv格式不支持此接口，使用Promise形式返回。 975 976**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 977 978**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 979 980**系统能力：** SystemCapability.Multimedia.Image.Core 981 982**返回值：** 983 984| 类型 | 说明 | 985| -------------------------------- | --------------------------- | 986| Promise\<[PixelMap](arkts-apis-image-PixelMap.md)> | Promise对象，返回PixelMap。 | 987 988**示例：** 989 990```ts 991import { BusinessError } from '@kit.BasicServicesKit'; 992 993async function CreateAlphaPixelmap(pixelMap:image.PixelMap) { 994 if (pixelMap != undefined) { 995 pixelMap.createAlphaPixelmap().then((alphaPixelMap: image.PixelMap) => { 996 console.info('Succeeded in creating alpha pixelmap.'); 997 }).catch((error: BusinessError) => { 998 console.error(`Failed to create alpha pixelmap. code is ${error.code}, message is ${error.message}`); 999 }) 1000 } 1001} 1002``` 1003 1004## createAlphaPixelmap<sup>9+</sup> 1005 1006createAlphaPixelmap(callback: AsyncCallback\<PixelMap>): void 1007 1008根据Alpha通道的信息，来生成一个仅包含Alpha通道信息的pixelmap，可用于阴影效果，yuv格式不支持此接口，使用callback形式返回。 1009 1010**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1011 1012**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1013 1014**系统能力：** SystemCapability.Multimedia.Image.Core 1015 1016**参数：** 1017 1018| 参数名 | 类型 | 必填 | 说明 | 1019| -------- | ------------------------ | ---- | ------------------------ | 1020| callback | AsyncCallback\<[PixelMap](arkts-apis-image-PixelMap.md)> | 是 | 回调函数，当创建PixelMap成功，err为undefined，data为获取到的PixelMap对象；否则为错误对象。 | 1021 1022**示例：** 1023 1024```ts 1025import { BusinessError } from '@kit.BasicServicesKit'; 1026 1027async function CreateAlphaPixelmap(pixelMap:image.PixelMap) { 1028 if (pixelMap != undefined) { 1029 pixelMap.createAlphaPixelmap((err: BusinessError, alphaPixelMap: image.PixelMap) => { 1030 if (alphaPixelMap == undefined) { 1031 console.error(`Failed to obtain new pixel map. code is ${err.code}, message is ${err.message}`); 1032 return; 1033 } else { 1034 console.info('Succeeded in obtaining new pixel map.'); 1035 } 1036 }) 1037 } 1038} 1039``` 1040 1041## createAlphaPixelmapSync<sup>12+</sup> 1042 1043createAlphaPixelmapSync(): PixelMap 1044 1045根据Alpha通道的信息，生成一个仅包含Alpha通道信息的PixelMap，可用于阴影效果，yuv格式不支持此接口，同步返回PixelMap类型的结果。 1046 1047**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1048 1049**系统能力：** SystemCapability.Multimedia.Image.Core 1050 1051**返回值：** 1052 1053| 类型 | 说明 | 1054| -------------------------------- | --------------------- | 1055| [PixelMap](arkts-apis-image-PixelMap.md) | 成功同步返回PixelMap对象，失败抛出异常。 | 1056 1057**错误码：** 1058 1059以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1060 1061| 错误码ID | 错误信息 | 1062| ------- | --------------------------------------------| 1063| 401 | Parameter error. Possible causes: 1.Parameter verification failed | 1064| 501 | Resource Unavailable | 1065 1066**示例：** 1067 1068```ts 1069function CreateAlphaPixelmapSync(pixelMap:image.PixelMap) { 1070 if (pixelMap != undefined) { 1071 let pixelmap : image.PixelMap = pixelMap.createAlphaPixelmapSync(); 1072 return pixelmap; 1073 } 1074 return undefined; 1075} 1076``` 1077 1078## scale<sup>9+</sup> 1079 1080scale(x: number, y: number, callback: AsyncCallback\<void>): void 1081 1082根据输入的宽高的缩放倍数对图片进行缩放，使用callback形式返回。 1083 1084> **说明：** 1085> 1086> 1. 建议宽高的缩放倍数取非负数，否则会产生翻转效果。 1087> 2. 宽高的缩放倍数 = 缩放后的图片宽高 / 缩放前的图片宽高。 1088 1089**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1090 1091**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1092 1093**系统能力：** SystemCapability.Multimedia.Image.Core 1094 1095**参数：** 1096 1097| 参数名 | 类型 | 必填 | 说明 | 1098| -------- | -------------------- | ---- | ------------------------------- | 1099| x | number | 是 | 宽度的缩放倍数。| 1100| y | number | 是 | 高度的缩放倍数。| 1101| callback | AsyncCallback\<void> | 是 | 回调函数。当对图片进行缩放成功，err为undefined，否则为错误对象。 | 1102 1103**示例：** 1104 1105```ts 1106import { BusinessError } from '@kit.BasicServicesKit'; 1107 1108async function Scale(pixelMap:image.PixelMap) { 1109 let scaleX: number = 2.0; 1110 let scaleY: number = 1.0; 1111 if (pixelMap != undefined) { 1112 pixelMap.scale(scaleX, scaleY, (err: BusinessError) => { 1113 if (err) { 1114 console.error(`Failed to scale pixelmap. code is ${err.code}, message is ${err.message}`); 1115 return; 1116 } else { 1117 console.info("Succeeded in scaling pixelmap."); 1118 } 1119 }) 1120 } 1121} 1122``` 1123 1124## scale<sup>9+</sup> 1125 1126scale(x: number, y: number): Promise\<void> 1127 1128根据输入的宽高的缩放倍数对图片进行缩放，使用Promise形式返回。 1129 1130> **说明：** 1131> 1132> 1. 建议宽高的缩放倍数取非负数，否则会产生翻转效果。 1133> 2. 宽高的缩放倍数 = 缩放后的图片宽高 / 缩放前的图片宽高。 1134 1135**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1136 1137**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1138 1139**系统能力：** SystemCapability.Multimedia.Image.Core 1140 1141**参数：** 1142 1143| 参数名 | 类型 | 必填 | 说明 | 1144| ------ | ------ | ---- | ------------------------------- | 1145| x | number | 是 | 宽度的缩放倍数。| 1146| y | number | 是 | 高度的缩放倍数。| 1147 1148**返回值：** 1149 1150| 类型 | 说明 | 1151| -------------- | --------------------------- | 1152| Promise\<void> | Promise对象。无返回结果的Promise对象。| 1153 1154**示例：** 1155 1156```ts 1157import { BusinessError } from '@kit.BasicServicesKit'; 1158 1159async function Scale(pixelMap:image.PixelMap) { 1160 let scaleX: number = 2.0; 1161 let scaleY: number = 1.0; 1162 if (pixelMap != undefined) { 1163 pixelMap.scale(scaleX, scaleY).then(() => { 1164 console.info('Succeeded in scaling pixelmap.'); 1165 }).catch((err: BusinessError) => { 1166 console.error(`Failed to scale pixelmap. code is ${err.code}, message is ${err.message}`); 1167 }) 1168 } 1169} 1170``` 1171 1172## scaleSync<sup>12+</sup> 1173 1174scaleSync(x: number, y: number): void 1175 1176根据输入的宽高的缩放倍数对图片进行缩放，同步返回结果。 1177 1178> **说明：** 1179> 1180> 1. 建议宽高的缩放倍数取非负数，否则会产生翻转效果。 1181> 2. 宽高的缩放倍数 = 缩放后的图片宽高 / 缩放前的图片宽高。 1182 1183**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1184 1185**系统能力：** SystemCapability.Multimedia.Image.Core 1186 1187**参数：** 1188 1189| 参数名 | 类型 | 必填 | 说明 | 1190| ------ | ------ | ---- | ------------------------------- | 1191| x | number | 是 | 宽度的缩放倍数。| 1192| y | number | 是 | 高度的缩放倍数。| 1193 1194**错误码：** 1195 1196以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1197 1198| 错误码ID | 错误信息 | 1199| ------- | --------------------------------------------| 1200| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 1201| 501 | Resource Unavailable | 1202 1203**示例：** 1204 1205```ts 1206function ScaleSync(pixelMap: image.PixelMap) { 1207 let scaleX: number = 2.0; 1208 let scaleY: number = 1.0; 1209 if (pixelMap != undefined) { 1210 pixelMap.scaleSync(scaleX, scaleY); 1211 } 1212} 1213``` 1214 1215## scale<sup>12+</sup> 1216 1217scale(x: number, y: number, level: AntiAliasingLevel): Promise\<void> 1218 1219根据指定的缩放算法和输入的宽高的缩放倍数对图片进行缩放，使用Promise形式返回。 1220 1221> **说明：** 1222> 1223> 1. 建议宽高的缩放倍数取非负数，否则会产生翻转效果。 1224> 2. 宽高的缩放倍数 = 缩放后的图片宽高 / 缩放前的图片宽高。 1225 1226**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1227 1228**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1229 1230**系统能力：** SystemCapability.Multimedia.Image.Core 1231 1232**参数：** 1233 1234| 参数名 | 类型 | 必填 | 说明 | 1235| ------ | ------ | ---- | ------------------------------- | 1236| x | number | 是 | 宽度的缩放倍数。| 1237| y | number | 是 | 高度的缩放倍数。| 1238| level | [AntiAliasingLevel](arkts-apis-image-e.md#antialiasinglevel12) | 是 | 采用的缩放算法。| 1239 1240**返回值：** 1241 1242| 类型 | 说明 | 1243| -------------- | --------------------------- | 1244| Promise\<void> | Promise对象。无返回结果的Promise对象。| 1245 1246**错误码：** 1247 1248以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1249 1250| 错误码ID | 错误信息 | 1251| ------- | --------------------------------------------| 1252| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 1253| 501 | Resource Unavailable | 1254 1255**示例：** 1256 1257```ts 1258import { BusinessError } from '@kit.BasicServicesKit'; 1259 1260function ScaleSync(pixelMap:image.PixelMap) { 1261 let scaleX: number = 2.0; 1262 let scaleY: number = 1.0; 1263 if (pixelMap != undefined) { 1264 pixelMap.scale(scaleX, scaleY, image.AntiAliasingLevel.LOW).then(() => { 1265 console.info('Succeeded in scaling pixelmap.'); 1266 }).catch((err: BusinessError) => { 1267 console.error(`Failed to scale pixelmap. code is ${err.code}, message is ${err.message}`); 1268 }) 1269 } 1270} 1271``` 1272 1273## scaleSync<sup>12+</sup> 1274 1275scaleSync(x: number, y: number, level: AntiAliasingLevel): void 1276 1277根据指定的缩放算法和输入的宽高的缩放倍数对图片进行缩放，同步返回结果。 1278 1279> **说明：** 1280> 1281> 1. 建议宽高的缩放倍数取非负数，否则会产生翻转效果。 1282> 2. 宽高的缩放倍数 = 缩放后的图片宽高 / 缩放前的图片宽高。 1283 1284**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1285 1286**系统能力：** SystemCapability.Multimedia.Image.Core 1287 1288**参数：** 1289 1290| 参数名 | 类型 | 必填 | 说明 | 1291| ------ | ------ | ---- | ------------------------------- | 1292| x | number | 是 | 宽度的缩放倍数。| 1293| y | number | 是 | 高度的缩放倍数。| 1294| level | [AntiAliasingLevel](arkts-apis-image-e.md#antialiasinglevel12) | 是 | 采用的缩放算法。| 1295 1296**错误码：** 1297 1298以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1299 1300| 错误码ID | 错误信息 | 1301| ------- | --------------------------------------------| 1302| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 1303| 501 | Resource Unavailable | 1304 1305**示例：** 1306 1307```ts 1308function ScaleSync(pixelMap: image.PixelMap) { 1309 let scaleX: number = 2.0; 1310 let scaleY: number = 1.0; 1311 if (pixelMap != undefined) { 1312 pixelMap.scaleSync(scaleX, scaleY, image.AntiAliasingLevel.LOW); 1313 } 1314} 1315``` 1316 1317## createScaledPixelMap<sup>18+</sup> 1318 1319createScaledPixelMap(x: number, y: number, level?: AntiAliasingLevel): Promise\<PixelMap> 1320 1321根据指定的缩放算法和输入的宽高的缩放倍数，创建一个新的缩放后的图片，使用Promise形式返回。 1322 1323**系统能力：** SystemCapability.Multimedia.Image.Core 1324 1325**参数：** 1326 1327| 参数名 | 类型 | 必填 | 说明 | 1328| ------ | ------ | ---- | ------------------------------- | 1329| x | number | 是 | 宽度的缩放倍数。| 1330| y | number | 是 | 高度的缩放倍数。| 1331| level | [AntiAliasingLevel](arkts-apis-image-e.md#antialiasinglevel12) | 否 | 采用的缩放算法。| 1332 1333**返回值：** 1334 1335| 类型 | 说明 | 1336| -------------- | --------------------------- | 1337| Promise\<[PixelMap](arkts-apis-image-PixelMap.md)> | Promise对象，返回PixelMap。 | 1338 1339**错误码：** 1340 1341以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1342 1343| 错误码ID | 错误信息 | 1344| ------- | --------------------------------------------| 1345| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 1346| 501 | Resource Unavailable | 1347 1348**示例：** 1349 1350```ts 1351import { BusinessError } from '@kit.BasicServicesKit'; 1352 1353async function CreateScaledPixelMap(pixelMap:image.PixelMap) { 1354 let scaleX: number = 2.0; 1355 let scaleY: number = 1.0; 1356 if (pixelMap != undefined) { 1357 pixelMap.createScaledPixelMap(scaleX, scaleY, image.AntiAliasingLevel.LOW).then((scaledPixelMap: image.PixelMap) => { 1358 console.info('Succeeded in creating scaledPixelMap.'); 1359 }).catch((error: BusinessError) => { 1360 console.error(`Failed to create scaledPixelMap. Error code is ${error.code}, error message is ${error.message}`); 1361 }) 1362 } 1363} 1364``` 1365 1366## createScaledPixelMapSync<sup>18+</sup> 1367 1368createScaledPixelMapSync(x: number, y: number, level?: AntiAliasingLevel): PixelMap 1369 1370根据指定的缩放算法和输入的宽高的缩放倍数，创建一个新的缩放后的图片，同步返回结果。 1371 1372**系统能力：** SystemCapability.Multimedia.Image.Core 1373 1374**参数：** 1375 1376| 参数名 | 类型 | 必填 | 说明 | 1377| ------ | ------ | ---- | ------------------------------- | 1378| x | number | 是 | 宽度的缩放倍数。| 1379| y | number | 是 | 高度的缩放倍数。| 1380| level | [AntiAliasingLevel](arkts-apis-image-e.md#antialiasinglevel12) | 否 | 采用的缩放算法。| 1381 1382**返回值：** 1383 1384| 类型 | 说明 | 1385| -------------------------------- | --------------------- | 1386| [PixelMap](arkts-apis-image-PixelMap.md) | 成功同步返回PixelMap对象，失败抛出异常。 | 1387 1388**错误码：** 1389 1390以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1391 1392| 错误码ID | 错误信息 | 1393| ------- | --------------------------------------------| 1394| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 1395| 501 | Resource Unavailable | 1396 1397**示例：** 1398 1399```ts 1400function CreateScaledPixelMapSync(pixelMap:image.PixelMap) { 1401 let scaleX: number = 2.0; 1402 let scaleY: number = 1.0; 1403 if (pixelMap != undefined) { 1404 let scaledPixelMap = pixelMap.createScaledPixelMapSync(scaleX, scaleY, image.AntiAliasingLevel.LOW); 1405 } 1406} 1407``` 1408 1409## clone<sup>18+</sup> 1410 1411clone(): Promise\<PixelMap> 1412 1413拷贝一份当前Pixelmap对象，使用Promise形式返回。 1414 1415**系统能力：**: SystemCapability.Multimedia.Image.Core 1416 1417**返回值：** 1418 1419| 类型 | 说明 | 1420| -------------------------------- | --------------------------- | 1421| Promise\<[PixelMap](arkts-apis-image-PixelMap.md)> | Promise对象，返回PixelMap。| 1422 1423**错误码：** 1424 1425以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1426 1427| 错误码ID | 错误信息 | 1428| ------- | --------------------------------------------| 1429| 501 | Resource unavailable. | 1430| 62980102 | Image malloc abnormal. This status code is thrown when an error occurs during the process of copying data. | 1431| 62980103 | Image YUV And ASTC types are not supported. | 1432| 62980104 | Image initialization abnormal. This status code is thrown when an error occurs during the process of createing empty pixelmap. | 1433| 62980106 | The image data is to large. This status code is thrown when an error occurs during the process of checking size. | 1434 1435**示例：** 1436 1437```ts 1438import { BusinessError } from '@kit.BasicServicesKit'; 1439 1440async function Clone(pixelMap:image.PixelMap) { 1441 if (pixelMap != undefined) { 1442 pixelMap.clone().then((clonePixelMap: image.PixelMap) => { 1443 console.info('Succeeded clone pixelmap.'); 1444 }).catch((error: BusinessError) => { 1445 console.error(`Failed to clone pixelmap. code is ${error.code}, message is ${error.message}`); 1446 }) 1447 } 1448} 1449``` 1450 1451## cloneSync<sup>18+</sup> 1452 1453cloneSync(): PixelMap 1454 1455拷贝一份当前Pixelmap对象, 同步返回结果。 1456 1457**系统能力：**: SystemCapability.Multimedia.Image.Core 1458 1459**返回值：** 1460 1461| 类型 | 说明 | 1462| -------------------------------- | --------------------------- | 1463| [PixelMap](arkts-apis-image-PixelMap.md) | 成功同步返回PixelMap对象，失败抛出异常。 | 1464 1465**错误码：** 1466 1467以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1468 1469| 错误码ID | 错误信息 | 1470| ------- | --------------------------------------------| 1471| 501 | Resource unavailable. | 1472| 62980102 | Image malloc abnormal. This status code is thrown when an error occurs during the process of copying data. | 1473| 62980103 | Image YUV And ASTC types are not supported. | 1474| 62980104 | Image initialization abnormal. This status code is thrown when an error occurs during the process of createing empty pixelmap. | 1475| 62980106 | The image data is to large. This status code is thrown when an error occurs during the process of checking size. | 1476 1477**示例：** 1478 1479```ts 1480import { BusinessError } from '@kit.BasicServicesKit'; 1481 1482function CloneSync(pixelMap: image.PixelMap) { 1483 if (pixelMap != undefined) { 1484 try { 1485 let clonedPixelMap:image.PixelMap = pixelMap.cloneSync(); 1486 } catch(e) { 1487 let error = e as BusinessError; 1488 console.error(`clone pixelmap error. code is ${error.code}, message is ${error.message}`); 1489 } 1490 } 1491} 1492``` 1493 1494## translate<sup>9+</sup> 1495 1496translate(x: number, y: number, callback: AsyncCallback\<void>): void 1497 1498根据输入的坐标对图片进行位置变换，使用callback形式返回。 1499 1500translate后的图片尺寸改变为：width+X ，height+Y，建议translate后的图片尺寸宽高不要超过屏幕的宽高。 1501 1502**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1503 1504**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1505 1506**系统能力：** SystemCapability.Multimedia.Image.Core 1507 1508**参数：** 1509 1510| 参数名 | 类型 | 必填 | 说明 | 1511| -------- | -------------------- | ---- | ----------------------------- | 1512| x | number | 是 | 区域横坐标。单位：像素。 | 1513| y | number | 是 | 区域纵坐标。单位：像素。 | 1514| callback | AsyncCallback\<void> | 是 | 回调函数。当对图片进行位置变换成功，err为undefined，否则为错误对象。| 1515 1516**示例：** 1517 1518```ts 1519import { BusinessError } from '@kit.BasicServicesKit'; 1520 1521async function Translate(pixelMap:image.PixelMap) { 1522 let translateX: number = 50.0; 1523 let translateY: number = 10.0; 1524 if (pixelMap != undefined) { 1525 pixelMap.translate(translateX, translateY, (err: BusinessError) => { 1526 if (err) { 1527 console.error(`Failed to translate pixelmap. code is ${err.code}, message is ${err.message}`); 1528 return; 1529 } else { 1530 console.info("Succeeded in translating pixelmap."); 1531 } 1532 }) 1533 } 1534} 1535``` 1536 1537## translate<sup>9+</sup> 1538 1539translate(x: number, y: number): Promise\<void> 1540 1541根据输入的坐标对图片进行位置变换，使用Promise形式返回。 1542 1543translate后的图片尺寸改变为：width+X ，height+Y，建议translate后的图片尺寸宽高不要超过屏幕的宽高。 1544 1545**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1546 1547**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1548 1549**系统能力：** SystemCapability.Multimedia.Image.Core 1550 1551**参数：** 1552 1553| 参数名 | 类型 | 必填 | 说明 | 1554| ------ | ------ | ---- | ----------- | 1555| x | number | 是 | 区域横坐标。单位：像素。 | 1556| y | number | 是 | 区域纵坐标。单位：像素。 | 1557 1558**返回值：** 1559 1560| 类型 | 说明 | 1561| -------------- | --------------------------- | 1562| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1563 1564**示例：** 1565 1566```ts 1567import { BusinessError } from '@kit.BasicServicesKit'; 1568 1569async function Translate(pixelMap:image.PixelMap) { 1570 let translateX: number = 50.0; 1571 let translateY: number = 10.0; 1572 if (pixelMap != undefined) { 1573 pixelMap.translate(translateX, translateY).then(() => { 1574 console.info('Succeeded in translating pixelmap.'); 1575 }).catch((err: BusinessError) => { 1576 console.error(`Failed to translate pixelmap. code is ${err.code}, message is ${err.message}`); 1577 }) 1578 } 1579} 1580``` 1581 1582## translateSync<sup>12+</sup> 1583 1584translateSync(x: number, y: number): void 1585 1586根据输入的坐标对图片进行位置变换，同步返回结果。 1587 1588translate后的图片尺寸改变为：width+X ，height+Y，建议translate后的图片尺寸宽高不要超过屏幕的宽高。 1589 1590**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1591 1592**系统能力：** SystemCapability.Multimedia.Image.Core 1593 1594**参数：** 1595 1596| 参数名 | 类型 | 必填 | 说明 | 1597| -------- | -------------------- | ---- | ------------------------------- | 1598| x | number | 是 | 区域横坐标。单位：像素。 | 1599| y | number | 是 | 区域纵坐标。单位：像素。 | 1600 1601**错误码：** 1602 1603以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1604 1605| 错误码ID | 错误信息 | 1606| ------- | --------------------------------------------| 1607| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 1608| 501 | Resource Unavailable | 1609 1610**示例：** 1611 1612```ts 1613function TranslateSync(pixelMap:image.PixelMap) { 1614 let translateX : number = 50.0; 1615 let translateY : number = 10.0; 1616 if (pixelMap != undefined) { 1617 pixelMap.translateSync(translateX, translateY); 1618 } 1619} 1620``` 1621 1622## rotate<sup>9+</sup> 1623 1624rotate(angle: number, callback: AsyncCallback\<void>): void 1625 1626根据输入的角度对图片进行旋转，使用callback形式返回。 1627 1628> **说明：** 1629> 1630> 1. 图片旋转的角度取值范围：0-360。超出取值范围时，根据圆周360度自动矫正。例如，-100度与260度效果相同。 1631> 2. 如果图片旋转的角度不是90的整数倍，旋转后图片的尺寸会发生改变。 1632 1633**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1634 1635**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1636 1637**系统能力：** SystemCapability.Multimedia.Image.Core 1638 1639**参数：** 1640 1641| 参数名 | 类型 | 必填 | 说明 | 1642| -------- | -------------------- | ---- | ----------------------------- | 1643| angle | number | 是 | 图片旋转的角度。 | 1644| callback | AsyncCallback\<void> | 是 | 回调函数。当对图片进行旋转成功，err为undefined，否则为错误对象。| 1645 1646**示例：** 1647 1648```ts 1649import { BusinessError } from '@kit.BasicServicesKit'; 1650 1651async function Rotate(pixelMap:image.PixelMap) { 1652 let angle: number = 90.0; 1653 if (pixelMap != undefined) { 1654 pixelMap.rotate(angle, (err: BusinessError) => { 1655 if (err) { 1656 console.error(`Failed to rotate pixelmap. code is ${err.code}, message is ${err.message}`); 1657 return; 1658 } else { 1659 console.info("Succeeded in rotating pixelmap."); 1660 } 1661 }) 1662 } 1663} 1664``` 1665 1666## rotate<sup>9+</sup> 1667 1668rotate(angle: number): Promise\<void> 1669 1670根据输入的角度对图片进行旋转，使用Promise形式返回。 1671 1672> **说明：** 1673> 1674> 1. 图片旋转的角度取值范围：0-360。超出取值范围时，根据圆周360度自动矫正。例如，-100度与260度效果相同。 1675> 2. 如果图片旋转的角度不是90的整数倍，旋转后图片的尺寸会发生改变。 1676 1677**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1678 1679**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1680 1681**系统能力：** SystemCapability.Multimedia.Image.Core 1682 1683**参数：** 1684 1685| 参数名 | 类型 | 必填 | 说明 | 1686| ------ | ------ | ---- | ----------------------------- | 1687| angle | number | 是 | 图片旋转的角度。 | 1688 1689**返回值：** 1690 1691| 类型 | 说明 | 1692| -------------- | --------------------------- | 1693| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1694 1695**示例：** 1696 1697```ts 1698import { BusinessError } from '@kit.BasicServicesKit'; 1699 1700async function Rotate(pixelMap:image.PixelMap) { 1701 let angle: number = 90.0; 1702 if (pixelMap != undefined) { 1703 pixelMap.rotate(angle).then(() => { 1704 console.info('Succeeded in rotating pixelmap.'); 1705 }).catch((err: BusinessError) => { 1706 console.error(`Failed to rotate pixelmap. code is ${err.code}, message is ${err.message}`); 1707 }) 1708 } 1709} 1710``` 1711 1712## rotateSync<sup>12+</sup> 1713 1714rotateSync(angle: number): void 1715 1716根据输入的角度对图片进行旋转，同步返回结果。 1717 1718> **说明：** 1719> 1720> 1. 图片旋转的角度取值范围：0-360。超出取值范围时，根据圆周360度自动矫正。例如，-100度与260度效果相同。 1721> 2. 如果图片旋转的角度不是90的整数倍，旋转后图片的尺寸会发生改变。 1722 1723**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1724 1725**系统能力：** SystemCapability.Multimedia.Image.Core 1726 1727**参数：** 1728 1729| 参数名 | 类型 | 必填 | 说明 | 1730| -------- | -------------------- | ---- | ----------------------------- | 1731| angle | number | 是 | 图片旋转的角度。 | 1732 1733**错误码：** 1734 1735以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1736 1737| 错误码ID | 错误信息 | 1738| ------- | --------------------------------------------| 1739| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 1740| 501 | Resource Unavailable | 1741 1742**示例：** 1743 1744```ts 1745function RotateSync(pixelMap: image.PixelMap) { 1746 let angle : number = 90.0; 1747 if (pixelMap != undefined) { 1748 pixelMap.rotateSync(angle); 1749 } 1750} 1751``` 1752 1753## flip<sup>9+</sup> 1754 1755flip(horizontal: boolean, vertical: boolean, callback: AsyncCallback\<void>): void 1756 1757根据输入的条件对图片进行翻转，使用callback形式返回。 1758 1759**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1760 1761**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1762 1763**系统能力：** SystemCapability.Multimedia.Image.Core 1764 1765**参数：** 1766 1767| 参数名 | 类型 | 必填 | 说明 | 1768| ---------- | -------------------- | ---- | ----------------------------- | 1769| horizontal | boolean | 是 | true表示进行水平翻转，false表示不进行水平翻转。 | 1770| vertical | boolean | 是 | true表示进行垂直翻转，false表示不进行垂直翻转。 | 1771| callback | AsyncCallback\<void> | 是 | 回调函数，当对图片翻转成功，err为undefined，否则为错误对象。| 1772 1773**示例：** 1774 1775```ts 1776import { BusinessError } from '@kit.BasicServicesKit'; 1777 1778async function Flip(pixelMap:image.PixelMap) { 1779 let horizontal: boolean = true; 1780 let vertical: boolean = false; 1781 if (pixelMap != undefined) { 1782 pixelMap.flip(horizontal, vertical, (err: BusinessError) => { 1783 if (err) { 1784 console.error(`Failed to flip pixelmap. code is ${err.code}, message is ${err.message}`); 1785 return; 1786 } else { 1787 console.info("Succeeded in flipping pixelmap."); 1788 } 1789 }) 1790 } 1791} 1792``` 1793 1794## flip<sup>9+</sup> 1795 1796flip(horizontal: boolean, vertical: boolean): Promise\<void> 1797 1798根据输入的条件对图片进行翻转，使用Promise形式返回。 1799 1800**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1801 1802**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1803 1804**系统能力：** SystemCapability.Multimedia.Image.Core 1805 1806**参数：** 1807 1808| 参数名 | 类型 | 必填 | 说明 | 1809| ---------- | ------- | ---- | --------- | 1810| horizontal | boolean | 是 | true表示进行水平翻转，false表示不进行水平翻转。 | 1811| vertical | boolean | 是 | true表示进行垂直翻转，false表示不进行垂直翻转。 | 1812 1813**返回值：** 1814 1815| 类型 | 说明 | 1816| -------------- | --------------------------- | 1817| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1818 1819**示例：** 1820 1821```ts 1822import { BusinessError } from '@kit.BasicServicesKit'; 1823 1824async function Flip(pixelMap:image.PixelMap) { 1825 let horizontal: boolean = true; 1826 let vertical: boolean = false; 1827 if (pixelMap != undefined) { 1828 pixelMap.flip(horizontal, vertical).then(() => { 1829 console.info('Succeeded in flipping pixelmap.'); 1830 }).catch((err: BusinessError) => { 1831 console.error(`Failed to flip pixelmap. code is ${err.code}, message is ${err.message}`); 1832 }) 1833 } 1834} 1835``` 1836 1837## flipSync<sup>12+</sup> 1838 1839flipSync(horizontal: boolean, vertical: boolean): void 1840 1841根据输入的条件对图片进行翻转并同步返回结果。 1842 1843**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1844 1845**系统能力：** SystemCapability.Multimedia.Image.Core 1846 1847**参数：** 1848 1849| 参数名 | 类型 | 必填 | 说明 | 1850| ---------- | -------------------- | ---- | ----------------------------- | 1851| horizontal | boolean | 是 | true表示进行水平翻转，false表示不进行水平翻转。 | 1852| vertical | boolean | 是 | true表示进行垂直翻转，false表示不进行垂直翻转。 | 1853 1854**错误码：** 1855 1856以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1857 1858| 错误码ID | 错误信息 | 1859| ------- | --------------------------------------------| 1860| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 1861| 501 | Resource Unavailable | 1862 1863**示例：** 1864 1865```ts 1866import { BusinessError } from '@kit.BasicServicesKit'; 1867 1868function FlipSync(pixelMap:image.PixelMap) { 1869 let horizontal : boolean = true; 1870 let vertical : boolean = false; 1871 if (pixelMap != undefined) { 1872 pixelMap.flipSync(horizontal, vertical); 1873 } 1874} 1875``` 1876 1877## crop<sup>9+</sup> 1878 1879crop(region: Region, callback: AsyncCallback\<void>): void 1880 1881根据输入的尺寸对图片进行裁剪，使用callback形式返回。 1882 1883**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1884 1885**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1886 1887**系统能力：** SystemCapability.Multimedia.Image.Core 1888 1889**参数：** 1890 1891| 参数名 | 类型 | 必填 | 说明 | 1892| -------- | -------------------- | ---- | ----------------------------- | 1893| region | [Region](arkts-apis-image-i.md#region8) | 是 | 裁剪的尺寸。取值范围不能超过图片的宽高。 | 1894| callback | AsyncCallback\<void> | 是 | 回调函数。当对图片进行裁剪成功，err为undefined，否则为错误对象。| 1895 1896**示例：** 1897 1898```ts 1899import { BusinessError } from '@kit.BasicServicesKit'; 1900 1901async function Crop(pixelMap:image.PixelMap) { 1902 let region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 1903 if (pixelMap != undefined) { 1904 pixelMap.crop(region, (err: BusinessError) => { 1905 if (err) { 1906 console.error(`Failed to crop pixelmap. code is ${err.code}, message is ${err.message}`); 1907 return; 1908 } else { 1909 console.info("Succeeded in cropping pixelmap."); 1910 } 1911 }) 1912 } 1913} 1914``` 1915 1916## crop<sup>9+</sup> 1917 1918crop(region: Region): Promise\<void> 1919 1920根据输入的尺寸对图片进行裁剪，使用Promise形式返回。 1921 1922**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 1923 1924**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1925 1926**系统能力：** SystemCapability.Multimedia.Image.Core 1927 1928**参数：** 1929 1930| 参数名 | 类型 | 必填 | 说明 | 1931| ------ | ------------------ | ---- | ----------- | 1932| region | [Region](arkts-apis-image-i.md#region8) | 是 | 裁剪的尺寸。取值范围不能超过图片的宽高。 | 1933 1934**返回值：** 1935 1936| 类型 | 说明 | 1937| -------------- | --------------------------- | 1938| Promise\<void> | Promise对象。无返回结果的Promise对象。| 1939 1940**示例：** 1941 1942```ts 1943import { BusinessError } from '@kit.BasicServicesKit'; 1944 1945async function Crop(pixelMap:image.PixelMap) { 1946 let region: image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 1947 if (pixelMap != undefined) { 1948 pixelMap.crop(region).then(() => { 1949 console.info('Succeeded in cropping pixelmap.'); 1950 }).catch((err: BusinessError) => { 1951 console.error(`Failed to crop pixelmap. code is ${err.code}, message is ${err.message}`); 1952 1953 }); 1954 } 1955} 1956``` 1957 1958## cropSync<sup>12+</sup> 1959 1960cropSync(region: Region): void 1961 1962根据输入的尺寸裁剪图片。 1963 1964**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1965 1966**系统能力：** SystemCapability.Multimedia.Image.Core 1967 1968**参数：** 1969 1970| 参数名 | 类型 | 必填 | 说明 | 1971| -------- | -------------------- | ---- | ----------------------------- | 1972| region | [Region](arkts-apis-image-i.md#region8) | 是 | 裁剪的尺寸。取值范围不能超过图片的宽高。 | 1973 1974**错误码：** 1975 1976以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 1977 1978| 错误码ID | 错误信息 | 1979| ------- | --------------------------------------------| 1980| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 1981| 501 | Resource Unavailable | 1982 1983**示例：** 1984 1985```ts 1986import { BusinessError } from '@kit.BasicServicesKit'; 1987 1988function CropSync(pixelMap:image.PixelMap) { 1989 let region : image.Region = { x: 0, y: 0, size: { height: 100, width: 100 } }; 1990 if (pixelMap != undefined) { 1991 pixelMap.cropSync(region); 1992 } 1993} 1994``` 1995 1996## getColorSpace<sup>10+</sup> 1997 1998getColorSpace(): colorSpaceManager.ColorSpaceManager 1999 2000获取图像广色域信息。 2001 2002**系统能力：** SystemCapability.Multimedia.Image.Core 2003 2004**返回值：** 2005 2006| 类型 | 说明 | 2007| ----------------------------------- | ---------------- | 2008| [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 图像广色域信息。 | 2009 2010**错误码：** 2011 2012以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2013 2014| 错误码ID | 错误信息 | 2015| ------- | --------------------------------------------| 2016| 62980101| If the image data abnormal. | 2017| 62980103| If the image data unsupport. | 2018| 62980115| If the image parameter invalid. | 2019 2020**示例：** 2021 2022```ts 2023import { BusinessError } from '@kit.BasicServicesKit'; 2024 2025function GetColorSpace(pixelMap:image.PixelMap) { 2026 if (pixelMap != undefined) { 2027 let csm = pixelMap.getColorSpace(); 2028 } 2029} 2030``` 2031 2032## setColorSpace<sup>10+</sup> 2033 2034setColorSpace(colorSpace: colorSpaceManager.ColorSpaceManager): void 2035 2036设置图像广色域信息。 2037 2038**系统能力：** SystemCapability.Multimedia.Image.Core 2039 2040**参数：** 2041 2042| 参数名 | 类型 | 必填 | 说明 | 2043| ---------- | ----------------------------------- | ---- | --------------- | 2044| colorSpace | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 是 | 图像广色域信息。| 2045 2046**错误码：** 2047 2048以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2049 2050| 错误码ID | 错误信息 | 2051| ------- | --------------------------------------------| 2052| 62980111| The image source data is incomplete. | 2053| 62980115| If the image parameter invalid. | 2054 2055**示例：** 2056 2057```ts 2058import { colorSpaceManager } from '@kit.ArkGraphics2D'; 2059 2060function SetColorSpace(pixelMap:image.PixelMap) { 2061 let colorSpaceName = colorSpaceManager.ColorSpace.SRGB; 2062 let csm: colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceName); 2063 if (pixelMap != undefined) { 2064 pixelMap.setColorSpace(csm); 2065 } 2066} 2067``` 2068 2069## applyColorSpace<sup>11+</sup> 2070 2071applyColorSpace(targetColorSpace: colorSpaceManager.ColorSpaceManager, callback: AsyncCallback\<void>): void 2072 2073根据输入的目标色彩空间对图像像素颜色进行色彩空间转换，使用callback形式返回。 2074 2075**系统能力：** SystemCapability.Multimedia.Image.Core 2076 2077**参数：** 2078 2079| 参数名 | 类型 | 必填 | 说明 | 2080| -------- | -------------------- | ---- | ----------------------------- | 2081| targetColorSpace | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 是 | 目标色彩空间，支持SRGB、DCI_P3、DISPLAY_P3、ADOBE_RGB_1998。| 2082| callback | AsyncCallback\<void> | 是 | 回调函数。当对图像像素颜色进行色彩空间转换成功，err为undefined，否则为错误对象。| 2083 2084**错误码：** 2085 2086以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2087 2088| 错误码ID | 错误信息 | 2089| ------- | ------------------------------------------| 2090| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2091| 62980104| Failed to initialize the internal object. | 2092| 62980108| Failed to convert the color space. | 2093| 62980115| Invalid image parameter. | 2094 2095**示例：** 2096 2097```ts 2098import { colorSpaceManager } from '@kit.ArkGraphics2D'; 2099import { BusinessError } from '@kit.BasicServicesKit'; 2100 2101function ApplyColorSpace(pixelMap:image.PixelMap) { 2102 let colorSpaceName = colorSpaceManager.ColorSpace.SRGB; 2103 let targetColorSpace: colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceName); 2104 if (pixelMap != undefined) { 2105 try { 2106 pixelMap.applyColorSpace(targetColorSpace, (error: BusinessError) => { 2107 if (error) { 2108 console.error(`ApplyColorSpace failed. code is ${error.code}, message is ${error.message}`); 2109 return; 2110 } else { 2111 console.info("Succeeded ApplyColorSpace."); 2112 } 2113 }); 2114 } catch (error) { 2115 console.error(`Failed to apply color space for pixelmap object, error code is ${error}`); 2116 return; 2117 } 2118 console.info('Succeeded in applying color space for pixelmap object.'); 2119 } 2120} 2121``` 2122 2123## applyColorSpace<sup>11+</sup> 2124 2125applyColorSpace(targetColorSpace: colorSpaceManager.ColorSpaceManager): Promise\<void> 2126 2127根据输入的目标色彩空间对图像像素颜色进行色彩空间转换，使用Promise形式返回。 2128 2129**系统能力：** SystemCapability.Multimedia.Image.Core 2130 2131**参数：** 2132 2133| 参数名 | 类型 | 必填 | 说明 | 2134| ------ | ------------------ | ---- | ----------- | 2135| targetColorSpace | [colorSpaceManager.ColorSpaceManager](../apis-arkgraphics2d/js-apis-colorSpaceManager.md#colorspacemanager) | 是 | 目标色彩空间，支持SRGB、DCI_P3、DISPLAY_P3、ADOBE_RGB_1998。| 2136 2137**返回值：** 2138 2139| 类型 | 说明 | 2140| -------------- | --------------------------- | 2141| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2142 2143**错误码：** 2144 2145以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2146 2147| 错误码ID | 错误信息 | 2148| ------- | ------------------------------------------| 2149| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed | 2150| 62980104| Failed to initialize the internal object. | 2151| 62980108| Failed to convert the color space. | 2152| 62980115| Invalid image parameter. | 2153 2154**示例：** 2155 2156```ts 2157import { colorSpaceManager } from '@kit.ArkGraphics2D'; 2158import { BusinessError } from '@kit.BasicServicesKit'; 2159 2160function ApplyColorSpace(pixelMap:image.PixelMap) { 2161 let colorSpaceName = colorSpaceManager.ColorSpace.SRGB; 2162 let targetColorSpace: colorSpaceManager.ColorSpaceManager = colorSpaceManager.create(colorSpaceName); 2163 if (pixelMap != undefined) { 2164 pixelMap.applyColorSpace(targetColorSpace).then(() => { 2165 console.info('Succeeded in applying color space for pixelmap object.'); 2166 }).catch((error: BusinessError) => { 2167 console.error(`Failed to apply color space for pixelmap object, error code is ${error}`); 2168 return; 2169 }); 2170 } 2171} 2172``` 2173 2174## toSdr<sup>12+<sup> 2175 2176toSdr(): Promise\<void> 2177 2178将HDR的图像内容转换为SDR的图像内容，异步使用Promise形式返回。 2179 2180**系统能力：** SystemCapability.Multimedia.Image.Core 2181 2182**返回值：** 2183 2184| 类型 | 说明 | 2185| -------------- | --------------------------- | 2186| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2187 2188**错误码：** 2189 2190以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2191 2192| 错误码ID | 错误信息 | 2193| ------- | --------------------------------------------| 2194| 62980137 | Invalid image operation. | 2195 2196**示例：** 2197 2198```ts 2199import { BusinessError } from '@kit.BasicServicesKit'; 2200 2201async function ToSdr(context: Context) { 2202 // 此处'app.media.startIcon'需要替换为本地hdr图片。 2203 let img = context.resourceManager.getMediaContentSync($r('app.media.startIcon').id); 2204 let imageSource = image.createImageSource(img.buffer.slice(0)); 2205 let decodingOptions: image.DecodingOptions = { 2206 desiredDynamicRange: image.DecodingDynamicRange.AUTO 2207 }; 2208 let pixelmap = imageSource.createPixelMapSync(decodingOptions); 2209 if (pixelmap != undefined) { 2210 console.info('Succeeded in creating pixelMap object.'); 2211 pixelmap.toSdr().then(() => { 2212 let imageInfo = pixelmap.getImageInfoSync(); 2213 console.info("after toSdr ,imageInfo isHdr:" + imageInfo.isHdr); 2214 }).catch((err: BusinessError) => { 2215 console.error(`Failed to set sdr. code is ${err.code}, message is ${err.message}`); 2216 }); 2217 } else { 2218 console.error('Failed to create pixelMap.'); 2219 } 2220} 2221``` 2222 2223## getMetadata<sup>12+</sup> 2224 2225getMetadata(key: HdrMetadataKey): HdrMetadataValue 2226 2227从PixelMap中获取元数据。 2228 2229**系统能力：** SystemCapability.Multimedia.Image.Core 2230 2231**参数：** 2232 2233| 参数名 | 类型 | 必填 | 说明 | 2234| ------------- | -------------------------------- | ---- | ---------------- | 2235| key | [HdrMetadataKey](arkts-apis-image-e.md#hdrmetadatakey12) | 是 | HDR元数据的关键字，可用于查询对应值。 | 2236 2237**返回值：** 2238 2239| 类型 | 说明 | 2240| --------------------------------- | --------------------------------- | 2241| [HdrMetadataValue](arkts-apis-image-t.md#hdrmetadatavalue12) | 返回元数据的值。 | 2242 2243**错误码：** 2244 2245以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2246 2247| 错误码ID | 错误信息 | 2248| ------- | --------------------------------------------| 2249| 401| Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 2250| 501 | Resource unavailable. | 2251| 62980173 | The DMA memory does not exist. | 2252| 62980302 | Memory copy failed. Possibly caused by invalid metadata value. | 2253 2254**示例：** 2255 2256```ts 2257async function GetMetadata(context: Context) { 2258 // 此处'app.media.startIcon'需要替换为本地hdr图片。 2259 let img = context.resourceManager.getMediaContentSync($r('app.media.startIcon').id); 2260 let imageSource = image.createImageSource(img.buffer.slice(0)); 2261 let decodingOptions: image.DecodingOptions = { 2262 desiredDynamicRange: image.DecodingDynamicRange.AUTO 2263 }; 2264 let pixelmap = imageSource.createPixelMapSync(decodingOptions); 2265 if (pixelmap != undefined) { 2266 console.info('Succeeded in creating pixelMap object.'); 2267 try { 2268 let staticMetadata = pixelmap.getMetadata(image.HdrMetadataKey.HDR_STATIC_METADATA); 2269 console.info(`getMetadata:${staticMetadata}`); 2270 } catch (e) { 2271 console.error('pixelmap create failed' + e); 2272 } 2273 } else { 2274 console.error('Failed to create pixelMap.'); 2275 } 2276} 2277 2278``` 2279 2280## setMetadata<sup>12+</sup> 2281 2282setMetadata(key: HdrMetadataKey, value: HdrMetadataValue): Promise\<void> 2283 2284设置PixelMap元数据。 2285 2286**系统能力：** SystemCapability.Multimedia.Image.Core 2287 2288**参数：** 2289 2290| 参数名 | 类型 | 必填 | 说明 | 2291| ------------- | -------------------------------- | ---- | ---------------- | 2292| key | [HdrMetadataKey](arkts-apis-image-e.md#hdrmetadatakey12) | 是 | HDR元数据的关键字，用于设置对应值。 | 2293| value | [HdrMetadataValue](arkts-apis-image-t.md#hdrmetadatavalue12) | 是 | 元数据的值。 | 2294 2295**返回值：** 2296 2297| 类型 | 说明 | 2298| -------------- | --------------------- | 2299| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2300 2301**错误码：** 2302 2303以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2304 2305| 错误码ID | 错误信息 | 2306| ------- | --------------------------------------------| 2307| 401| Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 2308| 501 | Resource unavailable. | 2309| 62980173 | The DMA memory does not exist. | 2310| 62980302 | Memory copy failed. Possibly caused by invalid metadata value. | 2311 2312**示例：** 2313 2314```ts 2315import { BusinessError } from '@kit.BasicServicesKit'; 2316 2317let staticMetadata: image.HdrStaticMetadata = { 2318 displayPrimariesX: [1.1, 1.1, 1.1], 2319 displayPrimariesY: [1.2, 1.2, 1.2], 2320 whitePointX: 1.1, 2321 whitePointY: 1.2, 2322 maxLuminance: 2.1, 2323 minLuminance: 1.0, 2324 maxContentLightLevel: 2.1, 2325 maxFrameAverageLightLevel: 2.1, 2326}; 2327const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4。 2328let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } }; 2329image.createPixelMap(color, opts).then((pixelMap: image.PixelMap) => { 2330 pixelMap.setMetadata(image.HdrMetadataKey.HDR_STATIC_METADATA, staticMetadata).then(() => { 2331 console.info('Succeeded in setting pixelMap metadata.'); 2332 }).catch((error: BusinessError) => { 2333 console.error(`Failed to set the metadata.code ${error.code},message is ${error.message}`); 2334 }) 2335}).catch((error: BusinessError) => { 2336 console.error(`Failed to create the PixelMap.code ${error.code},message is ${error.message}`); 2337}) 2338``` 2339 2340## setTransferDetached<sup>12+<sup> 2341 2342setTransferDetached(detached: boolean): void 2343 2344pixelmap在跨线程传输时，断开原线程的引用。适用于需立即释放pixelmap的场景。 2345 2346**系统能力：** SystemCapability.Multimedia.Image.Core 2347 2348**参数：** 2349 2350| 参数名 | 类型 | 必填 | 说明 | 2351| ------- | ------------------ | ---- | ----------------------------- | 2352| detached | boolean | 是 | true表示断开原线程引用，false表示不断开原线程引用。 | 2353 2354**错误码：** 2355 2356以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2357 2358| 错误码ID | 错误信息 | 2359| ------- | --------------------------------------------| 2360| 501 | Resource Unavailable | 2361 2362**示例：** 2363 2364```ts 2365import { common } from '@kit.AbilityKit'; 2366import { taskpool } from '@kit.ArkTS'; 2367 2368@Concurrent 2369// 子线程方法。 2370async function loadPixelMap(rawFileDescriptor: number): Promise<PixelMap> { 2371 // 创建imageSource。 2372 const imageSource = image.createImageSource(rawFileDescriptor); 2373 // 创建pixelMap。 2374 const pixelMap = imageSource.createPixelMapSync(); 2375 // 释放imageSource。 2376 imageSource.release(); 2377 // 使pixelMap在跨线程传输完成后，断开原线程的引用。 2378 pixelMap.setTransferDetached(true); 2379 // 返回pixelMap给主线程。 2380 return pixelMap; 2381} 2382 2383@Component 2384struct Demo { 2385 @State pixelMap: PixelMap | undefined = undefined; 2386 // 主线程方法。 2387 private loadImageFromThread(): void { 2388 let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 2389 const resourceMgr = context.resourceManager; 2390 // 此处‘example.jpg’仅作示例，请开发者自行替换，否则imageSource创建失败会导致后续无法正常执行。 2391 resourceMgr.getRawFd('example.jpg').then(rawFileDescriptor => { 2392 taskpool.execute(loadPixelMap, rawFileDescriptor).then(pixelMap => { 2393 if (pixelMap) { 2394 this.pixelMap = pixelMap as PixelMap; 2395 console.log('Succeeded in creating pixelMap.'); 2396 // 主线程释放pixelMap。由于子线程返回pixelMap时已调用setTransferDetached，所以此处能够立即释放pixelMap。 2397 this.pixelMap.release(); 2398 } else { 2399 console.error('Failed to create pixelMap.'); 2400 } 2401 }); 2402 }); 2403 } 2404 build() { 2405 // ... 2406 } 2407} 2408``` 2409 2410## marshalling<sup>10+</sup> 2411 2412marshalling(sequence: rpc.MessageSequence): void 2413 2414将PixelMap序列化后写入MessageSequence。 2415 2416**系统能力：** SystemCapability.Multimedia.Image.Core 2417 2418**参数：** 2419 2420| 参数名 | 类型 | 必填 | 说明 | 2421| ---------------------- | ------------------------------------------------------ | ---- | ---------------------------------------- | 2422| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是 | 新创建的MessageSequence。 | 2423 2424**错误码：** 2425 2426以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2427 2428| 错误码ID | 错误信息 | 2429| ------- | --------------------------------------------| 2430| 62980115 | Invalid image parameter. | 2431| 62980097 | IPC error. Possible cause: 1.IPC communication failed. 2. Image upload exception. 3. Decode process exception. 4. Insufficient memory. | 2432 2433**示例：** 2434 2435```ts 2436import { rpc } from '@kit.IPCKit'; 2437 2438class MySequence implements rpc.Parcelable { 2439 pixel_map: image.PixelMap; 2440 constructor(conPixelMap : image.PixelMap) { 2441 this.pixel_map = conPixelMap; 2442 } 2443 marshalling(messageSequence : rpc.MessageSequence) { 2444 this.pixel_map.marshalling(messageSequence); 2445 console.info('marshalling'); 2446 return true; 2447 } 2448 unmarshalling(messageSequence : rpc.MessageSequence) { 2449 image.createPixelMap(new ArrayBuffer(96), {size: { height:4, width: 6}}).then((pixelParcel: image.PixelMap) => { 2450 pixelParcel.unmarshalling(messageSequence).then(async (pixelMap: image.PixelMap) => { 2451 this.pixel_map = pixelMap; 2452 pixelMap.getImageInfo().then((imageInfo: image.ImageInfo) => { 2453 console.info(`unmarshalling information h: ${imageInfo.size.height} w: ${imageInfo.size.width}`); 2454 }) 2455 }) 2456 }); 2457 return true; 2458 } 2459} 2460async function Marshalling() { 2461 const color: ArrayBuffer = new ArrayBuffer(96); 2462 let bufferArr: Uint8Array = new Uint8Array(color); 2463 for (let i = 0; i < bufferArr.length; i++) { 2464 bufferArr[i] = 0x80; 2465 } 2466 let opts: image.InitializationOptions = { 2467 editable: true, 2468 pixelFormat: image.PixelMapFormat.BGRA_8888, 2469 size: { height: 4, width: 6 }, 2470 alphaType: image.AlphaType.UNPREMUL 2471 } 2472 let pixelMap: image.PixelMap | undefined = undefined; 2473 await image.createPixelMap(color, opts).then((srcPixelMap: image.PixelMap) => { 2474 pixelMap = srcPixelMap; 2475 }) 2476 if (pixelMap != undefined) { 2477 // 序列化。 2478 let parcelable: MySequence = new MySequence(pixelMap); 2479 let data: rpc.MessageSequence = rpc.MessageSequence.create(); 2480 data.writeParcelable(parcelable); 2481 2482 // 反序列化rpc获取到data。 2483 let ret: MySequence = new MySequence(pixelMap); 2484 data.readParcelable(ret); 2485 } 2486} 2487``` 2488 2489## unmarshalling<sup>10+</sup> 2490 2491unmarshalling(sequence: rpc.MessageSequence): Promise\<PixelMap> 2492 2493从MessageSequence中获取PixelMap，如需使用同步方式创建PixelMap可使用：[createPixelMapFromParcel](arkts-apis-image-f.md#imagecreatepixelmapfromparcel11)。 2494 2495**系统能力：** SystemCapability.Multimedia.Image.Core 2496 2497**参数：** 2498 2499| 参数名 | 类型 | 必填 | 说明 | 2500| ---------------------- | ----------------------------------------------------- | ---- | ---------------------------------------- | 2501| sequence | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是 | 保存有PixelMap信息的MessageSequence。 | 2502 2503**返回值：** 2504 2505| 类型 | 说明 | 2506| -------------------------------- | --------------------- | 2507| Promise\<[PixelMap](arkts-apis-image-PixelMap.md)> |Promise对象，返回PixelMap。 | 2508 2509**错误码：** 2510 2511以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2512 2513| 错误码ID | 错误信息 | 2514| ------- | --------------------------------------------| 2515| 62980115 | Invalid image parameter. | 2516| 62980097 | IPC error. Possible cause: 1.IPC communication failed. 2. Image upload exception. 3. Decode process exception. 4. Insufficient memory. | 2517| 62980096 | The operation failed. Possible cause: 1.Image upload exception. 2. Decoding process exception. 3. Insufficient memory. | 2518 2519**示例：** 2520 2521```ts 2522import { rpc } from '@kit.IPCKit'; 2523 2524class MySequence implements rpc.Parcelable { 2525 pixel_map: image.PixelMap; 2526 constructor(conPixelMap: image.PixelMap) { 2527 this.pixel_map = conPixelMap; 2528 } 2529 marshalling(messageSequence: rpc.MessageSequence) { 2530 this.pixel_map.marshalling(messageSequence); 2531 console.info('marshalling'); 2532 return true; 2533 } 2534 unmarshalling(messageSequence: rpc.MessageSequence) { 2535 image.createPixelMap(new ArrayBuffer(96), {size: { height:4, width: 6}}).then((pixelParcel : image.PixelMap) => { 2536 pixelParcel.unmarshalling(messageSequence).then(async (pixelMap : image.PixelMap) => { 2537 this.pixel_map = pixelMap; 2538 pixelMap.getImageInfo().then((imageInfo : image.ImageInfo) => { 2539 console.info(`unmarshalling information h: ${imageInfo.size.height} w: ${imageInfo.size.width}`); 2540 }) 2541 }) 2542 }); 2543 return true; 2544 } 2545} 2546async function Unmarshalling() { 2547 const color: ArrayBuffer = new ArrayBuffer(96); 2548 let bufferArr: Uint8Array = new Uint8Array(color); 2549 for (let i = 0; i < bufferArr.length; i++) { 2550 bufferArr[i] = 0x80; 2551 } 2552 let opts: image.InitializationOptions = { 2553 editable: true, 2554 pixelFormat: image.PixelMapFormat.BGRA_8888, 2555 size: { height: 4, width: 6 }, 2556 alphaType: image.AlphaType.UNPREMUL 2557 } 2558 let pixelMap: image.PixelMap | undefined = undefined; 2559 await image.createPixelMap(color, opts).then((srcPixelMap : image.PixelMap) => { 2560 pixelMap = srcPixelMap; 2561 }) 2562 if (pixelMap != undefined) { 2563 // 序列化。 2564 let parcelable: MySequence = new MySequence(pixelMap); 2565 let data : rpc.MessageSequence = rpc.MessageSequence.create(); 2566 data.writeParcelable(parcelable); 2567 2568 // 反序列化rpc获取到data。 2569 let ret : MySequence = new MySequence(pixelMap); 2570 data.readParcelable(ret); 2571 } 2572} 2573``` 2574 2575## release<sup>7+</sup> 2576 2577release():Promise\<void> 2578 2579释放PixelMap对象，使用Promise形式返回释放结果。 2580 2581ArkTS有内存回收机制，PixelMap对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 2582 2583**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2584 2585**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2586 2587**系统能力：** SystemCapability.Multimedia.Image.Core 2588 2589**返回值：** 2590 2591| 类型 | 说明 | 2592| -------------- | ------------------------------- | 2593| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2594 2595**示例：** 2596 2597```ts 2598import { BusinessError } from '@kit.BasicServicesKit'; 2599 2600async function Release(pixelMap:image.PixelMap) { 2601 if (pixelMap != undefined) { 2602 await pixelMap.release().then(() => { 2603 console.info('Succeeded in releasing pixelmap object.'); 2604 }).catch((error: BusinessError) => { 2605 console.error(`Failed to release pixelmap object. code is ${error.code}, message is ${error.message}`); 2606 }) 2607 } 2608} 2609``` 2610 2611## release<sup>7+</sup> 2612 2613release(callback: AsyncCallback\<void>): void 2614 2615释放PixelMap对象，使用callback形式返回释放结果。 2616 2617ArkTS有内存回收机制，PixelMap对象不调用release方法，内存最终也会由系统统一释放。但图片使用的内存往往较大，为尽快释放内存，建议应用在使用完成后主动调用release方法提前释放内存。 2618 2619**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 2620 2621**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2622 2623**系统能力：** SystemCapability.Multimedia.Image.Core 2624 2625**参数：** 2626 2627| 参数名 | 类型 | 必填 | 说明 | 2628| -------- | -------------------- | ---- | ------------------ | 2629| callback | AsyncCallback\<void> | 是 | 回调函数。当对PixelMap对象释放成功，err为undefined，否则为错误对象。 | 2630 2631**示例：** 2632 2633```ts 2634import { BusinessError } from '@kit.BasicServicesKit'; 2635 2636async function Release(pixelMap:image.PixelMap) { 2637 if (pixelMap != undefined) { 2638 pixelMap.release((err: BusinessError) => { 2639 if (err) { 2640 console.error(`Failed to release pixelmap object. code is ${err.code}, message is ${err.message}`); 2641 return; 2642 } else { 2643 console.info('Succeeded in releasing pixelmap object.'); 2644 } 2645 }) 2646 } 2647} 2648``` 2649 2650## convertPixelFormat<sup>12+</sup> 2651 2652convertPixelFormat(targetPixelFormat: PixelMapFormat): Promise\<void> 2653 2654YUV和RGB类型互转，目前仅支持NV12/NV21与RGB888/RGBA8888/RGB565/BGRA8888/RGBAF16互转，YCRCB_P010/YCBCR_P010与RGBA1010102互转。 2655 2656从API18开始，可用于ASTC_4x4类型转为RGBA_8888类型，目前仅支持ASTC_4x4转为RGBA_8888。 2657 2658> **注意：** 2659> 仅在ASTC_4x4格式的图像需要进行像素访问时，建议调用此接口将ASTC_4x4类型转为RGBA_8888类型。由于使用ASTC_4x4反解为RGBA_8888时延较高，其余情况下不推荐使用。 2660 2661**系统能力：** SystemCapability.Multimedia.Image.Core 2662 2663**参数：** 2664 2665| 参数名 | 类型 | 必填 | 说明 | 2666| -------- | -------------------- | ---- | ------------------ | 2667| targetPixelFormat | [PixelMapFormat](arkts-apis-image-e.md#pixelmapformat7) | 是 | 目标像素格式，用于YUV和RGB类型互转，或者ASTC_4x4类型转为RGBA_8888类型。目前仅支持NV12/NV21与RGB888/RGBA8888/RGB565/BGRA8888/RGBAF16互转，YCRCB_P010/YCBCR_P010与RGBA1010102互转，ASTC_4x4转为RGBA_8888。 | 2668 2669**返回值：** 2670 2671| 类型 | 说明 | 2672| -------------- | ------------------------------- | 2673| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2674 2675**错误码：** 2676 2677以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2678 2679| 错误码ID | 错误信息 | 2680| ------- | --------------------------------------------| 2681| 62980111 | The image source data is incomplete. | 2682| 62980115 | Invalid input parameter. | 2683| 62980178 | Failed to create the pixelmap. | 2684| 62980274 | The conversion failed | 2685| 62980276 | The type to be converted is an unsupported target pixel format| 2686 2687**示例：** 2688 2689```ts 2690import { BusinessError } from '@kit.BasicServicesKit'; 2691 2692async function ConvertPixelFormat(pixelMap: image.PixelMap) { 2693 if (pixelMap != undefined) { 2694 // 设置目标像素格式为NV12。 2695 let targetPixelFormat = image.PixelMapFormat.NV12; 2696 pixelMap.convertPixelFormat(targetPixelFormat).then(() => { 2697 // pixelMap转换成NV12格式成功。 2698 console.info('PixelMapFormat convert Succeeded'); 2699 }).catch((error: BusinessError) => { 2700 // pixelMap转换成NV12格式失败。 2701 console.error(`PixelMapFormat convert Failed. code is ${error.code}, message is ${error.message}`); 2702 }) 2703 } 2704} 2705``` 2706 2707## setMemoryNameSync<sup>13+</sup> 2708 2709setMemoryNameSync(name: string): void 2710 2711设置PixelMap内存标识符。 2712 2713**系统能力：** SystemCapability.Multimedia.Image.Core 2714 2715**参数：** 2716 2717| 参数名 | 类型 | 必填 | 说明 | 2718| ------------- | -------------------------------- | ---- | ---------------- | 2719| name | string | 是 | pixelmap内存标识符，只允许DMA和ASHMEM内存形式的pixelmap设置。DMA内存设置名字长度取值范围为[1, 255]，ASHMEM内存设置名字长度取值范围为[1, 244]，单位字节。 | 2720 2721**错误码：** 2722 2723以下错误码的详细介绍请参见[Image错误码](errorcode-image.md)。 2724 2725| 错误码ID | 错误信息 | 2726| ------- | --------------------------------------------| 2727| 401 | Parameter error. Possible causes: 1.The length of the input parameter is too long. 2.Parameter verification failed. | 2728| 501 | Resource unavailable. | 2729| 62980286 | Memory format not supported. | 2730 2731**示例：** 2732 2733```ts 2734import { BusinessError } from '@kit.BasicServicesKit'; 2735 2736function SetMemoryNameSync(pixelMap:image.PixelMap) { 2737 if (pixelMap != undefined) { 2738 try { 2739 pixelMap.setMemoryNameSync("PixelMapName Test"); 2740 } catch(e) { 2741 let error = e as BusinessError; 2742 console.error(`setMemoryNameSync error. code is ${error.code}, message is ${error.message}`); 2743 } 2744 } 2745} 2746``` 2747
