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