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 CodecEnumerateCapbility(uint32_t index, CodecCapbility *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 CodecGetCapbility(AvCodecMime mime, CodecType type, uint32_t flags, CodecCapbility *cap); 104 105 /** 106 * @brief Creates a specific codec component 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 attr Indicates the pointer to the parameters in the array required for creating the component. 113 * @param len Indicates the number of elements in the parameter array. 114 * @param handle Indicates the pointer to the codec handle returned. 115 * @return Returns <b>0</b> if the codec component is created and the handle is available; 116 * returns a non-zero value otherwise. 117 */ 118 int32_t CodecCreate(const char* name, const Param *attr, int len, CODEC_HANDLETYPE *handle); 119 120 /** 121 * @brief Destroys a codec component. 122 * 123 * @param handle Indicates the handle of the codec component. 124 * @return Returns <b>0</b> if the codec component is destroyed; returns a non-zero value otherwise. 125 * @see CodecCreate 126 */ 127 int32_t CodecDestroy(CODEC_HANDLETYPE handle); 128 129 /** 130 * @brief Sets the input or output buffer mode. 131 * 132 * You can learn about the support of the codec input/output buffer for internal and external buffer modes 133 * by calling {@link CodecGetCapbility}. In this way, you can determine whether to use an internal or 134 * external buffer mode. If the current codec can use only the specific buffer mode, you do not need to set it. 135 * 136 * @param handle Indicates the handle of the codec component. 137 * @param type Specifies whether the buffer type is an input type or an output type. 138 * @param mode Specifies whether to use an internal or external buffer mode. 139 * @return Returns <b>0</b> if the setting is successful; returns a non-zero value otherwise. 140 */ 141 int32_t CodecSetPortMode(CODEC_HANDLETYPE handle, DirectionType type, BufferMode mode); 142 143 /** 144 * @brief Sets parameters required by a codec component. 145 * 146 * You should call this function to set parameters after {@link CodecCreate} is called 147 * but before {@link CodecStart} is called. 148 * 149 * @param handle Indicates the handle of the codec component. 150 * @param params Indicates the pointer to the parameters to set in the array. 151 * @param paramCnt Indicates the number of elements in the parameter array. 152 * @return Returns <b>0</b> if the setting is successful; returns a non-zero value otherwise. 153 * @see CodecGetParameter 154 */ 155 int32_t CodecSetParameter(CODEC_HANDLETYPE handle, const Param *params, int paramCnt); 156 157 /** 158 * @brief Obtains parameters from a codec component. 159 * 160 * This function must be called after {@link CodecCreate}. 161 * 162 * @param handle Indicates the handle of the codec component. 163 * @param params Indicates the pointer to the parameters in the array used when the component is created. 164 * @param paramCnt Indicates the number of elements in the parameter array. 165 * @return Returns <b>0</b> if all parameters to obtain are supported; returns a non-zero value otherwise. 166 * @see CodecSetParameter 167 */ 168 int32_t CodecGetParameter(CODEC_HANDLETYPE handle, Param *params, int paramCnt); 169 170 /** 171 * @brief Starts a codec component. 172 * 173 * You can restart a component after it is stopped. 174 * 175 * @param handle Indicates the handle of the codec component. 176 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 177 */ 178 int32_t CodecStart(CODEC_HANDLETYPE handle); 179 180 /** 181 * @brief Stops a codec component. 182 * 183 * @param handle Indicates the handle of the codec component. 184 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 185 */ 186 int32_t CodecStop(CODEC_HANDLETYPE handle); 187 188 /** 189 * @brief Clears the cache when the codec component is the running state. 190 * 191 * Generally, this function is called when the seek operation is performed during playback. 192 * 193 * @param handle Indicates the handle of the codec component. 194 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 195 */ 196 int32_t CodecFlush(CODEC_HANDLETYPE handle, DirectionType directType); 197 198 /** 199 * @brief Queues input data. 200 * 201 * This function works with {@link CodecDequeInput} to implement input data transmission. 202 * 203 * @param handle Indicates the handle of the codec component. 204 * @param inputData Indicates the pointer to the input data. 205 * @param timeoutMs Indicates the timeout duration. 206 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 207 */ 208 int32_t CodecQueueInput(CODEC_HANDLETYPE handle, const InputInfo *inputData, uint32_t timeoutMs); 209 210 /** 211 * @brief Dequeues input data that has been used. 212 * 213 * This function works with {@link CodecQueueInput} to implement input data transmission. 214 * 215 * @param handle Indicates the handle of the codec component. 216 * @param timeoutMs Indicates the timeout duration. Generally, the value is less than or equal to <b>3</b> seconds. 217 * @param inputData Indicates the pointer to the input data that is used. 218 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 219 */ 220 int32_t CodecDequeInput(CODEC_HANDLETYPE handle, uint32_t timeoutMs, InputInfo *inputData); 221 222 /** 223 * @brief Queues output data. 224 * 225 * This function works with {@link CodecDequeueOutput} to implement output data transmission. 226 * 227 * @param handle Indicates the handle of the codec component. 228 * @param outInfo Indicates the pointer to the output data. 229 * @param timeoutMs Indicates the timeout duration. 230 * @param releaseFenceFd Indicates that the descriptor comes from a buffer consumer. 231 * The output data can be used only after waiting for <b>releaseFenceFd</b> is successful. 232 * The value <b>-1</b> indicates that <b>releaseFenceFd</b> is invalid. 233 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 234 */ 235 int32_t CodecQueueOutput(CODEC_HANDLETYPE handle, OutputInfo *outInfo, uint32_t timeoutMs, int releaseFenceFd); 236 237 /** 238 * @brief Dequeues output data. 239 * 240 * This function works with {@link CodecQueueOutput} to implement output data transmission. 241 * 242 * @param handle Indicates the handle of the codec component. 243 * @param timeoutMs Indicates the timeout duration. 244 * @param acquireFd Indicates that this parameter is derived from the codec mode. 245 * The output data can be used only after waiting for <b>acquireFd</b> is successful. 246 * The value <b>-1</b> indicates that <b>acquireFd</b> is invalid. 247 * @param outInfo Indicates the pointer to the output data. 248 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 249 */ 250 int32_t CodecDequeueOutput(CODEC_HANDLETYPE handle, uint32_t timeoutMs, int *acquireFd, OutputInfo *outInfo); 251 252 /** 253 * @brief Sets the callback function. 254 * 255 * The codec uses the callback function to notify the upper layer of events and asynchronously 256 * report available input/output information. 257 * 258 * @param handle Indicates the handle of the codec component. 259 * @param cb Indicates the pointer to the callback function. For details, see {@link CodecCallback}. 260 * @param instance Indicates the upper-layer instance to be notified. 261 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 262 */ 263 int32_t CodecSetCallback(CODEC_HANDLETYPE handle, const CodecCallback *cb, UINTPTR instance); 264 265 #ifdef __cplusplus 266 #if __cplusplus 267 } 268 #endif 269 #endif /* __cplusplus */ 270 271 #endif /* CODEC_INTERFACE_H */ 272 /** @} */