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 #ifndef NATIVE_AVCODEC_VIDEOENCODER_H 17 #define NATIVE_AVCODEC_VIDEOENCODER_H 18 19 #include <stdint.h> 20 #include <stdio.h> 21 #include "native_avcodec_base.h" 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 /** 28 * @brief Creates a video encoder instance from the mime type, which is recommended in most cases. 29 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 30 * @param mime mime type description string, refer to {@link AVCODEC_MIME_TYPE} 31 * @return Returns a Pointer to an OH_AVCodec instance 32 * @since 9 33 * @version 1.0 34 */ 35 OH_AVCodec *OH_VideoEncoder_CreateByMime(const char *mime); 36 37 /** 38 * @brief Create a video encoder instance through the video encoder name. The premise of using this interface is to 39 * know the exact name of the encoder. 40 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 41 * @param name Video encoder name 42 * @return Returns a Pointer to an OH_AVCodec instance 43 * @since 9 44 * @version 1.0 45 */ 46 OH_AVCodec *OH_VideoEncoder_CreateByName(const char *name); 47 48 /** 49 * @brief Clear the internal resources of the encoder and destroy the encoder instance 50 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 51 * @param codec Pointer to an OH_AVCodec instance 52 * @return Returns AV_ERR_OK if the execution is successful, 53 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 54 * @since 9 55 * @version 1.0 56 */ 57 OH_AVErrCode OH_VideoEncoder_Destroy(OH_AVCodec *codec); 58 59 /** 60 * @brief Set the asynchronous callback function so that your application can respond to the events generated by the 61 * video encoder. This interface must be called before Prepare is called. 62 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 63 * @param codec Pointer to an OH_AVCodec instance 64 * @param callback A collection of all callback functions, see {@link OH_AVCodecAsyncCallback} 65 * @param userData User specific data 66 * @return Returns AV_ERR_OK if the execution is successful, 67 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 68 * @deprecated since 11 69 * @useinstead OH_VideoEncoder_RegisterCallback 70 * @since 9 71 * @version 1.0 72 */ 73 OH_AVErrCode OH_VideoEncoder_SetCallback(OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData); 74 75 /** 76 * @brief Set the asynchronous callback function so that your application can respond to the events generated by the 77 * video encoder. This interface must be called before Prepare is called. 78 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 79 * @param codec Pointer to an OH_AVCodec instance 80 * @param callback A collection of all callback functions, see {@link OH_AVCodecCallback} 81 * @param userData User specific data 82 * @return Returns AV_ERR_OK if the execution is successful, otherwise returns a specific error code, refer to {@link 83 * OH_AVErrCode} 84 * @since 11 85 */ 86 OH_AVErrCode OH_VideoEncoder_RegisterCallback(OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData); 87 88 /** 89 * @brief To configure the video encoder, typically, you need to configure the description information of the 90 * encoded video track. 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 format A pointer to an OH_AVFormat that gives the description of the video track to be encoded 94 * @return Returns AV_ERR_OK if the execution is successful, 95 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 96 * @since 9 97 * @version 1.0 98 */ 99 OH_AVErrCode OH_VideoEncoder_Configure(OH_AVCodec *codec, OH_AVFormat *format); 100 101 /** 102 * @brief To prepare the internal resources of the encoder, the Configure interface must be called before 103 * calling this interface. 104 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 105 * @param codec Pointer to an OH_AVCodec instance 106 * @return Returns AV_ERR_OK if the execution is successful, 107 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 108 * @since 9 109 * @version 1.0 110 */ 111 OH_AVErrCode OH_VideoEncoder_Prepare(OH_AVCodec *codec); 112 113 /** 114 * @brief Start the encoder, this interface must be called after the Prepare is successful. After being 115 * successfully started, the encoder will start reporting NeedInputData events. 116 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 117 * @param codec Pointer to an OH_AVCodec instance 118 * @return Returns AV_ERR_OK if the execution is successful, 119 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 120 * @since 9 121 * @version 1.0 122 */ 123 OH_AVErrCode OH_VideoEncoder_Start(OH_AVCodec *codec); 124 125 /** 126 * @brief Stop the encoder. After stopping, you can re-enter the Started state through Start. 127 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 128 * @param codec Pointer to an OH_AVCodec instance 129 * @return Returns AV_ERR_OK if the execution is successful, 130 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 131 * @since 9 132 * @version 1.0 133 */ 134 OH_AVErrCode OH_VideoEncoder_Stop(OH_AVCodec *codec); 135 136 /** 137 * @brief Clear the input and output data buffered in the encoder. After this interface is called, all the Buffer 138 * indexes previously reported through the asynchronous callback will be invalidated, make sure not to access the 139 * Buffers corresponding to these indexes. 140 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 141 * @param codec Pointer to an OH_AVCodec instance 142 * @return Returns AV_ERR_OK if the execution is successful, 143 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 144 * @since 9 145 * @version 1.0 146 */ 147 OH_AVErrCode OH_VideoEncoder_Flush(OH_AVCodec *codec); 148 149 /** 150 * @brief Reset the encoder. To continue coding, you need to call the Configure interface again to 151 * configure the encoder instance. 152 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 153 * @param codec Pointer to an OH_AVCodec instance 154 * @return Returns AV_ERR_OK if the execution is successful, 155 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 156 * @since 9 157 * @version 1.0 158 */ 159 OH_AVErrCode OH_VideoEncoder_Reset(OH_AVCodec *codec); 160 161 /** 162 * @brief Get the description information of the output data of the encoder, refer to {@link OH_AVFormat} for details. 163 * It should be noted that the life cycle of the OH_AVFormat instance pointed to by the return value * needs to 164 * be manually released by the caller. 165 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 166 * @param codec Pointer to an OH_AVCodec instance 167 * @return Returns a pointer to an OH_AVFormat instance 168 * @since 9 169 * @version 1.0 170 */ 171 OH_AVFormat *OH_VideoEncoder_GetOutputDescription(OH_AVCodec *codec); 172 173 /** 174 * @brief Set dynamic parameters to the encoder. Note: This interface can only be called after the encoder is started. 175 * At the same time, incorrect parameter settings may cause the encoding to fail. 176 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 177 * @param codec Pointer to an OH_AVCodec instance 178 * @param format OH_AVFormat handle pointer 179 * @return Returns AV_ERR_OK if the execution is successful, 180 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 181 * @since 9 182 * @version 1.0 183 */ 184 OH_AVErrCode OH_VideoEncoder_SetParameter(OH_AVCodec *codec, OH_AVFormat *format); 185 186 /** 187 * @brief Get the input Surface from the video encoder, this interface must be called before Prepare is called. 188 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 189 * @param codec Pointer to an OH_AVCodec instance 190 * @param window A pointer to a OHNativeWindow instance, see {@link OHNativeWindow}, the application is responsible for 191 * managing the life cycle of the window, call OH_NativeWindow_DestroyNativeWindow() when done. 192 * @return Returns AV_ERR_OK if the execution is successful, 193 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 194 * @since 9 195 * @version 1.0 196 */ 197 OH_AVErrCode OH_VideoEncoder_GetSurface(OH_AVCodec *codec, OHNativeWindow **window); 198 199 /** 200 * @brief Return the processed output Buffer to the encoder. 201 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 202 * @param codec Pointer to an OH_AVCodec instance 203 * @param index The index value corresponding to the output Buffer 204 * @return Returns AV_ERR_OK if the execution is successful, 205 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 206 * @deprecated since 11 207 * @useinstead OH_VideoEncoder_FreeOutputBuffer 208 * @since 9 209 * @version 1.0 210 */ 211 OH_AVErrCode OH_VideoEncoder_FreeOutputData(OH_AVCodec *codec, uint32_t index); 212 213 /** 214 * @brief Notifies the video encoder that the input stream has ended. It is recommended to use this interface to notify 215 * the encoder of the end of the stream in surface mode 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 * @since 9 221 * @version 1.0 222 */ 223 OH_AVErrCode OH_VideoEncoder_NotifyEndOfStream(OH_AVCodec *codec); 224 225 /** 226 * @brief Submit the input buffer filled with data to the video encoder. 227 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 228 * @param codec Pointer to an OH_AVCodec instance 229 * @param index Enter the index value corresponding to the Buffer 230 * @param attr Information describing the data contained in the Buffer 231 * @return Returns AV_ERR_OK if the execution is successful, 232 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 233 * @deprecated since 11 234 * @useinstead OH_VideoEncoder_PushInputBuffer 235 * @since 10 236 */ 237 OH_AVErrCode OH_VideoEncoder_PushInputData(OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr); 238 239 /** 240 * @brief Submit the input buffer filled with data to the video encoder. 241 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 242 * @param codec Pointer to an OH_AVCodec instance 243 * @param index Enter the index value corresponding to the Buffer 244 * @return Returns AV_ERR_OK if the execution is successful, 245 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 246 * @since 11 247 */ 248 OH_AVErrCode OH_VideoEncoder_PushInputBuffer(OH_AVCodec *codec, uint32_t index); 249 250 /** 251 * @brief Return the processed output Buffer to the encoder. 252 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 253 * @param codec Pointer to an OH_AVCodec instance 254 * @param index The index value corresponding to the output Buffer 255 * @return Returns AV_ERR_OK if the execution is successful, 256 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 257 * @since 11 258 */ 259 OH_AVErrCode OH_VideoEncoder_FreeOutputBuffer(OH_AVCodec *codec, uint32_t index); 260 261 /** 262 * @brief Get the input data description of the encoder after call {@OH_VideoEncoder_Configure}, 263 * refer to {@link OH_AVFormat} for details. It should be noted that the life cycle of the OH_AVFormat 264 * instance pointed to by the return value needs to be manually released by the caller. 265 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 266 * @param codec Pointer to an OH_AVCodec instance 267 * @return Returns a pointer to an OH_AVFormat instance 268 * @since 10 269 */ 270 OH_AVFormat *OH_VideoEncoder_GetInputDescription(OH_AVCodec *codec); 271 272 /** 273 * @brief Check whether the current codec instance is valid. It can be used fault recovery or app 274 * switchback from the background 275 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 276 * @param codec Pointer to an OH_AVCodec instance 277 * @param isValid Output Parameter. A pointer to a boolean instance, it is true if the codec instance is valid, 278 * false if the codec instance is invalid 279 * @return Returns AV_ERR_OK if the execution is successful, 280 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 281 * @since 10 282 */ 283 OH_AVErrCode OH_VideoEncoder_IsValid(OH_AVCodec *codec, bool *isValid); 284 285 /** 286 * @brief The bitrate mode of video encoder. 287 * @syscap SystemCapability.Multimedia.Media.VideoEncoder 288 * @since 9 289 * @version 1.0 290 */ 291 typedef enum OH_VideoEncodeBitrateMode { 292 /* constant bit rate mode. */ 293 CBR = 0, 294 /* variable bit rate mode. */ 295 VBR = 1, 296 /* constant quality mode. */ 297 CQ = 2, 298 } OH_VideoEncodeBitrateMode; 299 300 #ifdef __cplusplus 301 } 302 #endif 303 304 #endif // NATIVE_AVCODEC_VIDEOENCODER_H