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