1/*
2 * Copyright (c) 2022 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 APIs related to the Codec module.
21 *
22 * The Codec module provides APIs for initializing the custom data and audio and video codecs,
23 * setting codec parameters, and controlling and transferring data.
24 *
25 * @since 3.1
26 */
27
28/**
29 * @file codec_component_if.h
30 *
31 * @brief Defines the APIs for codec components.
32 *
33 * The APIs can be used to obtain component information, send commands to components, set component parameters,
34 * and control and transfer buffer data.
35 *
36 * @since 3.1
37 */
38
39#ifndef CODEC_COMPONENT_H
40#define CODEC_COMPONENT_H
41
42#include <stdint.h>
43#include "codec_callback_if.h"
44#include "codec_component_type.h"
45
46#ifdef __cplusplus
47extern "C" {
48#endif /* __cplusplus */
49
50#define CODEC_COMPONENT_INTERFACE_DESC "CODEC_HDI_2.0_COMPONENT"
51
52/**
53 * @brief Defines the APIs for codec components.
54 *
55 * The APIs can be used to:
56 * Obtain the component version.
57 * Obtain and set component parameters.
58 * Send a command to a component to obtain the component status.
59 * Set a callback.
60 * Set or release the buffer used by a component.
61 * Process the input and output buffers for encoding and decoding.
62 * For details, see the description of the APIs.
63 */
64struct CodecComponentType {
65    /**
66     * @brief Obtains the version of a codec component.
67     *
68     * @param self Indicates the pointer to the target codec component.
69     * @param verInfo Indicates info of the component. For details, see {@link CompVerInfo}
70     *
71     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
72     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation failed due to invalid parameters.
73     * @return Returns <b>HDF_ERR_INVALID_OBJECT</b> if the operation failed due to invalid objects.
74     * @return Returns <b>HDF_ERR_MALLOC_FAIL</b> if the operation failed due to insufficient memory.
75     */
76    int32_t (*GetComponentVersion)(struct CodecComponentType *self, struct CompVerInfo *verInfo);
77
78    /**
79     * @brief Sends a command to a component.
80     *
81     * If the command is used to set status, a callback will be invoked to return the result. There is no event
82     * reporting for other commands.
83     *
84     * @param self Indicates the pointer to the target codec component.
85     * @param cmd Indicates the command to be executed by the component. For details, see {@link OMX_COMMANDTYPE}.
86     * @param param Indicates the parameters to be carried in the command.
87     * If <b>cmd</b> is <b>OMX_CommandStateSet</b>, see {@link OMX_STATETYPE} for the value of <b>param</b>.
88     * If <b>cmd</b> is <b>OMX_CommandFlush</b>, <b>OMX_CommandPortDisable</b>, <b>OMX_CommandPortEnable</b>,
89     * or <b>OMX_CommandMarkBuffer</b>, <b>param</b> specifies the target port.
90     * @param cmdData Indicates the pointer to <b>OMX_MARKTYPE</b> if <b>cmd</b> is <b>OMX_CommandMarkBuffer</b>.
91     * @param cmdDataLen Indicates the length of <b>cmdData</b>, in bytes.
92     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
93     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation failed due to invalid parameters.
94     * @return Returns <b>HDF_ERR_INVALID_OBJECT</b> if the operation failed due to invalid objects.
95     * @return Returns <b>HDF_ERR_MALLOC_FAIL</b> if the operation failed due to insufficient memory.
96     */
97    int32_t (*SendCommand)(struct CodecComponentType *self, enum OMX_COMMANDTYPE cmd, uint32_t param,
98        int8_t *cmdData, uint32_t cmdDataLen);
99
100    /**
101     * @brief Obtains parameter settings of a component.
102     *
103     * When a component is in a state other than OMX_StateInvalid,
104     * you can call this API to obtain component parameters.
105     *
106     * @param self Indicates the pointer to the target codec component.
107     * @param paramIndex Indicates the index of the structure to fill. For details, see {@link OMX_INDEXTYPE}.
108     * @param paramStruct Indicates the pointer to the structure, allocated by the application,
109     * to be filled by the component.
110     * @param paramStructLen Indicates the length of <b>paramStruct</b>, in bytes.
111     *
112     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
113     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation failed due to invalid parameters.
114     * @return Returns <b>HDF_ERR_INVALID_OBJECT</b> if the operation failed due to invalid objects.
115     * @return Returns <b>HDF_ERR_MALLOC_FAIL</b> if the operation failed due to insufficient memory.
116     */
117    int32_t (*GetParameter)(struct CodecComponentType *self, uint32_t paramIndex, int8_t *paramStruct,
118        uint32_t paramStructLen);
119
120    /**
121     * @brief Sets parameters for a component.
122     *
123     * This API can be used to set component parameters when the component is in the <b>OMX_StateLoaded</b> or
124     * <b>OMX_StateWaitForResources</b> state or the port is disabled.
125     *
126     * @param self Indicates the pointer to the target codec component.
127     * @param index Indicates the index of the structure to set. For details, see {@link OMX_INDEXTYPE}.
128     * @param paramStruct Indicates the pointer to the structure allocated by the application
129     * for component initialization.
130     * @param paramStructLen Indicates the length of <b>paramStruct</b>, in bytes.
131     *
132     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
133     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation failed due to invalid parameters.
134     * @return Returns <b>HDF_ERR_INVALID_OBJECT</b> if the operation failed due to invalid objects.
135     * @return Returns <b>HDF_ERR_MALLOC_FAIL</b> if the operation failed due to insufficient memory.
136     */
137    int32_t (*SetParameter)(struct CodecComponentType *self, uint32_t index, int8_t *paramStruct,
138        uint32_t paramStructLen);
139
140    /**
141     * @brief Obtains the configuration of a component.
142     *
143     * This API can be used to obtain the component configuration after a component is loaded.
144     *
145     * @param self Indicates the pointer to the target codec component.
146     * @param index Indicates the index of the structure to fill. For details, see {@link OMX_INDEXTYPE}.
147     * @param cfgStruct Indicates the pointer to the structure, allocated by the application,
148     * to be filled by the component.
149     * @param cfgStructLen Indicates the length of <b>cfgStruct</b>, in bytes.
150     *
151     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
152     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation failed due to invalid parameters.
153     * @return Returns <b>HDF_ERR_INVALID_OBJECT</b> if the operation failed due to invalid objects.
154     * @return Returns <b>HDF_ERR_MALLOC_FAIL</b> if the operation failed due to insufficient memory.
155     */
156    int32_t (*GetConfig)(struct CodecComponentType *self, uint32_t index, int8_t *cfgStruct, uint32_t cfgStructLen);
157
158    /**
159     * @brief Sets the component parameters.
160     *
161     * This API can be used to set a component after it is loaded.
162     *
163     * @param self Indicates the pointer to the target codec component.
164     * @param index Indicates the index of the structure to set. For details, see {@link OMX_INDEXTYPE}.
165     * @param cfgStruct Indicates the pointer to the structure allocated by the application
166     * for component initialization.
167     * @param cfgStructLen Indicates the length of <b>cfgStruct</b>, in bytes.
168     *
169     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
170     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation failed due to invalid parameters.
171     * @return Returns <b>HDF_ERR_INVALID_OBJECT</b> if the operation failed due to invalid objects.
172     * @return Returns <b>HDF_ERR_MALLOC_FAIL</b> if the operation failed due to insufficient memory.
173     */
174    int32_t (*SetConfig)(struct CodecComponentType *self, uint32_t index, int8_t *cfgStruct, uint32_t cfgStructLen);
175
176    /**
177     * @brief Obtains the extended index of a component based on a given string.
178     *
179     * This API converts an extended string into an Openmax IL structure index.
180     *
181     * @param self Indicates the pointer to the target codec component.
182     * @param paramName Indicates the pointer to the string to be converted.
183     * @param indexType Indicates the pointer to the configuration index converted from the given <b>paramName</b>.
184     * For details, see {@link OMX_INDEXTYPE}.
185     *
186     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
187     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation failed due to invalid parameters.
188     * @return Returns <b>HDF_ERR_INVALID_OBJECT</b> if the operation failed due to invalid objects.
189     * @return Returns <b>HDF_ERR_MALLOC_FAIL</b> if the operation failed due to insufficient memory.
190     */
191    int32_t (*GetExtensionIndex)(struct CodecComponentType *self, const char *paramName, uint32_t *indexType);
192
193    /**
194     * @brief Obtains component status.
195     *
196     * For details about component status, see {@link OMX_STATETYPE}.
197     *
198     * @param self Indicates the pointer to the target codec component.
199     * @param state Indicates the pointer to the status obtained. For more details, see {@link OMX_STATETYPE}.
200     *
201     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
202     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation failed due to invalid parameters.
203     * @return Returns <b>HDF_ERR_INVALID_OBJECT</b> if the operation failed due to invalid objects.
204     * @return Returns <b>HDF_ERR_MALLOC_FAIL</b> if the operation failed due to insufficient memory.
205     */
206    int32_t (*GetState)(struct CodecComponentType *self, enum OMX_STATETYPE *state);
207
208    /**
209     * @brief Sets tunnel communication for a component.
210     *
211     * When a component is in the OMX_StateLoaded state, you can call this API to set tunnel communication
212     * if the component supports tunnel transmission.
213     *
214     * @param self Indicates the pointer to the target codec component.
215     * @param port Indicates the port to set for the component.
216     * @param tunneledComp Indicates the tunnel handle of the component.
217     * @param tunneledPort Indicates the port to be used for tunnel communication.
218     * @param tunnelSetup Indicates the pointer to the tunnel structure set. For details,
219     * see {@link OMX_TUNNELSETUPTYPE}.
220     *
221     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
222     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation failed due to invalid parameters.
223     * @return Returns <b>HDF_ERR_INVALID_OBJECT</b> if the operation failed due to invalid objects.
224     * @return Returns <b>HDF_ERR_MALLOC_FAIL</b> if the operation failed due to insufficient memory.
225     */
226    int32_t (*ComponentTunnelRequest)(struct CodecComponentType *self, uint32_t port,
227        int32_t tunneledComp, uint32_t tunneledPort, struct OMX_TUNNELSETUPTYPE *tunnelSetup);
228
229    /**
230     * @brief Specify the buffer of the component port.
231     *
232     * This API is used when:
233     * The component is in the OMX_StateLoaded state, and has sent a request for changing the state to OMX_StateIdle.
234     * The component is in the OMX_StateWaitForResources state, the required resources are available,
235     * and the component is ready to enter the OMX_StateIdle state.
236     * The component is in the OMX_StateExecuting, OMX_StatePause, or OMX_StateIdle state on a disabled port.
237     *
238     * @param self Indicates the pointer to the target codec component.
239     * @param portIndex Indicates the port of the component.
240     * @param buffer Indicates the pointer to the buffer to use. For details, see {@link OmxCodecBuffer}.
241     *
242     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
243     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation failed due to invalid parameters.
244     * @return Returns <b>HDF_ERR_INVALID_OBJECT</b> if the operation failed due to invalid objects.
245     * @return Returns <b>HDF_ERR_MALLOC_FAIL</b> if the operation failed due to insufficient memory.
246     */
247    int32_t (*UseBuffer)(struct CodecComponentType *self, uint32_t portIndex, struct OmxCodecBuffer *buffer);
248
249    /**
250     * @brief Requests a port buffer from the component.
251     *
252     * This API is used to request a new buffer from a component when:
253     * The component is in the OMX_StateLoaded state and has sent a request for changing the state to OMX_StateIdle.
254     * The component is in the OMX_StateWaitForResources state, the required resources are available,
255     * and the component is ready to enter the OMX_StateIdle state.
256     * The component is in the OMX_StateExecuting, OMX_StatePause, or OMX_StateIdle state on a disabled port.
257     *
258     * @param self Indicates the pointer to the target codec component.
259     * @param portIndex Indicates the port of the component.
260     * @param buffer Indicates the pointer to the buffer requested. For details, see {@link OmxCodecBuffer}.
261     *
262     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
263     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation failed due to invalid parameters.
264     * @return Returns <b>HDF_ERR_INVALID_OBJECT</b> if the operation failed due to invalid objects.
265     * @return Returns <b>HDF_ERR_MALLOC_FAIL</b> if the operation failed due to insufficient memory.
266     */
267    int32_t (*AllocateBuffer)(struct CodecComponentType *self, uint32_t portIndex, struct OmxCodecBuffer *buffer);
268
269    /**
270     * @brief Releases a buffer.
271     *
272     * This API is used to release a buffer when:
273     * The component is in the OMX_StateIdle state and has sent a request for changing the state to OMX_StateLoaded.
274     * The component is in the OMX_StateExecuting, OMX_StatePause, or OMX_StateIdle state on a disabled port.
275     * This API can be called at any time. However, if it is not called in any of the previous conditions,
276     * the component may report an OMX_ErrorPortUnpopulated event.
277     *
278     * @param self Indicates the pointer to the target codec component.
279     * @param portIndex Indicates the port of the component.
280     * @param buffer Indicates the pointer to the buffer to release. For details, see {@link OmxCodecBuffer}.
281     *
282     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
283     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation failed due to invalid parameters.
284     * @return Returns <b>HDF_ERR_INVALID_OBJECT</b> if the operation failed due to invalid objects.
285     * @return Returns <b>HDF_ERR_MALLOC_FAIL</b> if the operation failed due to insufficient memory.
286     */
287    int32_t (*FreeBuffer)(struct CodecComponentType *self, uint32_t portIndex, const struct OmxCodecBuffer *buffer);
288
289    /**
290     * @brief Specify the buffer to be emptied by a component.
291     *
292     * This API should be called when the component is in the OMX_StateExecuting or OMX_StatePause state.
293     *
294     * @param self Indicates the pointer to the target codec component.
295     * @param buffer Indicates the pointer to the {@link OmxCodecBuffer} structure.
296     *
297     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
298     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation failed due to invalid parameters.
299     * @return Returns <b>HDF_ERR_INVALID_OBJECT</b> if the operation failed due to invalid objects.
300     * @return Returns <b>HDF_ERR_MALLOC_FAIL</b> if the operation failed due to insufficient memory.
301     */
302    int32_t (*EmptyThisBuffer)(struct CodecComponentType *self, const struct OmxCodecBuffer *buffer);
303
304    /**
305     * @brief Specify the buffer to be filled with the encoding and decoding output by a component.
306     *
307     * This API should be called when the component is in the OMX_StateExecuting or OMX_StatePause state.
308     *
309     * @param self Indicates the pointer to the target codec component.
310     * @param buffer Indicates the pointer to the {@link OmxCodecBuffer} structure.
311     *
312     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
313     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation failed due to invalid parameters.
314     * @return Returns <b>HDF_ERR_INVALID_OBJECT</b> if the operation failed due to invalid objects.
315     * @return Returns <b>HDF_ERR_MALLOC_FAIL</b> if the operation failed due to insufficient memory.
316     */
317    int32_t (*FillThisBuffer)(struct CodecComponentType *self, const struct OmxCodecBuffer *buffer);
318
319    /**
320     * @brief Set a callback for the codec component.
321     *
322     * This API is called to report an event or report available input or output information when the component
323     * is in the OMX_StateLoaded state.
324     *
325     * @param self Indicates the pointer to the target codec component.
326     * @param callback Indicates the pointer to the {@link CodecCallbackType} object.
327     * @param appData Indicates the pointer to the value defined by the application.
328     * The value is returned by the callback.
329     *
330     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
331     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation failed due to invalid parameters.
332     * @return Returns <b>HDF_ERR_INVALID_OBJECT</b> if the operation failed due to invalid objects.
333     * @return Returns <b>HDF_ERR_MALLOC_FAIL</b> if the operation failed due to insufficient memory.
334     */
335    int32_t (*SetCallbacks)(struct CodecComponentType *self, struct CodecCallbackType *callback, int64_t appData);
336
337    /**
338     * @brief Deinitializes a component.
339     *
340     * This API can be called to close a component in the OMX_StateLoaded state.
341     *
342     * @param self Indicates the pointer to the codec component to close.
343     *
344     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
345     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation failed due to invalid parameters.
346     * @return Returns <b>HDF_ERR_INVALID_OBJECT</b> if the operation failed due to invalid objects.
347     * @return Returns <b>HDF_ERR_MALLOC_FAIL</b> if the operation failed due to insufficient memory.
348     */
349    int32_t (*ComponentDeInit)(struct CodecComponentType *self);
350
351    /**
352     * @brief Uses the space allocated by EGL.
353     *
354     * This API is used when:
355     * The component is in the OMX_StateLoaded state and has sent a request for changing the state to OMX_StateIdle.
356     * The component is in the OMX_StateWaitForResources state, the required resources are available,
357     * and the component is ready to enter the OMX_StateIdle state.
358     * The component is in the OMX_StateExecuting, OMX_StatePause, or OMX_StateIdle state on a disabled port.
359     *
360     * @param self Indicates the pointer to the target codec component.
361     * @param buffer Indicates the pointer to the {@link OmxCodecBuffer} structure.
362     * @param portIndex Indicates the port of the component.
363     * @param eglImage Indicates the pointer to the image provided by EGL.
364     * @param eglImageLen Indicates the length of <b>eglImage</b>, in bytes.
365     *
366     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
367     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation failed due to invalid parameters.
368     * @return Returns <b>HDF_ERR_INVALID_OBJECT</b> if the operation failed due to invalid objects.
369     * @return Returns <b>HDF_ERR_MALLOC_FAIL</b> if the operation failed due to insufficient memory.
370     */
371    int32_t (*UseEglImage)(struct CodecComponentType *self, struct OmxCodecBuffer *buffer, uint32_t portIndex,
372        int8_t *eglImage, uint32_t eglImageLen);
373
374    /**
375     * @brief Obtains the component role.
376     *
377     * This API is used to obtain the role of a component based on the role index.
378     *
379     * @param self Indicates the pointer to the target codec component.
380     * @param role Indicates the pointer to the role name.
381     * @param roleLen Indicates the length of the role, in bytes.
382     * @param index Indicates the index of a role. A component may support multiple roles.
383     *
384     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
385     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation failed due to invalid parameters.
386     * @return Returns <b>HDF_ERR_INVALID_OBJECT</b> if the operation failed due to invalid objects.
387     * @return Returns <b>HDF_ERR_MALLOC_FAIL</b> if the operation failed due to insufficient memory.
388     */
389    int32_t (*ComponentRoleEnum)(struct CodecComponentType *self, uint8_t *role, uint32_t roleLen, uint32_t index);
390
391    struct HdfRemoteService *(*AsObject)(struct CodecComponentType *self);
392};
393
394/**
395 * @brief Instantiates a <b>CodecComponentType</b> object.
396 *
397 * @param remote Indicates the pointer to the <b>RemoteService</b>.
398 *
399 * @return Returns the <b>CodecComponentType</b> object instantiated.
400 */
401struct CodecComponentType *CodecComponentTypeGet(struct HdfRemoteService *remote);
402
403/**
404 * @brief Releases a <b>CodecComponentType</b> object.
405 *
406 * @param instance Indicates the pointer to the <b>CodecComponentType</b> object to release.
407 */
408void CodecComponentTypeRelease(struct CodecComponentType *instance);
409
410#ifdef __cplusplus
411}
412#endif /* __cplusplus */
413
414#endif // CODEC_COMPONENT_H