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_VIDEODECODER_H 17 #define NATIVE_AVCODEC_VIDEODECODER_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 typedef struct MediaKeySession MediaKeySession; 28 29 /** 30 * @brief Creates a video decoder instance from the mime type, which is recommended in most cases. 31 * @syscap SystemCapability.Multimedia.Media.VideoDecoder 32 * @param mime mime type description string, refer to {@link AVCODEC_MIME_TYPE} 33 * @return Returns a Pointer to an OH_AVCodec instance 34 * @since 9 35 * @version 1.0 36 */ 37 OH_AVCodec *OH_VideoDecoder_CreateByMime(const char *mime); 38 39 /** 40 * @brief Create a video decoder instance through the video decoder name. 41 * The premise of using this interface is to know the exact name of the decoder. 42 * @syscap SystemCapability.Multimedia.Media.VideoDecoder 43 * @param name video codec name 44 * @return Returns a Pointer to an OH_AVCodec instance 45 * @since 9 46 * @version 1.0 47 */ 48 OH_AVCodec *OH_VideoDecoder_CreateByName(const char *name); 49 50 /** 51 * @brief Clear the internal resources of the decoder and destroy the decoder instance 52 * @syscap SystemCapability.Multimedia.Media.VideoDecoder 53 * @param codec Pointer to an OH_AVCodec instance 54 * @return Returns AV_ERR_OK if the execution is successful, 55 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 56 * @since 9 57 * @version 1.0 58 */ 59 OH_AVErrCode OH_VideoDecoder_Destroy(OH_AVCodec *codec); 60 61 /** 62 * @brief Set the asynchronous callback function so that your application can respond to the events 63 * generated by the video decoder. This interface must be called before Prepare is called. 64 * @syscap SystemCapability.Multimedia.Media.VideoDecoder 65 * @param codec Pointer to an OH_AVCodec instance 66 * @param callback A collection of all callback functions, see {@link OH_AVCodecAsyncCallback} 67 * @param userData User specific data 68 * @return Returns AV_ERR_OK if the execution is successful, 69 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 70 * @deprecated since 11 71 * @useinstead OH_VideoDecoder_RegisterCallback 72 * @since 9 73 * @version 1.0 74 */ 75 OH_AVErrCode OH_VideoDecoder_SetCallback(OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData); 76 77 /** 78 * @brief Set the asynchronous callback function so that your application can respond to the events 79 * generated by the video decoder. This interface must be called before Prepare is called. 80 * @syscap SystemCapability.Multimedia.Media.VideoDecoder 81 * @param codec Pointer to an OH_AVCodec instance 82 * @param callback A collection of all callback functions, see {@link OH_AVCodecCallback} 83 * @param userData User specific data 84 * @return Returns AV_ERR_OK if the execution is successful, 85 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 86 * @since 11 87 */ 88 OH_AVErrCode OH_VideoDecoder_RegisterCallback(OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData); 89 90 /** 91 * @brief Specify the output Surface to provide video decoding output, 92 * this interface must be called before Prepare is called 93 * @syscap SystemCapability.Multimedia.Media.VideoDecoder 94 * @param codec Pointer to an OH_AVCodec instance 95 * @param window A pointer to a OHNativeWindow instance, see {@link OHNativeWindow} 96 * @return Returns AV_ERR_OK if the execution is successful, 97 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 98 * @since 9 99 * @version 1.0 100 */ 101 OH_AVErrCode OH_VideoDecoder_SetSurface(OH_AVCodec *codec, OHNativeWindow *window); 102 103 /** 104 * @brief To configure the video decoder, typically, you need to configure the description information of the decoded 105 * video track, which can be extracted from the OH_AVSource. This interface must be called before Prepare is called. 106 * @syscap SystemCapability.Multimedia.Media.VideoDecoder 107 * @param codec Pointer to an OH_AVCodec instance 108 * @param format A pointer to an OH_AVFormat to give the description of the video track to be decoded 109 * @return Returns AV_ERR_OK if the execution is successful, 110 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 111 * @since 9 112 * @version 1.0 113 */ 114 OH_AVErrCode OH_VideoDecoder_Configure(OH_AVCodec *codec, OH_AVFormat *format); 115 116 /** 117 * @brief To prepare the internal resources of the decoder, the Configure interface must be called before 118 * calling this interface. 119 * @syscap SystemCapability.Multimedia.Media.VideoDecoder 120 * @param codec Pointer to an OH_AVCodec instance 121 * @return Returns AV_ERR_OK if the execution is successful, 122 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 123 * @since 9 124 * @version 1.0 125 */ 126 OH_AVErrCode OH_VideoDecoder_Prepare(OH_AVCodec *codec); 127 128 /** 129 * @brief Start the decoder, this interface must be called after the Prepare is successful. 130 * After being successfully started, the decoder will start reporting NeedInputData events. 131 * @syscap SystemCapability.Multimedia.Media.VideoDecoder 132 * @param codec Pointer to an OH_AVCodec instance 133 * @return Returns AV_ERR_OK if the execution is successful, 134 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 135 * @since 9 136 * @version 1.0 137 */ 138 OH_AVErrCode OH_VideoDecoder_Start(OH_AVCodec *codec); 139 140 /** 141 * @brief Stop the decoder. After stopping, you can re-enter the Started state through Start, 142 * but it should be noted that if Codec-Specific-Data has been input to the decoder before, it needs to be input again. 143 * @syscap SystemCapability.Multimedia.Media.VideoDecoder 144 * @param codec Pointer to an OH_AVCodec instance 145 * @return Returns AV_ERR_OK if the execution is successful, 146 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 147 * @since 9 148 * @version 1.0 149 */ 150 OH_AVErrCode OH_VideoDecoder_Stop(OH_AVCodec *codec); 151 152 /** 153 * @brief Clear the input and output data buffered in the decoder. After this interface is called, all the Buffer 154 * indexes previously reported through the asynchronous callback will be invalidated, make sure not to access 155 * the Buffers corresponding to these indexes. 156 * @syscap SystemCapability.Multimedia.Media.VideoDecoder 157 * @param codec Pointer to an OH_AVCodec instance 158 * @return Returns AV_ERR_OK if the execution is successful, 159 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 160 * @since 9 161 * @version 1.0 162 */ 163 OH_AVErrCode OH_VideoDecoder_Flush(OH_AVCodec *codec); 164 165 /** 166 * @brief Reset the decoder. To continue decoding, you need to call the Configure interface again 167 * to configure the decoder instance. 168 * @syscap SystemCapability.Multimedia.Media.VideoDecoder 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 * @since 9 173 * @version 1.0 174 */ 175 OH_AVErrCode OH_VideoDecoder_Reset(OH_AVCodec *codec); 176 177 /** 178 * @brief Get the description information of the output data of the decoder, refer to {@link OH_AVFormat} 179 * It should be noted that the life cycle of the OH_AVFormat instance pointed to by the return value * needs 180 * to be manually released by the caller. 181 * @syscap SystemCapability.Multimedia.Media.VideoDecoder 182 * @param codec Pointer to an OH_AVCodec instance 183 * @return Returns a pointer to an OH_AVFormat instance 184 * @since 9 185 * @version 1.0 186 */ 187 OH_AVFormat *OH_VideoDecoder_GetOutputDescription(OH_AVCodec *codec); 188 189 /** 190 * @brief Set dynamic parameters to the decoder. Note: This interface can only be called after the decoder is started. 191 * At the same time, incorrect parameter settings may cause decoding failure. 192 * @syscap SystemCapability.Multimedia.Media.VideoDecoder 193 * @param codec Pointer to an OH_AVCodec instance 194 * @param format pointer to an OH_AVFormat instance 195 * @return Returns AV_ERR_OK if the execution is successful, 196 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 197 * @since 9 198 * @version 1.0 199 */ 200 OH_AVErrCode OH_VideoDecoder_SetParameter(OH_AVCodec *codec, OH_AVFormat *format); 201 202 /** 203 * @brief Submit the input buffer filled with data to the video decoder. The {@link OH_AVCodecOnNeedInputData} callback 204 * will report the available input buffer and the corresponding index value. Once the buffer with the specified index 205 * is submitted to the video decoder, the buffer cannot be accessed again until the {@link OH_AVCodecOnNeedInputData} 206 * callback is received again reporting that the buffer with the same index is available. In addition, for some 207 * decoders, it is required to input Codec-Specific-Data to the decoder at the beginning to initialize the decoding 208 * process of the decoder, such as PPS/SPS data in H264 format. 209 * @syscap SystemCapability.Multimedia.Media.VideoDecoder 210 * @param codec Pointer to an OH_AVCodec instance 211 * @param index Enter the index value corresponding to the Buffer 212 * @param attr Information describing the data contained in the Buffer 213 * @return Returns AV_ERR_OK if the execution is successful, 214 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 215 * @deprecated since 11 216 * @useinstead OH_VideoDecoder_PushInputBuffer 217 * @since 9 218 * @version 1.0 219 */ 220 OH_AVErrCode OH_VideoDecoder_PushInputData(OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr); 221 222 /** 223 * @brief Return the processed output Buffer to the decoder, and notify the decoder to finish rendering the 224 * decoded data contained in the Buffer on the output Surface. If the output surface is not configured before, 225 * calling this interface only returns the output buffer corresponding to the specified index to the decoder. 226 * @syscap SystemCapability.Multimedia.Media.VideoDecoder 227 * @param codec Pointer to an OH_AVCodec instance 228 * @param index The index value corresponding to the output Buffer 229 * @return Returns AV_ERR_OK if the execution is successful, 230 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 231 * @deprecated since 11 232 * @useinstead OH_VideoDecoder_RenderOutputBuffer 233 * @since 9 234 * @version 1.0 235 */ 236 OH_AVErrCode OH_VideoDecoder_RenderOutputData(OH_AVCodec *codec, uint32_t index); 237 238 /** 239 * @brief Return the processed output Buffer to the decoder. 240 * @syscap SystemCapability.Multimedia.Media.VideoDecoder 241 * @param codec Pointer to an OH_AVCodec instance 242 * @param index The index value corresponding to the output Buffer 243 * @return Returns AV_ERR_OK if the execution is successful, 244 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 245 * @deprecated since 11 246 * @useinstead OH_VideoDecoder_FreeOutputBuffer 247 * @since 9 248 * @version 1.0 249 */ 250 OH_AVErrCode OH_VideoDecoder_FreeOutputData(OH_AVCodec *codec, uint32_t index); 251 252 /** 253 * @brief Submit the input buffer filled with data to the video decoder. The {@link OH_AVCodecOnNeedInputBuffer} 254 * callback will report the available input buffer and the corresponding index value. Once the buffer with the 255 * specified index is submitted to the video decoder, the buffer cannot be accessed again until the 256 * {@link OH_AVCodecOnNeedInputBuffer} callback is received again reporting that the buffer with the same index is 257 * available. In addition, for some decoders, it is required to input Codec-Specific-Data to the decoder at the 258 * beginning to initialize the decoding process of the decoder, such as PPS/SPS data in H264 format. 259 * @syscap SystemCapability.Multimedia.Media.VideoDecoder 260 * @param codec Pointer to an OH_AVCodec instance 261 * @param index The index of the input buffer. 262 * @return Returns AV_ERR_OK if the execution is successful, 263 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 264 * @since 11 265 */ 266 OH_AVErrCode OH_VideoDecoder_PushInputBuffer(OH_AVCodec *codec, uint32_t index); 267 268 /** 269 * @brief Return the processed output Buffer to the decoder, and notify the decoder to finish rendering the 270 * decoded data contained in the Buffer on the output Surface. If the output surface is not configured before, 271 * calling this interface only returns the output buffer corresponding to the specified index to the decoder. 272 * @syscap SystemCapability.Multimedia.Media.VideoDecoder 273 * @param codec Pointer to an OH_AVCodec instance 274 * @param index The index value corresponding to the output Buffer 275 * @return Returns AV_ERR_OK if the execution is successful, otherwise returns a specific error code, refer to {@link 276 * OH_AVErrCode} 277 * @since 11 278 */ 279 OH_AVErrCode OH_VideoDecoder_RenderOutputBuffer(OH_AVCodec *codec, uint32_t index); 280 281 /** 282 * @brief Return the processed output Buffer to the decoder. 283 * @syscap SystemCapability.Multimedia.Media.VideoDecoder 284 * @param codec Pointer to an OH_AVCodec instance 285 * @param index The index value corresponding to the output Buffer 286 * @return Returns AV_ERR_OK if the execution is successful, 287 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 288 * @since 11 289 */ 290 OH_AVErrCode OH_VideoDecoder_FreeOutputBuffer(OH_AVCodec *codec, uint32_t index); 291 292 /** 293 * @brief Check whether the current codec instance is valid. It can be used fault recovery or app 294 * switchback from the background. 295 * @syscap SystemCapability.Multimedia.Media.VideoDecoder 296 * @param codec Pointer to an OH_AVCodec instance 297 * @param isValid Output parameter. A pointer to a boolean instance, it is true if the codec instance is valid, 298 * false if the codec instance is invalid 299 * @return Returns AV_ERR_OK if the execution is successful, 300 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 301 * @since 10 302 */ 303 OH_AVErrCode OH_VideoDecoder_IsValid(OH_AVCodec *codec, bool *isValid); 304 305 /** 306 * @brief Set decryption info. 307 * 308 * @syscap SystemCapability.Multimedia.Media.VideoDecoder 309 * @param codec Pointer to an OH_AVCodec instance 310 * @param mediaKeySession A media key session instance with decryption function. 311 * @param secureVideoPath Require secure decoder or not. 312 * @return Returns AV_ERR_OK if the execution is successful, 313 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 314 * @since 11 315 * @version 1.0 316 */ 317 OH_AVErrCode OH_VideoDecoder_SetDecryptionConfig(OH_AVCodec *codec, MediaKeySession *mediaKeySession, 318 bool secureVideoPath); 319 320 #ifdef __cplusplus 321 } 322 #endif 323 324 #endif // NATIVE_AVCODEC_VIDEODECODER_H