声明视频处理函数。
提供视频处理能力，包括颜色空间转换、元数据生成和视频缩放。
引用文件： <multimedia/video_processing_engine/video_processing.h>
库： libvideo_processing.so
系统能力： SystemCapability.Multimedia.VideoProcessingEngine
起始版本： 12
相关模块： VideoProcessing
VideoProcessing_ErrorCode OH_VideoProcessing_InitializeEnvironment(void)
描述
初始化视频处理全局环境。
该函数是可选的。
该函数只在主进程启动时被调用一次，用于初始化视频处理全局环境，这样可以减少OH_VideoProcessing_Create的时间。
调用OH_VideoProcessing_DeinitializeEnvironment释放视频处理全局环境。
初始化后，必须释放视频处理全局环境，释放方式及时机详见OH_VideoProcessing_DeinitializeEnvironment。
起始版本： 12
返回：
| 类型 | 说明 |
|---|---|
| VideoProcessing_ErrorCode | 如果初始化成功，返回VIDEO_PROCESSING_SUCCESS，否则返回VIDEO_PROCESSING_ERROR_INITIALIZE_FAILED。 如果失败，应用需要检查GPU是否正常工作。 |
VideoProcessing_ErrorCode OH_VideoProcessing_DeinitializeEnvironment(void)
描述
释放视频处理全局环境。
调用前，必须调用OH_VideoProcessing_InitializeEnvironment初始化。
通常在主进程即将退出时调用该函数来释放通过调用OH_VideoProcessing_InitializeEnvironment函数初始化的全局环境。
如果仍有视频处理的实例运行中，就不能调用该函数。
起始版本： 12
返回：
| 类型 | 说明 |
|---|---|
| VideoProcessing_ErrorCode | 如果执行成功，返回VIDEO_PROCESSING_SUCCESS。 如果还有视频处理的实例没有销毁或者没有调用OH_VideoProcessing_InitializeEnvironment，返回VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED。 |
bool OH_VideoProcessing_IsColorSpaceConversionSupported(const VideoProcessing_ColorSpaceInfo* sourceVideoInfo,const VideoProcessing_ColorSpaceInfo* destinationVideoInfo)
描述
查询是否支持视频颜色空间转换。
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| const VideoProcessing_ColorSpaceInfo* sourceVideoInfo | 输入视频颜色空间信息。 |
| const VideoProcessing_ColorSpaceInfo* destinationVideoInfo | 输出视频颜色空间信息。 |
返回：
| 类型 | 说明 |
|---|---|
| bool | 如果支持视频颜色空间转换返回true，否则返回false。 |
bool OH_VideoProcessing_IsMetadataGenerationSupported(const VideoProcessing_ColorSpaceInfo* sourceVideoInfo)
描述
查询是否支持视频元数据生成。
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| const VideoProcessing_ColorSpaceInfo* sourceVideoInfo | 输入视频颜色空间信息。 |
返回：
| 类型 | 说明 |
|---|---|
| bool | 如果支持视频元数据生成返回true，否则返回false。 |
VideoProcessing_ErrorCode OH_VideoProcessing_Create(OH_VideoProcessing** videoProcessor, int type)
描述
创建视频处理实例。
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| OH_VideoProcessing** videoProcessor | 输出参数。指向视频处理对象的指针的指针。输入前*videoProcessor必须是空指针。 |
| int type | 使用视频处理实例常量来指定处理类型。实例的处理类型不能改变。 |
返回：
| 类型 | 说明 |
|---|---|
| VideoProcessing_ErrorCode | 如果视频处理实例创建成功，返回VIDEO_PROCESSING_SUCCESS。 如果处理类型不支持，返回VIDEO_PROCESSING_ERROR_UNSUPPORTED_PROCESSING，例如，不支持元数据生成。 如果创建视频处理实例失败，返回VIDEO_PROCESSING_ERROR_CREATE_FAILED。 如果实例为空或实例的指针非空，返回VIDEO_PROCESSING_ERROR_INVALID_INSTANCE。 如果处理类型无效，返回VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 |
VideoProcessing_ErrorCode OH_VideoProcessing_Destroy(OH_VideoProcessing* videoProcessor)
描述
销毁视频处理实例。
销毁之前先停止实例，参阅OH_VideoProcessing_Stop。
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| OH_VideoProcessing* videoProcessor | 指向视频处理实例的指针，建议在实例销毁之后将其设置为空指针。 |
返回：
| 类型 | 说明 |
|---|---|
| VideoProcessing_ErrorCode | 如果实例销毁成功，返回VIDEO_PROCESSING_SUCCESS。 如果实例为空或者不是一个视频处理实例，返回VIDEO_PROCESSING_ERROR_INVALID_INSTANCE。 如果实例仍在运行，返回VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED。 |
VideoProcessing_ErrorCode OH_VideoProcessing_RegisterCallback(OH_VideoProcessing* videoProcessor,const VideoProcessing_Callback* callback, void* userData)
描述
注册回调函数。
在开始视频处理之前注册回调函数，视频处理过程中无法注册回调函数。
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| OH_VideoProcessing* videoProcessor | 指向视频处理实例的指针。 |
| const VideoProcessing_Callback* callback | 回调函数指针。 |
| void* userData | 指向用户特定数据的指针，如this指针。 |
返回：
| 类型 | 说明 |
|---|---|
| VideoProcessing_ErrorCode | 如果回调函数注册成功，返回VIDEO_PROCESSING_SUCCESS。 如果实例为空或者不是一个视频处理实例，返回VIDEO_PROCESSING_ERROR_INVALID_INSTANCE。 如果回调函数指针为空，返回VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 如果实例仍在运行，返回VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED。 |
VideoProcessing_ErrorCode OH_VideoProcessing_SetSurface(OH_VideoProcessing* videoProcessor,const OHNativeWindow* window)
描述
设置视频处理输出surface。
在视频处理启动之前设置输出surface。
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| OH_VideoProcessing* videoProcessor | 指向视频处理实例的指针。 |
| const OHNativeWindow* window | 指向输出surface的指针。 |
返回：
| 类型 | 说明 |
|---|---|
| VideoProcessing_ErrorCode | 如果输出surface设置成功，返回VIDEO_PROCESSING_SUCCESS。 如果实例为空或者不是一个视频处理实例，返回VIDEO_PROCESSING_ERROR_INVALID_INSTANCE。 如果window为空指针，返回VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 |
VideoProcessing_ErrorCode OH_VideoProcessing_GetSurface(OH_VideoProcessing* videoProcessor, OHNativeWindow** window)
描述
创建surface。
在视频处理启动之前创建输入surface。调用OH_NativeWindow_DestroyNativeWindow销毁输入surface。
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| OH_VideoProcessing* videoProcessor | 指向视频处理实例的指针。 |
| OHNativeWindow** window | 指向输入surface的指针。例如，此输入surface指针可以指向视频解码器输出surface。 |
返回：
| 类型 | 说明 |
|---|---|
| VideoProcessing_ErrorCode | 如果执行成功，返回VIDEO_PROCESSING_SUCCESS。 如果实例为空或者不是一个视频处理实例，返回VIDEO_PROCESSING_ERROR_INVALID_INSTANCE。 如果window为空指针或指向window的指针为空，返回VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 如果创建surface失败，或者输入surface已经创建，或者视频处理实例还在运行，返回VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED。 |
VideoProcessing_ErrorCode OH_VideoProcessing_SetParameter(OH_VideoProcessing* videoProcessor,const OH_AVFormat* parameter)
描述
设置视频处理输出参数。
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| OH_VideoProcessing* videoProcessor | 指向视频处理实例的指针。 |
| const OH_AVFormat* parameter | 指向视频处理参数实例的指针，用于传入需设置的视频处理参数，例如视频宽度、高度、像素格式及编解码格式等。 |
返回：
| 类型 | 说明 |
|---|---|
| VideoProcessing_ErrorCode | 如果参数设置成功，返回VIDEO_PROCESSING_SUCCESS。 如果实例为空或者不是一个视频处理实例，返回VIDEO_PROCESSING_ERROR_INVALID_INSTANCE。 如果参数为空，返回VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 如果参数的某些属性无效，返回VIDEO_PROCESSING_ERROR_INVALID_VALUE，例如，包含不支持的参数值。 如果内存分配失败，返回VIDEO_PROCESSING_ERROR_NO_MEMORY。 |
VideoProcessing_ErrorCode OH_VideoProcessing_GetParameter(OH_VideoProcessing* videoProcessor, OH_AVFormat* parameter)
描述
获取视频处理参数。
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| OH_VideoProcessing* videoProcessor | 指向视频处理实例的指针。 |
| OH_AVFormat* parameter | 指向视频处理参数实例的指针，用于获取当前视频处理的参数，比如视频宽度、高度、像素格式、编解码格式等。 |
返回：
| 类型 | 说明 |
|---|---|
| VideoProcessing_ErrorCode | 如果参数获取成功，返回VIDEO_PROCESSING_SUCCESS。 如果实例为空或者不是一个视频处理实例，返回VIDEO_PROCESSING_ERROR_INVALID_INSTANCE。 如果参数为空，返回VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 |
VideoProcessing_ErrorCode OH_VideoProcessing_Start(OH_VideoProcessing* videoProcessor)
描述
启动视频处理。
成功启动后，回调函数OH_VideoProcessingCallback_OnState会报告VideoProcessing_State.VIDEO_PROCESSING_STATE_RUNNING状态。
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| OH_VideoProcessing* videoProcessor | 指向视频处理实例的指针。 |
返回：
| 类型 | 说明 |
|---|---|
| VideoProcessing_ErrorCode | 如果执行成功，返回VIDEO_PROCESSING_SUCCESS。 如果实例为空或者不是一个视频处理实例，返回VIDEO_PROCESSING_ERROR_INVALID_INSTANCE。 如果没有设置输出surface，或者没有创建输入surface，或者实例已经运行，返回VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED。 |
VideoProcessing_ErrorCode OH_VideoProcessing_Stop(OH_VideoProcessing* videoProcessor)
描述
停止视频处理。
成功停止后，回调函数OH_VideoProcessingCallback_OnState会报告VideoProcessing_State.VIDEO_PROCESSING_STATE_STOPPED状态。
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| OH_VideoProcessing* videoProcessor | 指向视频处理实例的指针。 |
返回：
| 类型 | 说明 |
|---|---|
| VideoProcessing_ErrorCode | 如果执行成功，返回VIDEO_PROCESSING_SUCCESS。 如果实例为空或者不是一个视频处理实例，返回VIDEO_PROCESSING_ERROR_INVALID_INSTANCE。 如果实例已经停止，返回VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED。 |
VideoProcessing_ErrorCode OH_VideoProcessing_RenderOutputBuffer(OH_VideoProcessing* videoProcessor, uint32_t index)
描述
渲染处理并输出buffer。
如果设置了回调函数OH_VideoProcessingCallback_OnNewOutputBuffer，当输出buffer准备好之后会通过回调函数把buffer的索引返回给用户。
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| OH_VideoProcessing* videoProcessor | 指向视频处理实例的指针。 |
| uint32_t index | 输出buffer的索引。 |
返回：
| 类型 | 说明 |
|---|---|
| VideoProcessing_ErrorCode | 如果执行成功，返回VIDEO_PROCESSING_SUCCESS。 如果实例为空或者不是一个视频处理实例，返回VIDEO_PROCESSING_ERROR_INVALID_INSTANCE。 如果索引值无效，输出VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 如果没有设置回调函数OH_VideoProcessingCallback_OnNewOutputBuffer或者实例已经停止运行，返回VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED。 |
VideoProcessing_ErrorCode OH_VideoProcessingCallback_Create(VideoProcessing_Callback** callback)
描述
创建视频处理回调函数对象。
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| VideoProcessing_Callback** callback | 输出参数。*callback是指向回调函数对象的指针。在创建回调函数对象之前*callback必须为空指针。 |
返回：
| 类型 | 说明 |
|---|---|
| VideoProcessing_ErrorCode | 如果回调函数对象创建成功，返回VIDEO_PROCESSING_SUCCESS。 如果callback为空，返回VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 如果内存不足，返回VIDEO_PROCESSING_ERROR_NO_MEMORY。 |
VideoProcessing_ErrorCode OH_VideoProcessingCallback_Destroy(VideoProcessing_Callback* callback)
描述
销毁回调对象。回调对象在注册之后就可以销毁。
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| VideoProcessing_Callback* callback | 指向回调对象的指针，建议在回调对象销毁之后将其设置为空指针。 |
返回：
| 类型 | 说明 |
|---|---|
| VideoProcessing_ErrorCode | 如果回调对象销毁成功，返回VIDEO_PROCESSING_SUCCESS。 如果callback为空，返回VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 |
VideoProcessing_ErrorCode OH_VideoProcessingCallback_BindOnError(VideoProcessing_Callback* callback,OH_VideoProcessingCallback_OnError onError)
描述
绑定回调函数OH_VideoProcessingCallback_OnError到回调对象。绑定完成之后，需要调用 OH_VideoProcessing_RegisterCallback，将回调对象注册到视频处理实例，才能使其生效。
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| VideoProcessing_Callback* callback | 指向回调对象的指针。 |
| OH_VideoProcessingCallback_OnError onError | 回调函数。 |
返回：
| 类型 | 说明 |
|---|---|
| VideoProcessing_ErrorCode | 如果函数绑定成功，返回VIDEO_PROCESSING_SUCCESS。 如果callback为空或者onError为空，返回VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 |
VideoProcessing_ErrorCode OH_VideoProcessingCallback_BindOnState(VideoProcessing_Callback* callback,OH_VideoProcessingCallback_OnState onState)
描述
绑定回调函数OH_VideoProcessingCallback_OnState到回调对象。绑定完成之后，需要调用 OH_VideoProcessing_RegisterCallback，将回调对象注册到视频处理实例，才能使其生效。
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| VideoProcessing_Callback* callback | 指向回调对象的指针。 |
| OH_VideoProcessingCallback_OnState onState | 回调函数。 |
返回：
| 类型 | 说明 |
|---|---|
| VideoProcessing_ErrorCode | 如果函数绑定成功，返回VIDEO_PROCESSING_SUCCESS。 如果callback为空或者onState为空，返回VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 |
VideoProcessing_ErrorCode OH_VideoProcessingCallback_BindOnNewOutputBuffer(VideoProcessing_Callback* callback,OH_VideoProcessingCallback_OnNewOutputBuffer onNewOutputBuffer)
描述
绑定回调函数OH_VideoProcessingCallback_OnNewOutputBuffer到回调对象。绑定完成之后，需要调用 OH_VideoProcessing_RegisterCallback，将回调对象注册到视频处理实例，才能使其生效。
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| VideoProcessing_Callback* callback | 指向回调对象的指针。 |
| OH_VideoProcessingCallback_OnNewOutputBuffer onNewOutputBuffer | 回调函数。 |
返回：
| 类型 | 说明 |
|---|---|
| VideoProcessing_ErrorCode | 如果函数绑定成功，返回VIDEO_PROCESSING_SUCCESS。 如果callback为空，返回VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 |
bool OH_VideoProcessing_IsAutoEffectSupported(uint32_t type)
描述
系统查询是否支持视频自动增强效果。
起始版本： 26.0.1
参数：
| 参数项 | 描述 |
|---|---|
| uint32_t type | 要查询的自动增强效果类型。 |
返回：
| 类型 | 说明 |
|---|---|
| bool | 是否支持视频自动增强效果，true表示支持视频自动增强效果，false表示不支持。 |
VideoProcessing_ErrorCode OH_VideoProcessing_UseAutoEffect(uint32_t type, bool enable, const char *name)
描述
在将要创建名字为name的XComponent中指定是否启用类型为type的自动增强效果。此接口应在OH_VideoProcessing_SetAutoEffectParam之前调用。
使用场景
在视频播放场景使用。AISR称作AI超分，是AutoEffect中的一种。应用在进行SDR视频播放，希望对播放的画面进行清晰度提升时，可使用AUTOEFFECT的AISR超分能力，对视频播放的XComponent组件使能此效果。HDR视频类型不支持本功能。
起始版本： 26.0.1
参数：
| 参数项 | 描述 |
|---|---|
| uint32_t type | 指定要使用的自动增强效果类型。 |
| bool enable | 启用或禁用指定的XComponent中该自动增强效果类型。 |
| const char *name | 指定XComponent的名称。 |
返回：
| 类型 | 说明 |
|---|---|
| VideoProcessing_ErrorCode | - 如果操作成功，返回VIDEO_PROCESSING_SUCCESS。 - 如果type不是VIDEO_PROCESSING_TYPE_AUTOEFFECT_AISR或name为空，返回VIDEO_PROCESSING_ERROR_INVALID_VALUE。 - 如果OH_VideoProcessing_IsAutoEffectSupported对该type返回false，或该name已通过调用本函数注册过，返回VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED。 |
VideoProcessing_ErrorCode OH_VideoProcessing_SetAutoEffectParam(uint32_t type, const char *name, const OH_AVFormat *param)
描述
对名字为name的XComponent设置AISR的参数param。此函数调用后，本次调用时指定的名为name的XComponent获得AISR效果，其他的XComponent失去AISR效果。
起始版本： 26.0.1
参数：
| 参数项 | 描述 |
|---|---|
| uint32_t type | 指定要使用的自动增强效果类型。 |
| const char *name | 指定XComponent的名称。 |
| const OH_AVFormat* param | 此参数依据type参数，具体的type可参考video_processing_types.h中的变量。 |
返回：
| 类型 | 说明 |
|---|---|
| VideoProcessing_ErrorCode | - 如果操作成功，返回VIDEO_PROCESSING_SUCCESS。 - 如果name为空或param值无效，返回VIDEO_PROCESSING_ERROR_INVALID_VALUE。 - 如果OH_VideoProcessing_IsAutoEffectSupported对该type返回false、name不匹配任何已注册的name、VPE实例尚未创建或未对该name调用过OH_VideoProcessing_UseAutoEffect，返回VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED。 - 如果发生内部算法错误，返回VIDEO_PROCESSING_ERROR_UNKNOWN。 |