1 /* 2 * Copyright (c) 2020-2021 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 Codec 18 * @{ 19 * 20 * @brief Defines codec-related APIs 21 * 22 * including custom data types and functions for initializing audio and video codecs, 23 * setting parameters, and controlling and transferring data. 24 * 25 * @since 1.0 26 * @version 1.0 27 */ 28 29 /** 30 * @file codec_interface.h 31 * 32 * @brief Declares codec-related APIs, including functions for initializing audio and video codecs, 33 * setting parameters, and controlling and transferring data. 34 * 35 * @since 1.0 36 * @version 1.0 37 */ 38 39 #ifndef CODEC_INTERFACE_H 40 #define CODEC_INTERFACE_H 41 42 #include "codec_type.h" 43 44 #ifdef __cplusplus 45 #if __cplusplus 46 extern "C" { 47 #endif 48 #endif /* __cplusplus */ 49 50 /** 51 * @brief Initializes the internal audio and video submodules of the codec. 52 * 53 * This function needs to be called only once in a process. 54 * 55 * @return Returns <b>0</b> if the initialization is successful; returns a non-zero value otherwise. 56 * @see CodecDeinit 57 */ 58 int32_t CodecInit(); 59 60 /** 61 * @brief Deinitializes the internal audio and video submodules of the codec. 62 * 63 * This function needs to be called only once in a process. 64 * 65 * @return Returns <b>0</b> if the deinitialization is successful; returns a non-zero value otherwise. 66 * @see CodecInit 67 */ 68 int32_t CodecDeinit(); 69 70 /** 71 * @brief Obtains the capabilities of a specified media type based on an index. 72 * 73 * You can call this function repeatedly to obtain the codec capabilities until <b>CODEC_END</b> is returned. 74 * The corresponding capabilities are described in the {@link Capability} structure, 75 * including the maximum and minimum resolutions, maximum and minimum bit rates, and supported profiles and levels. 76 * After obtaining the capabilities, determine whether they can meet your requirements, for example, 77 * whether specific media files can be played and whether audio and video frames can be compressed. 78 * 79 * @param index Indicates the index of the capabilities. 80 * @param cap Indicates the pointer to the capabilities. 81 * @return Returns <b>0</b> if the capabilities corresponding to the index are available; 82 * returns <b>-1</b> otherwise. 83 */ 84 int32_t CodecEnumerateCapability(uint32_t index, CodecCapability *cap); 85 86 /** 87 * @brief Obtains the capabilities of a specified media type. 88 * 89 * You can call this function to obtain the codec capabilities. 90 * The corresponding capabilities are described in the {@link Capability} structure, 91 * including the maximum and minimum resolutions, maximum and minimum bit rates, and supported profiles and levels. 92 * After obtaining the capabilities, determine whether they can meet your requirements, for example, 93 * whether specific media files can be played and whether audio and video frames can be compressed. 94 * 95 * @param mime Indicates the media type. For details, see {@link AvCodecMime}. 96 * @param type Indicates the audio and video codec types. For details, see {@link CodecType}. 97 * @param flags Indicates the audio and video codec flags. <b>0</b> indicates hardware codec, 98 * and <b>1</b> indicates software codec. 99 * @param cap Indicates the pointer to the capabilities. 100 * @return Returns <b>0</b> if the codec is supported and capabilities are available; 101 * returns a non-zero value if the codec is not supported or the capabilities are unavailable. 102 */ 103 int32_t CodecGetCapability(AvCodecMime mime, CodecType type, uint32_t flags, CodecCapability *cap); 104 105 /** 106 * @brief Creates a specific codec component by name and returns the component context through a handle. 107 * 108 * You can adjust the parameters required for creating a component based on service requirements. 109 * 110 * @param name Indicates the pointer to the unique name of the component, for example, 111 * <b>codec.avc.hardware.decoder</b>. 112 * @param handle Indicates the pointer to the codec handle returned. 113 * @return Returns <b>0</b> if the codec component is created and the handle is available; 114 * returns a non-zero value otherwise. 115 */ 116 int32_t CodecCreate(const char* name, CODEC_HANDLETYPE *handle); 117 118 /** 119 * @brief Creates a specific codec component by codec type and codec format, 120 * returns the component context through a handle. 121 * 122 * You can adjust the parameters required for creating a component based on service requirements. 123 * 124 * @param type Indicates the codec type, for example, <b>VIDEO_DECODER</b>. 125 * @param mime Indicates the codec format, for example, <b>MEDIA_MIMETYPE_VIDEO_AVC</b>. 126 * @param handle Indicates the pointer to the codec handle returned. 127 * @return Returns <b>0</b> if the codec component is created and the handle is available; 128 * returns a non-zero value otherwise. 129 */ 130 int32_t CodecCreateByType(CodecType type, AvCodecMime mime, CODEC_HANDLETYPE *handle); 131 132 /** 133 * @brief Destroys a codec component. 134 * 135 * @param handle Indicates the handle of the codec component. 136 * @return Returns <b>0</b> if the codec component is destroyed; returns a non-zero value otherwise. 137 * @see CodecCreate 138 */ 139 int32_t CodecDestroy(CODEC_HANDLETYPE handle); 140 141 /** 142 * @brief Sets the input or output buffer mode. 143 * 144 * You can learn about the support of the codec input/output buffer for internal and external buffer modes 145 * by calling {@link CodecGetCapability}. In this way, you can determine whether to use an internal or 146 * external buffer mode. If the current codec can use only the specific buffer mode, you do not need to set it. 147 * 148 * @param handle Indicates the handle of the codec component. 149 * @param direct Specifies whether the buffer type is an input type or an output type. 150 * @param mode Specifies whether to use an internal or external buffer mode. 151 * @param type Specifies the buffer memory type. 152 * @return Returns <b>0</b> if the setting is successful; returns a non-zero value otherwise. 153 */ 154 int32_t CodecSetPortMode(CODEC_HANDLETYPE handle, DirectionType direct, AllocateBufferMode mode, BufferType type); 155 156 int32_t CodecGetPortMode(CODEC_HANDLETYPE handle, DirectionType direct, AllocateBufferMode *mode, BufferType *type); 157 158 /** 159 * @brief Sets parameters required by a codec component. 160 * 161 * You should call this function to set parameters after {@link CodecCreate} is called 162 * but before {@link CodecStart} is called. 163 * 164 * @param handle Indicates the handle of the codec component. 165 * @param params Indicates the pointer to the parameters to set in the array. 166 * @param paramCnt Indicates the number of elements in the parameter array. 167 * @return Returns <b>0</b> if the setting is successful; returns a non-zero value otherwise. 168 * @see CodecGetParameter 169 */ 170 int32_t CodecSetParameter(CODEC_HANDLETYPE handle, const Param *params, int paramCnt); 171 172 /** 173 * @brief Obtains parameters from a codec component. 174 * 175 * This function must be called after {@link CodecCreate}. 176 * 177 * @param handle Indicates the handle of the codec component. 178 * @param params Indicates the pointer to the parameters in the array used when the component is created. 179 * @param paramCnt Indicates the number of elements in the parameter array. 180 * @return Returns <b>0</b> if all parameters to obtain are supported; returns a non-zero value otherwise. 181 * @see CodecSetParameter 182 */ 183 int32_t CodecGetParameter(CODEC_HANDLETYPE handle, Param *params, int paramCnt); 184 185 /** 186 * @brief Starts a codec component. 187 * 188 * You can restart a component after it is stopped. 189 * 190 * @param handle Indicates the handle of the codec component. 191 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 192 */ 193 int32_t CodecStart(CODEC_HANDLETYPE handle); 194 195 /** 196 * @brief Stops a codec component. 197 * 198 * @param handle Indicates the handle of the codec component. 199 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 200 */ 201 int32_t CodecStop(CODEC_HANDLETYPE handle); 202 203 /** 204 * @brief Reset a codec component. 205 * 206 * @param handle Indicates the handle of the codec component. 207 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 208 */ 209 int32_t CodecReset(CODEC_HANDLETYPE handle); 210 211 /** 212 * @brief Clears the cache when the codec component is the running state. 213 * 214 * Generally, this function is called when the seek operation is performed during playback. 215 * 216 * @param handle Indicates the handle of the codec component. 217 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 218 */ 219 int32_t CodecFlush(CODEC_HANDLETYPE handle, DirectionType directType); 220 221 /** 222 * @brief Queues input data. 223 * 224 * This function works with {@link CodecDequeInput} to implement input data transmission. 225 * 226 * @param handle Indicates the handle of the codec component. 227 * @param inputData Indicates the pointer to the input data. 228 * @param timeoutMs Indicates the timeout duration. 229 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 230 */ 231 int32_t CodecQueueInput(CODEC_HANDLETYPE handle, const CodecBuffer *inputData, uint32_t timeoutMs, int releaseFenceFd); 232 233 /** 234 * @brief Dequeues input data that has been used. 235 * 236 * This function works with {@link CodecQueueInput} to implement input data transmission. 237 * 238 * @param handle Indicates the handle of the codec component. 239 * @param timeoutMs Indicates the timeout duration. Generally, the value is less than or equal to <b>3</b> seconds. 240 * @param inputData Indicates the pointer to the input data that is used. 241 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 242 */ 243 int32_t CodecDequeueInput(CODEC_HANDLETYPE handle, uint32_t timeoutMs, int *acquireFd, CodecBuffer *inputData); 244 245 /** 246 * @brief Queues output data. 247 * 248 * This function works with {@link CodecDequeueOutput} to implement output data transmission. 249 * 250 * @param handle Indicates the handle of the codec component. 251 * @param outInfo Indicates the pointer to the output data. 252 * @param timeoutMs Indicates the timeout duration. 253 * @param releaseFenceFd Indicates that the descriptor comes from a buffer consumer. 254 * The output data can be used only after waiting for <b>releaseFenceFd</b> is successful. 255 * The value <b>-1</b> indicates that <b>releaseFenceFd</b> is invalid. 256 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 257 */ 258 int32_t CodecQueueOutput(CODEC_HANDLETYPE handle, CodecBuffer *outInfo, uint32_t timeoutMs, int releaseFenceFd); 259 260 /** 261 * @brief Dequeues output data. 262 * 263 * This function works with {@link CodecQueueOutput} to implement output data transmission. 264 * 265 * @param handle Indicates the handle of the codec component. 266 * @param timeoutMs Indicates the timeout duration. 267 * @param acquireFd Indicates that this parameter is derived from the codec mode. 268 * The output data can be used only after waiting for <b>acquireFd</b> is successful. 269 * The value <b>-1</b> indicates that <b>acquireFd</b> is invalid. 270 * @param outInfo Indicates the pointer to the output data. 271 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 272 */ 273 int32_t CodecDequeueOutput(CODEC_HANDLETYPE handle, uint32_t timeoutMs, int *acquireFd, CodecBuffer *outInfo); 274 275 /** 276 * @brief Sets the callback function. 277 * 278 * The codec uses the callback function to notify the upper layer of events and asynchronously 279 * report available input/output information. 280 * 281 * @param handle Indicates the handle of the codec component. 282 * @param cb Indicates the pointer to the callback function. For details, see {@link CodecCallback}. 283 * @param instance Indicates the upper-layer instance to be notified. 284 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 285 */ 286 int32_t CodecSetCallback(CODEC_HANDLETYPE handle, const CodecCallback *cb, UINTPTR instance); 287 288 #ifdef __cplusplus 289 #if __cplusplus 290 } 291 #endif 292 #endif /* __cplusplus */ 293 294 #endif /* CODEC_INTERFACE_H */ 295 /** @} */