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 47 extern "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 */ 64 struct 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 */ 401 struct 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 */ 408 void CodecComponentTypeRelease(struct CodecComponentType *instance); 409 410 #ifdef __cplusplus 411 } 412 #endif /* __cplusplus */ 413 414 #endif // CODEC_COMPONENT_H