1# @ohos.multimedia.videoProcessingEngine (Video Processing Engine) 2 3The module provides the capabilities for enhancing the clarity and scaling of image content. 4 5This module includes a base class: [ImageProcessor](#imageprocessor). 6 7> **NOTE** 8> 9> The initial APIs of this module are supported since API version 18. Newly added APIs will be marked with a superscript to indicate their earliest API version. 10 11## Modules to Import 12 13```ts 14import { videoProcessingEngine } from '@kit.ImageKit'; 15``` 16 17## videoProcessingEngine.initializeEnvironment 18 19initializeEnvironment(): Promise\<void> 20 21Initializes the environment. This API uses a promise to return the result. 22 23**Widget capability**: This API can be used in ArkTS widgets since API version 18. 24 25**System capability**: SystemCapability.Multimedia.VideoProcessingEngine 26 27**Return value** 28 29| Type| Description | 30| ------------ | ------------ | 31| Promise\<void> | Promise that returns no value. | 32 33**Error codes** 34 35For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Video Processing Engine Error Codes](errorcode-videoprocessingengine.md). 36 37 38| ID | Error Message | 39| :------------ | :------------ | 40| 801 | Capability not supported. Function initializeEnvironment can not work correctly due to limited device capabilities.| 41| 29200002 | The global environment initialization for image processing failed, such as failure to initialize the GPU environment. | 42| 29200006 | The operation is not permitted. This may be caused by incorrect status. | 43| 29200007 | Out of memory. | 44 45**Example** 46 47```ts 48import { videoProcessingEngine } from '@kit.ImageKit'; 49async function initializeEnvironment() { 50videoProcessingEngine.initializeEnvironment(); 51} 52``` 53 54## videoProcessingEngine.deinitializeEnvironment 55 56deinitializeEnvironment(): Promise\<void> 57 58Deinitializes the environment. This API uses a promise to return the result. 59 60**Widget capability**: This API can be used in ArkTS widgets since API version 18. 61 62**System capability**: SystemCapability.Multimedia.VideoProcessingEngine 63 64**Return value** 65 66| Type| Description | 67| ------------ | ------------ | 68| Promise\<void> | Promise that returns no value. | 69 70**Error codes** 71 72For details about the error codes, see [Video Processing Engine Error Codes](errorcode-videoprocessingengine.md). 73 74| ID | Error Message | 75| :------------ | :------------ | 76| 29200006 | The operation is not permitted. This may be caused by incorrect status. | 77 78**Example** 79 80```ts 81import { videoProcessingEngine } from '@kit.ImageKit'; 82async function deinitializeEnvironment() { 83 videoProcessingEngine.initializeEnvironment(); 84 videoProcessingEngine.deinitializeEnvironment(); 85} 86``` 87 88## videoProcessingEngine.create 89 90create(): ImageProcessor 91 92Creates an instance of the image processing module. If the operation fails, null is returned. 93 94**Widget capability**: This API can be used in ArkTS widgets since API version 18. 95 96**System capability**: SystemCapability.Multimedia.VideoProcessingEngine 97 98**Return value** 99 100| Type| Description | 101| ------------ | ------------ | 102| [ImageProcessor](#imageprocessor) | Instance of the image processing module. | 103 104**Error codes** 105 106For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Video Processing Engine Error Codes](errorcode-videoprocessingengine.md). 107 108| ID | Error Message | 109| :------------ | :------------ | 110| 801 | Capability not supported. Function create can not work correctly due to limited device capabilities.| 111| 29200003 | Failed to create image processing instance. For example, the number of instances exceeds the upper limit. | 112| 29200007 | Out of memory. | 113 114**Example** 115 116```ts 117import { videoProcessingEngine } from '@kit.ImageKit'; 118async function create() { 119videoProcessingEngine.initializeEnvironment(); 120let imageProcessor = videoProcessingEngine.create() as videoProcessingEngine.ImageProcessor; 121} 122``` 123 124## ImageProcessor 125 126Image processing class, which provides capabilities for enhancing the clarity and scaling of image content. It performs necessary scaling operations based on the source image's width and height to generate the target image. It offers different scaling methods to balance performance and image quality. 127 128Constraints: 129 130- Only Standard Dynamic Range (SDR) images can be processed. 131- Images in RGBA, BGRA, NV12, and NV21 pixel formats can be processed. The output format is the same as the input format. 132 133### enhanceDetail 134 135enhanceDetail(sourceImage: image.PixelMap, width: number, height: number, level?: QualityLevel): Promise\<image.PixelMap\> 136 137Carries out detail enhancement processing. This API uses a promise to return the result. 138 139**Widget capability**: This API can be used in ArkTS widgets since API version 18. 140 141**System capability**: SystemCapability.Multimedia.VideoProcessingEngine 142 143**Parameters** 144 145| Name| Type | Mandatory | Description | 146| :------------ | :------------ | :------------ | :------------ | 147| sourceImage | [image.PixelMap](arkts-apis-image-PixelMap.md) | Yes | Input image. | 148| width | number | Yes | Target width, in px. | 149| height | number | Yes | Target height, in px.| 150| level | [QualityLevel](#qualitylevel)| No | Algorithm level (**HIGH**, **MEDIUM**, **LOW**, or **NONE**). The default value is **NONE**.| 151 152**Return value** 153 154| Type| Description | 155| ------------ | ------------ | 156| Promise\<[image.PixelMap](arkts-apis-image-PixelMap.md)\> | Promise usd to return the PixelMap object.| 157 158**Error codes** 159 160For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Video Processing Engine Error Codes](errorcode-videoprocessingengine.md). 161 162| ID | Error Message | 163| :------------ | :------------ | 164| 801 | Capability not supported. Function enhanceDetail can not work correctly due to limited device capabilities.| 165| 29200007 | Out of memory. | 166| 29200009 | Input value is invalid. This error is returned for all of the following error conditions: <br>1 - Invalid input or output image buffer - The image buffer width(height) is too large or colorspace is incorrect. <br>2 - Invalid parameter - The parameter does not contain valid information, such as detail enhancer level is incorrect. | 167 168**Example** 169 170```ts 171import { image, videoProcessingEngine } from '@kit.ImageKit'; 172async function enhanceDetail(sourceImage: image.PixelMap, width: number, height: number) { 173 videoProcessingEngine.initializeEnvironment(); 174 let imageProcessor = videoProcessingEngine.create() as videoProcessingEngine.ImageProcessor; 175 let enhancedPixelmap: Promise<image.PixelMap> = imageProcessor.enhanceDetail(sourceImage, width, height, videoProcessingEngine.QualityLevel.HIGH); 176} 177``` 178 179### enhanceDetail 180 181enhanceDetail(sourceImage: image.PixelMap, scale: number, level?: QualityLevel): Promise\<image.PixelMap\> 182 183Carries out detail enhancement processing. This API uses a promise to return the result. 184 185**Widget capability**: This API can be used in ArkTS widgets since API version 18. 186 187**System capability**: SystemCapability.Multimedia.VideoProcessingEngine 188 189**Parameters** 190 191| Name| Type | Mandatory | Description | 192| :------------ | :------------ | :------------ | :------------ | 193| sourceImage | [image.PixelMap](arkts-apis-image-PixelMap.md) | Yes | Input image. | 194| scale | number | Yes| Target scale factor.| 195| level | [QualityLevel](#qualitylevel)| No | Algorithm level (**HIGH**, **MEDIUM**, **LOW**, or **NONE**). The default value is **NONE**.| 196 197**Return value** 198 199| Type| Description | 200| ------------ | ------------ | 201| Promise\<[image.PixelMap](arkts-apis-image-PixelMap.md)\> | Promise usd to return the PixelMap object.| 202 203**Error codes** 204 205For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Video Processing Engine Error Codes](errorcode-videoprocessingengine.md). 206 207| ID | Error Message | 208| :------------ | :------------ | 209| 801 | Capability not supported. Function enhanceDetail can not work correctly due to limited device capabilities.| 210| 29200007 | Out of memory. | 211| 29200009 | Input value is invalid. This error is returned for all of the following error conditions: <br>1 - Invalid input or output image buffer - The image buffer width(height) is too large or colorspace is incorrect. <br>2 - Invalid parameter - The parameter does not contain valid information, such as detail enhancer level is incorrect. | 212 213**Example** 214 215```ts 216import { image, videoProcessingEngine } from '@kit.ImageKit'; 217async function enhanceDetail(sourceImage: image.PixelMap, scale: number) { 218 videoProcessingEngine.initializeEnvironment(); 219 let imageProcessor = videoProcessingEngine.create() as videoProcessingEngine.ImageProcessor; 220 let enhancedPixelmap: Promise<image.PixelMap> = imageProcessor.enhanceDetail(sourceImage, scale, videoProcessingEngine.QualityLevel.HIGH); 221} 222``` 223 224### enhanceDetailSync 225 226enhanceDetailSync(sourceImage: image.PixelMap, width: number, height: number, level?: QualityLevel): image.PixelMap 227 228Carries out detail enhancement processing. This API returns the result synchronously. 229 230**Widget capability**: This API can be used in ArkTS widgets since API version 18. 231 232**System capability**: SystemCapability.Multimedia.VideoProcessingEngine 233 234**Parameters** 235 236| Name| Type | Mandatory | Description | 237| :------------ | :------------ | :------------ | :------------ | 238| sourceImage | [image.PixelMap](arkts-apis-image-PixelMap.md) | Yes | Input image. | 239| width | number | Yes | Target width, in px. | 240| height | number | Yes| Target height, in px.| 241| level | [QualityLevel](#qualitylevel)| No | Algorithm level (**HIGH**, **MEDIUM**, **LOW**, or **NONE**). The default value is **NONE**.| 242 243**Return value** 244 245| Type| Description | 246| ------------ | ------------ | 247| [image.PixelMap](arkts-apis-image-PixelMap.md) | PixelMap object.| 248 249**Error codes** 250 251For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Video Processing Engine Error Codes](errorcode-videoprocessingengine.md). 252 253| ID | Error Message | 254| :------------ | :------------ | 255| 801 | Capability not supported. Function enhanceDetailSync can not work correctly due to limited device capabilities.| 256| 29200004 | Failed to process image buffer. For example, the processing times out. | 257| 29200007 | Out of memory. | 258| 29200009 | Input value is invalid. This error is returned for all of the following error conditions: <br>1 - Invalid input or output image buffer - The image buffer width(height) is too large or colorspace is incorrect. <br>2 - Invalid parameter - The parameter does not contain valid information, such as detail enhancer level is incorrect. | 259 260**Example** 261 262```ts 263import { image, videoProcessingEngine } from '@kit.ImageKit'; 264async function enhanceDetailSync(sourceImage:image.PixelMap, width: number, height: number) { 265 videoProcessingEngine.initializeEnvironment(); 266 let imageProcessor = videoProcessingEngine.create() as videoProcessingEngine.ImageProcessor; 267 let enhancedPixelmap: image.PixelMap = imageProcessor.enhanceDetailSync( 268sourceImage, width, height, videoProcessingEngine.QualityLevel.HIGH); 269} 270``` 271 272### enhanceDetailSync 273 274enhanceDetailSync(sourceImage: image.PixelMap, scale: number, level?: QualityLevel): image.PixelMap 275 276Carries out detail enhancement processing. This API returns the result synchronously. 277 278**Widget capability**: This API can be used in ArkTS widgets since API version 18. 279 280**System capability**: SystemCapability.Multimedia.VideoProcessingEngine 281 282**Parameters** 283 284| Name| Type | Mandatory | Description | 285| :------------ | :------------ | :------------ | :------------ | 286| sourceImage | [image.PixelMap](arkts-apis-image-PixelMap.md) | Yes | Input image. | 287| scale | number | Yes| Target scale factor.| 288| level | [QualityLevel](#qualitylevel)| No | Algorithm level (**HIGH**, **MEDIUM**, **LOW**, or **NONE**). The default value is **NONE**.| 289 290**Return value** 291 292| Type| Description | 293| ------------ | ------------ | 294| [image.PixelMap](arkts-apis-image-PixelMap.md) | PixelMap object.| 295 296**Error codes** 297 298For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Video Processing Engine Error Codes](errorcode-videoprocessingengine.md). 299 300| ID | Error Message | 301| :------------ | :------------ | 302| 801 | Capability not supported. Function enhanceDetailSync can not work correctly due to limited device capabilities.| 303| 29200004 | Failed to process image buffer. For example, the processing times out. | 304| 29200007 | Out of memory. | 305| 29200009 | Input value is invalid. This error is returned for all of the following error conditions: <br>1 - Invalid input or output image buffer - The image buffer width(height) is too large or colorspace is incorrect. <br>2 - Invalid parameter - The parameter does not contain valid information, such as detail enhancer level is incorrect. | 306 307**Example** 308 309```ts 310import { image, videoProcessingEngine } from '@kit.ImageKit'; 311async function enhanceDetailSync(sourceImage:image.PixelMap, scale: number) { 312 videoProcessingEngine.initializeEnvironment(); 313 let imageProcessor = videoProcessingEngine.create() as videoProcessingEngine.ImageProcessor; 314 let enhancedPixelmap: image.PixelMap = imageProcessor.enhanceDetailSync( 315sourceImage, scale, videoProcessingEngine.QualityLevel.HIGH); 316} 317``` 318 319## QualityLevel 320 321Enumerates the algorithm levels. 322 323**Widget capability**: This API can be used in ArkTS widgets since API version 18. 324 325**System capability**: SystemCapability.Multimedia.VideoProcessingEngine 326 327| Name | Value | Description | 328| ------------ | ------------ | ------------ | 329| NONE | 0 | Applies only to scaling scenarios. Changing the aspect ratio is supported.<br>- Input resolution requirements (in px): width: [32, 3000]; height: [32, 3000]<br>- Output resolution requirements (in px): width: [32, 3000]; height: [32, 3000] | 330| LOW | 1 | Applies only to scaling scenarios. Changing the aspect ratio is supported.<br>- Input resolution requirements (in px): width: [32, 3000]; height: [32, 3000]<br>- Output resolution requirements (in px): width: [32, 3000]; height: [32, 3000] | 331| MEDIUM | 2 | Applies only to scaling scenarios. Changing the aspect ratio is supported.<br>- Input resolution requirements (in px): width: [32, 3000]; height: [32, 3000]<br>- Output resolution requirements (in px): width: [32, 3000]; height: [32, 3000] | 332| HIGH | 3 | 1. In scaling scenarios: Changing the aspect ratio is not supported.<br>- Input resolution requirements (in px): width: (32, 512) (2000, 8192]; height: (32, 512) (2000, 8192]<br>- Output resolution requirements (in px): width: (32, 512) (2000, 8192]; height: (32, 512) (2000, 8192]<br>2. In clarity enhancement and scaling scenarios: Changing the aspect ratio is supported.<br>- Input resolution requirements (in px): width: [512, 2000]; height: [512, 2000]<br>- Output resolution requirements (in px): width: [512, 2000]; height: [512, 2000]| 333