1/* 2 * Copyright (C) 2023 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 * @file native_avcodec_videoencoder.h 18 * 19 * @brief Provides video encoder capabilities. 20 * 21 * @kit AVCodecKit 22 * @library libnative_media_venc.so 23 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 24 * @since 9 25 */ 26 27#ifndef NATIVE_AVCODEC_VIDEOENCODER_H 28#define NATIVE_AVCODEC_VIDEOENCODER_H 29 30#include <stdint.h> 31#include <stdio.h> 32#include "native_avcodec_base.h" 33 34#ifdef __cplusplus 35extern "C" { 36#endif 37 38/** 39 * @brief When OH_AVCodec needs new input parameter during the running process, the function pointer will be called and 40 * carry an available OH_AVFormat to fill in the new input parameter. This parameter takes effect immediately with the 41 * frame. 42 * 43 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 44 * @param codec OH_AVCodec instance 45 * @param index The index corresponding to the new OH_AVFormat instance 46 * @param parameter Parameter containing the new OH_AVFormat instance 47 * @param userData specified data 48 * @since 12 49 */ 50typedef void (*OH_VideoEncoder_OnNeedInputParameter)(OH_AVCodec *codec, uint32_t index, OH_AVFormat *parameter, 51 void *userData); 52 53/** 54 * @brief Creates a video encoder instance from the mime type, which is recommended in most cases. 55 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 56 * @param mime mime type description string, refer to {@link AVCODEC_MIME_TYPE} 57 * @return Returns a Pointer to an OH_AVCodec instance. 58 * Return nullptr if memory ran out or the mime type is not supported. 59 * @since 9 60 */ 61OH_AVCodec *OH_VideoEncoder_CreateByMime(const char *mime); 62 63/** 64 * @brief Create a video encoder instance through the video encoder name. The premise of using this interface is to 65 * know the exact name of the encoder. 66 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 67 * @param name Video encoder name 68 * @return Returns a Pointer to an OH_AVCodec instance. 69 * Return nullptr if memory ran out or the encoder name is not supported. 70 * @since 9 71 */ 72OH_AVCodec *OH_VideoEncoder_CreateByName(const char *name); 73 74/** 75 * @brief Clear the internal resources of the encoder and destroy the encoder instance 76 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 77 * @param codec Pointer to an OH_AVCodec instance 78 * @return Returns AV_ERR_OK if the execution is successful, 79 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 80 * {@link AV_ERR_NO_MEMORY}, inner resource has already released. 81 * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. 82 * {@link AV_ERR_UNKNOWN}, unknown error. 83 * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. 84 * @since 9 85 */ 86OH_AVErrCode OH_VideoEncoder_Destroy(OH_AVCodec *codec); 87 88/** 89 * @brief Set the asynchronous callback function so that your application can respond to the events generated by the 90 * video encoder. This interface must be called before Prepare is called. 91 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 92 * @param codec Pointer to an OH_AVCodec instance 93 * @param callback A collection of all callback functions, see {@link OH_AVCodecAsyncCallback} 94 * @param userData User specific data 95 * @return Returns AV_ERR_OK if the execution is successful, 96 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 97 * {@link AV_ERR_NO_MEMORY}, inner resource has already released. 98 * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. 99 * {@link AV_ERR_UNKNOWN}, unknown error. 100 * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. 101 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state, must be called before Prepare. 102 * @deprecated since 11 103 * @useinstead OH_VideoEncoder_RegisterCallback 104 * @since 9 105 */ 106OH_AVErrCode OH_VideoEncoder_SetCallback(OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData); 107 108/** 109 * @brief Set the asynchronous callback function so that your application can respond to the events generated by the 110 * video encoder. This interface must be called before Prepare is called. 111 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 112 * @param codec Pointer to an OH_AVCodec instance 113 * @param callback A collection of all callback functions, see {@link OH_AVCodecCallback} 114 * @param userData User specific data 115 * @return Returns AV_ERR_OK if the execution is successful, 116 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 117 * {@link AV_ERR_NO_MEMORY}, inner resource has already released. 118 * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. 119 * {@link AV_ERR_UNKNOWN}, unknown error. 120 * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. 121 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state, must be called before Prepare. 122 * @since 11 123 */ 124OH_AVErrCode OH_VideoEncoder_RegisterCallback(OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData); 125 126/** 127 * @brief Set the asynchronous callback function so that your application can respond to the events generated by the 128 * video encoder. This interface is optional only for input surface. If this interface is used, it must be invoked 129 * before {@link OH_VideoEncoder_Configure}. 130 * 131 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 132 * @param codec Pointer to an OH_AVCodec instance 133 * @param onInputParameter A callback functions, see {@link OH_VideoEncoder_OnNeedInputParameter} 134 * @param userData User specific data 135 * @return Returns AV_ERR_OK if the execution is successful, 136 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 137 * {@link AV_ERR_NO_MEMORY}, inner resource has already released. 138 * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. 139 * {@link AV_ERR_UNKNOWN}, unknown error. 140 * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. 141 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state, must be called before Prepare. 142 * @since 12 143 */ 144OH_AVErrCode OH_VideoEncoder_RegisterParameterCallback(OH_AVCodec *codec, 145 OH_VideoEncoder_OnNeedInputParameter onInputParameter, 146 void *userData); 147 148/** 149 * @brief To configure the video encoder, typically, you need to configure the description information of the 150 * encoded video track. This interface must be called before Prepare is called. 151 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 152 * @param codec Pointer to an OH_AVCodec instance 153 * @param format A pointer to an OH_AVFormat that gives the description of the video track to be encoded 154 * @return Returns AV_ERR_OK if the execution is successful, 155 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 156 * {@link AV_ERR_NO_MEMORY}, instance has already released. 157 * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. Invalid param in format. 158 * {@link AV_ERR_UNKNOWN}, unknown error. 159 * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. 160 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state, must be called before Prepare. 161 * @since 9 162 */ 163OH_AVErrCode OH_VideoEncoder_Configure(OH_AVCodec *codec, OH_AVFormat *format); 164 165/** 166 * @brief To prepare the internal resources of the encoder, the Configure interface must be called before 167 * calling this interface. 168 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 169 * @param codec Pointer to an OH_AVCodec instance 170 * @return Returns AV_ERR_OK if the execution is successful, 171 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 172 * {@link AV_ERR_NO_MEMORY}, instance has already released. 173 * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. 174 * {@link AV_ERR_UNKNOWN}, unknown error. 175 * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. 176 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 177 * @since 9 178 */ 179OH_AVErrCode OH_VideoEncoder_Prepare(OH_AVCodec *codec); 180 181/** 182 * @brief Start the encoder, this interface must be called after the Prepare is successful. After being 183 * successfully started, the encoder will start reporting NeedInputData events. 184 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 185 * @param codec Pointer to an OH_AVCodec instance 186 * @return Returns AV_ERR_OK if the execution is successful, 187 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 188 * {@link AV_ERR_NO_MEMORY}, instance has already released. 189 * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. 190 * {@link AV_ERR_UNKNOWN}, unknown error. 191 * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. 192 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 193 * @since 9 194 */ 195OH_AVErrCode OH_VideoEncoder_Start(OH_AVCodec *codec); 196 197/** 198 * @brief Stop the encoder. After stopping, you can re-enter the Started state through Start. 199 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 200 * @param codec Pointer to an OH_AVCodec instance 201 * @return Returns AV_ERR_OK if the execution is successful, 202 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 203 * {@link AV_ERR_NO_MEMORY}, instance has already released. 204 * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. 205 * {@link AV_ERR_UNKNOWN}, unknown error. 206 * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. 207 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 208 * @since 9 209 */ 210OH_AVErrCode OH_VideoEncoder_Stop(OH_AVCodec *codec); 211 212/** 213 * @brief Clear the input and output data buffered in the encoder. After this interface is called, all the Buffer 214 * indexes previously reported through the asynchronous callback will be invalidated, make sure not to access the 215 * Buffers corresponding to these indexes. 216 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 217 * @param codec Pointer to an OH_AVCodec instance 218 * @return Returns AV_ERR_OK if the execution is successful, 219 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 220 * {@link AV_ERR_NO_MEMORY}, instance has already released. 221 * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. 222 * {@link AV_ERR_UNKNOWN}, unknown error. 223 * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. 224 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 225 * @since 9 226 */ 227OH_AVErrCode OH_VideoEncoder_Flush(OH_AVCodec *codec); 228 229/** 230 * @brief Reset the encoder. To continue coding, you need to call the Configure interface again to 231 * configure the encoder instance. 232 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 233 * @param codec Pointer to an OH_AVCodec instance 234 * @return Returns AV_ERR_OK if the execution is successful, 235 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 236 * {@link AV_ERR_NO_MEMORY}, instance has already released. 237 * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. 238 * {@link AV_ERR_UNKNOWN}, unknown error. 239 * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. 240 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 241 * @since 9 242 */ 243OH_AVErrCode OH_VideoEncoder_Reset(OH_AVCodec *codec); 244 245/** 246 * @brief Get the description information of the output data of the encoder, refer to {@link OH_AVFormat} for details. 247 * It should be noted that the life cycle of the OH_AVFormat instance pointed to by the return value * needs to 248 * be manually released by the caller. 249 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 250 * @param codec Pointer to an OH_AVCodec instance 251 * @return Returns a pointer to an OH_AVFormat instance. 252 * Return nullptr if the codec is nullptr or invaild. 253 * @since 9 254 */ 255OH_AVFormat *OH_VideoEncoder_GetOutputDescription(OH_AVCodec *codec); 256 257/** 258 * @brief Set dynamic parameters to the encoder. Note: This interface can only be called after the encoder is started. 259 * At the same time, incorrect parameter settings may cause the encoding to fail. 260 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 261 * @param codec Pointer to an OH_AVCodec instance 262 * @param format OH_AVFormat handle pointer 263 * @return Returns AV_ERR_OK if the execution is successful, 264 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 265 * {@link AV_ERR_NO_MEMORY}, instance has already released. 266 * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. Invalid param in format. 267 * {@link AV_ERR_UNKNOWN}, unknown error. 268 * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. 269 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 270 * @since 9 271 */ 272OH_AVErrCode OH_VideoEncoder_SetParameter(OH_AVCodec *codec, OH_AVFormat *format); 273 274/** 275 * @brief Get the input Surface from the video encoder, this interface must be called before Prepare is called. 276 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 277 * @param codec Pointer to an OH_AVCodec instance 278 * @param window A pointer to a OHNativeWindow instance, see {@link OHNativeWindow}, the application is responsible for 279 * managing the life cycle of the window, call OH_NativeWindow_DestroyNativeWindow() when done. 280 * @return Returns AV_ERR_OK if the execution is successful, 281 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 282 * {@link AV_ERR_NO_MEMORY}, inner resource has already released. 283 * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. 284 * {@link AV_ERR_UNKNOWN}, unknown error. 285 * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. 286 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 287 * @since 9 288 */ 289OH_AVErrCode OH_VideoEncoder_GetSurface(OH_AVCodec *codec, OHNativeWindow **window); 290 291/** 292 * @brief Return the processed output Buffer to the encoder. 293 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 294 * @param codec Pointer to an OH_AVCodec instance 295 * @param index The index value corresponding to the output Buffer 296 * @return Returns AV_ERR_OK if the execution is successful, 297 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 298 * {@link AV_ERR_NO_MEMORY}, instance has already released. 299 * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. 300 * Buffer index should be given by {@link OH_AVCodecOnNewOutputData}. 301 * {@link AV_ERR_UNKNOWN}, unknown error. 302 * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. 303 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 304 * @deprecated since 11 305 * @useinstead OH_VideoEncoder_FreeOutputBuffer 306 * @since 9 307 */ 308OH_AVErrCode OH_VideoEncoder_FreeOutputData(OH_AVCodec *codec, uint32_t index); 309 310/** 311 * @brief Notifies the video encoder that the input stream has ended. It is recommended to use this interface to notify 312 * the encoder of the end of the stream in surface mode 313 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 314 * @param codec Pointer to an OH_AVCodec instance 315 * @return Returns AV_ERR_OK if the execution is successful, 316 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 317 * {@link AV_ERR_NO_MEMORY}, instance has already released. 318 * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. 319 * {@link AV_ERR_UNKNOWN}, unknown error. 320 * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. 321 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 322 * @since 9 323 */ 324OH_AVErrCode OH_VideoEncoder_NotifyEndOfStream(OH_AVCodec *codec); 325 326/** 327 * @brief Submit the input buffer filled with data to the video encoder. 328 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 329 * @param codec Pointer to an OH_AVCodec instance 330 * @param index Enter the index value corresponding to the Buffer 331 * @param attr Information describing the data contained in the Buffer 332 * @return Returns AV_ERR_OK if the execution is successful, 333 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 334 * {@link AV_ERR_NO_MEMORY}, instance has already released. 335 * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. 336 * Buffer index should be given by {@link OH_AVCodecOnNeedInputData}. 337 * {@link AV_ERR_UNKNOWN}, unknown error. 338 * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. 339 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 340 * @deprecated since 11 341 * @useinstead OH_VideoEncoder_PushInputBuffer 342 * @since 10 343 */ 344OH_AVErrCode OH_VideoEncoder_PushInputData(OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr); 345 346/** 347 * @brief Submit the input buffer filled with data to the video encoder. 348 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 349 * @param codec Pointer to an OH_AVCodec instance 350 * @param index Enter the index value corresponding to the Buffer 351 * @return Returns AV_ERR_OK if the execution is successful, 352 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 353 * {@link AV_ERR_NO_MEMORY}, instance has already released. 354 * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. 355 * Buffer index should be given by {@link OH_AVCodecOnNeedInputBuffer}. 356 * {@link AV_ERR_UNKNOWN}, unknown error. 357 * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. 358 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 359 360 * @since 11 361 */ 362OH_AVErrCode OH_VideoEncoder_PushInputBuffer(OH_AVCodec *codec, uint32_t index); 363 364/** 365 * @brief Submit the input parameter filled with data to the video encoder. 366 * 367 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 368 * @param codec Pointer to an OH_AVCodec instance 369 * @param index Enter the index value corresponding to the input parameter 370 * @return Returns AV_ERR_OK if the execution is successful, 371 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 372 * {@link AV_ERR_NO_MEMORY}, instance has already released. 373 * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. 374 * Index should be given by {@link OH_VideoEncoder_OnNeedInputParameter}. 375 * {@link AV_ERR_UNKNOWN}, unknown error. 376 * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. 377 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 378 * @since 12 379 */ 380OH_AVErrCode OH_VideoEncoder_PushInputParameter(OH_AVCodec *codec, uint32_t index); 381 382/** 383 * @brief Return the processed output Buffer to the encoder. 384 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 385 * @param codec Pointer to an OH_AVCodec instance 386 * @param index The index value corresponding to the output Buffer 387 * @return Returns AV_ERR_OK if the execution is successful, 388 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 389 * {@link AV_ERR_NO_MEMORY}, instance has already released. 390 * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. 391 * Buffer index should be given by {@link OH_AVCodecOnNewOutputBuffer}. 392 * {@link AV_ERR_UNKNOWN}, unknown error. 393 * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. 394 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 395 * @since 11 396 */ 397OH_AVErrCode OH_VideoEncoder_FreeOutputBuffer(OH_AVCodec *codec, uint32_t index); 398 399/** 400 * @brief Get the input data description of the encoder after call {@OH_VideoEncoder_Configure}, 401 * refer to {@link OH_AVFormat} for details. It should be noted that the life cycle of the OH_AVFormat 402 * instance pointed to by the return value needs to be manually released by the caller. 403 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 404 * @param codec Pointer to an OH_AVCodec instance 405 * @return Returns a pointer to an OH_AVFormat instance. 406 * Return nullptr if the encoder is nullptr or invaild. 407 * @since 10 408 */ 409OH_AVFormat *OH_VideoEncoder_GetInputDescription(OH_AVCodec *codec); 410 411/** 412 * @brief Check whether the current codec instance is valid. It can be used fault recovery or app 413 * switchback from the background 414 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 415 * @param codec Pointer to an OH_AVCodec instance 416 * @param isValid Output Parameter. A pointer to a boolean instance, it is true if the codec instance is valid, 417 * false if the codec instance is invalid 418 * @return Returns AV_ERR_OK if the execution is successful, 419 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 420 * {@link AV_ERR_NO_MEMORY}, instance has already released. 421 * {@link AV_ERR_INVALID_VAL}, the encoder is nullptr or invalid. 422 * {@link AV_ERR_UNKNOWN}, unknown error. 423 * {@link AV_ERR_SERVICE_DIED}, avcodec service is died. 424 * @since 10 425 */ 426OH_AVErrCode OH_VideoEncoder_IsValid(OH_AVCodec *codec, bool *isValid); 427 428/** 429 * @brief The bitrate mode of video encoder. 430 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 431 * @since 9 432 */ 433typedef enum OH_VideoEncodeBitrateMode { 434 /* constant bit rate mode. */ 435 CBR = 0, 436 /* variable bit rate mode. */ 437 VBR = 1, 438 /* constant quality mode. */ 439 CQ = 2, 440} OH_VideoEncodeBitrateMode; 441 442#ifdef __cplusplus 443} 444#endif 445 446#endif // NATIVE_AVCODEC_VIDEOENCODER_H