@ohos.multimedia.videoProcessingEngine (Video Processing Engine)
The module provides the capabilities for enhancing the clarity and scaling of image content.
This module includes a base class: ImageProcessor.
NOTE
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.
Modules to Import
import { videoProcessingEngine } from '@kit.ImageKit';
videoProcessingEngine.initializeEnvironment
initializeEnvironment(): Promise<void>
Initializes the environment. This API uses a promise to return the result.
Widget capability: This API can be used in ArkTS widgets since API version 18.
System capability: SystemCapability.Multimedia.VideoProcessingEngine
Return value
| Type | Description |
|---|---|
| Promise<void> | Promise that returns no value. |
Error codes
For details about the error codes, see Universal Error Codes and Video Processing Engine Error Codes.
| ID | Error Message |
|---|---|
| 801 | Capability not supported. Function initializeEnvironment can not work correctly due to limited device capabilities. |
| 29200002 | The global environment initialization for image processing failed, such as failure to initialize the GPU environment. |
| 29200006 | The operation is not permitted. This may be caused by incorrect status. |
| 29200007 | Out of memory. |
Example
import { videoProcessingEngine } from '@kit.ImageKit';
async function initializeEnvironment() {
videoProcessingEngine.initializeEnvironment();
}
videoProcessingEngine.deinitializeEnvironment
deinitializeEnvironment(): Promise<void>
Deinitializes the environment. This API uses a promise to return the result.
Widget capability: This API can be used in ArkTS widgets since API version 18.
System capability: SystemCapability.Multimedia.VideoProcessingEngine
Return value
| Type | Description |
|---|---|
| Promise<void> | Promise that returns no value. |
Error codes
For details about the error codes, see Video Processing Engine Error Codes.
| ID | Error Message |
|---|---|
| 29200006 | The operation is not permitted. This may be caused by incorrect status. |
Example
import { videoProcessingEngine } from '@kit.ImageKit';
async function deinitializeEnvironment() {
videoProcessingEngine.initializeEnvironment();
videoProcessingEngine.deinitializeEnvironment();
}
videoProcessingEngine.create
create(): ImageProcessor
Creates an instance of the image processing module. If the operation fails, null is returned.
Widget capability: This API can be used in ArkTS widgets since API version 18.
System capability: SystemCapability.Multimedia.VideoProcessingEngine
Return value
| Type | Description |
|---|---|
| ImageProcessor | Instance of the image processing module. |
Error codes
For details about the error codes, see Universal Error Codes and Video Processing Engine Error Codes.
| ID | Error Message |
|---|---|
| 801 | Capability not supported. Function create can not work correctly due to limited device capabilities. |
| 29200003 | Failed to create image processing instance. For example, the number of instances exceeds the upper limit. |
| 29200007 | Out of memory. |
Example
import { videoProcessingEngine } from '@kit.ImageKit';
async function create() {
videoProcessingEngine.initializeEnvironment();
let imageProcessor = videoProcessingEngine.create() as videoProcessingEngine.ImageProcessor;
}
ImageProcessor
Image 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.
Constraints:
- Only Standard Dynamic Range (SDR) images can be processed.
- Images in RGBA, BGRA, NV12, and NV21 pixel formats can be processed. The output format is the same as the input format.
enhanceDetail
enhanceDetail(sourceImage: image.PixelMap, width: number, height: number, level?: QualityLevel): Promise<image.PixelMap>
Carries out detail enhancement processing. This API uses a promise to return the result.
Widget capability: This API can be used in ArkTS widgets since API version 18.
System capability: SystemCapability.Multimedia.VideoProcessingEngine
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| sourceImage | image.PixelMap | Yes | Input image, which must be allocated in DMA memory. For details, see PixelMap Memory Types. |
| width | number | Yes | Target width, in px. Its value range is [512, 2000] when level is HIGH and [32, 3000] when level is other values. |
| height | number | Yes | Target height, in px. Its value range is [512, 2000] when level is HIGH and [32, 3000] when level is other values. |
| level | QualityLevel | No | Algorithm level (HIGH, MEDIUM, LOW, or NONE). The default value is NONE. |
Return value
| Type | Description |
|---|---|
| Promise<image.PixelMap> | Promise usd to return the PixelMap object. |
Error codes
For details about the error codes, see Universal Error Codes and Video Processing Engine Error Codes.
| ID | Error Message |
|---|---|
| 801 | Capability not supported. Function enhanceDetail can not work correctly due to limited device capabilities. |
| 29200007 | Out of memory. |
| 29200009 | Input value is invalid. This error is returned for all of the following error conditions: 1 - Invalid input or output image buffer - The image buffer width(height) is too large or colorspace is incorrect. 2 - Invalid parameter - The parameter does not contain valid information, such as detail enhancer level is incorrect. |
Example
import { image, videoProcessingEngine } from '@kit.ImageKit';
async function enhanceDetail(sourceImage: image.PixelMap, width: number, height: number) {
videoProcessingEngine.initializeEnvironment();
let imageProcessor = videoProcessingEngine.create() as videoProcessingEngine.ImageProcessor;
// Example: The width can be set to 1024, and the height can be set to 1280.
let enhancedPixelmap: Promise<image.PixelMap> =
imageProcessor.enhanceDetail(sourceImage, width, height, videoProcessingEngine.QualityLevel.HIGH);
}
enhanceDetail
enhanceDetail(sourceImage: image.PixelMap, scale: number, level?: QualityLevel): Promise<image.PixelMap>
Carries out detail enhancement processing. This API uses a promise to return the result.
Widget capability: This API can be used in ArkTS widgets since API version 18.
System capability: SystemCapability.Multimedia.VideoProcessingEngine
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| sourceImage | image.PixelMap | Yes | Input image, which must be allocated in DMA memory. For details, see PixelMap Memory Types. |
| scale | number | Yes | Target scale factor. Its value range is (0.0, 32.0]. The maximum supported scale is 32x, provided the resulting resolution stays within the required bounds. |
| level | QualityLevel | No | Algorithm level (HIGH, MEDIUM, LOW, or NONE). The default value is NONE. |
Return value
| Type | Description |
|---|---|
| Promise<image.PixelMap> | Promise usd to return the PixelMap object. |
Error codes
For details about the error codes, see Universal Error Codes and Video Processing Engine Error Codes.
| ID | Error Message |
|---|---|
| 801 | Capability not supported. Function enhanceDetail can not work correctly due to limited device capabilities. |
| 29200007 | Out of memory. |
| 29200009 | Input value is invalid. This error is returned for all of the following error conditions: 1 - Invalid input or output image buffer - The image buffer width(height) is too large or colorspace is incorrect. 2 - Invalid parameter - The parameter does not contain valid information, such as detail enhancer level is incorrect. |
Example
import { image, videoProcessingEngine } from '@kit.ImageKit';
async function enhanceDetail(sourceImage: image.PixelMap, scale: number) {
videoProcessingEngine.initializeEnvironment();
let imageProcessor = videoProcessingEngine.create() as videoProcessingEngine.ImageProcessor;
// Example: The scale can be set to 2.0.
let enhancedPixelmap: Promise<image.PixelMap> =
imageProcessor.enhanceDetail(sourceImage, scale, videoProcessingEngine.QualityLevel.HIGH);
}
enhanceDetailSync
enhanceDetailSync(sourceImage: image.PixelMap, width: number, height: number, level?: QualityLevel): image.PixelMap
Carries out detail enhancement processing. This API returns the result synchronously.
Widget capability: This API can be used in ArkTS widgets since API version 18.
System capability: SystemCapability.Multimedia.VideoProcessingEngine
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| sourceImage | image.PixelMap | Yes | Input image, which must be allocated in DMA memory. For details, see PixelMap Memory Types. |
| width | number | Yes | Target width, in px. Its value range is [512, 2000] when level is HIGH and [32, 3000] when level is other values. |
| height | number | Yes | Target height, in px. Its value range is [512, 2000] when level is HIGH and [32, 3000] when level is other values. |
| level | QualityLevel | No | Algorithm level (HIGH, MEDIUM, LOW, or NONE). The default value is NONE. |
Return value
| Type | Description |
|---|---|
| image.PixelMap | PixelMap object. |
Error codes
For details about the error codes, see Universal Error Codes and Video Processing Engine Error Codes.
| ID | Error Message |
|---|---|
| 801 | Capability not supported. Function enhanceDetailSync can not work correctly due to limited device capabilities. |
| 29200004 | Failed to process image buffer. For example, the processing times out. |
| 29200007 | Out of memory. |
| 29200009 | Input value is invalid. This error is returned for all of the following error conditions: 1 - Invalid input or output image buffer - The image buffer width(height) is too large or colorspace is incorrect. 2 - Invalid parameter - The parameter does not contain valid information, such as detail enhancer level is incorrect. |
Example
import { image, videoProcessingEngine } from '@kit.ImageKit';
async function enhanceDetailSync(sourceImage: image.PixelMap, width: number, height: number) {
videoProcessingEngine.initializeEnvironment();
let imageProcessor = videoProcessingEngine.create() as videoProcessingEngine.ImageProcessor;
// Example: The width can be set to 1024, and the height can be set to 1280.
let enhancedPixelmap: image.PixelMap = imageProcessor.enhanceDetailSync(
sourceImage, width, height, videoProcessingEngine.QualityLevel.HIGH);
}
enhanceDetailSync
enhanceDetailSync(sourceImage: image.PixelMap, scale: number, level?: QualityLevel): image.PixelMap
Carries out detail enhancement processing. This API returns the result synchronously.
Widget capability: This API can be used in ArkTS widgets since API version 18.
System capability: SystemCapability.Multimedia.VideoProcessingEngine
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| sourceImage | image.PixelMap | Yes | Input image, which must be allocated in DMA memory. For details, see PixelMap Memory Types. |
| scale | number | Yes | Target scale factor. Its value range is (0.0, 32.0]. The maximum supported scale is 32x, provided the resulting resolution stays within the required bounds. |
| level | QualityLevel | No | Algorithm level (HIGH, MEDIUM, LOW, or NONE). The default value is NONE. |
Return value
| Type | Description |
|---|---|
| image.PixelMap | PixelMap object. |
Error codes
For details about the error codes, see Universal Error Codes and Video Processing Engine Error Codes.
| ID | Error Message |
|---|---|
| 801 | Capability not supported. Function enhanceDetailSync can not work correctly due to limited device capabilities. |
| 29200004 | Failed to process image buffer. For example, the processing times out. |
| 29200007 | Out of memory. |
| 29200009 | Input value is invalid. This error is returned for all of the following error conditions: 1 - Invalid input or output image buffer - The image buffer width(height) is too large or colorspace is incorrect. 2 - Invalid parameter - The parameter does not contain valid information, such as detail enhancer level is incorrect. |
Example
import { image, videoProcessingEngine } from '@kit.ImageKit';
async function enhanceDetailSync(sourceImage: image.PixelMap, scale: number) {
videoProcessingEngine.initializeEnvironment();
let imageProcessor = videoProcessingEngine.create() as videoProcessingEngine.ImageProcessor;
// Example: The scale can be set to 2.0.
let enhancedPixelmap: image.PixelMap = imageProcessor.enhanceDetailSync(
sourceImage, scale, videoProcessingEngine.QualityLevel.HIGH);
}
QualityLevel
Enumerates the algorithm levels.
Widget capability: This API can be used in ArkTS widgets since API version 18.
System capability: SystemCapability.Multimedia.VideoProcessingEngine
| Name | Value | Description |
|---|---|---|
| NONE | 0 | Applies only to scaling scenarios. Changing the aspect ratio is supported. - Input resolution requirements (in px): width: [32, 3000]; height: [32, 3000] - Output resolution requirements (in px): width: [32, 3000]; height: [32, 3000] |
| LOW | 1 | Applies only to scaling scenarios. Changing the aspect ratio is supported. - Input resolution requirements (in px): width: [32, 3000]; height: [32, 3000] - Output resolution requirements (in px): width: [32, 3000]; height: [32, 3000] |
| MEDIUM | 2 | Applies only to scaling scenarios. Changing the aspect ratio is supported. - Input resolution requirements (in px): width: [32, 3000]; height: [32, 3000] - Output resolution requirements (in px): width: [32, 3000]; height: [32, 3000] |
| HIGH | 3 | 1. In scaling scenarios: Changing the aspect ratio is not supported. - Input resolution requirements (in px): width: (32, 512) (2000, 8192]; height: (32, 512) (2000, 8192] - Output resolution requirements (in px): width: (32, 512) (2000, 8192]; height: (32, 512) (2000, 8192] 2. In clarity enhancement and scaling scenarios: Changing the aspect ratio is supported. - Input resolution requirements (in px): width: [512, 2000]; height: [512, 2000] - Output resolution requirements (in px): width: [512, 2000]; height: [512, 2000] |