1 /* 2 * Copyright (c) 2008 The Khronos Group Inc. 3 * 4 * Permission is hereby granted, free of charge, to any person obtaining 5 * a copy of this software and associated documentation files (the 6 * "Software"), to deal in the Software without restriction, including 7 * without limitation the rights to use, copy, modify, merge, publish, 8 * distribute, sublicense, and/or sell copies of the Software, and to 9 * permit persons to whom the Software is furnished to do so, subject 10 * to the following conditions: 11 * The above copyright notice and this permission notice shall be included 12 * in all copies or substantial portions of the Software. 13 * 14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 15 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 16 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 17 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 18 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 19 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 20 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 21 * 22 */ 23 24 /** OMX_Core.h - OpenMax IL version 1.1.2 25 * The OMX_Core header file contains the definitions used by both the 26 * application and the component to access common items. 27 */ 28 29 #ifndef OMX_Core_h 30 #define OMX_Core_h 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif /* __cplusplus */ 35 36 37 /* Each OMX header shall include all required header files to allow the 38 * header to compile without errors. The includes below are required 39 * for this header file to compile successfully 40 */ 41 42 #include <OMX_Index.h> 43 44 45 /** The OMX_COMMANDTYPE enumeration is used to specify the action in the 46 * OMX_SendCommand macro. 47 * @ingroup core 48 */ 49 typedef enum OMX_COMMANDTYPE 50 { 51 OMX_CommandStateSet, /**< Change the component state */ 52 OMX_CommandFlush, /**< Flush the data queue(s) of a component */ 53 OMX_CommandPortDisable, /**< Disable a port on a component. */ 54 OMX_CommandPortEnable, /**< Enable a port on a component. */ 55 OMX_CommandMarkBuffer, /**< Mark a component/buffer for observation */ 56 OMX_CommandKhronosExtensions = 0x6F000000, /**< Reserved region for introducing Khronos Standard Extensions */ 57 OMX_CommandVendorStartUnused = 0x7F000000, /**< Reserved region for introducing Vendor Extensions */ 58 OMX_CommandMax = 0X7FFFFFFF 59 } OMX_COMMANDTYPE; 60 61 62 63 /** The OMX_STATETYPE enumeration is used to indicate or change the component 64 * state. This enumeration reflects the current state of the component when 65 * used with the OMX_GetState macro or becomes the parameter in a state change 66 * command when used with the OMX_SendCommand macro. 67 * 68 * The component will be in the Loaded state after the component is initially 69 * loaded into memory. In the Loaded state, the component is not allowed to 70 * allocate or hold resources other than to build it's internal parameter 71 * and configuration tables. The application will send one or more 72 * SetParameters/GetParameters and SetConfig/GetConfig commands to the 73 * component and the component will record each of these parameter and 74 * configuration changes for use later. When the application sends the 75 * Idle command, the component will acquire the resources needed for the 76 * specified configuration and will transition to the idle state if the 77 * allocation is successful. If the component cannot successfully 78 * transition to the idle state for any reason, the state of the component 79 * shall be fully rolled back to the Loaded state (e.g. all allocated 80 * resources shall be released). When the component receives the command 81 * to go to the Executing state, it shall begin processing buffers by 82 * sending all input buffers it holds to the application. While 83 * the component is in the Idle state, the application may also send the 84 * Pause command. If the component receives the pause command while in the 85 * Idle state, the component shall send all input buffers it holds to the 86 * application, but shall not begin processing buffers. This will allow the 87 * application to prefill buffers. 88 * 89 * @ingroup comp 90 */ 91 92 typedef enum OMX_STATETYPE 93 { 94 OMX_StateInvalid, /**< component has detected that it's internal data 95 structures are corrupted to the point that 96 it cannot determine it's state properly */ 97 OMX_StateLoaded, /**< component has been loaded but has not completed 98 initialization. The OMX_SetParameter macro 99 and the OMX_GetParameter macro are the only 100 valid macros allowed to be sent to the 101 component in this state. */ 102 OMX_StateIdle, /**< component initialization has been completed 103 successfully and the component is ready to 104 to start. */ 105 OMX_StateExecuting, /**< component has accepted the start command and 106 is processing data (if data is available) */ 107 OMX_StatePause, /**< component has received pause command */ 108 OMX_StateWaitForResources, /**< component is waiting for resources, either after 109 preemption or before it gets the resources requested. 110 See specification for complete details. */ 111 OMX_StateKhronosExtensions = 0x6F000000, /**< Reserved region for introducing Khronos Standard Extensions */ 112 OMX_StateVendorStartUnused = 0x7F000000, /**< Reserved region for introducing Vendor Extensions */ 113 OMX_StateMax = 0X7FFFFFFF 114 } OMX_STATETYPE; 115 116 /** The OMX_ERRORTYPE enumeration defines the standard OMX Errors. These 117 * errors should cover most of the common failure cases. However, 118 * vendors are free to add additional error messages of their own as 119 * long as they follow these rules: 120 * 1. Vendor error messages shall be in the range of 0x90000000 to 121 * 0x9000FFFF. 122 * 2. Vendor error messages shall be defined in a header file provided 123 * with the component. No error messages are allowed that are 124 * not defined. 125 */ 126 typedef enum OMX_ERRORTYPE 127 { 128 OMX_ErrorNone = 0, 129 130 /** There were insufficient resources to perform the requested operation */ 131 OMX_ErrorInsufficientResources = (OMX_S32) 0x80001000, 132 133 /** There was an error, but the cause of the error could not be determined */ 134 OMX_ErrorUndefined = (OMX_S32) 0x80001001, 135 136 /** The component name string was not valid */ 137 OMX_ErrorInvalidComponentName = (OMX_S32) 0x80001002, 138 139 /** No component with the specified name string was found */ 140 OMX_ErrorComponentNotFound = (OMX_S32) 0x80001003, 141 142 /** The component specified did not have a "OMX_ComponentInit" or 143 "OMX_ComponentDeInit entry point */ 144 OMX_ErrorInvalidComponent = (OMX_S32) 0x80001004, 145 146 /** One or more parameters were not valid */ 147 OMX_ErrorBadParameter = (OMX_S32) 0x80001005, 148 149 /** The requested function is not implemented */ 150 OMX_ErrorNotImplemented = (OMX_S32) 0x80001006, 151 152 /** The buffer was emptied before the next buffer was ready */ 153 OMX_ErrorUnderflow = (OMX_S32) 0x80001007, 154 155 /** The buffer was not available when it was needed */ 156 OMX_ErrorOverflow = (OMX_S32) 0x80001008, 157 158 /** The hardware failed to respond as expected */ 159 OMX_ErrorHardware = (OMX_S32) 0x80001009, 160 161 /** The component is in the state OMX_StateInvalid */ 162 OMX_ErrorInvalidState = (OMX_S32) 0x8000100A, 163 164 /** Stream is found to be corrupt */ 165 OMX_ErrorStreamCorrupt = (OMX_S32) 0x8000100B, 166 167 /** Ports being connected are not compatible */ 168 OMX_ErrorPortsNotCompatible = (OMX_S32) 0x8000100C, 169 170 /** Resources allocated to an idle component have been 171 lost resulting in the component returning to the loaded state */ 172 OMX_ErrorResourcesLost = (OMX_S32) 0x8000100D, 173 174 /** No more indicies can be enumerated */ 175 OMX_ErrorNoMore = (OMX_S32) 0x8000100E, 176 177 /** The component detected a version mismatch */ 178 OMX_ErrorVersionMismatch = (OMX_S32) 0x8000100F, 179 180 /** The component is not ready to return data at this time */ 181 OMX_ErrorNotReady = (OMX_S32) 0x80001010, 182 183 /** There was a timeout that occurred */ 184 OMX_ErrorTimeout = (OMX_S32) 0x80001011, 185 186 /** This error occurs when trying to transition into the state you are already in */ 187 OMX_ErrorSameState = (OMX_S32) 0x80001012, 188 189 /** Resources allocated to an executing or paused component have been 190 preempted, causing the component to return to the idle state */ 191 OMX_ErrorResourcesPreempted = (OMX_S32) 0x80001013, 192 193 /** A non-supplier port sends this error to the IL client (via the EventHandler callback) 194 during the allocation of buffers (on a transition from the LOADED to the IDLE state or 195 on a port restart) when it deems that it has waited an unusually long time for the supplier 196 to send it an allocated buffer via a UseBuffer call. */ 197 OMX_ErrorPortUnresponsiveDuringAllocation = (OMX_S32) 0x80001014, 198 199 /** A non-supplier port sends this error to the IL client (via the EventHandler callback) 200 during the deallocation of buffers (on a transition from the IDLE to LOADED state or 201 on a port stop) when it deems that it has waited an unusually long time for the supplier 202 to request the deallocation of a buffer header via a FreeBuffer call. */ 203 OMX_ErrorPortUnresponsiveDuringDeallocation = (OMX_S32) 0x80001015, 204 205 /** A supplier port sends this error to the IL client (via the EventHandler callback) 206 during the stopping of a port (either on a transition from the IDLE to LOADED 207 state or a port stop) when it deems that it has waited an unusually long time for 208 the non-supplier to return a buffer via an EmptyThisBuffer or FillThisBuffer call. */ 209 OMX_ErrorPortUnresponsiveDuringStop = (OMX_S32) 0x80001016, 210 211 /** Attempting a state transtion that is not allowed */ 212 OMX_ErrorIncorrectStateTransition = (OMX_S32) 0x80001017, 213 214 /* Attempting a command that is not allowed during the present state. */ 215 OMX_ErrorIncorrectStateOperation = (OMX_S32) 0x80001018, 216 217 /** The values encapsulated in the parameter or config structure are not supported. */ 218 OMX_ErrorUnsupportedSetting = (OMX_S32) 0x80001019, 219 220 /** The parameter or config indicated by the given index is not supported. */ 221 OMX_ErrorUnsupportedIndex = (OMX_S32) 0x8000101A, 222 223 /** The port index supplied is incorrect. */ 224 OMX_ErrorBadPortIndex = (OMX_S32) 0x8000101B, 225 226 /** The port has lost one or more of its buffers and it thus unpopulated. */ 227 OMX_ErrorPortUnpopulated = (OMX_S32) 0x8000101C, 228 229 /** Component suspended due to temporary loss of resources */ 230 OMX_ErrorComponentSuspended = (OMX_S32) 0x8000101D, 231 232 /** Component suspended due to an inability to acquire dynamic resources */ 233 OMX_ErrorDynamicResourcesUnavailable = (OMX_S32) 0x8000101E, 234 235 /** When the macroblock error reporting is enabled the component returns new error 236 for every frame that has errors */ 237 OMX_ErrorMbErrorsInFrame = (OMX_S32) 0x8000101F, 238 239 /** A component reports this error when it cannot parse or determine the format of an input stream. */ 240 OMX_ErrorFormatNotDetected = (OMX_S32) 0x80001020, 241 242 /** The content open operation failed. */ 243 OMX_ErrorContentPipeOpenFailed = (OMX_S32) 0x80001021, 244 245 /** The content creation operation failed. */ 246 OMX_ErrorContentPipeCreationFailed = (OMX_S32) 0x80001022, 247 248 /** Separate table information is being used */ 249 OMX_ErrorSeperateTablesUsed = (OMX_S32) 0x80001023, 250 251 /** Tunneling is unsupported by the component*/ 252 OMX_ErrorTunnelingUnsupported = (OMX_S32) 0x80001024, 253 254 OMX_ErrorKhronosExtensions = (OMX_S32)0x8F000000, /**< Reserved region for introducing Khronos Standard Extensions */ 255 OMX_ErrorVendorStartUnused = (OMX_S32)0x90000000, /**< Reserved region for introducing Vendor Extensions */ 256 OMX_ErrorMax = 0x7FFFFFFF 257 } OMX_ERRORTYPE; 258 259 /** @ingroup core */ 260 typedef OMX_ERRORTYPE (* OMX_COMPONENTINITTYPE)(OMX_IN OMX_HANDLETYPE hComponent); 261 262 /** @ingroup core */ 263 typedef struct OMX_COMPONENTREGISTERTYPE 264 { 265 const char * pName; /* Component name, 128 byte limit (including '\0') applies */ 266 OMX_COMPONENTINITTYPE pInitialize; /* Component instance initialization function */ 267 } OMX_COMPONENTREGISTERTYPE; 268 269 /** @ingroup core */ 270 extern OMX_COMPONENTREGISTERTYPE OMX_ComponentRegistered[]; 271 272 /** @ingroup rpm */ 273 typedef struct OMX_PRIORITYMGMTTYPE { 274 OMX_U32 nSize; /**< size of the structure in bytes */ 275 OMX_VERSIONTYPE nVersion; /**< OMX specification version information */ 276 OMX_U32 nGroupPriority; /**< Priority of the component group */ 277 OMX_U32 nGroupID; /**< ID of the component group */ 278 } OMX_PRIORITYMGMTTYPE; 279 280 /* Component name and Role names are limited to 128 characters including the terminating '\0'. */ 281 #define OMX_MAX_STRINGNAME_SIZE 128 282 283 /** @ingroup comp */ 284 typedef struct OMX_PARAM_COMPONENTROLETYPE { 285 OMX_U32 nSize; /**< size of the structure in bytes */ 286 OMX_VERSIONTYPE nVersion; /**< OMX specification version information */ 287 OMX_U8 cRole[OMX_MAX_STRINGNAME_SIZE]; /**< name of standard component which defines component role */ 288 } OMX_PARAM_COMPONENTROLETYPE; 289 290 /** End of Stream Buffer Flag: 291 * 292 * A component sets EOS when it has no more data to emit on a particular 293 * output port. Thus an output port shall set EOS on the last buffer it 294 * emits. A component's determination of when an output port should 295 * cease sending data is implemenation specific. 296 * @ingroup buf 297 */ 298 299 #define OMX_BUFFERFLAG_EOS 0x00000001 300 301 /** Start Time Buffer Flag: 302 * 303 * The source of a stream (e.g. a demux component) sets the STARTTIME 304 * flag on the buffer that contains the starting timestamp for the 305 * stream. The starting timestamp corresponds to the first data that 306 * should be displayed at startup or after a seek. 307 * The first timestamp of the stream is not necessarily the start time. 308 * For instance, in the case of a seek to a particular video frame, 309 * the target frame may be an interframe. Thus the first buffer of 310 * the stream will be the intra-frame preceding the target frame and 311 * the starttime will occur with the target frame (with any other 312 * required frames required to reconstruct the target intervening). 313 * 314 * The STARTTIME flag is directly associated with the buffer's 315 * timestamp ' thus its association to buffer data and its 316 * propagation is identical to the timestamp's. 317 * 318 * When a Sync Component client receives a buffer with the 319 * STARTTIME flag it shall perform a SetConfig on its sync port 320 * using OMX_ConfigTimeClientStartTime and passing the buffer's 321 * timestamp. 322 * 323 * @ingroup buf 324 */ 325 326 #define OMX_BUFFERFLAG_STARTTIME 0x00000002 327 328 329 330 /** Decode Only Buffer Flag: 331 * 332 * The source of a stream (e.g. a demux component) sets the DECODEONLY 333 * flag on any buffer that should shall be decoded but should not be 334 * displayed. This flag is used, for instance, when a source seeks to 335 * a target interframe that requires the decode of frames preceding the 336 * target to facilitate the target's reconstruction. In this case the 337 * source would emit the frames preceding the target downstream 338 * but mark them as decode only. 339 * 340 * The DECODEONLY is associated with buffer data and propagated in a 341 * manner identical to the buffer timestamp. 342 * 343 * A component that renders data should ignore all buffers with 344 * the DECODEONLY flag set. 345 * 346 * @ingroup buf 347 */ 348 349 #define OMX_BUFFERFLAG_DECODEONLY 0x00000004 350 351 352 /* Data Corrupt Flag: This flag is set when the IL client believes the data in the associated buffer is corrupt 353 * @ingroup buf 354 */ 355 356 #define OMX_BUFFERFLAG_DATACORRUPT 0x00000008 357 358 /* End of Frame: The buffer contains exactly one end of frame and no data 359 * occurs after the end of frame. This flag is an optional hint. The absence 360 * of this flag does not imply the absence of an end of frame within the buffer. 361 * @ingroup buf 362 */ 363 #define OMX_BUFFERFLAG_ENDOFFRAME 0x00000010 364 365 /* Sync Frame Flag: This flag is set when the buffer content contains a coded sync frame ' 366 * a frame that has no dependency on any other frame information 367 * @ingroup buf 368 */ 369 #define OMX_BUFFERFLAG_SYNCFRAME 0x00000020 370 371 /* Extra data present flag: there is extra data appended to the data stream 372 * residing in the buffer 373 * @ingroup buf 374 */ 375 #define OMX_BUFFERFLAG_EXTRADATA 0x00000040 376 377 /** Codec Config Buffer Flag: 378 * OMX_BUFFERFLAG_CODECCONFIG is an optional flag that is set by an 379 * output port when all bytes in the buffer form part or all of a set of 380 * codec specific configuration data. Examples include SPS/PPS nal units 381 * for OMX_VIDEO_CodingAVC or AudioSpecificConfig data for 382 * OMX_AUDIO_CodingAAC. Any component that for a given stream sets 383 * OMX_BUFFERFLAG_CODECCONFIG shall not mix codec configuration bytes 384 * with frame data in the same buffer, and shall send all buffers 385 * containing codec configuration bytes before any buffers containing 386 * frame data that those configurations bytes describe. 387 * If the stream format for a particular codec has a frame specific 388 * header at the start of each frame, for example OMX_AUDIO_CodingMP3 or 389 * OMX_AUDIO_CodingAAC in ADTS mode, then these shall be presented as 390 * normal without setting OMX_BUFFERFLAG_CODECCONFIG. 391 * @ingroup buf 392 */ 393 #define OMX_BUFFERFLAG_CODECCONFIG 0x00000080 394 395 /* 396 * OMX_BUFFERFLAG_READONLY: This flag is set when a component emitting the 397 * buffer on an output port or the IL client wishes to identify the buffer 398 * payload contents to be read-only. An IL client or an input port 399 * shall not alter the contents of the buffer. This flag shall only be 400 * cleared by the originator of the buffer when the buffer is returned. 401 * For tunneled ports, the usage of this flag shall be allowed only if the 402 * components negotiated a read-only tunnel 403 */ 404 #define OMX_BUFFERFLAG_READONLY 0x00000200 405 406 /** @ingroup buf */ 407 typedef struct OMX_BUFFERHEADERTYPE 408 { 409 OMX_U32 nSize; /**< size of the structure in bytes */ 410 OMX_VERSIONTYPE nVersion; /**< OMX specification version information */ 411 OMX_U8* pBuffer; /**< Pointer to actual block of memory 412 that is acting as the buffer */ 413 OMX_U32 nAllocLen; /**< size of the buffer allocated, in bytes */ 414 OMX_U32 nFilledLen; /**< number of bytes currently in the 415 buffer */ 416 OMX_U32 nOffset; /**< start offset of valid data in bytes from 417 the start of the buffer */ 418 OMX_PTR pAppPrivate; /**< pointer to any data the application 419 wants to associate with this buffer */ 420 OMX_PTR pPlatformPrivate; /**< pointer to any data the platform 421 wants to associate with this buffer */ 422 OMX_PTR pInputPortPrivate; /**< pointer to any data the input port 423 wants to associate with this buffer */ 424 OMX_PTR pOutputPortPrivate; /**< pointer to any data the output port 425 wants to associate with this buffer */ 426 OMX_HANDLETYPE hMarkTargetComponent; /**< The component that will generate a 427 mark event upon processing this buffer. */ 428 OMX_PTR pMarkData; /**< Application specific data associated with 429 the mark sent on a mark event to disambiguate 430 this mark from others. */ 431 OMX_U32 nTickCount; /**< Optional entry that the component and 432 application can update with a tick count 433 when they access the component. This 434 value should be in microseconds. Since 435 this is a value relative to an arbitrary 436 starting point, this value cannot be used 437 to determine absolute time. This is an 438 optional entry and not all components 439 will update it.*/ 440 OMX_TICKS nTimeStamp; /**< Timestamp corresponding to the sample 441 starting at the first logical sample 442 boundary in the buffer. Timestamps of 443 successive samples within the buffer may 444 be inferred by adding the duration of the 445 of the preceding buffer to the timestamp 446 of the preceding buffer.*/ 447 OMX_U32 nFlags; /**< buffer specific flags */ 448 OMX_U32 nOutputPortIndex; /**< The index of the output port (if any) using 449 this buffer */ 450 OMX_U32 nInputPortIndex; /**< The index of the input port (if any) using 451 this buffer */ 452 } OMX_BUFFERHEADERTYPE; 453 454 /** The OMX_EXTRADATATYPE enumeration is used to define the 455 * possible extra data payload types. 456 * NB: this enum is binary backwards compatible with the previous 457 * OMX_EXTRADATA_QUANT define. This should be replaced with 458 * OMX_ExtraDataQuantization. 459 */ 460 typedef enum OMX_EXTRADATATYPE 461 { 462 OMX_ExtraDataNone = 0, /**< Indicates that no more extra data sections follow */ 463 OMX_ExtraDataQuantization, /**< The data payload contains quantization data */ 464 OMX_ExtraDataKhronosExtensions = 0x6F000000, /**< Reserved region for introducing Khronos Standard Extensions */ 465 OMX_ExtraDataVendorStartUnused = 0x7F000000, /**< Reserved region for introducing Vendor Extensions */ 466 OMX_ExtraDataMax = 0x7FFFFFFF 467 } OMX_EXTRADATATYPE; 468 469 470 typedef struct OMX_OTHER_EXTRADATATYPE { 471 OMX_U32 nSize; 472 OMX_VERSIONTYPE nVersion; 473 OMX_U32 nPortIndex; 474 OMX_EXTRADATATYPE eType; /* Extra Data type */ 475 OMX_U32 nDataSize; /* Size of the supporting data to follow */ 476 OMX_U8 data[1]; /* Supporting data hint */ 477 } OMX_OTHER_EXTRADATATYPE; 478 479 /** @ingroup comp */ 480 typedef struct OMX_PORT_PARAM_TYPE { 481 OMX_U32 nSize; /**< size of the structure in bytes */ 482 OMX_VERSIONTYPE nVersion; /**< OMX specification version information */ 483 OMX_U32 nPorts; /**< The number of ports for this component */ 484 OMX_U32 nStartPortNumber; /** first port number for this type of port */ 485 } OMX_PORT_PARAM_TYPE; 486 487 /** @ingroup comp */ 488 typedef enum OMX_EVENTTYPE 489 { 490 OMX_EventCmdComplete, /**< component has sucessfully completed a command */ 491 OMX_EventError, /**< component has detected an error condition */ 492 OMX_EventMark, /**< component has detected a buffer mark */ 493 OMX_EventPortSettingsChanged, /**< component is reported a port settings change */ 494 OMX_EventBufferFlag, /**< component has detected an EOS */ 495 OMX_EventResourcesAcquired, /**< component has been granted resources and is 496 automatically starting the state change from 497 OMX_StateWaitForResources to OMX_StateIdle. */ 498 OMX_EventComponentResumed, /**< Component resumed due to reacquisition of resources */ 499 OMX_EventDynamicResourcesAvailable, /**< Component has acquired previously unavailable dynamic resources */ 500 OMX_EventPortFormatDetected, /**< Component has detected a supported format. */ 501 OMX_EventKhronosExtensions = 0x6F000000, /**< Reserved region for introducing Khronos Standard Extensions */ 502 OMX_EventVendorStartUnused = 0x7F000000, /**< Reserved region for introducing Vendor Extensions */ 503 OMX_EventMax = 0x7FFFFFFF 504 } OMX_EVENTTYPE; 505 506 typedef struct OMX_CALLBACKTYPE 507 { 508 /** The EventHandler method is used to notify the application when an 509 event of interest occurs. Events are defined in the OMX_EVENTTYPE 510 enumeration. Please see that enumeration for details of what will 511 be returned for each type of event. Callbacks should not return 512 an error to the component, so if an error occurs, the application 513 shall handle it internally. This is a blocking call. 514 515 The application should return from this call within 5 msec to avoid 516 blocking the component for an excessively long period of time. 517 518 @param hComponent 519 handle of the component to access. This is the component 520 handle returned by the call to the GetHandle function. 521 @param pAppData 522 pointer to an application defined value that was provided in the 523 pAppData parameter to the OMX_GetHandle method for the component. 524 This application defined value is provided so that the application 525 can have a component specific context when receiving the callback. 526 @param eEvent 527 Event that the component wants to notify the application about. 528 @param nData1 529 nData will be the OMX_ERRORTYPE for an error event and will be 530 an OMX_COMMANDTYPE for a command complete event and OMX_INDEXTYPE for a OMX_PortSettingsChanged event. 531 @param nData2 532 nData2 will hold further information related to the event. Can be OMX_STATETYPE for 533 a OMX_CommandStateSet command or port index for a OMX_PortSettingsChanged event. 534 Default value is 0 if not used. ) 535 @param pEventData 536 Pointer to additional event-specific data (see spec for meaning). 537 */ 538 539 OMX_ERRORTYPE (*EventHandler)( 540 OMX_IN OMX_HANDLETYPE hComponent, 541 OMX_IN OMX_PTR pAppData, 542 OMX_IN OMX_EVENTTYPE eEvent, 543 OMX_IN OMX_U32 nData1, 544 OMX_IN OMX_U32 nData2, 545 OMX_IN OMX_PTR pEventData); 546 547 /** The EmptyBufferDone method is used to return emptied buffers from an 548 input port back to the application for reuse. This is a blocking call 549 so the application should not attempt to refill the buffers during this 550 call, but should queue them and refill them in another thread. There 551 is no error return, so the application shall handle any errors generated 552 internally. 553 554 The application should return from this call within 5 msec. 555 556 @param hComponent 557 handle of the component to access. This is the component 558 handle returned by the call to the GetHandle function. 559 @param pAppData 560 pointer to an application defined value that was provided in the 561 pAppData parameter to the OMX_GetHandle method for the component. 562 This application defined value is provided so that the application 563 can have a component specific context when receiving the callback. 564 @param pBuffer 565 pointer to an OMX_BUFFERHEADERTYPE structure allocated with UseBuffer 566 or AllocateBuffer indicating the buffer that was emptied. 567 @ingroup buf 568 */ 569 OMX_ERRORTYPE (*EmptyBufferDone)( 570 OMX_IN OMX_HANDLETYPE hComponent, 571 OMX_IN OMX_PTR pAppData, 572 OMX_IN OMX_BUFFERHEADERTYPE* pBuffer); 573 574 /** The FillBufferDone method is used to return filled buffers from an 575 output port back to the application for emptying and then reuse. 576 This is a blocking call so the application should not attempt to 577 empty the buffers during this call, but should queue the buffers 578 and empty them in another thread. There is no error return, so 579 the application shall handle any errors generated internally. The 580 application shall also update the buffer header to indicate the 581 number of bytes placed into the buffer. 582 583 The application should return from this call within 5 msec. 584 585 @param hComponent 586 handle of the component to access. This is the component 587 handle returned by the call to the GetHandle function. 588 @param pAppData 589 pointer to an application defined value that was provided in the 590 pAppData parameter to the OMX_GetHandle method for the component. 591 This application defined value is provided so that the application 592 can have a component specific context when receiving the callback. 593 @param pBuffer 594 pointer to an OMX_BUFFERHEADERTYPE structure allocated with UseBuffer 595 or AllocateBuffer indicating the buffer that was filled. 596 @ingroup buf 597 */ 598 OMX_ERRORTYPE (*FillBufferDone)( 599 OMX_OUT OMX_HANDLETYPE hComponent, 600 OMX_OUT OMX_PTR pAppData, 601 OMX_OUT OMX_BUFFERHEADERTYPE* pBuffer); 602 603 } OMX_CALLBACKTYPE; 604 605 /** The OMX_BUFFERSUPPLIERTYPE enumeration is used to dictate port supplier 606 preference when tunneling between two ports. 607 @ingroup tun buf 608 */ 609 typedef enum OMX_BUFFERSUPPLIERTYPE 610 { 611 OMX_BufferSupplyUnspecified = 0x0, /**< port supplying the buffers is unspecified, 612 or don't care */ 613 OMX_BufferSupplyInput, /**< input port supplies the buffers */ 614 OMX_BufferSupplyOutput, /**< output port supplies the buffers */ 615 OMX_BufferSupplyKhronosExtensions = 0x6F000000, /**< Reserved region for introducing Khronos Standard Extensions */ 616 OMX_BufferSupplyVendorStartUnused = 0x7F000000, /**< Reserved region for introducing Vendor Extensions */ 617 OMX_BufferSupplyMax = 0x7FFFFFFF 618 } OMX_BUFFERSUPPLIERTYPE; 619 620 621 /** buffer supplier parameter 622 * @ingroup tun 623 */ 624 typedef struct OMX_PARAM_BUFFERSUPPLIERTYPE { 625 OMX_U32 nSize; /**< size of the structure in bytes */ 626 OMX_VERSIONTYPE nVersion; /**< OMX specification version information */ 627 OMX_U32 nPortIndex; /**< port that this structure applies to */ 628 OMX_BUFFERSUPPLIERTYPE eBufferSupplier; /**< buffer supplier */ 629 } OMX_PARAM_BUFFERSUPPLIERTYPE; 630 631 632 /**< indicates that buffers received by an input port of a tunnel 633 may not modify the data in the buffers 634 @ingroup tun 635 */ 636 #define OMX_PORTTUNNELFLAG_READONLY 0x00000001 637 638 639 /** The OMX_TUNNELSETUPTYPE structure is used to pass data from an output 640 port to an input port as part the two ComponentTunnelRequest calls 641 resulting from a OMX_SetupTunnel call from the IL Client. 642 @ingroup tun 643 */ 644 typedef struct OMX_TUNNELSETUPTYPE 645 { 646 OMX_U32 nTunnelFlags; /**< bit flags for tunneling */ 647 OMX_BUFFERSUPPLIERTYPE eSupplier; /**< supplier preference */ 648 } OMX_TUNNELSETUPTYPE; 649 650 /* OMX Component headers is included to enable the core to use 651 macros for functions into the component for OMX release 1.0. 652 Developers should not access any structures or data from within 653 the component header directly */ 654 /* TO BE REMOVED - #include <OMX_Component.h> */ 655 656 /** GetComponentVersion will return information about the component. 657 This is a blocking call. This macro will go directly from the 658 application to the component (via a core macro). The 659 component will return from this call within 5 msec. 660 @param [in] hComponent 661 handle of component to execute the command 662 @param [out] pComponentName 663 pointer to an empty string of length 128 bytes. The component 664 will write its name into this string. The name will be 665 terminated by a single zero byte. The name of a component will 666 be 127 bytes or less to leave room for the trailing zero byte. 667 An example of a valid component name is "OMX.ABC.ChannelMixer\0". 668 @param [out] pComponentVersion 669 pointer to an OMX Version structure that the component will fill 670 in. The component will fill in a value that indicates the 671 component version. NOTE: the component version is NOT the same 672 as the OMX Specification version (found in all structures). The 673 component version is defined by the vendor of the component and 674 its value is entirely up to the component vendor. 675 @param [out] pSpecVersion 676 pointer to an OMX Version structure that the component will fill 677 in. The SpecVersion is the version of the specification that the 678 component was built against. Please note that this value may or 679 may not match the structure's version. For example, if the 680 component was built against the 2.0 specification, but the 681 application (which creates the structure is built against the 682 1.0 specification the versions would be different. 683 @param [out] pComponentUUID 684 pointer to the UUID of the component which will be filled in by 685 the component. The UUID is a unique identifier that is set at 686 RUN time for the component and is unique to each instantion of 687 the component. 688 @return OMX_ERRORTYPE 689 If the command successfully executes, the return code will be 690 OMX_ErrorNone. Otherwise the appropriate OMX error will be returned. 691 @ingroup comp 692 */ 693 #define OMX_GetComponentVersion( \ 694 hComponent, \ 695 pComponentName, \ 696 pComponentVersion, \ 697 pSpecVersion, \ 698 pComponentUUID) \ 699 ((OMX_COMPONENTTYPE*)hComponent)->GetComponentVersion( \ 700 hComponent, \ 701 pComponentName, \ 702 pComponentVersion, \ 703 pSpecVersion, \ 704 pComponentUUID) /* Macro End */ 705 706 707 /** Send a command to the component. This call is a non-blocking call. 708 The component should check the parameters and then queue the command 709 to the component thread to be executed. The component thread shall 710 send the EventHandler() callback at the conclusion of the command. 711 This macro will go directly from the application to the component (via 712 a core macro). The component will return from this call within 5 msec. 713 714 When the command is "OMX_CommandStateSet" the component will queue a 715 state transition to the new state idenfied in nParam. 716 717 When the command is "OMX_CommandFlush", to flush a port's buffer queues, 718 the command will force the component to return all buffers NOT CURRENTLY 719 BEING PROCESSED to the application, in the order in which the buffers 720 were received. 721 722 When the command is "OMX_CommandPortDisable" or 723 "OMX_CommandPortEnable", the component's port (given by the value of 724 nParam) will be stopped or restarted. 725 726 When the command "OMX_CommandMarkBuffer" is used to mark a buffer, the 727 pCmdData will point to a OMX_MARKTYPE structure containing the component 728 handle of the component to examine the buffer chain for the mark. nParam1 729 contains the index of the port on which the buffer mark is applied. 730 731 Specification text for more details. 732 733 @param [in] hComponent 734 handle of component to execute the command 735 @param [in] Cmd 736 Command for the component to execute 737 @param [in] nParam 738 Parameter for the command to be executed. When Cmd has the value 739 OMX_CommandStateSet, value is a member of OMX_STATETYPE. When Cmd has 740 the value OMX_CommandFlush, value of nParam indicates which port(s) 741 to flush. -1 is used to flush all ports a single port index will 742 only flush that port. When Cmd has the value "OMX_CommandPortDisable" 743 or "OMX_CommandPortEnable", the component's port is given by 744 the value of nParam. When Cmd has the value "OMX_CommandMarkBuffer" 745 the components pot is given by the value of nParam. 746 @param [in] pCmdData 747 Parameter pointing to the OMX_MARKTYPE structure when Cmd has the value 748 "OMX_CommandMarkBuffer". 749 @return OMX_ERRORTYPE 750 If the command successfully executes, the return code will be 751 OMX_ErrorNone. Otherwise the appropriate OMX error will be returned. 752 @ingroup comp 753 */ 754 #define OMX_SendCommand( \ 755 hComponent, \ 756 Cmd, \ 757 nParam, \ 758 pCmdData) \ 759 ((OMX_COMPONENTTYPE*)hComponent)->SendCommand( \ 760 hComponent, \ 761 Cmd, \ 762 nParam, \ 763 pCmdData) /* Macro End */ 764 765 766 /** The OMX_GetParameter macro will get one of the current parameter 767 settings from the component. This macro cannot only be invoked when 768 the component is in the OMX_StateInvalid state. The nParamIndex 769 parameter is used to indicate which structure is being requested from 770 the component. The application shall allocate the correct structure 771 and shall fill in the structure size and version information before 772 invoking this macro. When the parameter applies to a port, the 773 caller shall fill in the appropriate nPortIndex value indicating the 774 port on which the parameter applies. If the component has not had 775 any settings changed, then the component should return a set of 776 valid DEFAULT parameters for the component. This is a blocking 777 call. 778 779 The component should return from this call within 20 msec. 780 781 @param [in] hComponent 782 Handle of the component to be accessed. This is the component 783 handle returned by the call to the OMX_GetHandle function. 784 @param [in] nParamIndex 785 Index of the structure to be filled. This value is from the 786 OMX_INDEXTYPE enumeration. 787 @param [in,out] pComponentParameterStructure 788 Pointer to application allocated structure to be filled by the 789 component. 790 @return OMX_ERRORTYPE 791 If the command successfully executes, the return code will be 792 OMX_ErrorNone. Otherwise the appropriate OMX error will be returned. 793 @ingroup comp 794 */ 795 #define OMX_GetParameter( \ 796 hComponent, \ 797 nParamIndex, \ 798 pComponentParameterStructure) \ 799 ((OMX_COMPONENTTYPE*)hComponent)->GetParameter( \ 800 hComponent, \ 801 nParamIndex, \ 802 pComponentParameterStructure) /* Macro End */ 803 804 805 /** The OMX_SetParameter macro will send an initialization parameter 806 structure to a component. Each structure shall be sent one at a time, 807 in a separate invocation of the macro. This macro can only be 808 invoked when the component is in the OMX_StateLoaded state, or the 809 port is disabled (when the parameter applies to a port). The 810 nParamIndex parameter is used to indicate which structure is being 811 passed to the component. The application shall allocate the 812 correct structure and shall fill in the structure size and version 813 information (as well as the actual data) before invoking this macro. 814 The application is free to dispose of this structure after the call 815 as the component is required to copy any data it shall retain. This 816 is a blocking call. 817 818 The component should return from this call within 20 msec. 819 820 @param [in] hComponent 821 Handle of the component to be accessed. This is the component 822 handle returned by the call to the OMX_GetHandle function. 823 @param [in] nIndex 824 Index of the structure to be sent. This value is from the 825 OMX_INDEXTYPE enumeration. 826 @param [in] pComponentParameterStructure 827 pointer to application allocated structure to be used for 828 initialization by the component. 829 @return OMX_ERRORTYPE 830 If the command successfully executes, the return code will be 831 OMX_ErrorNone. Otherwise the appropriate OMX error will be returned. 832 @ingroup comp 833 */ 834 #define OMX_SetParameter( \ 835 hComponent, \ 836 nParamIndex, \ 837 pComponentParameterStructure) \ 838 ((OMX_COMPONENTTYPE*)hComponent)->SetParameter( \ 839 hComponent, \ 840 nParamIndex, \ 841 pComponentParameterStructure) /* Macro End */ 842 843 844 /** The OMX_GetConfig macro will get one of the configuration structures 845 from a component. This macro can be invoked anytime after the 846 component has been loaded. The nParamIndex call parameter is used to 847 indicate which structure is being requested from the component. The 848 application shall allocate the correct structure and shall fill in the 849 structure size and version information before invoking this macro. 850 If the component has not had this configuration parameter sent before, 851 then the component should return a set of valid DEFAULT values for the 852 component. This is a blocking call. 853 854 The component should return from this call within 5 msec. 855 856 @param [in] hComponent 857 Handle of the component to be accessed. This is the component 858 handle returned by the call to the OMX_GetHandle function. 859 @param [in] nIndex 860 Index of the structure to be filled. This value is from the 861 OMX_INDEXTYPE enumeration. 862 @param [in,out] pComponentConfigStructure 863 pointer to application allocated structure to be filled by the 864 component. 865 @return OMX_ERRORTYPE 866 If the command successfully executes, the return code will be 867 OMX_ErrorNone. Otherwise the appropriate OMX error will be returned. 868 @ingroup comp 869 */ 870 #define OMX_GetConfig( \ 871 hComponent, \ 872 nConfigIndex, \ 873 pComponentConfigStructure) \ 874 ((OMX_COMPONENTTYPE*)hComponent)->GetConfig( \ 875 hComponent, \ 876 nConfigIndex, \ 877 pComponentConfigStructure) /* Macro End */ 878 879 880 /** The OMX_SetConfig macro will send one of the configuration 881 structures to a component. Each structure shall be sent one at a time, 882 each in a separate invocation of the macro. This macro can be invoked 883 anytime after the component has been loaded. The application shall 884 allocate the correct structure and shall fill in the structure size 885 and version information (as well as the actual data) before invoking 886 this macro. The application is free to dispose of this structure after 887 the call as the component is required to copy any data it shall retain. 888 This is a blocking call. 889 890 The component should return from this call within 5 msec. 891 892 @param [in] hComponent 893 Handle of the component to be accessed. This is the component 894 handle returned by the call to the OMX_GetHandle function. 895 @param [in] nConfigIndex 896 Index of the structure to be sent. This value is from the 897 OMX_INDEXTYPE enumeration above. 898 @param [in] pComponentConfigStructure 899 pointer to application allocated structure to be used for 900 initialization by the component. 901 @return OMX_ERRORTYPE 902 If the command successfully executes, the return code will be 903 OMX_ErrorNone. Otherwise the appropriate OMX error will be returned. 904 @ingroup comp 905 */ 906 #define OMX_SetConfig( \ 907 hComponent, \ 908 nConfigIndex, \ 909 pComponentConfigStructure) \ 910 ((OMX_COMPONENTTYPE*)hComponent)->SetConfig( \ 911 hComponent, \ 912 nConfigIndex, \ 913 pComponentConfigStructure) /* Macro End */ 914 915 916 /** The OMX_GetExtensionIndex macro will invoke a component to translate 917 a vendor specific configuration or parameter string into an OMX 918 structure index. There is no requirement for the vendor to support 919 this command for the indexes already found in the OMX_INDEXTYPE 920 enumeration (this is done to save space in small components). The 921 component shall support all vendor supplied extension indexes not found 922 in the master OMX_INDEXTYPE enumeration. This is a blocking call. 923 924 The component should return from this call within 5 msec. 925 926 @param [in] hComponent 927 Handle of the component to be accessed. This is the component 928 handle returned by the call to the GetHandle function. 929 @param [in] cParameterName 930 OMX_STRING that shall be less than 128 characters long including 931 the trailing null byte. This is the string that will get 932 translated by the component into a configuration index. 933 @param [out] pIndexType 934 a pointer to a OMX_INDEXTYPE to receive the index value. 935 @return OMX_ERRORTYPE 936 If the command successfully executes, the return code will be 937 OMX_ErrorNone. Otherwise the appropriate OMX error will be returned. 938 @ingroup comp 939 */ 940 #define OMX_GetExtensionIndex( \ 941 hComponent, \ 942 cParameterName, \ 943 pIndexType) \ 944 ((OMX_COMPONENTTYPE*)hComponent)->GetExtensionIndex( \ 945 hComponent, \ 946 cParameterName, \ 947 pIndexType) /* Macro End */ 948 949 950 /** The OMX_GetState macro will invoke the component to get the current 951 state of the component and place the state value into the location 952 pointed to by pState. 953 954 The component should return from this call within 5 msec. 955 956 @param [in] hComponent 957 Handle of the component to be accessed. This is the component 958 handle returned by the call to the OMX_GetHandle function. 959 @param [out] pState 960 pointer to the location to receive the state. The value returned 961 is one of the OMX_STATETYPE members 962 @return OMX_ERRORTYPE 963 If the command successfully executes, the return code will be 964 OMX_ErrorNone. Otherwise the appropriate OMX error will be returned. 965 @ingroup comp 966 */ 967 #define OMX_GetState( \ 968 hComponent, \ 969 pState) \ 970 ((OMX_COMPONENTTYPE*)hComponent)->GetState( \ 971 hComponent, \ 972 pState) /* Macro End */ 973 974 975 /** The OMX_UseBuffer macro will request that the component use 976 a buffer (and allocate its own buffer header) already allocated 977 by another component, or by the IL Client. This is a blocking 978 call. 979 980 The component should return from this call within 20 msec. 981 982 @param [in] hComponent 983 Handle of the component to be accessed. This is the component 984 handle returned by the call to the OMX_GetHandle function. 985 @param [out] ppBuffer 986 pointer to an OMX_BUFFERHEADERTYPE structure used to receive the 987 pointer to the buffer header 988 @return OMX_ERRORTYPE 989 If the command successfully executes, the return code will be 990 OMX_ErrorNone. Otherwise the appropriate OMX error will be returned. 991 @ingroup comp buf 992 */ 993 994 #define OMX_UseBuffer( \ 995 hComponent, \ 996 ppBufferHdr, \ 997 nPortIndex, \ 998 pAppPrivate, \ 999 nSizeBytes, \ 1000 pBuffer) \ 1001 ((OMX_COMPONENTTYPE*)hComponent)->UseBuffer( \ 1002 hComponent, \ 1003 ppBufferHdr, \ 1004 nPortIndex, \ 1005 pAppPrivate, \ 1006 nSizeBytes, \ 1007 pBuffer) 1008 1009 1010 /** The OMX_AllocateBuffer macro will request that the component allocate 1011 a new buffer and buffer header. The component will allocate the 1012 buffer and the buffer header and return a pointer to the buffer 1013 header. This is a blocking call. 1014 1015 The component should return from this call within 5 msec. 1016 1017 @param [in] hComponent 1018 Handle of the component to be accessed. This is the component 1019 handle returned by the call to the OMX_GetHandle function. 1020 @param [out] ppBuffer 1021 pointer to an OMX_BUFFERHEADERTYPE structure used to receive 1022 the pointer to the buffer header 1023 @param [in] nPortIndex 1024 nPortIndex is used to select the port on the component the buffer will 1025 be used with. The port can be found by using the nPortIndex 1026 value as an index into the Port Definition array of the component. 1027 @param [in] pAppPrivate 1028 pAppPrivate is used to initialize the pAppPrivate member of the 1029 buffer header structure. 1030 @param [in] nSizeBytes 1031 size of the buffer to allocate. Used when bAllocateNew is true. 1032 @return OMX_ERRORTYPE 1033 If the command successfully executes, the return code will be 1034 OMX_ErrorNone. Otherwise the appropriate OMX error will be returned. 1035 @ingroup comp buf 1036 */ 1037 #define OMX_AllocateBuffer( \ 1038 hComponent, \ 1039 ppBuffer, \ 1040 nPortIndex, \ 1041 pAppPrivate, \ 1042 nSizeBytes) \ 1043 ((OMX_COMPONENTTYPE*)hComponent)->AllocateBuffer( \ 1044 hComponent, \ 1045 ppBuffer, \ 1046 nPortIndex, \ 1047 pAppPrivate, \ 1048 nSizeBytes) /* Macro End */ 1049 1050 1051 /** The OMX_FreeBuffer macro will release a buffer header from the component 1052 which was allocated using either OMX_AllocateBuffer or OMX_UseBuffer. If 1053 the component allocated the buffer (see the OMX_UseBuffer macro) then 1054 the component shall free the buffer and buffer header. This is a 1055 blocking call. 1056 1057 The component should return from this call within 20 msec. 1058 1059 @param [in] hComponent 1060 Handle of the component to be accessed. This is the component 1061 handle returned by the call to the OMX_GetHandle function. 1062 @param [in] nPortIndex 1063 nPortIndex is used to select the port on the component the buffer will 1064 be used with. 1065 @param [in] pBuffer 1066 pointer to an OMX_BUFFERHEADERTYPE structure allocated with UseBuffer 1067 or AllocateBuffer. 1068 @return OMX_ERRORTYPE 1069 If the command successfully executes, the return code will be 1070 OMX_ErrorNone. Otherwise the appropriate OMX error will be returned. 1071 @ingroup comp buf 1072 */ 1073 #define OMX_FreeBuffer( \ 1074 hComponent, \ 1075 nPortIndex, \ 1076 pBuffer) \ 1077 ((OMX_COMPONENTTYPE*)hComponent)->FreeBuffer( \ 1078 hComponent, \ 1079 nPortIndex, \ 1080 pBuffer) /* Macro End */ 1081 1082 1083 /** The OMX_EmptyThisBuffer macro will send a buffer full of data to an 1084 input port of a component. The buffer will be emptied by the component 1085 and returned to the application via the EmptyBufferDone call back. 1086 This is a non-blocking call in that the component will record the buffer 1087 and return immediately and then empty the buffer, later, at the proper 1088 time. As expected, this macro may be invoked only while the component 1089 is in the OMX_StateExecuting. If nPortIndex does not specify an input 1090 port, the component shall return an error. 1091 1092 The component should return from this call within 5 msec. 1093 1094 @param [in] hComponent 1095 Handle of the component to be accessed. This is the component 1096 handle returned by the call to the OMX_GetHandle function. 1097 @param [in] pBuffer 1098 pointer to an OMX_BUFFERHEADERTYPE structure allocated with UseBuffer 1099 or AllocateBuffer. 1100 @return OMX_ERRORTYPE 1101 If the command successfully executes, the return code will be 1102 OMX_ErrorNone. Otherwise the appropriate OMX error will be returned. 1103 @ingroup comp buf 1104 */ 1105 #define OMX_EmptyThisBuffer( \ 1106 hComponent, \ 1107 pBuffer) \ 1108 ((OMX_COMPONENTTYPE*)hComponent)->EmptyThisBuffer( \ 1109 hComponent, \ 1110 pBuffer) /* Macro End */ 1111 1112 1113 /** The OMX_FillThisBuffer macro will send an empty buffer to an 1114 output port of a component. The buffer will be filled by the component 1115 and returned to the application via the FillBufferDone call back. 1116 This is a non-blocking call in that the component will record the buffer 1117 and return immediately and then fill the buffer, later, at the proper 1118 time. As expected, this macro may be invoked only while the component 1119 is in the OMX_ExecutingState. If nPortIndex does not specify an output 1120 port, the component shall return an error. 1121 1122 The component should return from this call within 5 msec. 1123 1124 @param [in] hComponent 1125 Handle of the component to be accessed. This is the component 1126 handle returned by the call to the OMX_GetHandle function. 1127 @param [in] pBuffer 1128 pointer to an OMX_BUFFERHEADERTYPE structure allocated with UseBuffer 1129 or AllocateBuffer. 1130 @return OMX_ERRORTYPE 1131 If the command successfully executes, the return code will be 1132 OMX_ErrorNone. Otherwise the appropriate OMX error will be returned. 1133 @ingroup comp buf 1134 */ 1135 #define OMX_FillThisBuffer( \ 1136 hComponent, \ 1137 pBuffer) \ 1138 ((OMX_COMPONENTTYPE*)hComponent)->FillThisBuffer( \ 1139 hComponent, \ 1140 pBuffer) /* Macro End */ 1141 1142 1143 1144 /** The OMX_UseEGLImage macro will request that the component use 1145 a EGLImage provided by EGL (and allocate its own buffer header) 1146 This is a blocking call. 1147 1148 The component should return from this call within 20 msec. 1149 1150 @param [in] hComponent 1151 Handle of the component to be accessed. This is the component 1152 handle returned by the call to the OMX_GetHandle function. 1153 @param [out] ppBuffer 1154 pointer to an OMX_BUFFERHEADERTYPE structure used to receive the 1155 pointer to the buffer header. Note that the memory location used 1156 for this buffer is NOT visible to the IL Client. 1157 @param [in] nPortIndex 1158 nPortIndex is used to select the port on the component the buffer will 1159 be used with. The port can be found by using the nPortIndex 1160 value as an index into the Port Definition array of the component. 1161 @param [in] pAppPrivate 1162 pAppPrivate is used to initialize the pAppPrivate member of the 1163 buffer header structure. 1164 @param [in] eglImage 1165 eglImage contains the handle of the EGLImage to use as a buffer on the 1166 specified port. The component is expected to validate properties of 1167 the EGLImage against the configuration of the port to ensure the component 1168 can use the EGLImage as a buffer. 1169 @return OMX_ERRORTYPE 1170 If the command successfully executes, the return code will be 1171 OMX_ErrorNone. Otherwise the appropriate OMX error will be returned. 1172 @ingroup comp buf 1173 */ 1174 #define OMX_UseEGLImage( \ 1175 hComponent, \ 1176 ppBufferHdr, \ 1177 nPortIndex, \ 1178 pAppPrivate, \ 1179 eglImage) \ 1180 ((OMX_COMPONENTTYPE*)hComponent)->UseEGLImage( \ 1181 hComponent, \ 1182 ppBufferHdr, \ 1183 nPortIndex, \ 1184 pAppPrivate, \ 1185 eglImage) 1186 1187 /** The OMX_Init method is used to initialize the OMX core. It shall be the 1188 first call made into OMX and it should only be executed one time without 1189 an interviening OMX_Deinit call. 1190 1191 The core should return from this call within 20 msec. 1192 1193 @return OMX_ERRORTYPE 1194 If the command successfully executes, the return code will be 1195 OMX_ErrorNone. Otherwise the appropriate OMX error will be returned. 1196 @ingroup core 1197 */ 1198 OMX_API OMX_ERRORTYPE OMX_APIENTRY OMX_Init(void); 1199 1200 1201 /** The OMX_Deinit method is used to deinitialize the OMX core. It shall be 1202 the last call made into OMX. In the event that the core determines that 1203 thare are components loaded when this call is made, the core may return 1204 with an error rather than try to unload the components. 1205 1206 The core should return from this call within 20 msec. 1207 1208 @return OMX_ERRORTYPE 1209 If the command successfully executes, the return code will be 1210 OMX_ErrorNone. Otherwise the appropriate OMX error will be returned. 1211 @ingroup core 1212 */ 1213 OMX_API OMX_ERRORTYPE OMX_APIENTRY OMX_Deinit(void); 1214 1215 1216 /** The OMX_ComponentNameEnum method will enumerate through all the names of 1217 recognised valid components in the system. This function is provided 1218 as a means to detect all the components in the system run-time. There is 1219 no strict ordering to the enumeration order of component names, although 1220 each name will only be enumerated once. If the OMX core supports run-time 1221 installation of new components, it is only requried to detect newly 1222 installed components when the first call to enumerate component names 1223 is made (i.e. when nIndex is 0x0). 1224 1225 The core should return from this call in 20 msec. 1226 1227 @param [out] cComponentName 1228 pointer to a null terminated string with the component name. The 1229 names of the components are strings less than 127 bytes in length 1230 plus the trailing null for a maximum size of 128 bytes. An example 1231 of a valid component name is "OMX.TI.AUDIO.DSP.MIXER\0". Names are 1232 assigned by the vendor, but shall start with "OMX." and then have 1233 the Vendor designation next. 1234 @param [in] nNameLength 1235 number of characters in the cComponentName string. With all 1236 component name strings restricted to less than 128 characters 1237 (including the trailing null) it is recomended that the caller 1238 provide a input string for the cComponentName of 128 characters. 1239 @param [in] nIndex 1240 number containing the enumeration index for the component. 1241 Multiple calls to OMX_ComponentNameEnum with increasing values 1242 of nIndex will enumerate through the component names in the 1243 system until OMX_ErrorNoMore is returned. The value of nIndex 1244 is 0 to (N-1), where N is the number of valid installed components 1245 in the system. 1246 @return OMX_ERRORTYPE 1247 If the command successfully executes, the return code will be 1248 OMX_ErrorNone. When the value of nIndex exceeds the number of 1249 components in the system minus 1, OMX_ErrorNoMore will be 1250 returned. Otherwise the appropriate OMX error will be returned. 1251 @ingroup core 1252 */ 1253 OMX_API OMX_ERRORTYPE OMX_APIENTRY OMX_ComponentNameEnum( 1254 OMX_OUT OMX_STRING cComponentName, 1255 OMX_IN OMX_U32 nNameLength, 1256 OMX_IN OMX_U32 nIndex); 1257 1258 1259 /** The OMX_GetHandle method will locate the component specified by the 1260 component name given, load that component into memory and then invoke 1261 the component's methods to create an instance of the component. 1262 1263 The core should return from this call within 20 msec. 1264 1265 @param [out] pHandle 1266 pointer to an OMX_HANDLETYPE pointer to be filled in by this method. 1267 @param [in] cComponentName 1268 pointer to a null terminated string with the component name. The 1269 names of the components are strings less than 127 bytes in length 1270 plus the trailing null for a maximum size of 128 bytes. An example 1271 of a valid component name is "OMX.TI.AUDIO.DSP.MIXER\0". Names are 1272 assigned by the vendor, but shall start with "OMX." and then have 1273 the Vendor designation next. 1274 @param [in] pAppData 1275 pointer to an application defined value that will be returned 1276 during callbacks so that the application can identify the source 1277 of the callback. 1278 @param [in] pCallBacks 1279 pointer to a OMX_CALLBACKTYPE structure that will be passed to the 1280 component to initialize it with. 1281 @return OMX_ERRORTYPE 1282 If the command successfully executes, the return code will be 1283 OMX_ErrorNone. Otherwise the appropriate OMX error will be returned. 1284 @ingroup core 1285 */ 1286 OMX_API OMX_ERRORTYPE OMX_APIENTRY OMX_GetHandle( 1287 OMX_OUT OMX_HANDLETYPE* pHandle, 1288 OMX_IN OMX_STRING cComponentName, 1289 OMX_IN OMX_PTR pAppData, 1290 OMX_IN OMX_CALLBACKTYPE* pCallBacks); 1291 1292 1293 /** The OMX_FreeHandle method will free a handle allocated by the OMX_GetHandle 1294 method. If the component reference count goes to zero, the component will 1295 be unloaded from memory. 1296 1297 The core should return from this call within 20 msec when the component is 1298 in the OMX_StateLoaded state. 1299 1300 @param [in] hComponent 1301 Handle of the component to be accessed. This is the component 1302 handle returned by the call to the GetHandle function. 1303 @return OMX_ERRORTYPE 1304 If the command successfully executes, the return code will be 1305 OMX_ErrorNone. Otherwise the appropriate OMX error will be returned. 1306 @ingroup core 1307 */ 1308 OMX_API OMX_ERRORTYPE OMX_APIENTRY OMX_FreeHandle( 1309 OMX_IN OMX_HANDLETYPE hComponent); 1310 1311 1312 1313 /** The OMX_SetupTunnel method will handle the necessary calls to the components 1314 to setup the specified tunnel the two components. NOTE: This is 1315 an actual method (not a #define macro). This method will make calls into 1316 the component ComponentTunnelRequest method to do the actual tunnel 1317 connection. 1318 1319 The ComponentTunnelRequest method on both components will be called. 1320 This method shall not be called unless the component is in the 1321 OMX_StateLoaded state except when the ports used for the tunnel are 1322 disabled. In this case, the component may be in the OMX_StateExecuting, 1323 OMX_StatePause, or OMX_StateIdle states. 1324 1325 The core should return from this call within 20 msec. 1326 1327 @param [in] hOutput 1328 Handle of the component to be accessed. Also this is the handle 1329 of the component whose port, specified in the nPortOutput parameter 1330 will be used the source for the tunnel. This is the component handle 1331 returned by the call to the OMX_GetHandle function. There is a 1332 requirement that hOutput be the source for the data when 1333 tunelling (i.e. nPortOutput is an output port). If 0x0, the component 1334 specified in hInput will have it's port specified in nPortInput 1335 setup for communication with the application / IL client. 1336 @param [in] nPortOutput 1337 nPortOutput is used to select the source port on component to be 1338 used in the tunnel. 1339 @param [in] hInput 1340 This is the component to setup the tunnel with. This is the handle 1341 of the component whose port, specified in the nPortInput parameter 1342 will be used the destination for the tunnel. This is the component handle 1343 returned by the call to the OMX_GetHandle function. There is a 1344 requirement that hInput be the destination for the data when 1345 tunelling (i.e. nPortInut is an input port). If 0x0, the component 1346 specified in hOutput will have it's port specified in nPortPOutput 1347 setup for communication with the application / IL client. 1348 @param [in] nPortInput 1349 nPortInput is used to select the destination port on component to be 1350 used in the tunnel. 1351 @return OMX_ERRORTYPE 1352 If the command successfully executes, the return code will be 1353 OMX_ErrorNone. Otherwise the appropriate OMX error will be returned. 1354 When OMX_ErrorNotImplemented is returned, one or both components is 1355 a non-interop component and does not support tunneling. 1356 1357 On failure, the ports of both components are setup for communication 1358 with the application / IL Client. 1359 @ingroup core tun 1360 */ 1361 OMX_API OMX_ERRORTYPE OMX_APIENTRY OMX_SetupTunnel( 1362 OMX_IN OMX_HANDLETYPE hOutput, 1363 OMX_IN OMX_U32 nPortOutput, 1364 OMX_IN OMX_HANDLETYPE hInput, 1365 OMX_IN OMX_U32 nPortInput); 1366 1367 /** @ingroup cp */ 1368 OMX_API OMX_ERRORTYPE OMX_GetContentPipe( 1369 OMX_OUT OMX_HANDLETYPE *hPipe, 1370 OMX_IN OMX_STRING szURI); 1371 1372 /** The OMX_GetComponentsOfRole method will return the number of components that support the given 1373 role and (if the compNames field is non-NULL) the names of those components. The call will fail if 1374 an insufficiently sized array of names is supplied. To ensure the array is sufficiently sized the 1375 client should: 1376 * first call this function with the compNames field NULL to determine the number of component names 1377 * second call this function with the compNames field pointing to an array of names allocated 1378 according to the number returned by the first call. 1379 1380 The core should return from this call within 5 msec. 1381 1382 @param [in] role 1383 This is generic standard component name consisting only of component class 1384 name and the type within that class (e.g. 'audio_decoder.aac'). 1385 @param [inout] pNumComps 1386 This is used both as input and output. 1387 1388 If compNames is NULL, the input is ignored and the output specifies how many components support 1389 the given role. 1390 1391 If compNames is not NULL, on input it bounds the size of the input structure and 1392 on output, it specifies the number of components string names listed within the compNames parameter. 1393 @param [inout] compNames 1394 If NULL this field is ignored. If non-NULL this points to an array of 128-byte strings which accepts 1395 a list of the names of all physical components that implement the specified standard component name. 1396 Each name is NULL terminated. numComps indicates the number of names. 1397 @ingroup core 1398 */ 1399 OMX_API OMX_ERRORTYPE OMX_GetComponentsOfRole ( 1400 OMX_IN OMX_STRING role, 1401 OMX_INOUT OMX_U32 *pNumComps, 1402 OMX_INOUT OMX_U8 **compNames); 1403 1404 /** The OMX_GetRolesOfComponent method will return the number of roles supported by the given 1405 component and (if the roles field is non-NULL) the names of those roles. The call will fail if 1406 an insufficiently sized array of names is supplied. To ensure the array is sufficiently sized the 1407 client should: 1408 * first call this function with the roles field NULL to determine the number of role names 1409 * second call this function with the roles field pointing to an array of names allocated 1410 according to the number returned by the first call. 1411 1412 The core should return from this call within 5 msec. 1413 1414 @param [in] compName 1415 This is the name of the component being queried about. 1416 @param [inout] pNumRoles 1417 This is used both as input and output. 1418 1419 If roles is NULL, the input is ignored and the output specifies how many roles the component supports. 1420 1421 If compNames is not NULL, on input it bounds the size of the input structure and 1422 on output, it specifies the number of roles string names listed within the roles parameter. 1423 @param [out] roles 1424 If NULL this field is ignored. If non-NULL this points to an array of 128-byte strings 1425 which accepts a list of the names of all standard components roles implemented on the 1426 specified component name. numComps indicates the number of names. 1427 @ingroup core 1428 */ 1429 OMX_API OMX_ERRORTYPE OMX_GetRolesOfComponent ( 1430 OMX_IN OMX_STRING compName, 1431 OMX_INOUT OMX_U32 *pNumRoles, 1432 OMX_OUT OMX_U8 **roles); 1433 1434 #ifdef __cplusplus 1435 } 1436 #endif /* __cplusplus */ 1437 1438 #endif 1439 /* File EOF */ 1440 1441
