/* * Copyright (c) 2022 Huawei Device Co., Ltd. * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** * @addtogroup Codec * @{ * * @brief Defines APIs related to the Codec module. * * The Codec module provides APIs for initializing the custom data and audio and video codecs, * setting codec parameters, and controlling and transferring data. * * @since 3.1 */ /** * @file codec_component_if.h * * @brief Defines the APIs for codec components. * * The APIs can be used to obtain component information, send commands to components, set component parameters, * and control and transfer buffer data. * * @since 3.1 */ #ifndef CODEC_COMPONENT_H #define CODEC_COMPONENT_H #include #include "codec_callback_if.h" #include "codec_component_type.h" #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ #define CODEC_COMPONENT_INTERFACE_DESC "CODEC_HDI_2.0_COMPONENT" /** * @brief Defines the APIs for codec components. * * The APIs can be used to: * Obtain the component version. * Obtain and set component parameters. * Send a command to a component to obtain the component status. * Set a callback. * Set or release the buffer used by a component. * Process the input and output buffers for encoding and decoding. * For details, see the description of the APIs. */ struct CodecComponentType { /** * @brief Obtains the version of a codec component. * * @param self Indicates the pointer to the target codec component. * @param verInfo Indicates info of the component. For details, see {@link CompVerInfo} * * @return Returns HDF_SUCCESS if the operation is successful. * @return Returns HDF_ERR_INVALID_PARAM if the operation failed due to invalid parameters. * @return Returns HDF_ERR_INVALID_OBJECT if the operation failed due to invalid objects. * @return Returns HDF_ERR_MALLOC_FAIL if the operation failed due to insufficient memory. */ int32_t (*GetComponentVersion)(struct CodecComponentType *self, struct CompVerInfo *verInfo); /** * @brief Sends a command to a component. * * If the command is used to set status, a callback will be invoked to return the result. There is no event * reporting for other commands. * * @param self Indicates the pointer to the target codec component. * @param cmd Indicates the command to be executed by the component. For details, see {@link OMX_COMMANDTYPE}. * @param param Indicates the parameters to be carried in the command. * If cmd is OMX_CommandStateSet, see {@link OMX_STATETYPE} for the value of param. * If cmd is OMX_CommandFlush, OMX_CommandPortDisable, OMX_CommandPortEnable, * or OMX_CommandMarkBuffer, param specifies the target port. * @param cmdData Indicates the pointer to OMX_MARKTYPE if cmd is OMX_CommandMarkBuffer. * @param cmdDataLen Indicates the length of cmdData, in bytes. * @return Returns HDF_SUCCESS if the operation is successful. * @return Returns HDF_ERR_INVALID_PARAM if the operation failed due to invalid parameters. * @return Returns HDF_ERR_INVALID_OBJECT if the operation failed due to invalid objects. * @return Returns HDF_ERR_MALLOC_FAIL if the operation failed due to insufficient memory. */ int32_t (*SendCommand)(struct CodecComponentType *self, enum OMX_COMMANDTYPE cmd, uint32_t param, int8_t *cmdData, uint32_t cmdDataLen); /** * @brief Obtains parameter settings of a component. * * When a component is in a state other than OMX_StateInvalid, * you can call this API to obtain component parameters. * * @param self Indicates the pointer to the target codec component. * @param paramIndex Indicates the index of the structure to fill. For details, see {@link OMX_INDEXTYPE}. * @param paramStruct Indicates the pointer to the structure, allocated by the application, * to be filled by the component. * @param paramStructLen Indicates the length of paramStruct, in bytes. * * @return Returns HDF_SUCCESS if the operation is successful. * @return Returns HDF_ERR_INVALID_PARAM if the operation failed due to invalid parameters. * @return Returns HDF_ERR_INVALID_OBJECT if the operation failed due to invalid objects. * @return Returns HDF_ERR_MALLOC_FAIL if the operation failed due to insufficient memory. */ int32_t (*GetParameter)(struct CodecComponentType *self, uint32_t paramIndex, int8_t *paramStruct, uint32_t paramStructLen); /** * @brief Sets parameters for a component. * * This API can be used to set component parameters when the component is in the OMX_StateLoaded or * OMX_StateWaitForResources state or the port is disabled. * * @param self Indicates the pointer to the target codec component. * @param index Indicates the index of the structure to set. For details, see {@link OMX_INDEXTYPE}. * @param paramStruct Indicates the pointer to the structure allocated by the application * for component initialization. * @param paramStructLen Indicates the length of paramStruct, in bytes. * * @return Returns HDF_SUCCESS if the operation is successful. * @return Returns HDF_ERR_INVALID_PARAM if the operation failed due to invalid parameters. * @return Returns HDF_ERR_INVALID_OBJECT if the operation failed due to invalid objects. * @return Returns HDF_ERR_MALLOC_FAIL if the operation failed due to insufficient memory. */ int32_t (*SetParameter)(struct CodecComponentType *self, uint32_t index, int8_t *paramStruct, uint32_t paramStructLen); /** * @brief Obtains the configuration of a component. * * This API can be used to obtain the component configuration after a component is loaded. * * @param self Indicates the pointer to the target codec component. * @param index Indicates the index of the structure to fill. For details, see {@link OMX_INDEXTYPE}. * @param cfgStruct Indicates the pointer to the structure, allocated by the application, * to be filled by the component. * @param cfgStructLen Indicates the length of cfgStruct, in bytes. * * @return Returns HDF_SUCCESS if the operation is successful. * @return Returns HDF_ERR_INVALID_PARAM if the operation failed due to invalid parameters. * @return Returns HDF_ERR_INVALID_OBJECT if the operation failed due to invalid objects. * @return Returns HDF_ERR_MALLOC_FAIL if the operation failed due to insufficient memory. */ int32_t (*GetConfig)(struct CodecComponentType *self, uint32_t index, int8_t *cfgStruct, uint32_t cfgStructLen); /** * @brief Sets the component parameters. * * This API can be used to set a component after it is loaded. * * @param self Indicates the pointer to the target codec component. * @param index Indicates the index of the structure to set. For details, see {@link OMX_INDEXTYPE}. * @param cfgStruct Indicates the pointer to the structure allocated by the application * for component initialization. * @param cfgStructLen Indicates the length of cfgStruct, in bytes. * * @return Returns HDF_SUCCESS if the operation is successful. * @return Returns HDF_ERR_INVALID_PARAM if the operation failed due to invalid parameters. * @return Returns HDF_ERR_INVALID_OBJECT if the operation failed due to invalid objects. * @return Returns HDF_ERR_MALLOC_FAIL if the operation failed due to insufficient memory. */ int32_t (*SetConfig)(struct CodecComponentType *self, uint32_t index, int8_t *cfgStruct, uint32_t cfgStructLen); /** * @brief Obtains the extended index of a component based on a given string. * * This API converts an extended string into an Openmax IL structure index. * * @param self Indicates the pointer to the target codec component. * @param paramName Indicates the pointer to the string to be converted. * @param indexType Indicates the pointer to the configuration index converted from the given paramName. * For details, see {@link OMX_INDEXTYPE}. * * @return Returns HDF_SUCCESS if the operation is successful. * @return Returns HDF_ERR_INVALID_PARAM if the operation failed due to invalid parameters. * @return Returns HDF_ERR_INVALID_OBJECT if the operation failed due to invalid objects. * @return Returns HDF_ERR_MALLOC_FAIL if the operation failed due to insufficient memory. */ int32_t (*GetExtensionIndex)(struct CodecComponentType *self, const char *paramName, uint32_t *indexType); /** * @brief Obtains component status. * * For details about component status, see {@link OMX_STATETYPE}. * * @param self Indicates the pointer to the target codec component. * @param state Indicates the pointer to the status obtained. For more details, see {@link OMX_STATETYPE}. * * @return Returns HDF_SUCCESS if the operation is successful. * @return Returns HDF_ERR_INVALID_PARAM if the operation failed due to invalid parameters. * @return Returns HDF_ERR_INVALID_OBJECT if the operation failed due to invalid objects. * @return Returns HDF_ERR_MALLOC_FAIL if the operation failed due to insufficient memory. */ int32_t (*GetState)(struct CodecComponentType *self, enum OMX_STATETYPE *state); /** * @brief Sets tunnel communication for a component. * * When a component is in the OMX_StateLoaded state, you can call this API to set tunnel communication * if the component supports tunnel transmission. * * @param self Indicates the pointer to the target codec component. * @param port Indicates the port to set for the component. * @param tunneledComp Indicates the tunnel handle of the component. * @param tunneledPort Indicates the port to be used for tunnel communication. * @param tunnelSetup Indicates the pointer to the tunnel structure set. For details, * see {@link OMX_TUNNELSETUPTYPE}. * * @return Returns HDF_SUCCESS if the operation is successful. * @return Returns HDF_ERR_INVALID_PARAM if the operation failed due to invalid parameters. * @return Returns HDF_ERR_INVALID_OBJECT if the operation failed due to invalid objects. * @return Returns HDF_ERR_MALLOC_FAIL if the operation failed due to insufficient memory. */ int32_t (*ComponentTunnelRequest)(struct CodecComponentType *self, uint32_t port, int32_t tunneledComp, uint32_t tunneledPort, struct OMX_TUNNELSETUPTYPE *tunnelSetup); /** * @brief Specify the buffer of the component port. * * This API is used when: * The component is in the OMX_StateLoaded state, and has sent a request for changing the state to OMX_StateIdle. * The component is in the OMX_StateWaitForResources state, the required resources are available, * and the component is ready to enter the OMX_StateIdle state. * The component is in the OMX_StateExecuting, OMX_StatePause, or OMX_StateIdle state on a disabled port. * * @param self Indicates the pointer to the target codec component. * @param portIndex Indicates the port of the component. * @param buffer Indicates the pointer to the buffer to use. For details, see {@link OmxCodecBuffer}. * * @return Returns HDF_SUCCESS if the operation is successful. * @return Returns HDF_ERR_INVALID_PARAM if the operation failed due to invalid parameters. * @return Returns HDF_ERR_INVALID_OBJECT if the operation failed due to invalid objects. * @return Returns HDF_ERR_MALLOC_FAIL if the operation failed due to insufficient memory. */ int32_t (*UseBuffer)(struct CodecComponentType *self, uint32_t portIndex, struct OmxCodecBuffer *buffer); /** * @brief Requests a port buffer from the component. * * This API is used to request a new buffer from a component when: * The component is in the OMX_StateLoaded state and has sent a request for changing the state to OMX_StateIdle. * The component is in the OMX_StateWaitForResources state, the required resources are available, * and the component is ready to enter the OMX_StateIdle state. * The component is in the OMX_StateExecuting, OMX_StatePause, or OMX_StateIdle state on a disabled port. * * @param self Indicates the pointer to the target codec component. * @param portIndex Indicates the port of the component. * @param buffer Indicates the pointer to the buffer requested. For details, see {@link OmxCodecBuffer}. * * @return Returns HDF_SUCCESS if the operation is successful. * @return Returns HDF_ERR_INVALID_PARAM if the operation failed due to invalid parameters. * @return Returns HDF_ERR_INVALID_OBJECT if the operation failed due to invalid objects. * @return Returns HDF_ERR_MALLOC_FAIL if the operation failed due to insufficient memory. */ int32_t (*AllocateBuffer)(struct CodecComponentType *self, uint32_t portIndex, struct OmxCodecBuffer *buffer); /** * @brief Releases a buffer. * * This API is used to release a buffer when: * The component is in the OMX_StateIdle state and has sent a request for changing the state to OMX_StateLoaded. * The component is in the OMX_StateExecuting, OMX_StatePause, or OMX_StateIdle state on a disabled port. * This API can be called at any time. However, if it is not called in any of the previous conditions, * the component may report an OMX_ErrorPortUnpopulated event. * * @param self Indicates the pointer to the target codec component. * @param portIndex Indicates the port of the component. * @param buffer Indicates the pointer to the buffer to release. For details, see {@link OmxCodecBuffer}. * * @return Returns HDF_SUCCESS if the operation is successful. * @return Returns HDF_ERR_INVALID_PARAM if the operation failed due to invalid parameters. * @return Returns HDF_ERR_INVALID_OBJECT if the operation failed due to invalid objects. * @return Returns HDF_ERR_MALLOC_FAIL if the operation failed due to insufficient memory. */ int32_t (*FreeBuffer)(struct CodecComponentType *self, uint32_t portIndex, const struct OmxCodecBuffer *buffer); /** * @brief Specify the buffer to be emptied by a component. * * This API should be called when the component is in the OMX_StateExecuting or OMX_StatePause state. * * @param self Indicates the pointer to the target codec component. * @param buffer Indicates the pointer to the {@link OmxCodecBuffer} structure. * * @return Returns HDF_SUCCESS if the operation is successful. * @return Returns HDF_ERR_INVALID_PARAM if the operation failed due to invalid parameters. * @return Returns HDF_ERR_INVALID_OBJECT if the operation failed due to invalid objects. * @return Returns HDF_ERR_MALLOC_FAIL if the operation failed due to insufficient memory. */ int32_t (*EmptyThisBuffer)(struct CodecComponentType *self, const struct OmxCodecBuffer *buffer); /** * @brief Specify the buffer to be filled with the encoding and decoding output by a component. * * This API should be called when the component is in the OMX_StateExecuting or OMX_StatePause state. * * @param self Indicates the pointer to the target codec component. * @param buffer Indicates the pointer to the {@link OmxCodecBuffer} structure. * * @return Returns HDF_SUCCESS if the operation is successful. * @return Returns HDF_ERR_INVALID_PARAM if the operation failed due to invalid parameters. * @return Returns HDF_ERR_INVALID_OBJECT if the operation failed due to invalid objects. * @return Returns HDF_ERR_MALLOC_FAIL if the operation failed due to insufficient memory. */ int32_t (*FillThisBuffer)(struct CodecComponentType *self, const struct OmxCodecBuffer *buffer); /** * @brief Set a callback for the codec component. * * This API is called to report an event or report available input or output information when the component * is in the OMX_StateLoaded state. * * @param self Indicates the pointer to the target codec component. * @param callback Indicates the pointer to the {@link CodecCallbackType} object. * @param appData Indicates the pointer to the value defined by the application. * The value is returned by the callback. * * @return Returns HDF_SUCCESS if the operation is successful. * @return Returns HDF_ERR_INVALID_PARAM if the operation failed due to invalid parameters. * @return Returns HDF_ERR_INVALID_OBJECT if the operation failed due to invalid objects. * @return Returns HDF_ERR_MALLOC_FAIL if the operation failed due to insufficient memory. */ int32_t (*SetCallbacks)(struct CodecComponentType *self, struct CodecCallbackType *callback, int64_t appData); /** * @brief Deinitializes a component. * * This API can be called to close a component in the OMX_StateLoaded state. * * @param self Indicates the pointer to the codec component to close. * * @return Returns HDF_SUCCESS if the operation is successful. * @return Returns HDF_ERR_INVALID_PARAM if the operation failed due to invalid parameters. * @return Returns HDF_ERR_INVALID_OBJECT if the operation failed due to invalid objects. * @return Returns HDF_ERR_MALLOC_FAIL if the operation failed due to insufficient memory. */ int32_t (*ComponentDeInit)(struct CodecComponentType *self); /** * @brief Uses the space allocated by EGL. * * This API is used when: * The component is in the OMX_StateLoaded state and has sent a request for changing the state to OMX_StateIdle. * The component is in the OMX_StateWaitForResources state, the required resources are available, * and the component is ready to enter the OMX_StateIdle state. * The component is in the OMX_StateExecuting, OMX_StatePause, or OMX_StateIdle state on a disabled port. * * @param self Indicates the pointer to the target codec component. * @param buffer Indicates the pointer to the {@link OmxCodecBuffer} structure. * @param portIndex Indicates the port of the component. * @param eglImage Indicates the pointer to the image provided by EGL. * @param eglImageLen Indicates the length of eglImage, in bytes. * * @return Returns HDF_SUCCESS if the operation is successful. * @return Returns HDF_ERR_INVALID_PARAM if the operation failed due to invalid parameters. * @return Returns HDF_ERR_INVALID_OBJECT if the operation failed due to invalid objects. * @return Returns HDF_ERR_MALLOC_FAIL if the operation failed due to insufficient memory. */ int32_t (*UseEglImage)(struct CodecComponentType *self, struct OmxCodecBuffer *buffer, uint32_t portIndex, int8_t *eglImage, uint32_t eglImageLen); /** * @brief Obtains the component role. * * This API is used to obtain the role of a component based on the role index. * * @param self Indicates the pointer to the target codec component. * @param role Indicates the pointer to the role name. * @param roleLen Indicates the length of the role, in bytes. * @param index Indicates the index of a role. A component may support multiple roles. * * @return Returns HDF_SUCCESS if the operation is successful. * @return Returns HDF_ERR_INVALID_PARAM if the operation failed due to invalid parameters. * @return Returns HDF_ERR_INVALID_OBJECT if the operation failed due to invalid objects. * @return Returns HDF_ERR_MALLOC_FAIL if the operation failed due to insufficient memory. */ int32_t (*ComponentRoleEnum)(struct CodecComponentType *self, uint8_t *role, uint32_t roleLen, uint32_t index); struct HdfRemoteService *(*AsObject)(struct CodecComponentType *self); }; /** * @brief Instantiates a CodecComponentType object. * * @param remote Indicates the pointer to the RemoteService. * * @return Returns the CodecComponentType object instantiated. */ struct CodecComponentType *CodecComponentTypeGet(struct HdfRemoteService *remote); /** * @brief Releases a CodecComponentType object. * * @param instance Indicates the pointer to the CodecComponentType object to release. */ void CodecComponentTypeRelease(struct CodecComponentType *instance); #ifdef __cplusplus } #endif /* __cplusplus */ #endif // CODEC_COMPONENT_H