diff --git a/zh-cn/multimedia/video_processing_engine/image_processing.h b/zh-cn/multimedia/video_processing_engine/image_processing.h new file mode 100644 index 000000000..c8fce2278 --- /dev/null +++ b/zh-cn/multimedia/video_processing_engine/image_processing.h @@ -0,0 +1,271 @@ +/* + * Copyright (c) 2024 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup ImageProcessing + * @{ + * + * @brief Provide APIs for image quality processing. + * + * @since 13 + */ + +/** + * @file image_processing.h + * + * @brief 声明图片处理函数。提供图片处理能力,包括色彩空间转换,元数据生成及图片缩放。 + * + * @library libimage_processing.so + * @syscap SystemCapability.Multimedia.VideoProcessingEngine + * @kit ImageKit + * @since 13 + */ + +#ifndef VIDEO_PROCESSING_ENGINE_C_API_IMAGE_PROCESSING_H +#define VIDEO_PROCESSING_ENGINE_C_API_IMAGE_PROCESSING_H + +#include +#include +#include "image_processing_types.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 初始化图片处理模块的全局环境。 + *
此函数为非必需函数。通常此函数在主进程启动时被调用,用于图片处理模块的全局环境初始化并可以减少{@link OH_ImageProcessing_Create}的耗时。调用 + * {@link OH_ImageProcessing_DeinitializeEnvironment}进行全局环境反初始化。可用于检查设备GPU是否正常工作。 + * + * @return 如果初始化成功,则返回IMAGE_PROCESSING_SUCCESS,否则返回IMAGE_PROCESSING_ERROR_INITIALIZE_FAILED。 + * @since 13 + */ +ImageProcessing_ErrorCode OH_ImageProcessing_InitializeEnvironment(void); + +/** + * @brief 反初始化图片处理模块的全局环境。 + *
如果{@link OH_ImageProcessing_InitializeEnvironment}被调用,则此函数为必需函数。通常此函数在主进程准备退出时被调用,用于反初始化图片处理模块的全局环境(由 + * {@link OH_ImageProcessing_InitializeEnvironment}接口初始化)。如果此时存在图片处理实例,则不应调用此函数。如果 + * {@link OH_ImageProcessing_InitializeEnvironment}未被调用,则不应调用此函数。 + * + * @return 如果反初始化成功,则返回IMAGE_PROCESSING_SUCCESS。 + *
如果存在图片处理实例未被销毁或{@link OH_ImageProcessing_InitializeEnvironment}接口未被调用, + * 则返回IMAGE_PROCESSING_ERROR_OPERATION_NOT_PERMITTED。 + * @since 13 + */ +ImageProcessing_ErrorCode OH_ImageProcessing_DeinitializeEnvironment(void); + +/** + * @brief 查询是否支持当前图片色彩空间转换能力。 + * + * @param sourceImageInfo 指向输入图片色彩空间信息的指针。 + * @param destinationImageInfo 指向输出图片色彩空间信息的指针, + * @return 如果支持当前色彩空间转换,返回true。 + *
如果不支持当前色彩空间转换,返回false。 + * @since 13 + */ +bool OH_ImageProcessing_IsColorSpaceConversionSupported( + const ImageProcessing_ColorSpaceInfo* sourceImageInfo, + const ImageProcessing_ColorSpaceInfo* destinationImageInfo); + +/** + * @brief 查询是否支持HDR双层图片转换为HDR单层图片。 + * + * @param sourceImageInfo 指向输入图片色彩空间信息的指针。 + * @param sourceGainmapInfo 指向输入Gainmap色彩空间信息的指针。 + * @param destinationImageInfo 指向输出图片色彩空间信息的指针。 + * @return 如果支持HDR双层图片转换HDR单层图片能力,返回true。 + *
如果不支持此能力,返回false。 + * @since 13 + */ +bool OH_ImageProcessing_IsCompositionSupported( + const ImageProcessing_ColorSpaceInfo* sourceImageInfo, + const ImageProcessing_ColorSpaceInfo* sourceGainmapInfo, + const ImageProcessing_ColorSpaceInfo* destinationImageInfo); + +/** + * @brief 查询是否支持HDR单层图片转换为HDR双层图片。 + * + * @param sourceImageInfo 指向输入图片色彩空间信息的指针。 + * @param destinationImageInfo 指向输出图片色彩空间信息的指针。 + * @param destinationGainmapInfo 指向输出Gainmap色彩空间信息的指针。 + * @return 如果支持HDR单层图片转换为HDR双层图片能力,返回true。 + *
如果不支持此能力,返回false。 + * @since 13 + */ +bool OH_ImageProcessing_IsDecompositionSupported( + const ImageProcessing_ColorSpaceInfo* sourceImageInfo, + const ImageProcessing_ColorSpaceInfo* destinationImageInfo, + const ImageProcessing_ColorSpaceInfo* destinationGainmapInfo); + +/** + * @brief 查询是否支持图片元数据生成能力。 + * + * @param sourceImageInfo 指向输入图片色彩空间信息的指针。 + * @return 如果支持图片元数据生成能力,返回true。 + *
如果不支持此能力,返回false。 + * @since 13 + */ +bool OH_ImageProcessing_IsMetadataGenerationSupported( + const ImageProcessing_ColorSpaceInfo* sourceImageInfo); + +/** + * @brief 创建一个图片处理模块实例。 + * + * @param imageProcessor 输出参数。指针\*imageProcessor指向一个新的图片处理对象。指针\*imageProcessor在传递前必须是一个空指针。 + * @param type 使用IMAGE_PROCESSING_TYPE_XXX来指定图片处理类型。此实例的类型在创建后不能更改。 + * @return 如果创建成功,则返回IMAGE_PROCESSING_SUCCESS。 + *
当指定的图片处理类型不支持时,返回IMAGE_PROCESSING_ERROR_UNSUPPORTED_PROCESSING,例如如果不支持图片元数据生成能力,则返回不支持该处理类型。 + *
当创建失败时,返回IMAGE_PROCESSING_ERROR_CREATE_FAILED。 + *
当该实例为空或指向该实例的指针为空时,返回IMAGE_PROCESSING_ERROR_INVALID_INSTANCE。 + *
当指定的图片处理类型无效时,返回IMAGE_PROCESSING_ERROR_INVALID_PARAMETER。 + * @since 13 + */ +ImageProcessing_ErrorCode OH_ImageProcessing_Create(OH_ImageProcessing** imageProcessor, int32_t type); + +/** + * @brief 销毁当前图片处理模块实例。 + * + * @param imageProcessor 指向图片处理模块实例的指针。当实例被销毁时,建议该指针设置为空。 + * @return 如果销毁成功,则返回IMAGE_PROCESSING_SUCCESS。 + *
当该实例为空或该实例不是图片处理模块实例时,返回IMAGE_PROCESSING_ERROR_INVALID_INSTANCE。 + * @since 13 + */ +ImageProcessing_ErrorCode OH_ImageProcessing_Destroy(OH_ImageProcessing* imageProcessor); + +/** + * @brief 设置图片处理模块参数。通过特定参数键添加参数。 + * + * @param imageProcessor 指向图片处理模块实例的指针。 + * @param parameter 图片处理参数。 + * @return 如果设置参数成功,则返回IMAGE_PROCESSING_SUCCESS。 + *
当该实例为空或该实例不是图片处理模块实例时,返回IMAGE_PROCESSING_ERROR_INVALID_INSTANCE。 + *
当参数为空时,返回IMAGE_PROCESSING_ERROR_INVALID_PARAMETER。 + *
当部分参数无效时,返回IMAGE_PROCESSING_ERROR_INVALID_VALUE,例如参数包含不支持的参数键或值。 + *
当内存分配失败时,返回IMAGE_PROCESSING_ERROR_NO_MEMORY。 + * @since 13 + */ +ImageProcessing_ErrorCode OH_ImageProcessing_SetParameter(OH_ImageProcessing* imageProcessor, + const OH_AVFormat* parameter); + +/** + * @brief 获取图片处理模块参数。通过特定参数键获取参数。 + * + * @param imageProcessor 指向图片处理模块实例的指针。 + * @param parameter 该图片处理模块实例使用的参数。 + * @return 如果获取参数成功,则返回IMAGE_PROCESSING_SUCCESS。 + *
当该实例为空或该实例不是图片处理模块实例时,返回IMAGE_PROCESSING_ERROR_INVALID_INSTANCE。 + *
当参数为空时,返回IMAGE_PROCESSING_ERROR_INVALID_PARAMETER。 + * @since 13 + */ +ImageProcessing_ErrorCode OH_ImageProcessing_GetParameter(OH_ImageProcessing* imageProcessor, + OH_AVFormat* parameter); + +/** + * @brief 实现单层图片间转换。此函数包括HDR图片到SDR图片的色彩空间转换,SDR图片到HDR图片的色彩空间转换,SDR图片到SDR图片的色彩空间转换和HDR图片的色彩空间转换。 + * + * @param imageProcessor 指向图片处理模块实例的指针。该实例应该由IMAGE_PROCESSING_TYPE_COLOR_SPACE_CONVERSION类型创建。 + * @param sourceImage 指向输入图片的指针,指向的OH_PixelmapNative需为DMA内存,具体情况请参考{@link PixelMap的内存类型介绍}。 + * @param destinationImage 指向输出图片的指针,指向的OH_PixelmapNative需为DMA内存,具体情况请参考{@link PixelMap的内存类型介绍}。 + * @return 如果图片处理成功,则返回IMAGE_PROCESSING_SUCCESS。 + *
当该实例为空或该实例不是图片处理模块实例时,返回IMAGE_PROCESSING_ERROR_INVALID_INSTANCE。 + *
当图片为空时,返回IMAGE_PROCESSING_ERROR_INVALID_PARAMETER。 + *
当图片的某些属性无效时,返回IMAGE_PROCESSING_ERROR_INVALID_VALUE,例如图片的色彩空间是不支持的。 + *
当该图片处理不支持时,返回IMAGE_PROCESSING_ERROR_UNSUPPORTED_PROCESSING。 + *
当该图片处理中返回错误时,返回IMAGE_PROCESSING_ERROR_PROCESS_FAILED。 + *
当内存分配失败时,返回IMAGE_PROCESSING_ERROR_NO_MEMORY。 + * @since 13 + */ +ImageProcessing_ErrorCode OH_ImageProcessing_ConvertColorSpace(OH_ImageProcessing* imageProcessor, + OH_PixelmapNative* sourceImage, OH_PixelmapNative* destinationImage); + +/** + * @brief 实现HDR双层图片到HDR单层图片的转换。此函数通过输入图片与输入Gainmap生成输出图片。 + * + * @param imageProcessor 指向图片处理模块实例的指针。该实例应该由IMAGE_PROCESSING_TYPE_COMPOSITION类型创建。 + * @param sourceImage 指向输入图片的指针,指向的OH_PixelmapNative需为DMA内存,具体情况请参考{@link PixelMap的内存类型介绍}。 + * @param sourceGainmap 指向输入Gainmap的指针,指向的OH_PixelmapNative需为DMA内存,具体情况请参考{@link PixelMap的内存类型介绍}。 + * @param destinationImage 指向输出图片的指针,指向的OH_PixelmapNative需为DMA内存,具体情况请参考{@link PixelMap的内存类型介绍}。 + * @return 如果图片处理成功,则返回IMAGE_PROCESSING_SUCCESS。 + *
当该实例为空或该实例不是图片处理模块实例时,返回IMAGE_PROCESSING_ERROR_INVALID_INSTANCE。 + *
当图片为空时,返回IMAGE_PROCESSING_ERROR_INVALID_PARAMETER。 + *
当图片的某些属性无效时,返回IMAGE_PROCESSING_ERROR_INVALID_VALUE,例如图片的色彩空间是不支持的。 + *
当该图片处理不支持时,返回IMAGE_PROCESSING_ERROR_UNSUPPORTED_PROCESSING。 + *
当该图片处理中返回错误时,返回IMAGE_PROCESSING_ERROR_PROCESS_FAILED。 + *
当内存分配失败时,返回IMAGE_PROCESSING_ERROR_NO_MEMORY。 + * @since 13 + */ +ImageProcessing_ErrorCode OH_ImageProcessing_Compose(OH_ImageProcessing* imageProcessor, + OH_PixelmapNative* sourceImage, OH_PixelmapNative* sourceGainmap, OH_PixelmapNative* destinationImage); + +/** + * @brief 实现HDR单层图片到HDR双层图片的转换。此函数通过输入图片生成输出图片和输出Gainmap。 + * + * @param imageProcessor 指向图片处理模块实例的指针。该实例应该由IMAGE_PROCESSING_TYPE_DECOMPOSITION类型创建。 + * @param sourceImage 指向输入图片的指针,指向的OH_PixelmapNative需为DMA内存,具体情况请参考{@link PixelMap的内存类型介绍}。 + * @param destinationImage 指向输出图片的指针,指向的OH_PixelmapNative需为DMA内存,具体情况请参考{@link PixelMap的内存类型介绍}。 + * @param destinationGainmap 指向输出Gainmap的指针,指向的OH_PixelmapNative需为DMA内存,具体情况请参考{@link PixelMap的内存类型介绍}。 + * @return 如果图片处理成功,则返回IMAGE_PROCESSING_SUCCESS。 + *
当该实例为空或该实例不是图片处理模块实例时,返回IMAGE_PROCESSING_ERROR_INVALID_INSTANCE。 + *
当图片为空时,返回IMAGE_PROCESSING_ERROR_INVALID_PARAMETER。 + *
当图片的某些属性无效时,返回IMAGE_PROCESSING_ERROR_INVALID_VALUE,例如图片的色彩空间是不支持的。 + *
当该图片处理不支持时,返回IMAGE_PROCESSING_ERROR_UNSUPPORTED_PROCESSING。 + *
当该图片处理中返回错误时,返回IMAGE_PROCESSING_ERROR_PROCESS_FAILED。 + *
当内存分配失败时,返回IMAGE_PROCESSING_ERROR_NO_MEMORY。 + * @since 13 + */ +ImageProcessing_ErrorCode OH_ImageProcessing_Decompose(OH_ImageProcessing* imageProcessor, + OH_PixelmapNative* sourceImage, OH_PixelmapNative* destinationImage, OH_PixelmapNative* destinationGainmap); + +/** + * @brief 生成HDR图片元数据。此函数为HDR图片生成元数据。 + * + * @param imageProcessor 指向图片处理模块实例的指针。该实例应该由IMAGE_PROCESSING_TYPE_METADATA_GENERATION类型创建。 + * @param sourceImage 指向输入图片的指针,指向的OH_PixelmapNative需为DMA内存,具体情况请参考{@link PixelMap的内存类型介绍}。 + * @return 如果图片处理成功,则返回IMAGE_PROCESSING_SUCCESS。 + *
当该实例为空或该实例不是图片处理模块实例时,返回IMAGE_PROCESSING_ERROR_INVALID_INSTANCE。 + *
当图片为空时,返回IMAGE_PROCESSING_ERROR_INVALID_PARAMETER。 + *
当图片的某些属性无效时,返回IMAGE_PROCESSING_ERROR_INVALID_VALUE,例如图片的色彩空间是不支持的。 + *
当该图片处理不支持时,返回IMAGE_PROCESSING_ERROR_UNSUPPORTED_PROCESSING。 + *
当该图片处理中返回错误时,返回IMAGE_PROCESSING_ERROR_PROCESS_FAILED。 + *
当内存分配失败时,返回IMAGE_PROCESSING_ERROR_NO_MEMORY。 + * @since 13 + */ +ImageProcessing_ErrorCode OH_ImageProcessing_GenerateMetadata(OH_ImageProcessing* imageProcessor, + OH_PixelmapNative* sourceImage); + +/** + * @brief 进行图片清晰度/细节增强。此函数根据输入图片和输出图片预设的尺寸,对源图片进行必要的缩放操作生成目标图片,并提供了多种缩放方法以平衡性能和图像质量。 + * + * @param imageProcessor 指向图片处理模块实例的指针。该实例应该由IMAGE_PROCESSING_TYPE_DETAIL_ENHANCER类型创建。 + * @param sourceImage 指向输入图片的指针,指向的OH_PixelmapNative需为DMA内存,具体情况请参考{@link PixelMap的内存类型介绍}。 + * @param destinationImage 指向输出图片的指针,指向的OH_PixelmapNative需为DMA内存,具体情况请参考{@link PixelMap的内存类型介绍}。 + * @return 如果图片处理成功,则返回IMAGE_PROCESSING_SUCCESS。 + *
当该实例为空或该实例不是图片处理模块实例时,返回IMAGE_PROCESSING_ERROR_INVALID_INSTANCE。 + *
当图片为空时,返回IMAGE_PROCESSING_ERROR_INVALID_PARAMETER。 + *
当图片的某些属性无效时,返回IMAGE_PROCESSING_ERROR_INVALID_VALUE,例如图片的色彩空间是不支持的。 + *
当该图片处理不支持时,返回IMAGE_PROCESSING_ERROR_UNSUPPORTED_PROCESSING。 + *
当该图片处理中返回错误时,返回IMAGE_PROCESSING_ERROR_PROCESS_FAILED。 + *
当内存分配失败时,返回IMAGE_PROCESSING_ERROR_NO_MEMORY。 + * @since 13 + */ +ImageProcessing_ErrorCode OH_ImageProcessing_EnhanceDetail(OH_ImageProcessing* imageProcessor, + OH_PixelmapNative* sourceImage, OH_PixelmapNative* destinationImage); +#ifdef __cplusplus +} +#endif + +#endif // VIDEO_PROCESSING_ENGINE_C_API_IMAGE_PROCESSING_H +/** @} */ diff --git a/zh-cn/multimedia/video_processing_engine/image_processing_types.h b/zh-cn/multimedia/video_processing_engine/image_processing_types.h new file mode 100644 index 000000000..7206215dd --- /dev/null +++ b/zh-cn/multimedia/video_processing_engine/image_processing_types.h @@ -0,0 +1,225 @@ +/* + * Copyright (c) 2024 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup ImageProcessing + * @{ + * + * @brief Provide image processing including color space conversion and metadata generation. + * + * @since 13 + */ + +/** + * @file image_processing_types.h + * + * @brief 图片处理的类型定义。 + * + * @library libimage_processing.so + * @syscap SystemCapability.Multimedia.VideoProcessingEngine + * @kit ImageKit + * @since 13 + */ + +#ifndef VIDEO_PROCESSING_ENGINE_C_API_IMAGE_PROCESSING_TYPES_H +#define VIDEO_PROCESSING_ENGINE_C_API_IMAGE_PROCESSING_TYPES_H + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 提供OH_ImageProcessing结构体声明。
定义一个初始化为空的OH_ImageProcessing指针,并调用{@link OH_ImageProcessing_Create}来创建图片处理实例。 + * 调用该接口前,应确保传入的指针为空。用户可根据不同的图片处理类型,分别创建多个图片处理实例。 + * + * @since 13 + */ +typedef struct OH_ImageProcessing OH_ImageProcessing; + +/** + * @brief OH_PixelmapNative是Native层封装的图像解码后无压缩的位图格式结构体,支持像素数据读写、不透明度设置、缩放、平移、旋转、翻转、裁剪等操作, + * 适用于需要在Native层对Pixelmap进行像素级处理与变换的场景。
创建OH_PixelmapNative需要使用{@link OH_PixelmapNative_CreatePixelmap}系列函数, + * 该函数在未指定源像素格式时,会默认按BGRA_8888格式解析源像素数据。使用完毕后,必须调用{@link OH_PixelmapNative_Release}函数释放资源,两者需配对使用,否则会导致内存泄漏。
+ * OH_PixelmapNative结构体的部分相关函数和操作方式如下: + * + * @since 13 + */ +typedef struct OH_PixelmapNative OH_PixelmapNative; + +/** + * @brief 为OH_AVFormat接口定义native层对象。 + * + * @since 13 + */ +typedef struct OH_AVFormat OH_AVFormat; + +/** + * @brief 用于创建色彩空间转换的图片处理实例。 + *
色彩空间转换包括单层HDR图片转换SDR图片,SDR图片之间的转换,以及SDR图片转换单层HDR图片,部分能力由厂商支持。使用 + * {@link OH_ImageProcessing_IsColorSpaceConversionSupported}查询某种转换是否支持在单层图片之间进行。 + *
**参考:**{@link OH_ImageProcessing_Create} + * + * @see OH_ImageProcessing_Create + * @since 13 + */ +extern const int32_t IMAGE_PROCESSING_TYPE_COLOR_SPACE_CONVERSION; + +/** + * @brief 用于创建双层HDR图片转换单层HDR图片的图片处理实例。 + *
包括从双层HDR图片转换为单层HDR图片的能力。部分能力由厂商支持。 + * 使用{@link OH_ImageProcessing_IsCompositionSupported}查询是否支持从双层HDR图片到单层HDR图片的转换。 + *
**参考:**{@link OH_ImageProcessing_Create} + * + * @see OH_ImageProcessing_Create + * @since 13 + */ +extern const int32_t IMAGE_PROCESSING_TYPE_COMPOSITION; + +/** + * @brief 用于创建单层HDR图片转换双层HDR图片的图片处理实例。 + *
包括从单层HDR图片转换为双层HDR图片的能力。部分能力由厂商支持。 + * 使用{@link OH_ImageProcessing_IsDecompositionSupported}查询是否支持从单层HDR图片到双层HDR图片的转换。 + *
**参考:**{@link OH_ImageProcessing_Create} + * + * @see OH_ImageProcessing_Create + * @since 13 + */ +extern const int32_t IMAGE_PROCESSING_TYPE_DECOMPOSITION; + +/** + * @brief 用于创建元数据生成的图片处理实例。 + *
生成单层HDR图片的HDR Vivid元数据。该能力由厂商支持。如果不支持该能力,{@link OH_ImageProcessing_Create}将返回 + * {@link IMAGE_PROCESSING_ERROR_UNSUPPORTED_PROCESSING}。 + *
**参考:**{@link OH_ImageProcessing_Create} + * + * @see OH_ImageProcessing_Create + * @since 13 + */ +extern const int32_t IMAGE_PROCESSING_TYPE_METADATA_GENERATION; + +/** + * @brief 用于创建细节增强的图片处理实例。 + *
按指定图像质量缩放或调整图片大小,或仅增强图像细节以在不更改分辨率的情况下渲染图片。 + *
**参考:**{@link OH_ImageProcessing_Create} + * + * @see OH_ImageProcessing_Create + * @since 13 + */ +extern const int32_t IMAGE_PROCESSING_TYPE_DETAIL_ENHANCER; + +/** + * @brief 用于设定图像细节增强的质量级别。 + *
使用{@link ImageDetailEnhancer_QualityLevel}获取其值。使用{@link OH_ImageProcessing_SetParameter}设置质量级别。使用 + * {@link OH_ImageProcessing_GetParameter}获取当前质量级别。 + * + * @see OH_VideoProcessing_SetParameter, OH_VideoProcessing_GetParameter + * @since 13 + */ +extern const char* IMAGE_DETAIL_ENHANCER_PARAMETER_KEY_QUALITY_LEVEL; + +/** + * @brief 色彩空间信息,用于色彩空间转换能力查询。 + * + * @see OH_ImageProcessing_IsColorSpaceConversionSupported, OH_ImageProcessing_IsCompositionSupported, + * OH_ImageProcessing_IsDecompositionSupported + * @since 13 + */ +typedef struct ImageProcessing_ColorSpaceInfo { + /** + * 定义元数据类型,参考{@link OH_Pixelmap_HdrMetadataKey}。 + */ + int32_t metadataType; + /** + * 定义色彩空间,参考{@link ColorSpaceName}。 + */ + int32_t colorSpace; + /** + * 定义像素格式,参考{@link PIXEL_FORMAT}。 + */ + int32_t pixelFormat; +} ImageProcessing_ColorSpaceInfo; + +/** + * @brief 质量级别,用于细节增强能力。 + *
键参数的值IMAGE_DETAIL_ENHANCER_PARAMETER_KEY_QUALITY_LEVEL。 + * + * @see OH_ImageProcessing_SetParameter, OH_ImageProcessing_GetParameter + * @since 13 + */ +typedef enum ImageDetailEnhancer_QualityLevel { + /** + * 无细节增强。
支持输入分辨率(px):宽:[32, 3000],高:[32, 3000]。
支持输出分辨率(px):宽:[32, 3000],高:[32, 3000]。 + */ + IMAGE_DETAIL_ENHANCER_QUALITY_LEVEL_NONE, + /** + * 细节增强质量较低,但速度较快。默认级别。
支持输入分辨率(px):宽:[32, 3000],高:[32, 3000]。
支持输出分辨率(px):宽:[32, 3000],高:[32, 3000]。 + */ + IMAGE_DETAIL_ENHANCER_QUALITY_LEVEL_LOW, + /** + * 细节增强质量中等,速度介于低级别与高级别之间。
支持输入分辨率(px):宽:[32, 3000],高:[32, 3000]。
支持输出分辨率(px):宽:[32, 3000],高:[32, 3000]。 + */ + IMAGE_DETAIL_ENHANCER_QUALITY_LEVEL_MEDIUM, + /** + * 细节增强质量较高,但速度较慢。
API version 13-22支持输入分辨率(px):宽:[512, 2000],高:[512, 2000]。
API version 13-22支持输出分辨率(px):宽: + * [512, 2000],高:[512, 2000]。
API version 23及以后支持输入分辨率(px):宽:[180, 2000],高:[180, 2000]。
API version + * 23及以后支持输出分辨率(px):宽:[512, 2000],高:[512, 2000]。 + */ + IMAGE_DETAIL_ENHANCER_QUALITY_LEVEL_HIGH, +} ImageDetailEnhancer_QualityLevel; + +/** + * @brief 图片处理接口错误码说明。 + * + * @since 13 + */ +typedef enum ImageProcessing_ErrorCode { + /** @error 成功。 */ + IMAGE_PROCESSING_SUCCESS, + /** @error 输入参数无效。 + *
在以下错误条件下返回该错误码: + *
1. 输入或输出buffer无效,例如图片buffer为空。 + *
2. 参数无效,例如参数为空。
3. 类型无效,例如在创建函数中传入的类型不存在。 + */ + IMAGE_PROCESSING_ERROR_INVALID_PARAMETER = 401, + /** @error 未知错误,例如GPU计算失败或memcpy失败。 */ + IMAGE_PROCESSING_ERROR_UNKNOWN = 29200001, + /** @error 全局环境初始化失败,例如GPU环境初始化失败。 */ + IMAGE_PROCESSING_ERROR_INITIALIZE_FAILED, + /** @error 创建图片处理实例失败,例如实例数量超过上限。 */ + IMAGE_PROCESSING_ERROR_CREATE_FAILED, + /** @error 处理图片buffer失败,例如处理超时。 */ + IMAGE_PROCESSING_ERROR_PROCESS_FAILED, + /** @error 当前处理不支持,可以通过“OH_ImageProcessing_IsXXXSupported”接口查询是否支持该能力。 */ + IMAGE_PROCESSING_ERROR_UNSUPPORTED_PROCESSING, + /** @error 无权限操作,可能由于状态不正确导致。 */ + IMAGE_PROCESSING_ERROR_OPERATION_NOT_PERMITTED, + /** @error 内存不足。 */ + IMAGE_PROCESSING_ERROR_NO_MEMORY, + /** @error 无效的图片处理实例,可能由于实例为空导致。 */ + IMAGE_PROCESSING_ERROR_INVALID_INSTANCE, + /** @error 输入值无效。
在以下错误条件下返回该错误码: + *
1. 输入或输出图片buffer无效,例如图片buffer的宽度(高度)过大或颜色空间不正确。 + *
2. 参数无效,例如参数不包括有效信息,例如细节增强的质量级别不正确。 */ + IMAGE_PROCESSING_ERROR_INVALID_VALUE +} ImageProcessing_ErrorCode; + +#ifdef __cplusplus +} +#endif + +#endif // VIDEO_PROCESSING_ENGINE_C_API_IMAGE_PROCESSING_TYPES_H +/** @} */ diff --git a/zh-cn/multimedia/video_processing_engine/video_processing.h b/zh-cn/multimedia/video_processing_engine/video_processing.h new file mode 100644 index 000000000..318fe1b46 --- /dev/null +++ b/zh-cn/multimedia/video_processing_engine/video_processing.h @@ -0,0 +1,346 @@ +/* + * Copyright (c) 2024 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup VideoProcessing + * @{ + * + * @brief 提供用于视频处理的API函数。 + * + * @since 12 + */ + +/** + * @file video_processing.h + * + * @brief 声明视频处理函数。 + * + * @library libvideo_processing.so + * @syscap SystemCapability.Multimedia.VideoProcessingEngine + * @kit MediaKit + * @since 12 + */ + +#ifndef VIDEO_PROCESSING_ENGINE_C_API_VIDEO_PROCESSING_H +#define VIDEO_PROCESSING_ENGINE_C_API_VIDEO_PROCESSING_H + +#include +#include +#include "video_processing_types.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 初始化视频处理全局环境。 + *
该函数是可选的。 + *
该函数只在主进程启动时被调用一次,用于初始化视频处理全局环境,这样可以减少{@link OH_VideoProcessing_Create}的时间。 + *
调用{@link OH_VideoProcessing_DeinitializeEnvironment}释放视频处理全局环境。 + *
初始化后,必须释放视频处理全局环境,释放方式及时机详见{@link OH_VideoProcessing_DeinitializeEnvironment}。 + * + * @return 如果初始化成功,返回VIDEO_PROCESSING_SUCCESS,否则返回VIDEO_PROCESSING_ERROR_INITIALIZE_FAILED。 + *
如果失败,应用需要检查GPU是否正常工作。 + * @since 12 + */ +VideoProcessing_ErrorCode OH_VideoProcessing_InitializeEnvironment(void); + +/** + * @brief 释放视频处理全局环境。 + *
调用前,必须调用{@link OH_VideoProcessing_InitializeEnvironment}初始化。 + *
通常在主进程即将退出时调用该函数,以释放通过调用{@link OH_VideoProcessing_InitializeEnvironment}函数初始化的全局环境。 + *
如果仍有视频处理的实例运行中,就不能调用该函数。 + * + * @return 如果执行成功,返回VIDEO_PROCESSING_SUCCESS。 + *
如果还有视频处理的实例没有销毁或者没有调用{@link OH_VideoProcessing_InitializeEnvironment}, + * 返回VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED。 + * @since 12 + */ +VideoProcessing_ErrorCode OH_VideoProcessing_DeinitializeEnvironment(void); + +/** + * @brief 查询是否支持视频颜色空间转换。 + * + * @param sourceVideoInfo 输入视频颜色空间信息。 + * @param destinationVideoInfo 输出视频颜色空间信息。 + * @return 如果支持视频颜色空间转换返回true,否则返回false。 + * @since 12 + */ +bool OH_VideoProcessing_IsColorSpaceConversionSupported( + const VideoProcessing_ColorSpaceInfo* sourceVideoInfo, + const VideoProcessing_ColorSpaceInfo* destinationVideoInfo); + +/** + * @brief 查询是否支持视频元数据生成。 + * + * @param sourceVideoInfo 输入视频颜色空间信息。 + * @return 如果支持视频元数据生成返回true,否则返回false。 + * @since 12 + */ +bool OH_VideoProcessing_IsMetadataGenerationSupported( + const VideoProcessing_ColorSpaceInfo* sourceVideoInfo); + +/** + * @brief 创建视频处理实例。 + * + * @param videoProcessor 输出参数。指向视频处理对象的指针的指针。输入前\*videoProcessor必须是空指针。 + * @param type 使用视频处理实例常量来指定处理类型。实例的处理类型不能改变。 + * @return 如果视频处理实例创建成功,返回VIDEO_PROCESSING_SUCCESS。 + *
如果处理类型不支持,返回VIDEO_PROCESSING_ERROR_UNSUPPORTED_PROCESSING,例如,不支持元数据生成。 + *
如果创建视频处理实例失败,返回VIDEO_PROCESSING_ERROR_CREATE_FAILED。 + *
如果实例为空或实例的指针非空,返回VIDEO_PROCESSING_ERROR_INVALID_INSTANCE。 + *
如果处理类型无效,返回VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 + * @since 12 + */ +VideoProcessing_ErrorCode OH_VideoProcessing_Create(OH_VideoProcessing** videoProcessor, int type); + +/** + * @brief 销毁视频处理实例。 + *
销毁之前先停止实例,参阅{@link OH_VideoProcessing_Stop}。 + * + * @param videoProcessor 指向视频处理实例的指针,建议在实例销毁之后将其设置为空指针。 + * @return 如果实例销毁成功,返回VIDEO_PROCESSING_SUCCESS。 + *
如果实例为空或者不是一个视频处理实例,返回VIDEO_PROCESSING_ERROR_INVALID_INSTANCE。 + *
如果实例仍在运行,返回VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED。 + * @since 12 + */ +VideoProcessing_ErrorCode OH_VideoProcessing_Destroy(OH_VideoProcessing* videoProcessor); + +/** + * @brief 注册回调函数。 + *
在开始视频处理之前注册回调函数,视频处理过程中无法注册回调函数。 + * + * @param videoProcessor 指向视频处理实例的指针。 + * @param callback 回调函数指针。 + * @param userData 指向用户特定数据的指针,如this指针。 + * @return 如果回调函数注册成功,返回VIDEO_PROCESSING_SUCCESS。 + *
如果实例为空或者不是一个视频处理实例,返回VIDEO_PROCESSING_ERROR_INVALID_INSTANCE。 + *
如果回调函数指针为空,返回VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 + *
如果实例仍在运行,返回VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED。 + * @since 12 + */ +VideoProcessing_ErrorCode OH_VideoProcessing_RegisterCallback(OH_VideoProcessing* videoProcessor, + const VideoProcessing_Callback* callback, void* userData); + +/** + * @brief 设置视频处理输出surface。 + *
在视频处理启动之前设置输出surface。 + * + * @param videoProcessor 指向视频处理实例的指针。 + * @param window 指向输出surface的指针。 + * @return 如果输出surface设置成功,返回VIDEO_PROCESSING_SUCCESS。 + *
如果实例为空或者不是一个视频处理实例,返回VIDEO_PROCESSING_ERROR_INVALID_INSTANCE。 + *
如果window为空指针,返回VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 + * @since 12 + */ +VideoProcessing_ErrorCode OH_VideoProcessing_SetSurface(OH_VideoProcessing* videoProcessor, + const OHNativeWindow* window); + +/** + * @brief 创建surface。 + *
在视频处理启动之前创建输入surface。调用{@link OH_NativeWindow_DestroyNativeWindow}销毁输入surface。 + * + * @param videoProcessor 指向视频处理实例的指针。 + * @param window 指向输入surface的指针。例如,此输入surface指针可以指向视频解码器输出surface。 + * @return 如果执行成功,返回VIDEO_PROCESSING_SUCCESS。 + *
如果实例为空或者不是一个视频处理实例,返回VIDEO_PROCESSING_ERROR_INVALID_INSTANCE。 + *
如果window为空指针或指向window的指针为空,返回VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 + *
如果创建surface失败,或者输入surface已经创建,或者视频处理实例还在运行,返回VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED。 + * @since 12 + */ +VideoProcessing_ErrorCode OH_VideoProcessing_GetSurface(OH_VideoProcessing* videoProcessor, OHNativeWindow** window); + +/** + * @brief 设置视频处理输出参数。 + * + * @param videoProcessor 指向视频处理实例的指针。 + * @param parameter 指向视频处理参数实例的指针,用于传入需设置的视频处理参数,例如视频宽度、高度、像素格式及编解码格式等。 + * @return 如果参数设置成功,返回VIDEO_PROCESSING_SUCCESS。 + *
如果实例为空或者不是一个视频处理实例,返回VIDEO_PROCESSING_ERROR_INVALID_INSTANCE。 + *
如果参数为空,返回VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 + *
如果参数的某些属性无效,返回VIDEO_PROCESSING_ERROR_INVALID_VALUE,例如,包含不支持的参数值。 + *
如果内存分配失败,返回VIDEO_PROCESSING_ERROR_NO_MEMORY。 + * @since 12 + */ +VideoProcessing_ErrorCode OH_VideoProcessing_SetParameter(OH_VideoProcessing* videoProcessor, + const OH_AVFormat* parameter); + +/** + * @brief 获取视频处理参数。 + * + * @param videoProcessor 指向视频处理实例的指针。 + * @param parameter 指向视频处理参数实例的指针,用于获取当前视频处理的参数,比如视频宽度、高度、像素格式、编解码格式等。 + * @return 如果参数获取成功,返回VIDEO_PROCESSING_SUCCESS。 + *
如果实例为空或者不是一个视频处理实例,返回VIDEO_PROCESSING_ERROR_INVALID_INSTANCE。 + *
如果参数为空,返回VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 + * @since 12 + */ +VideoProcessing_ErrorCode OH_VideoProcessing_GetParameter(OH_VideoProcessing* videoProcessor, OH_AVFormat* parameter); + +/** + * @brief 启动视频处理。 + *
成功启动后,回调函数{@link OH_VideoProcessingCallback_OnState}会报告{@link VideoProcessing_State}. + * VIDEO_PROCESSING_STATE_RUNNING状态。 + * + * @param videoProcessor 指向视频处理实例的指针。 + * @return 如果执行成功,返回VIDEO_PROCESSING_SUCCESS。 + *
如果实例为空或者不是一个视频处理实例,返回VIDEO_PROCESSING_ERROR_INVALID_INSTANCE。 + *
如果没有设置输出surface,或者没有创建输入surface,或者实例已经运行,返回VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED。 + * @since 12 + */ +VideoProcessing_ErrorCode OH_VideoProcessing_Start(OH_VideoProcessing* videoProcessor); + +/** + * @brief 停止视频处理。 + *
成功停止后,回调函数{@link OH_VideoProcessingCallback_OnState}会报告{@link VideoProcessing_State}. + * VIDEO_PROCESSING_STATE_STOPPED状态。 + * + * @param videoProcessor 指向视频处理实例的指针。 + * @return 如果执行成功,返回VIDEO_PROCESSING_SUCCESS。 + *
如果实例为空或者不是一个视频处理实例,返回VIDEO_PROCESSING_ERROR_INVALID_INSTANCE。 + *
如果实例已经停止,返回VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED。 + * @since 12 + */ +VideoProcessing_ErrorCode OH_VideoProcessing_Stop(OH_VideoProcessing* videoProcessor); + +/** + * @brief 渲染处理并输出buffer。 + *
如果设置了回调函数{@link OH_VideoProcessingCallback_OnNewOutputBuffer},当输出buffer准备好之后会通过回调函数把buffer的索引返回给用户。 + * + * @param videoProcessor 指向视频处理实例的指针。 + * @param index 输出buffer的索引。 + * @return 如果执行成功,返回VIDEO_PROCESSING_SUCCESS。 + *
如果实例为空或者不是一个视频处理实例,返回VIDEO_PROCESSING_ERROR_INVALID_INSTANCE。 + *
如果索引值无效,输出VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 + *
如果没有设置回调函数{@link OH_VideoProcessingCallback_OnNewOutputBuffer}或者实例已经停止运行, + * 返回VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED。 + * @since 12 + */ +VideoProcessing_ErrorCode OH_VideoProcessing_RenderOutputBuffer(OH_VideoProcessing* videoProcessor, uint32_t index); + +/** + * @brief 创建视频处理回调函数对象。 + * + * @param callback 输出参数。\*callback是指向回调函数对象的指针。在创建回调函数对象之前\*callback必须为空指针。 + * @return 如果回调函数对象创建成功,返回VIDEO_PROCESSING_SUCCESS。 + *
如果callback为空,返回VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 + *
如果内存不足,返回VIDEO_PROCESSING_ERROR_NO_MEMORY。 + * @since 12 + */ +VideoProcessing_ErrorCode OH_VideoProcessingCallback_Create(VideoProcessing_Callback** callback); + +/** + * @brief 销毁回调对象。回调对象在注册之后就可以销毁。 + * + * @param callback 指向回调对象的指针,建议在回调对象销毁之后将其设置为空指针。 + * @return 如果回调对象销毁成功,返回VIDEO_PROCESSING_SUCCESS。 + *
如果callback为空,返回VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 + * @since 12 + */ +VideoProcessing_ErrorCode OH_VideoProcessingCallback_Destroy(VideoProcessing_Callback* callback); + +/** + * @brief 绑定回调函数{@link OH_VideoProcessingCallback_OnError}到回调对象。 + * 绑定完成之后,需要调用 {@link OH_VideoProcessing_RegisterCallback}, + * 将回调对象注册到视频处理实例,才能使其生效。 + * + * @param callback 指向回调对象的指针。 + * @param onError 回调函数。 + * @return 如果函数绑定成功,返回VIDEO_PROCESSING_SUCCESS。 + *
如果callback为空或者onError为空,返回VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 + * @since 12 + */ +VideoProcessing_ErrorCode OH_VideoProcessingCallback_BindOnError(VideoProcessing_Callback* callback, + OH_VideoProcessingCallback_OnError onError); + +/** + * @brief 绑定回调函数{@link OH_VideoProcessingCallback_OnState}到回调对象。 + * 绑定完成之后,需要调用 {@link OH_VideoProcessing_RegisterCallback}, + * 将回调对象注册到视频处理实例,才能使其生效。 + * + * @param callback 指向回调对象的指针。 + * @param onState 回调函数。 + * @return 如果函数绑定成功,返回VIDEO_PROCESSING_SUCCESS。 + *
如果callback为空或者onState为空,返回VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 + * @since 12 + */ +VideoProcessing_ErrorCode OH_VideoProcessingCallback_BindOnState(VideoProcessing_Callback* callback, + OH_VideoProcessingCallback_OnState onState); + +/** + * @brief 绑定回调函数{@link OH_VideoProcessingCallback_OnNewOutputBuffer}到回调对象。绑定完成之后,需要调用 + * {@link OH_VideoProcessing_RegisterCallback},将回调对象注册到视频处理实例,才能使其生效。 + * + * @param callback 指向回调对象的指针。 + * @param onNewOutputBuffer 回调函数。 + * @return 如果函数绑定成功,返回VIDEO_PROCESSING_SUCCESS。 + *
如果callback为空,返回VIDEO_PROCESSING_ERROR_INVALID_PARAMETER。 + * @since 12 + */ +VideoProcessing_ErrorCode OH_VideoProcessingCallback_BindOnNewOutputBuffer(VideoProcessing_Callback* callback, + OH_VideoProcessingCallback_OnNewOutputBuffer onNewOutputBuffer); + +/** + * @brief Query if the autoeffect is supported. + * + * @param type [in] The autoeffect type to query. + * @return
  • true if the autoeffect is supported.
  • + *
  • false if the autoeffect is not supported.
+ * @since 26.1.0 + */ +bool OH_VideoProcessing_IsAutoEffectSupported(uint32_t type); + +/** + * @brief Specifies whether the type effect is required in the XComponent named name that will be created. + * + * Records the mapping between type, enable, and name in the internal map. + * This should be called before {@link OH_VideoProcessing_SetAutoEffectParam}. + * @param type [in] Specify AutoEffect to use. + * @param enable [in] Enable or disable the type effect in the XComponent named name to be created later. + * @param name [in] Specifies the name of an XComponent. If the current application has multiple XComponents with + * the same name, this parameter takes effect only on the first active XComponent. + * @return
  • {@link VIDEO_PROCESSING_SUCCESS} if the operation is successful.
  • + *
  • {@link VIDEO_PROCESSING_ERROR_INVALID_VALUE} if type is not {@link VIDEO_PROCESSING_TYPE_AUTOEFFECT_AISR} + * or name is null.
  • + *
  • {@link VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED} if {@link OH_VideoProcessing_IsAutoEffectSupported} + * returns false for the type, or the same name has already been registered by calling this function.
+ * @since 26.1.0 + */ +VideoProcessing_ErrorCode OH_VideoProcessing_UseAutoEffect(uint32_t type, bool enable, const char *name); + +/** + * @brief Sets parameters for the automatic effect associated with the XComponent. + * Currently, the AutoEffect only takes effect on the last invoked XComponent. + * @param type [in] Specify AutoEffect to use. + * @param name [in] Specifies the name of an XComponent. If the current application has multiple XComponents + * with the same name, this parameter takes effect only on the first active XComponent. + * @param param [in] The parameter according to the type see video_processing_type.h. + * @return
  • {@link VIDEO_PROCESSING_SUCCESS} if the operation is successful.
  • + *
  • {@link VIDEO_PROCESSING_ERROR_INVALID_VALUE} if the name is nullptr or the param value is invalid.
  • + *
  • {@link VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED} if {@link OH_VideoProcessing_IsAutoEffectSupported} + * returns false for the type, or name does not match any registered name, or the VPE instance has not been + * created or {@link OH_VideoProcessing_UseAutoEffect} has not been called for the name.
  • + *
  • {@link VIDEO_PROCESSING_ERROR_UNKNOWN} if an internal algorithm error occurs.
+ * @since 26.1.0 + */ +VideoProcessing_ErrorCode OH_VideoProcessing_SetAutoEffectParam(uint32_t type, const char *name, + const OH_AVFormat *param); + +#ifdef __cplusplus +} +#endif + +#endif // VIDEO_PROCESSING_ENGINE_C_API_VIDEO_PROCESSING_H +/** @} */ diff --git a/zh-cn/multimedia/video_processing_engine/video_processing_types.h b/zh-cn/multimedia/video_processing_engine/video_processing_types.h new file mode 100644 index 000000000..4fa29e872 --- /dev/null +++ b/zh-cn/multimedia/video_processing_engine/video_processing_types.h @@ -0,0 +1,311 @@ +/* + * Copyright (c) 2024 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup VideoProcessing + * @{ + * + * @brief 提供用于视频处理的API函数。 + * + * @since 12 + */ + +/** + * @file video_processing_types.h + * + * @brief 视频处理类型定义。 + * + * @library libvideo_processing.so + * @syscap SystemCapability.Multimedia.VideoProcessingEngine + * @kit MediaKit + * @since 12 + */ + +#ifndef VIDEO_PROCESSING_ENGINE_C_API_VIDEO_PROCESSING_TYPES_H +#define VIDEO_PROCESSING_ENGINE_C_API_VIDEO_PROCESSING_TYPES_H + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 定义视频处理对象。 + *
定义一个OH_VideoProcessing空指针,调用{@link OH_VideoProcessing_Create}创建视频处理实例,该指针在创建实例之前必须为空。 + * 用户可以对不同的处理类型创建不同的视频处理实例。 + * + * @since 12 + */ +typedef struct OH_VideoProcessing OH_VideoProcessing; + +/** + * @brief 定义NativeWindow对象。 + * + * @since 12 + */ +typedef struct NativeWindow OHNativeWindow; + +/** + * @brief 定义OH_AVFormat对象。 + * + * @since 12 + */ +typedef struct OH_AVFormat OH_AVFormat; + +/** + * @brief 表示创建颜色空间转换视频处理实例。 + *
调用{@link OH_VideoProcessing_Create}创建颜色空间转换视频处理实例,如果不支持该能力返回{@link VideoProcessing_ErrorCode}. + * VIDEO_PROCESSING_ERROR_UNSUPPORTED_PROCESSING。
可以调用{@link OH_VideoProcessing_IsColorSpaceConversionSupported} + * 来检查是否支持这种处理。 + * + * @see OH_VideoProcessing_Create + * @since 12 + */ +extern const int32_t VIDEO_PROCESSING_TYPE_COLOR_SPACE_CONVERSION; + +/** + * @brief 表示创建元数据生成视频处理实例。 + *
调用{@link OH_VideoProcessing_Create}创建元数据生成视频处理实例,如果不支持该能力返回{@link VideoProcessing_ErrorCode}. + * VIDEO_PROCESSING_ERROR_UNSUPPORTED_PROCESSING。
可以调用{@link OH_VideoProcessing_IsMetadataGenerationSupported} + * 来检查是否支持这种处理。 + * + * @see OH_VideoProcessing_Create + * @since 12 + */ +extern const int32_t VIDEO_PROCESSING_TYPE_METADATA_GENERATION; + +/** + * @brief 表示创建细节增强视频处理实例。 + *
调用{@link OH_VideoProcessing_Create}创建细节增强视频处理实例,如果不支持该能力返回{@link VideoProcessing_ErrorCode}. + * VIDEO_PROCESSING_ERROR_UNSUPPORTED_PROCESSING。 + * + * @see OH_ImageProcessing_Create + * @since 12 + */ +extern const int32_t VIDEO_PROCESSING_TYPE_DETAIL_ENHANCER; + +/** + * @brief 指定视频细节增强的质量等级,参考{@link VideoDetailEnhancer_QualityLevel}查看具体取值。 + *
调用{@link OH_VideoProcessing_SetParameter}设置质量等级。 + *
调用{@link OH_VideoProcessing_GetParameter}获取当前质量等级。 + * + * @see OH_VideoProcessing_SetParameter, OH_VideoProcessing_GetParameter + * @since 12 + */ +extern const char* VIDEO_DETAIL_ENHANCER_PARAMETER_KEY_QUALITY_LEVEL; + +/** + * @brief 指定视频元数据生成的风格模式。具体取值请参考{@link VideoMetadataGeneratorStyleControl}。 + *
调用{@link OH_AVFormat_SetIntValue}设置视频元数据生成的风格模式到AVFormat参数。 + *
调用{@link OH_VideoProcessing_SetParameter}设置当前视频元数据生成的风格模式。 + *
调用{@link OH_VideoProcessing_GetParameter}获取当前视频元数据生成的风格模式。 + * + * @since 22 + */ +extern const char* VIDEO_METADATA_GENERATOR_STYLE_CONTROL; + +/** + * @brief 视频颜色空间信息数据结构。 + * + * @see OH_VideoProcessing_IsColorSpaceConversionSupported + * @since 12 + */ +typedef struct VideoProcessing_ColorSpaceInfo { + /** + * 视频元数据类型,参考{@link OH_NativeBuffer_MetadataType}。 + */ + int32_t metadataType; + /** + * 视频颜色空间类型,参考{@link OH_NativeBuffer_ColorSpace}。 + */ + int32_t colorSpace; + /** + * 视频像素格式,参考{@link OH_NativeBuffer_Format}。 + */ + int32_t pixelFormat; +} VideoProcessing_ColorSpaceInfo; + +/** + * @brief 用于细节增强的质量等级。参数{@link VIDEO_DETAIL_ENHANCER_PARAMETER_KEY_QUALITY_LEVEL}的具体取值,设置方法详见开发指南。 + * + * @see OH_VideoProcessing_SetParameter, OH_VideoProcessing_GetParameter + * @since 12 + */ +typedef enum VideoDetailEnhancer_QualityLevel { + /** 无细节增强。 */ + VIDEO_DETAIL_ENHANCER_QUALITY_LEVEL_NONE, + /** 低质量等级细节增强,速度较快,默认设置。 */ + VIDEO_DETAIL_ENHANCER_QUALITY_LEVEL_LOW, + /** 中等质量等级细节增强,速度适中。 */ + VIDEO_DETAIL_ENHANCER_QUALITY_LEVEL_MEDIUM, + /** 高质量等级细节增强,速度相对较慢。 */ + VIDEO_DETAIL_ENHANCER_QUALITY_LEVEL_HIGH, +} VideoDetailEnhancer_QualityLevel; + +/** + * @brief 视频元数据生成的风格模式。参数的具体取值请参考{@link VIDEO_METADATA_GENERATOR_STYLE_CONTROL}。 + * + * @see OH_AVFormat_SetIntValue, OH_VideoProcessing_SetParameter, OH_VideoProcessing_GetParameter + * @since 22 + */ +typedef enum VideoMetadataGeneratorStyleControl { + /** 对比度优先模式。 */ + VIDEO_METADATA_GENERATOR_CONTRAST_MODE = 0, + /** 亮度优先模式。 */ + VIDEO_METADATA_GENERATOR_BRIGHT_MODE = 1 +} VideoMetadataGeneratorStyleControl; + +/** + * @brief 视频处理错误码。 + * + * @since 12 + */ +typedef enum VideoProcessing_ErrorCode { + /** @error 处理成功。 */ + VIDEO_PROCESSING_SUCCESS, + /** @error 输入参数无效。以下情况都会返回该错误码: + *
1. 无效的输入或输出视频buffer,视频buffer为空。 + *
2. 无效的参数,参数为空。 + *
3. 无效的处理类型。 + */ + VIDEO_PROCESSING_ERROR_INVALID_PARAMETER = 401, + /** @error 未知错误,比如GPU计算失败或memcpy失败。 */ + VIDEO_PROCESSING_ERROR_UNKNOWN = 29210001, + /** @error 视频处理全局环境初始化失败,比如初始化GPU环境失败。 + * 请检查设备是否支持GPU加速,或尝试重启应用后重试。 + */ + VIDEO_PROCESSING_ERROR_INITIALIZE_FAILED, + /** @error 创建视频处理实例失败,比如实例总数超出上限。可调用{@link OH_VideoProcessing_Destroy}释放不再使用的实例后重试。 */ + VIDEO_PROCESSING_ERROR_CREATE_FAILED, + /** @error 处理过程失败,比如处理时间超时。 */ + VIDEO_PROCESSING_ERROR_PROCESS_FAILED, + /** @error 不支持的处理类型,比如试图创建不支持的视频处理实例。 + * 目前可对两种视频处理功能检查支持情况:{@link OH_VideoProcessing_IsColorSpaceConversionSupported}, + * {@link OH_VideoProcessing_IsMetadataGenerationSupported}。 + */ + VIDEO_PROCESSING_ERROR_UNSUPPORTED_PROCESSING, + /** @error 不允许的操作,比如不满足调用接口所需的运行状态下调用该接口。 */ + VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED, + /** @error 内存不足。请释放不再使用的资源后重试,或减少视频处理的分辨率。 */ + VIDEO_PROCESSING_ERROR_NO_MEMORY, + /** @error 视频处理实例无效,比如视频处理实例为空实例。 */ + VIDEO_PROCESSING_ERROR_INVALID_INSTANCE, + /** @error 输入值无效,以下情况都会造成这种错误: + *
1. 视频buffer宽高太大或者颜色空间错误。 + *
2. 参数包含无效的值,比如细节增强的质量等级错误。 + */ + VIDEO_PROCESSING_ERROR_INVALID_VALUE +} VideoProcessing_ErrorCode; + +/** + * @brief 视频处理状态。视频处理状态通过回调函数{@link OH_VideoProcessingCallback_OnState}进行报告。 + * + * @since 12 + */ +typedef enum VideoProcessing_State { + /** 视频处理进行中。 */ + VIDEO_PROCESSING_STATE_RUNNING, + /** 视频处理已停止。 */ + VIDEO_PROCESSING_STATE_STOPPED +} VideoProcessing_State; + +/** + * @brief 视频处理回调对象类型。 + *
定义一个VideoProcessing_Callback空指针,调用{@link OH_VideoProcessingCallback_Create}来创建一个回调对象。 + * 创建之前该指针必须为空。通过调用{@link OH_VideoProcessing_RegisterCallback}来向视频处理实例注册回调对象。 + * + * @since 12 + */ +typedef struct VideoProcessing_Callback VideoProcessing_Callback; + +/** + * @brief 视频处理过程中报告错误的回调函数指针。 + *
错误码{@link VideoProcessing_ErrorCode}: + *
VIDEO_PROCESSING_ERROR_UNSUPPORTED_PROCESSING,不支持的处理,比如不支持输入输出的颜色空间类型转换。 + *
VIDEO_PROCESSING_ERROR_INVALID_VALUE,无效的视频属性,比如视频的颜色空间无效。 + *
VIDEO_PROCESSING_ERROR_NO_MEMORY,内存不足。 + *
VIDEO_PROCESSING_ERROR_PROCESS_FAILED,处理过程中出错。 + * + * @param videoProcessor 视频处理实例。 + * @param error 报告给用户的错误码。 + * @param userData 用户的自定义数据。 + * @since 12 + */ +typedef void (*OH_VideoProcessingCallback_OnError)(OH_VideoProcessing* videoProcessor, + VideoProcessing_ErrorCode error, void* userData); + +/** + * @brief 报告视频处理状态的回调函数指针。 + *
{@link OH_VideoProcessing_Start}成功调用之后状态会变为{@link VideoProcessing_State}.VIDEO_PROCESSING_STATE_RUNNING. + * 调用{@link OH_VideoProcessing_Stop},所有的缓存buffer处理完成后,状态会变为 + * {@link VideoProcessing_State}.VIDEO_PROCESSING_STATE_STOPPED。 + * + * @param videoProcessor 视频处理实例。 + * @param state 视频处理状态。 + * @param userData 用户的自定义数据。 + * @since 12 + */ +typedef void (*OH_VideoProcessingCallback_OnState)(OH_VideoProcessing* videoProcessor, VideoProcessing_State state, + void* userData); + +/** + * @brief 报告输出buffer已填充好数据的回调函数指针。 + *
每个新输出buffer填充好数据之后该buffer的索引就会报告给用户。 + * 调用{@link OH_VideoProcessing_RenderOutputBuffer}根据索引来处理渲染并输出该buffer。如果未注册该函数, + * 则输出buffer填充好数据后不会报告用户,而是直接进行处理渲染并输出。 + * + * @param videoProcessor 视频处理实例。 + * @param index 新输出buffer的索引。 + * @param userData 用户自定义的数据。 + * @since 12 + */ +typedef void (*OH_VideoProcessingCallback_OnNewOutputBuffer)(OH_VideoProcessing* videoProcessor, uint32_t index, + void* userData); + +/** + * @brief Used to define video aisr autoeffect in XComponent. + * + * Use {@link OH_VideoProcessing_IsAutoEffectSupported} to query if aisr autoeffect is supported. + * @since 26.1.0 + */ +extern const int32_t VIDEO_PROCESSING_TYPE_AUTOEFFECT_AISR; + +/** + * @brief Sets the key value for enabling or disabling AutoEffect. + * + * Use {@link OH_AVFormat_SetIntValue} to set the enable value (0 is false, 1 is true) to the AVFormat parameter. + * Use {@link OH_VideoProcessing_SetAutoEffectParam} to set the parameters to the video processing instance. + * @since 26.1.0 + */ +extern const char *VIDEO_AUTOEFFECT_ENABLE; + +/** + * @brief Sets the AISR strength. + * + * Use {@link OH_AVFormat_SetFloatValue} to set the strength value to the AVFormat parameter. + * When the value is in the range [0.0, 1.0], the larger the value, the better the image quality, + * If this parameter is set to a value less than 0, the image quality enhancement is adaptive. + * Use {@link OH_VideoProcessing_SetAutoEffectParam} to set the parameters of the video processing instance. + * @since 26.1.0 + */ +extern const char *VIDEO_AUTOEFFECT_AISR_STRENGTH; + +#ifdef __cplusplus +} +#endif + +#endif // VIDEO_PROCESSING_ENGINE_C_API_VIDEO_PROCESSING_TYPES_H +/** @} */