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 APIs for video quality processing. 21 * 22 * @since 12 23 */ 24 25 /** 26 * @file video_processing.h 27 * 28 * @brief Declare video processing functions. 29 * 30 * Provides SDR content processing for videos, including color space conversion, metadata generation 31 * and video scaling. 32 * 33 * @library libvideo_processing.so 34 * @syscap SystemCapability.Multimedia.VideoProcessingEngine 35 * @kit MediaKit 36 * @since 12 37 */ 38 39 #ifndef VIDEO_PROCESSING_ENGINE_C_API_VIDEO_PROCESSING_H 40 #define VIDEO_PROCESSING_ENGINE_C_API_VIDEO_PROCESSING_H 41 42 #include <stdint.h> 43 #include <stdbool.h> 44 #include "video_processing_types.h" 45 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 /** 51 * @brief Initialize global environment for video processing. 52 * 53 * This function is optional. \n 54 * Typically, this function is called once when the host process is started to initialize the global environment for 55 * video processing, which can reduce the time of {@link OH_VideoProcessing_Create}. \n 56 * To deinitialize global environment, call {@link OH_VideoProcessing_DeinitializeEnvironment}. 57 * 58 * @return {@link VIDEO_PROCESSING_SUCCESS} if initialization is successful. \n 59 * {@link VIDEO_PROCESSING_ERROR_INITIALIZE_FAILED} if initialization is failed. \n 60 * You can check if the device GPU is working properly. 61 * @since 12 62 */ 63 VideoProcessing_ErrorCode OH_VideoProcessing_InitializeEnvironment(void); 64 65 /** 66 * @brief Deinitialize global environment for video processing. 67 * 68 * This function is required if {@link OH_VideoProcessing_InitializeEnvironment} is called. Typically, this 69 * function is called when the host process is about to exit to deinitialize the global environment, which is 70 * initialized by calling {@link OH_VideoProcessing_InitializeEnvironment}. \n 71 * If there is some video processing instance existing, this function should not be called. \n 72 * If the {@link OH_VideoProcessing_InitializeEnvironment} is not called, this function should not be called. 73 * 74 * @return {@link VIDEO_PROCESSING_SUCCESS} if deinitialization is successful. \n 75 * {@link VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED} if some video processing instance is not destroyed or 76 * {@link OH_VideoProcessing_InitializeEnvironment} is not called. \n 77 * @since 12 78 */ 79 VideoProcessing_ErrorCode OH_VideoProcessing_DeinitializeEnvironment(void); 80 81 /** 82 * @brief Query if the video color space conversion is supported. 83 * 84 * @param sourceVideoInfo Source video color space information. 85 * @param destinationVideoInfo Destination video color space information. 86 * @return <b>true</b> if the video color space conversion is supported. \n 87 * <b>false</b> if the video color space conversion is not supported. 88 * @since 12 89 */ 90 bool OH_VideoProcessing_IsColorSpaceConversionSupported( 91 const VideoProcessing_ColorSpaceInfo* sourceVideoInfo, 92 const VideoProcessing_ColorSpaceInfo* destinationVideoInfo); 93 94 /** 95 * @brief Query if the video metadata generation is supported. 96 * 97 * @param sourceVideoInfo Source video color space information. 98 * @return <b>true</b> if the video metadata generation is supported. \n 99 * <b>false</b> if the video metadata generation is not supported. 100 * @since 12 101 */ 102 bool OH_VideoProcessing_IsMetadataGenerationSupported( 103 const VideoProcessing_ColorSpaceInfo* sourceVideoInfo); 104 105 /** 106 * @brief Create a video processing instance. 107 * 108 * @param videoProcessor Output parameter. The *videoProcessor points to a new video processing object. 109 * The *videoProcessor must be null before passed in. 110 * @param type Use VIDEO_PROCESSING_TYPE_XXX to specify the processing type. The processing type of the instance can not 111 * be changed. 112 * @return {@link VIDEO_PROCESSING_SUCCESS} if creating a video processing instance successfully. \n 113 * {@link VIDEO_PROCESSING_ERROR_UNSUPPORTED_PROCESSING} if the type is not supported. For example, if metadata 114 * generation is not supported by vendor, it returns unsupported processing. \n 115 * {@link VIDEO_PROCESSING_ERROR_CREATE_FAILED} if failed to create a video processing instance. \n 116 * {@link VIDEO_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or <b>*</b>instance is <b>not</b> null. \n 117 * {@link VIDEO_PROCESSING_ERROR_INVALID_PARAMETER} if type is invalid. 118 * @since 12 119 */ 120 VideoProcessing_ErrorCode OH_VideoProcessing_Create(OH_VideoProcessing** videoProcessor, int type); 121 122 /** 123 * @brief Destroy the video processing instance. 124 * 125 * Stop the instance before destroying it. see {@link OH_VideoProcessing_Stop}. \n 126 * 127 * @param videoProcessor The video processing instance pointer to be destroyed. It is recommended setting the 128 * instance pointer to null after the instance is destroyed. 129 * @return {@link VIDEO_PROCESSING_SUCCESS} if the instance is destroyed successfully . \n 130 * {@link VIDEO_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not a video processing instance. \n 131 * {@link VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED} if the instance is still running. 132 * @since 12 133 */ 134 VideoProcessing_ErrorCode OH_VideoProcessing_Destroy(OH_VideoProcessing* videoProcessor); 135 136 /** 137 * @brief Register callback object. 138 * 139 * Register the callback object before starting video processing. 140 * 141 * @param videoProcessor A video processing instance pointer. 142 * @param callback Callback pointer to be registered. 143 * @param userData User's custom data pointer. 144 * @return {@link VIDEO_PROCESSING_SUCCESS} if callback is registered successfully. \n 145 * {@link VIDEO_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not a video processing instance. \n 146 * {@link VIDEO_PROCESSING_ERROR_INVALID_PARAMETER} if callback is null. \n 147 * {@link VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED} if video processing instance is running. 148 * @since 12 149 */ 150 VideoProcessing_ErrorCode OH_VideoProcessing_RegisterCallback(OH_VideoProcessing* videoProcessor, 151 const VideoProcessing_Callback* callback, void* userData); 152 153 /** 154 * @brief Set the output surface for video processing. 155 * 156 * Set the output surface before starting video processing. 157 * 158 * @param videoProcessor A video processing instance pointer. 159 * @param window The output surface pointer. 160 * @return {@link VIDEO_PROCESSING_SUCCESS} if setting output surface successfully. \n 161 * {@link VIDEO_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not a video processing instance. \n 162 * {@link VIDEO_PROCESSING_ERROR_INVALID_PARAMETER} if window is null. 163 * @since 12 164 */ 165 VideoProcessing_ErrorCode OH_VideoProcessing_SetSurface(OH_VideoProcessing* videoProcessor, 166 const OHNativeWindow* window); 167 168 /** 169 * @brief Create an input surface. 170 * 171 * Create the input surface before starting video processing. 172 * Call {@link OH_NativeWindow_DestroyNativeWindow} to destroy the input surface. 173 * 174 * @param videoProcessor A video processing instance pointer. 175 * @param window The input surface pointer. For example, it is the output surface of a video decoder. 176 * @return {@link VIDEO_PROCESSING_SUCCESS} if operation is successful. \n 177 * {@link VIDEO_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not a video processing instance. \n 178 * {@link VIDEO_PROCESSING_ERROR_INVALID_PARAMETER} if window is null or <b>*</b>window is <b>not</b> null. \n 179 * {@link VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED} if creating surface failed, input surface is already created 180 * or video processing instance is running. 181 * @since 12 182 */ 183 VideoProcessing_ErrorCode OH_VideoProcessing_GetSurface(OH_VideoProcessing* videoProcessor, OHNativeWindow** window); 184 185 /** 186 * @brief Set parameter for video processing. 187 * 188 * Add parameter identified by the specified parameter key. 189 * 190 * @param videoProcessor An video processing instance pointer. 191 * @param parameter The parameter for video processing. 192 * @return {@link VIDEO_PROCESSING_SUCCESS} if setting parameter is successful. \n 193 * {@link VIDEO_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not an video processing instance. \n 194 * {@link VIDEO_PROCESSING_ERROR_INVALID_PARAMETER} if the parameter is null. \n 195 * {@link VIDEO_PROCESSING_ERROR_INVALID_VALUE} if some property of the parameter is invalid. For example, the parameter 196 * contains unsupported parameter key or value. \n 197 * {@link VIDEO_PROCESSING_ERROR_NO_MEMORY} if memory allocation failed. 198 * @since 12 199 */ 200 VideoProcessing_ErrorCode OH_VideoProcessing_SetParameter(OH_VideoProcessing* videoProcessor, 201 const OH_AVFormat* parameter); 202 203 /** 204 * @brief Get parameter of video processing. 205 * 206 * Get parameter identified by the specified parameter key. 207 * 208 * @param videoProcessor An video processing instance pointer. 209 * @param parameter The parameter used by the video processing instance. 210 * @return {@link VIDEO_PROCESSING_SUCCESS} if getting parameter is successful. \n 211 * {@link VIDEO_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not an video processing instance. \n 212 * {@link VIDEO_PROCESSING_ERROR_INVALID_PARAMETER} if the parameter is null. \n 213 * @since 12 214 */ 215 VideoProcessing_ErrorCode OH_VideoProcessing_GetParameter(OH_VideoProcessing* videoProcessor, OH_AVFormat* parameter); 216 217 /** 218 * @brief Start video processing instance. 219 * 220 * After successfully calling this function, the state {@link VIDEO_PROCESSING_STATE_RUNNING} is reported by callback 221 * function {@link OH_VideoProcessingCallback_OnState}. 222 * 223 * @param videoProcessor A video processing instance pointer. 224 * @return {@link VIDEO_PROCESSING_SUCCESS} if the operation is successful. \n 225 * {@link VIDEO_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not a video processing instance. \n 226 * {@link VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED} if output surface is not set, input surface is not created or 227 * instance is already running. 228 * @since 12 229 */ 230 VideoProcessing_ErrorCode OH_VideoProcessing_Start(OH_VideoProcessing* videoProcessor); 231 232 /** 233 * @brief To stop video processing instance. 234 * 235 * After the video processing instance is stopped successfully, the state {@link VIDEO_PROCESSING_STATE_STOPPED} is 236 * reported by callback function {@link OH_VideoProcessing_OnState}. 237 * 238 * @param videoProcessor A video processing instance pointer. 239 * @return {@link VIDEO_PROCESSING_SUCCESS} if the operation is successful. \n 240 * {@link VIDEO_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not a video processing instance. \n 241 * {@link VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED} if instance is already stopped. 242 * @since 12 243 */ 244 VideoProcessing_ErrorCode OH_VideoProcessing_Stop(OH_VideoProcessing* videoProcessor); 245 246 /** 247 * @brief Send the output buffer out. 248 * 249 * If the callback function {@link OH_VideoProcessingCallback_OnNewOutputBuffer} is set, the buffer's index is reported 250 * to user by the callback function when an output buffer is ready. 251 * 252 * @param videoProcessor A video processing instance pointer. 253 * @param index The output buffer's index. 254 * @return {@link VIDEO_PROCESSING_SUCCESS} if the operation is successful. \n 255 * {@link VIDEO_PROCESSING_ERROR_INVALID_INSTANCE} if instance is null or not a video processing instance. \n 256 * {@link VIDEO_PROCESSING_ERROR_INVALID_PARAMETER} if index is invalid. \n 257 * {@link VIDEO_PROCESSING_ERROR_OPERATION_NOT_PERMITTED} if callback {@link OH_VideoProcessing_OnNewOutputBuffer} is 258 * not set or instance is stopped. 259 * @since 12 260 */ 261 VideoProcessing_ErrorCode OH_VideoProcessing_RenderOutputBuffer(OH_VideoProcessing* videoProcessor, uint32_t index); 262 263 /** 264 * @brief Create a video processing callback object. 265 * 266 * @param callback Output parameter. The *callback points to a new callback object. The *callback should be null before 267 * creating the callback object. 268 * @return {@link VIDEO_PROCESSING_SUCCESS} if callback object is created successfully. \n 269 * {@link VIDEO_PROCESSING_ERROR_INVALID_PARAMETER} if callback is null or <b>*</b>callback is <b>not</b> null. \n 270 * {@link VIDEO_PROCESSING_ERROR_NO_MEMORY} if out of memory. 271 * @since 12 272 */ 273 VideoProcessing_ErrorCode OH_VideoProcessingCallback_Create(VideoProcessing_Callback** callback); 274 275 /** 276 * @brief Destroy the callback object. 277 * 278 * The callback object can be destroyed after it is registered to video processing instance. 279 * 280 * @param callback The callback object pointer. It is recommended setting the callback pointer to null after the 281 * callback object is destroyed. 282 * @return {@link VIDEO_PROCESSING_SUCCESS} if callback is successfully destroyed. \n 283 * {@link VIDEO_PROCESSING_ERROR_INVALID_PARAMETER} if callback is null. 284 * @since 12 285 */ 286 VideoProcessing_ErrorCode OH_VideoProcessingCallback_Destroy(VideoProcessing_Callback* callback); 287 288 /** 289 * @brief Bind the {@link OH_VideoProcessingCallback_OnError} callback function to callback object. 290 * 291 * @param callback A callback object pointer. 292 * @param onError The callback function. 293 * @return {@link VIDEO_PROCESSING_SUCCESS} if the function is bound to callback object successfully. \n 294 * {@link VIDEO_PROCESSING_ERROR_INVALID_PARAMETER} if the callback is null or onError is null. 295 * @since 12 296 */ 297 VideoProcessing_ErrorCode OH_VideoProcessingCallback_BindOnError(VideoProcessing_Callback* callback, 298 OH_VideoProcessingCallback_OnError onError); 299 300 /** 301 * @brief Bind the {@link OH_VideoProcessingCallback_OnState} callback function to callback object. 302 * 303 * @param callback A callback object pointer. 304 * @param onState The callback function. 305 * @return {@link VIDEO_PROCESSING_SUCCESS} if the function is bound to callback object successfully. \n 306 * {@link VIDEO_PROCESSING_ERROR_INVALID_PARAMETER} if the callback is null or onState is null. 307 * @since 12 308 */ 309 VideoProcessing_ErrorCode OH_VideoProcessingCallback_BindOnState(VideoProcessing_Callback* callback, 310 OH_VideoProcessingCallback_OnState onState); 311 312 /** 313 * @brief Bind the {@link OH_VideoProcessingCallback_OnNewOutputBuffer} callback function to callback object. 314 * 315 * @param callback A callback object pointer. 316 * @param onNewOutputBuffer The callback function. 317 * @return {@link VIDEO_PROCESSING_SUCCESS} if the function is bound to callback object successfully. \n 318 * {@link VIDEO_PROCESSING_ERROR_INVALID_PARAMETER} if the callback is null. 319 * @since 12 320 */ 321 VideoProcessing_ErrorCode OH_VideoProcessingCallback_BindOnNewOutputBuffer(VideoProcessing_Callback* callback, 322 OH_VideoProcessingCallback_OnNewOutputBuffer onNewOutputBuffer); 323 324 #ifdef __cplusplus 325 } 326 #endif 327 328 #endif // VIDEO_PROCESSING_ENGINE_C_API_VIDEO_PROCESSING_H 329 /** @} */ 330