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
46extern "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 */
58int32_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 */
68int32_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 */
84int32_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 */
103int32_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 */
116int32_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 */
130int32_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 */
139int32_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 */
154int32_t CodecSetPortMode(CODEC_HANDLETYPE handle, DirectionType direct, AllocateBufferMode mode, BufferType type);
155
156int32_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 */
170int32_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 */
183int32_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 */
193int32_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 */
201int32_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 */
209int32_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 */
219int32_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 */
231int32_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 */
243int32_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 */
258int32_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 */
273int32_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 */
286int32_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/** @} */