1 /* 2 * Copyright (c) 2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup VideoProcessing 18 * @{ 19 * 20 * @brief Provide video processing including color space conversion and metadata generation. 21 * 22 * @since 12 23 */ 24 25 /** 26 * @file video_processing_types.h 27 * 28 * @brief Type definitions for video processing. 29 * 30 * @library libvideo_processing.so 31 * @syscap SystemCapability.Multimedia.VideoProcessingEngine 32 * @kit MediaKit 33 * @since 12 34 */ 35 36 #ifndef VIDEO_PROCESSING_ENGINE_C_API_VIDEO_PROCESSING_TYPES_H 37 #define VIDEO_PROCESSING_ENGINE_C_API_VIDEO_PROCESSING_TYPES_H 38 39 #include <stdint.h> 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /** 46 * @brief Define the video processing object. 47 * 48 * Define a null pointer of OH_VideoProcessing and call {@link OH_VideoProcessing_Create} to create a video processing 49 * instance. The pointer should be null before creating instance. 50 * User can create multiple video processing instances for different processing types. 51 * 52 * @since 12 53 */ 54 typedef struct OH_VideoProcessing OH_VideoProcessing; 55 56 /** 57 * @brief Forward declaration of NativeWindow. 58 * 59 * @since 12 60 */ 61 typedef struct NativeWindow OHNativeWindow; 62 63 /** 64 * @brief Forward declaration of OH_AVFormat. 65 * 66 * @since 12 67 */ 68 typedef struct OH_AVFormat OH_AVFormat; 69 70 /** 71 * @brief Used to create a video processing instance for color space conversion. 72 * 73 * Some capabilities are supported by vendor. Use {@link OH_VideoProcessing_IsColorSpaceConversionSupported} to query if 74 * the conversion is supported. 75 * 76 * @see OH_VideoProcessing_Create 77 * @since 12 78 */ 79 extern const int32_t VIDEO_PROCESSING_TYPE_COLOR_SPACE_CONVERSION; 80 81 /** 82 * @brief Used to create a video processing instance for metadata generation. 83 * 84 * Generate HDR vivid metadata for video. The capability is supported by vendor. If the capability is not supported, 85 * {@link OH_VideoProcessing_Create} returns {@link VIDEO_PROCESSING_ERROR_UNSUPPORTED_PROCESSING}. 86 * 87 * @see OH_VideoProcessing_Create 88 * @since 12 89 */ 90 extern const int32_t VIDEO_PROCESSING_TYPE_METADATA_GENERATION; 91 92 /** 93 * @brief Used to create an video processing instance of detail enhancement. 94 * 95 * Scale or resize video with the specified quality or just enhance details for rendering without changing its 96 * resolution. 97 * 98 * @see OH_ImageProcessing_Create 99 * @since 12 100 */ 101 extern const int32_t VIDEO_PROCESSING_TYPE_DETAIL_ENHANCER; 102 103 /** 104 * @brief The key is used to specify the quality level for video detail enhancement. 105 * 106 * See {@link VideoDetailEnhancer_QualityLevel} for its values. 107 * Use {@link OH_VideoProcessing_SetParameter} to set the quality level. 108 * Use {@link OH_VideoProcessing_GetParameter} to get the current quality level. 109 * 110 * @see OH_VideoProcessing_SetParameter 111 * @see OH_VideoProcessing_GetParameter 112 * @since 12 113 */ 114 extern const char* VIDEO_DETAIL_ENHANCER_PARAMETER_KEY_QUALITY_LEVEL; 115 116 /** 117 * @brief Video color space information structure of querying if video color space conversion is supported. 118 * 119 * @see OH_VideoProcessing_IsColorSpaceConversionSupported 120 * @since 12 121 */ 122 typedef struct VideoProcessing_ColorSpaceInfo { 123 /** The metadata type of the video, see {@link enum OH_NativeBuffer_MetadataType} */ 124 int32_t metadataType; 125 /** The color space type of the video, see {@link enum OH_NativeBuffer_ColorSpace} */ 126 int32_t colorSpace; 127 /** The pixel format of the video, see {@link enum OH_NativeBuffer_Format} */ 128 int32_t pixelFormat; 129 } VideoProcessing_ColorSpaceInfo; 130 131 /** 132 * @brief The quality level is used for detail enhancement. 133 * 134 * It is the value of the key parameter {@link VIDEO_DETAIL_ENHANCER_PARAMETER_KEY_QUALITY_LEVEL}. 135 * 136 * @see OH_VideoProcessing_SetParameter 137 * @see OH_VideoProcessing_GetParameter 138 * @since 12 139 */ 140 typedef enum VideoDetailEnhancer_QualityLevel { 141 /** No detail enhancement */ 142 VIDEO_DETAIL_ENHANCER_QUALITY_LEVEL_NONE, 143 /** A low level of detail enhancement quality but with a fast speed. It's the default level */ 144 VIDEO_DETAIL_ENHANCER_QUALITY_LEVEL_LOW, 145 /** A medium level of detail enhancement quality. Its speed is between the low setting and high setting */ 146 VIDEO_DETAIL_ENHANCER_QUALITY_LEVEL_MEDIUM, 147 /** A high level of detail enhancement quality but with a relatively slow speed */ 148 VIDEO_DETAIL_ENHANCER_QUALITY_LEVEL_HIGH, 149 } VideoDetailEnhancer_QualityLevel; 150 151 /** 152 * @brief Video processing error code. 153 * 154 * @since 12 155 */ 156 typedef enum VideoProcessing_ErrorCode { 157 /** @error Operation is successful. */ 158 VIDEO_PROCESSING_SUCCESS, 159 /** @error Input parameter is invalid. This error is returned for all of the following error conditions: 160 * 1 - Invalid input or output video buffer - The video buffer is null. 161 * 2 - Invalid parameter - The parameter is null. 162 * 3 - Invalid type - The type passed in the create function does not exist. 163 */ 164 VIDEO_PROCESSING_ERROR_INVALID_PARAMETER = 401, 165 /** @error Some unknown error occurred, such as GPU calculation failure or memcpy failure. */ 166 VIDEO_PROCESSING_ERROR_UNKNOWN = 29210001, 167 /** @error The global environment initialization for video processing failed, such as failure to initialize 168 * the GPU environment. 169 */ 170 VIDEO_PROCESSING_ERROR_INITIALIZE_FAILED, 171 /** @error Failed to create video processing instance. For example, 172 * the number of instances exceeds the upper limit. 173 */ 174 VIDEO_PROCESSING_ERROR_CREATE_FAILED, 175 /** @error Failed to process video buffer. For example, the processing times out. */ 176 VIDEO_PROCESSING_ERROR_PROCESS_FAILED, 177 /** @error The processing is not supported. You may call OH_VideoProcessing_IsXXXSupported 178 * to check whether the capability is supported. 179 */ 180 VIDEO_PROCESSING_ERROR_UNSUPPORTED_PROCESSING, 181 /** @error The operation is not permitted. This may be caused by incorrect status. */ 182 VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED, 183 /** @error Out of memory. */ 184 VIDEO_PROCESSING_ERROR_NO_MEMORY, 185 /** @error The video processing instance is invalid. This may be caused by null instance. */ 186 VIDEO_PROCESSING_ERROR_INVALID_INSTANCE, 187 /** @error Input value is invalid. This error is returned for all of the following error conditions: 188 * 1 - Invalid input or output video buffer - The video buffer width(height) 189 * is too large or colorspace is incorrect. 190 * 2 - Invalid parameter - The parameter does not contain valid information, 191 * such as detail enhancer level is incorrect. 192 */ 193 VIDEO_PROCESSING_ERROR_INVALID_VALUE 194 } VideoProcessing_ErrorCode; 195 196 /** 197 * @brief Video processing states. 198 * 199 * The state is reported to user by callback function {@link OH_VideoProcessing_OnState}. 200 * 201 * @since 12 202 */ 203 typedef enum VideoProcessing_State { 204 /** Video processing is running */ 205 VIDEO_PROCESSING_STATE_RUNNING, 206 /** Video processing is stopped */ 207 VIDEO_PROCESSING_STATE_STOPPED 208 } VideoProcessing_State; 209 210 /** 211 * @brief Video processing asynchronous callback object type. 212 * 213 * Define a null pointer of VideoProcessing_Callback and call {@link OH_VideoProcessingCallback_Create} to create a 214 * callback object. The pointer should be null before creating the callback object. 215 * Register the callback to a video processing instance by calling {@link OH_VideoProcessing_RegisterCallback}. 216 * 217 * @since 12 218 */ 219 typedef struct VideoProcessing_Callback VideoProcessing_Callback; 220 221 /** 222 * @brief The callback function pointer definition for reporting error during video processing. 223 * 224 * Errors: \n 225 * {@link VIDEO_PROCESSING_ERROR_UNSUPPORTED_PROCESSING}, the processing is not supported. For example, the 226 * color space conversion according to the source and destination videos' properties is not supported. \n 227 * {@link VIDEO_PROCESSING_ERROR_INVALID_VALUE}, some property of the video is invalid. For example, the color space of 228 * the video is invalid. \n 229 * {@link VIDEO_PROCESSING_ERROR_NO_MEMORY}, out of memory. \n 230 * {@link VIDEO_PROCESSING_ERROR_PROCESS_FAILED}, some processing error occurs. \n 231 * For more errors, see {@link VideoProcessing_ErrorCode}. 232 * 233 * @param videoProcessor The video processing instance. 234 * @param error Error code reporting to user. 235 * @param userData User's custom data. 236 * @since 12 237 */ 238 typedef void (*OH_VideoProcessingCallback_OnError)(OH_VideoProcessing* videoProcessor, 239 VideoProcessing_ErrorCode error, void* userData); 240 241 /** 242 * @brief The callback function pointer definition for reporting video processing state. 243 * 244 * The state will be {@link VIDEO_PROCESSING_STATE_RUNNING} after {@link OH_VideoProcessing_Start} is called 245 * successfully. 246 * The state will be {@link VIDEO_PROCESSING_STATE_STOPPED} after all the buffers cached before 247 * {@link OH_VideoProcessing_Stop} is called are processed. 248 * 249 * @param videoProcessor The video processing instance. 250 * @param state see {@link VideoProcessing_State}. 251 * @param userData User's custom data. 252 * @since 12 253 */ 254 typedef void (*OH_VideoProcessingCallback_OnState)(OH_VideoProcessing* videoProcessor, VideoProcessing_State state, 255 void* userData); 256 257 /** 258 * @brief The callback function pointer definition for reporting a new output buffer is filled with processed data. 259 * 260 * Every new output buffer's index will report to user once the buffer is filled with processed data. Then call 261 * {@link OH_VideoProcessing_RenderOutputBuffer} with the buffer's index to send the output buffer out. 262 * If this function is not registered, the output buffer is sent out as soon as the buffer is filled with processed 263 * data without reporting. 264 * 265 * @param videoProcessor The video processing instance. 266 * @param index The index of the new output buffer. 267 * @param userData The user's custom data. 268 * @since 12 269 */ 270 typedef void (*OH_VideoProcessingCallback_OnNewOutputBuffer)(OH_VideoProcessing* videoProcessor, uint32_t index, 271 void* userData); 272 273 #ifdef __cplusplus 274 } 275 #endif 276 277 #endif // VIDEO_PROCESSING_ENGINE_C_API_VIDEO_PROCESSING_TYPES_H 278 /** @} */ 279