wearable/omx/headers/OMX_Core.h

   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
 397 /** @ingroup buf */
 398 typedef struct OMX_BUFFERHEADERTYPE
 399 {
 400     OMX_U32 nSize;              /**< size of the structure in bytes */
 401     OMX_VERSIONTYPE nVersion;   /**< OMX specification version information */
 402     OMX_U8* pBuffer;            /**< Pointer to actual block of memory
 403                                      that is acting as the buffer */
 404     OMX_U32 nAllocLen;          /**< size of the buffer allocated, in bytes */
 405     OMX_U32 nFilledLen;         /**< number of bytes currently in the
 406                                      buffer */
 407     OMX_U32 nOffset;            /**< start offset of valid data in bytes from
 408                                      the start of the buffer */
 409     OMX_PTR pAppPrivate;        /**< pointer to any data the application
 410                                      wants to associate with this buffer */
 411     OMX_PTR pPlatformPrivate;   /**< pointer to any data the platform
 412                                      wants to associate with this buffer */
 413     OMX_PTR pInputPortPrivate;  /**< pointer to any data the input port
 414                                      wants to associate with this buffer */
 415     OMX_PTR pOutputPortPrivate; /**< pointer to any data the output port
 416                                      wants to associate with this buffer */
 417     OMX_HANDLETYPE hMarkTargetComponent; /**< The component that will generate a
 418                                               mark event upon processing this buffer. */
 419     OMX_PTR pMarkData;          /**< Application specific data associated with
 420                                      the mark sent on a mark event to disambiguate
 421                                      this mark from others. */
 422     OMX_U32 nTickCount;         /**< Optional entry that the component and
 423                                      application can update with a tick count
 424                                      when they access the component.  This
 425                                      value should be in microseconds.  Since
 426                                      this is a value relative to an arbitrary
 427                                      starting point, this value cannot be used
 428                                      to determine absolute time.  This is an
 429                                      optional entry and not all components
 430                                      will update it.*/
 431  OMX_TICKS nTimeStamp;          /**< Timestamp corresponding to the sample
 432                                      starting at the first logical sample
 433                                      boundary in the buffer. Timestamps of
 434                                      successive samples within the buffer may
 435                                      be inferred by adding the duration of the
 436                                      of the preceding buffer to the timestamp
 437                                      of the preceding buffer.*/
 438   OMX_U32     nFlags;           /**< buffer specific flags */
 439   OMX_U32 nOutputPortIndex;     /**< The index of the output port (if any) using
 440                                      this buffer */
 441   OMX_U32 nInputPortIndex;      /**< The index of the input port (if any) using
 442                                      this buffer */
 443   OMX_U32 output_width;
 444   OMX_U32 output_height;
 445 } OMX_BUFFERHEADERTYPE;
 446
 447 /** The OMX_EXTRADATATYPE enumeration is used to define the
 448  * possible extra data payload types.
 449  * NB: this enum is binary backwards compatible with the previous
 450  * OMX_EXTRADATA_QUANT define.  This should be replaced with
 451  * OMX_ExtraDataQuantization.
 452  */
 453 typedef enum OMX_EXTRADATATYPE
 454 {
 455    OMX_ExtraDataNone = 0,                       /**< Indicates that no more extra data sections follow */
 456    OMX_ExtraDataQuantization,                   /**< The data payload contains quantization data */
 457    OMX_ExtraDataKhronosExtensions = 0x6F000000, /**< Reserved region for introducing Khronos Standard Extensions */
 458    OMX_ExtraDataVendorStartUnused = 0x7F000000, /**< Reserved region for introducing Vendor Extensions */
 459    OMX_ExtraDataMax = 0x7FFFFFFF
 460 } OMX_EXTRADATATYPE;
 461
 462
 463 typedef struct OMX_OTHER_EXTRADATATYPE  {
 464     OMX_U32 nSize;
 465     OMX_VERSIONTYPE nVersion;
 466     OMX_U32 nPortIndex;
 467     OMX_EXTRADATATYPE eType;       /* Extra Data type */
 468     OMX_U32 nDataSize;   /* Size of the supporting data to follow */
 469     OMX_U8  data[1];     /* Supporting data hint  */
 470 } OMX_OTHER_EXTRADATATYPE;
 471
 472 /** @ingroup comp */
 473 typedef struct OMX_PORT_PARAM_TYPE {
 474     OMX_U32 nSize;              /**< size of the structure in bytes */
 475     OMX_VERSIONTYPE nVersion;   /**< OMX specification version information */
 476     OMX_U32 nPorts;             /**< The number of ports for this component */
 477     OMX_U32 nStartPortNumber;   /** first port number for this type of port */
 478 } OMX_PORT_PARAM_TYPE;
 479
 480 /** @ingroup comp */
 481 typedef enum OMX_EVENTTYPE
 482 {
 483     OMX_EventCmdComplete,         /**< component has sucessfully completed a command */
 484     OMX_EventError,               /**< component has detected an error condition */
 485     OMX_EventMark,                /**< component has detected a buffer mark */
 486     OMX_EventPortSettingsChanged, /**< component is reported a port settings change */
 487     OMX_EventBufferFlag,          /**< component has detected an EOS */
 488     OMX_EventResourcesAcquired,   /**< component has been granted resources and is
 489                                        automatically starting the state change from
 490                                        OMX_StateWaitForResources to OMX_StateIdle. */
 491    OMX_EventComponentResumed,     /**< Component resumed due to reacquisition of resources */
 492    OMX_EventDynamicResourcesAvailable, /**< Component has acquired previously unavailable dynamic resources */
 493    OMX_EventPortFormatDetected,      /**< Component has detected a supported format. */
 494    OMX_EventKhronosExtensions = 0x6F000000, /**< Reserved region for introducing Khronos Standard Extensions */
 495    OMX_EventVendorStartUnused = 0x7F000000, /**< Reserved region for introducing Vendor Extensions */
 496    OMX_EventMax = 0x7FFFFFFF
 497 } OMX_EVENTTYPE;
 498
 499 typedef struct OMX_CALLBACKTYPE
 500 {
 501     /** The EventHandler method is used to notify the application when an
 502         event of interest occurs.  Events are defined in the OMX_EVENTTYPE
 503         enumeration.  Please see that enumeration for details of what will
 504         be returned for each type of event. Callbacks should not return
 505         an error to the component, so if an error occurs, the application
 506         shall handle it internally.  This is a blocking call.
 507
 508         The application should return from this call within 5 msec to avoid
 509         blocking the component for an excessively long period of time.
 510
 511         @param hComponent
 512             handle of the component to access.  This is the component
 513             handle returned by the call to the GetHandle function.
 514         @param pAppData
 515             pointer to an application defined value that was provided in the
 516             pAppData parameter to the OMX_GetHandle method for the component.
 517             This application defined value is provided so that the application
 518             can have a component specific context when receiving the callback.
 519         @param eEvent
 520             Event that the component wants to notify the application about.
 521         @param nData1
 522             nData will be the OMX_ERRORTYPE for an error event and will be
 523             an OMX_COMMANDTYPE for a command complete event and OMX_INDEXTYPE for a OMX_PortSettingsChanged event.
 524          @param nData2
 525             nData2 will hold further information related to the event. Can be OMX_STATETYPE for
 526             a OMX_CommandStateSet command or port index for a OMX_PortSettingsChanged event.
 527             Default value is 0 if not used. )
 528         @param pEventData
 529             Pointer to additional event-specific data (see spec for meaning).
 530       */
 531
 532    OMX_ERRORTYPE (*EventHandler)(
 533         OMX_IN OMX_HANDLETYPE hComponent,
 534         OMX_IN OMX_PTR pAppData,
 535         OMX_IN OMX_EVENTTYPE eEvent,
 536         OMX_IN OMX_U32 nData1,
 537         OMX_IN OMX_U32 nData2,
 538         OMX_IN OMX_PTR pEventData);
 539
 540     /** The EmptyBufferDone method is used to return emptied buffers from an
 541         input port back to the application for reuse.  This is a blocking call
 542         so the application should not attempt to refill the buffers during this
 543         call, but should queue them and refill them in another thread.  There
 544         is no error return, so the application shall handle any errors generated
 545         internally.
 546
 547         The application should return from this call within 5 msec.
 548
 549         @param hComponent
 550             handle of the component to access.  This is the component
 551             handle returned by the call to the GetHandle function.
 552         @param pAppData
 553             pointer to an application defined value that was provided in the
 554             pAppData parameter to the OMX_GetHandle method for the component.
 555             This application defined value is provided so that the application
 556             can have a component specific context when receiving the callback.
 557         @param pBuffer
 558             pointer to an OMX_BUFFERHEADERTYPE structure allocated with UseBuffer
 559             or AllocateBuffer indicating the buffer that was emptied.
 560         @ingroup buf
 561      */
 562     OMX_ERRORTYPE (*EmptyBufferDone)(
 563         OMX_IN OMX_HANDLETYPE hComponent,
 564         OMX_IN OMX_PTR pAppData,
 565         OMX_IN OMX_BUFFERHEADERTYPE* pBuffer);
 566
 567     /** The FillBufferDone method is used to return filled buffers from an
 568         output port back to the application for emptying and then reuse.
 569         This is a blocking call so the application should not attempt to
 570         empty the buffers during this call, but should queue the buffers
 571         and empty them in another thread.  There is no error return, so
 572         the application shall handle any errors generated internally.  The
 573         application shall also update the buffer header to indicate the
 574         number of bytes placed into the buffer.
 575
 576         The application should return from this call within 5 msec.
 577
 578         @param hComponent
 579             handle of the component to access.  This is the component
 580             handle returned by the call to the GetHandle function.
 581         @param pAppData
 582             pointer to an application defined value that was provided in the
 583             pAppData parameter to the OMX_GetHandle method for the component.
 584             This application defined value is provided so that the application
 585             can have a component specific context when receiving the callback.
 586         @param pBuffer
 587             pointer to an OMX_BUFFERHEADERTYPE structure allocated with UseBuffer
 588             or AllocateBuffer indicating the buffer that was filled.
 589         @ingroup buf
 590      */
 591     OMX_ERRORTYPE (*FillBufferDone)(
 592         OMX_OUT OMX_HANDLETYPE hComponent,
 593         OMX_OUT OMX_PTR pAppData,
 594         OMX_OUT OMX_BUFFERHEADERTYPE* pBuffer);
 595
 596 } OMX_CALLBACKTYPE;
 597
 598 /** The OMX_BUFFERSUPPLIERTYPE enumeration is used to dictate port supplier
 599     preference when tunneling between two ports.
 600     @ingroup tun buf
 601 */
 602 typedef enum OMX_BUFFERSUPPLIERTYPE
 603 {
 604     OMX_BufferSupplyUnspecified = 0x0, /**< port supplying the buffers is unspecified,
 605                                               or don't care */
 606     OMX_BufferSupplyInput,             /**< input port supplies the buffers */
 607     OMX_BufferSupplyOutput,            /**< output port supplies the buffers */
 608     OMX_BufferSupplyKhronosExtensions = 0x6F000000, /**< Reserved region for introducing Khronos Standard Extensions */
 609     OMX_BufferSupplyVendorStartUnused = 0x7F000000, /**< Reserved region for introducing Vendor Extensions */
 610     OMX_BufferSupplyMax = 0x7FFFFFFF
 611 } OMX_BUFFERSUPPLIERTYPE;
 612
 613
 614 /** buffer supplier parameter
 615  * @ingroup tun
 616  */
 617 typedef struct OMX_PARAM_BUFFERSUPPLIERTYPE {
 618     OMX_U32 nSize; /**< size of the structure in bytes */
 619     OMX_VERSIONTYPE nVersion; /**< OMX specification version information */
 620     OMX_U32 nPortIndex; /**< port that this structure applies to */
 621     OMX_BUFFERSUPPLIERTYPE eBufferSupplier; /**< buffer supplier */
 622 } OMX_PARAM_BUFFERSUPPLIERTYPE;
 623
 624
 625 /**< indicates that buffers received by an input port of a tunnel
 626      may not modify the data in the buffers
 627      @ingroup tun
 628  */
 629 #define OMX_PORTTUNNELFLAG_READONLY 0x00000001
 630
 631
 632 /** The OMX_TUNNELSETUPTYPE structure is used to pass data from an output
 633     port to an input port as part the two ComponentTunnelRequest calls
 634     resulting from a OMX_SetupTunnel call from the IL Client.
 635     @ingroup tun
 636  */
 637 typedef struct OMX_TUNNELSETUPTYPE
 638 {
 639     OMX_U32 nTunnelFlags;             /**< bit flags for tunneling */
 640     OMX_BUFFERSUPPLIERTYPE eSupplier; /**< supplier preference */
 641 } OMX_TUNNELSETUPTYPE;
 642
 643 /* OMX Component headers is included to enable the core to use
 644    macros for functions into the component for OMX release 1.0.
 645    Developers should not access any structures or data from within
 646    the component header directly */
 647 /* TO BE REMOVED - #include <OMX_Component.h> */
 648
 649 /** GetComponentVersion will return information about the component.
 650     This is a blocking call.  This macro will go directly from the
 651     application to the component (via a core macro).  The
 652     component will return from this call within 5 msec.
 653     @param [in] hComponent
 654         handle of component to execute the command
 655     @param [out] pComponentName
 656         pointer to an empty string of length 128 bytes.  The component
 657         will write its name into this string.  The name will be
 658         terminated by a single zero byte.  The name of a component will
 659         be 127 bytes or less to leave room for the trailing zero byte.
 660         An example of a valid component name is "OMX.ABC.ChannelMixer\0".
 661     @param [out] pComponentVersion
 662         pointer to an OMX Version structure that the component will fill
 663         in.  The component will fill in a value that indicates the
 664         component version.  NOTE: the component version is NOT the same
 665         as the OMX Specification version (found in all structures).  The
 666         component version is defined by the vendor of the component and
 667         its value is entirely up to the component vendor.
 668     @param [out] pSpecVersion
 669         pointer to an OMX Version structure that the component will fill
 670         in.  The SpecVersion is the version of the specification that the
 671         component was built against.  Please note that this value may or
 672         may not match the structure's version.  For example, if the
 673         component was built against the 2.0 specification, but the
 674         application (which creates the structure is built against the
 675         1.0 specification the versions would be different.
 676     @param [out] pComponentUUID
 677         pointer to the UUID of the component which will be filled in by
 678         the component.  The UUID is a unique identifier that is set at
 679         RUN time for the component and is unique to each instantion of
 680         the component.
 681     @return OMX_ERRORTYPE
 682         If the command successfully executes, the return code will be
 683         OMX_ErrorNone.  Otherwise the appropriate OMX error will be returned.
 684     @ingroup comp
 685  */
 686 #define OMX_GetComponentVersion(                            \
 687         hComponent,                                         \
 688         pComponentName,                                     \
 689         pComponentVersion,                                  \
 690         pSpecVersion,                                       \
 691         pComponentUUID)                                     \
 692     ((OMX_COMPONENTTYPE*)hComponent)->GetComponentVersion(  \
 693         hComponent,                                         \
 694         pComponentName,                                     \
 695         pComponentVersion,                                  \
 696         pSpecVersion,                                       \
 697         pComponentUUID)                 /* Macro End */
 698
 699
 700 /** Send a command to the component.  This call is a non-blocking call.
 701     The component should check the parameters and then queue the command
 702     to the component thread to be executed.  The component thread shall
 703     send the EventHandler() callback at the conclusion of the command.
 704     This macro will go directly from the application to the component (via
 705     a core macro).  The component will return from this call within 5 msec.
 706
 707     When the command is "OMX_CommandStateSet" the component will queue a
 708     state transition to the new state idenfied in nParam.
 709
 710     When the command is "OMX_CommandFlush", to flush a port's buffer queues,
 711     the command will force the component to return all buffers NOT CURRENTLY
 712     BEING PROCESSED to the application, in the order in which the buffers
 713     were received.
 714
 715     When the command is "OMX_CommandPortDisable" or
 716     "OMX_CommandPortEnable", the component's port (given by the value of
 717     nParam) will be stopped or restarted.
 718
 719     When the command "OMX_CommandMarkBuffer" is used to mark a buffer, the
 720     pCmdData will point to a OMX_MARKTYPE structure containing the component
 721     handle of the component to examine the buffer chain for the mark.  nParam1
 722     contains the index of the port on which the buffer mark is applied.
 723
 724     Specification text for more details.
 725
 726     @param [in] hComponent
 727         handle of component to execute the command
 728     @param [in] Cmd
 729         Command for the component to execute
 730     @param [in] nParam
 731         Parameter for the command to be executed.  When Cmd has the value
 732         OMX_CommandStateSet, value is a member of OMX_STATETYPE.  When Cmd has
 733         the value OMX_CommandFlush, value of nParam indicates which port(s)
 734         to flush. -1 is used to flush all ports a single port index will
 735         only flush that port.  When Cmd has the value "OMX_CommandPortDisable"
 736         or "OMX_CommandPortEnable", the component's port is given by
 737         the value of nParam.  When Cmd has the value "OMX_CommandMarkBuffer"
 738         the components pot is given by the value of nParam.
 739     @param [in] pCmdData
 740         Parameter pointing to the OMX_MARKTYPE structure when Cmd has the value
 741         "OMX_CommandMarkBuffer".
 742     @return OMX_ERRORTYPE
 743         If the command successfully executes, the return code will be
 744         OMX_ErrorNone.  Otherwise the appropriate OMX error will be returned.
 745     @ingroup comp
 746  */
 747 #define OMX_SendCommand(                                    \
 748          hComponent,                                        \
 749          Cmd,                                               \
 750          nParam,                                            \
 751          pCmdData)                                          \
 752      ((OMX_COMPONENTTYPE*)hComponent)->SendCommand(         \
 753          hComponent,                                        \
 754          Cmd,                                               \
 755          nParam,                                            \
 756          pCmdData)                          /* Macro End */
 757
 758
 759 /** The OMX_GetParameter macro will get one of the current parameter
 760     settings from the component.  This macro cannot only be invoked when
 761     the component is in the OMX_StateInvalid state.  The nParamIndex
 762     parameter is used to indicate which structure is being requested from
 763     the component.  The application shall allocate the correct structure
 764     and shall fill in the structure size and version information before
 765     invoking this macro.  When the parameter applies to a port, the
 766     caller shall fill in the appropriate nPortIndex value indicating the
 767     port on which the parameter applies. If the component has not had
 768     any settings changed, then the component should return a set of
 769     valid DEFAULT  parameters for the component.  This is a blocking
 770     call.
 771
 772     The component should return from this call within 20 msec.
 773
 774     @param [in] hComponent
 775         Handle of the component to be accessed.  This is the component
 776         handle returned by the call to the OMX_GetHandle function.
 777     @param [in] nParamIndex
 778         Index of the structure to be filled.  This value is from the
 779         OMX_INDEXTYPE enumeration.
 780     @param [in,out] pComponentParameterStructure
 781         Pointer to application allocated structure to be filled by the
 782         component.
 783     @return OMX_ERRORTYPE
 784         If the command successfully executes, the return code will be
 785         OMX_ErrorNone.  Otherwise the appropriate OMX error will be returned.
 786     @ingroup comp
 787  */
 788 #define OMX_GetParameter(                                   \
 789         hComponent,                                         \
 790         nParamIndex,                                        \
 791         pComponentParameterStructure)                        \
 792     ((OMX_COMPONENTTYPE*)hComponent)->GetParameter(         \
 793         hComponent,                                         \
 794         nParamIndex,                                        \
 795         pComponentParameterStructure)    /* Macro End */
 796
 797
 798 /** The OMX_SetParameter macro will send an initialization parameter
 799     structure to a component.  Each structure shall be sent one at a time,
 800     in a separate invocation of the macro.  This macro can only be
 801     invoked when the component is in the OMX_StateLoaded state, or the
 802     port is disabled (when the parameter applies to a port). The
 803     nParamIndex parameter is used to indicate which structure is being
 804     passed to the component.  The application shall allocate the
 805     correct structure and shall fill in the structure size and version
 806     information (as well as the actual data) before invoking this macro.
 807     The application is free to dispose of this structure after the call
 808     as the component is required to copy any data it shall retain.  This
 809     is a blocking call.
 810
 811     The component should return from this call within 20 msec.
 812
 813     @param [in] hComponent
 814         Handle of the component to be accessed.  This is the component
 815         handle returned by the call to the OMX_GetHandle function.
 816     @param [in] nIndex
 817         Index of the structure to be sent.  This value is from the
 818         OMX_INDEXTYPE enumeration.
 819     @param [in] pComponentParameterStructure
 820         pointer to application allocated structure to be used for
 821         initialization by the component.
 822     @return OMX_ERRORTYPE
 823         If the command successfully executes, the return code will be
 824         OMX_ErrorNone.  Otherwise the appropriate OMX error will be returned.
 825     @ingroup comp
 826  */
 827 #define OMX_SetParameter(                                   \
 828         hComponent,                                         \
 829         nParamIndex,                                        \
 830         pComponentParameterStructure)                        \
 831     ((OMX_COMPONENTTYPE*)hComponent)->SetParameter(         \
 832         hComponent,                                         \
 833         nParamIndex,                                        \
 834         pComponentParameterStructure)    /* Macro End */
 835
 836
 837 /** The OMX_GetConfig macro will get one of the configuration structures
 838     from a component.  This macro can be invoked anytime after the
 839     component has been loaded.  The nParamIndex call parameter is used to
 840     indicate which structure is being requested from the component.  The
 841     application shall allocate the correct structure and shall fill in the
 842     structure size and version information before invoking this macro.
 843     If the component has not had this configuration parameter sent before,
 844     then the component should return a set of valid DEFAULT values for the
 845     component.  This is a blocking call.
 846
 847     The component should return from this call within 5 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] nIndex
 853         Index of the structure to be filled.  This value is from the
 854         OMX_INDEXTYPE enumeration.
 855     @param [in,out] pComponentConfigStructure
 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_GetConfig(                                      \
 864         hComponent,                                         \
 865         nConfigIndex,                                       \
 866         pComponentConfigStructure)                           \
 867     ((OMX_COMPONENTTYPE*)hComponent)->GetConfig(            \
 868         hComponent,                                         \
 869         nConfigIndex,                                       \
 870         pComponentConfigStructure)       /* Macro End */
 871
 872
 873 /** The OMX_SetConfig macro will send one of the configuration
 874     structures to a component.  Each structure shall be sent one at a time,
 875     each in a separate invocation of the macro.  This macro can be invoked
 876     anytime after the component has been loaded.  The application shall
 877     allocate the correct structure and shall fill in the structure size
 878     and version information (as well as the actual data) before invoking
 879     this macro.  The application is free to dispose of this structure after
 880     the call as the component is required to copy any data it shall retain.
 881     This is a blocking call.
 882
 883     The component should return from this call within 5 msec.
 884
 885     @param [in] hComponent
 886         Handle of the component to be accessed.  This is the component
 887         handle returned by the call to the OMX_GetHandle function.
 888     @param [in] nConfigIndex
 889         Index of the structure to be sent.  This value is from the
 890         OMX_INDEXTYPE enumeration above.
 891     @param [in] pComponentConfigStructure
 892         pointer to application allocated structure to be used for
 893         initialization by the component.
 894     @return OMX_ERRORTYPE
 895         If the command successfully executes, the return code will be
 896         OMX_ErrorNone.  Otherwise the appropriate OMX error will be returned.
 897     @ingroup comp
 898  */
 899 #define OMX_SetConfig(                                      \
 900         hComponent,                                         \
 901         nConfigIndex,                                       \
 902         pComponentConfigStructure)                           \
 903     ((OMX_COMPONENTTYPE*)hComponent)->SetConfig(            \
 904         hComponent,                                         \
 905         nConfigIndex,                                       \
 906         pComponentConfigStructure)       /* Macro End */
 907
 908
 909 /** The OMX_GetExtensionIndex macro will invoke a component to translate
 910     a vendor specific configuration or parameter string into an OMX
 911     structure index.  There is no requirement for the vendor to support
 912     this command for the indexes already found in the OMX_INDEXTYPE
 913     enumeration (this is done to save space in small components).  The
 914     component shall support all vendor supplied extension indexes not found
 915     in the master OMX_INDEXTYPE enumeration.  This is a blocking call.
 916
 917     The component should return from this call within 5 msec.
 918
 919     @param [in] hComponent
 920         Handle of the component to be accessed.  This is the component
 921         handle returned by the call to the GetHandle function.
 922     @param [in] cParameterName
 923         OMX_STRING that shall be less than 128 characters long including
 924         the trailing null byte.  This is the string that will get
 925         translated by the component into a configuration index.
 926     @param [out] pIndexType
 927         a pointer to a OMX_INDEXTYPE to receive the index value.
 928     @return OMX_ERRORTYPE
 929         If the command successfully executes, the return code will be
 930         OMX_ErrorNone.  Otherwise the appropriate OMX error will be returned.
 931     @ingroup comp
 932  */
 933 #define OMX_GetExtensionIndex(                              \
 934         hComponent,                                         \
 935         cParameterName,                                     \
 936         pIndexType)                                         \
 937     ((OMX_COMPONENTTYPE*)hComponent)->GetExtensionIndex(    \
 938         hComponent,                                         \
 939         cParameterName,                                     \
 940         pIndexType)                     /* Macro End */
 941
 942
 943 /** The OMX_GetState macro will invoke the component to get the current
 944     state of the component and place the state value into the location
 945     pointed to by pState.
 946
 947     The component should return from this call within 5 msec.
 948
 949     @param [in] hComponent
 950         Handle of the component to be accessed.  This is the component
 951         handle returned by the call to the OMX_GetHandle function.
 952     @param [out] pState
 953         pointer to the location to receive the state.  The value returned
 954         is one of the OMX_STATETYPE members
 955     @return OMX_ERRORTYPE
 956         If the command successfully executes, the return code will be
 957         OMX_ErrorNone.  Otherwise the appropriate OMX error will be returned.
 958     @ingroup comp
 959  */
 960 #define OMX_GetState(                                       \
 961         hComponent,                                         \
 962         pState)                                             \
 963     ((OMX_COMPONENTTYPE*)hComponent)->GetState(             \
 964         hComponent,                                         \
 965         pState)                         /* Macro End */
 966
 967
 968 /** The OMX_UseBuffer macro will request that the component use
 969     a buffer (and allocate its own buffer header) already allocated
 970     by another component, or by the IL Client. This is a blocking
 971     call.
 972
 973     The component should return from this call within 20 msec.
 974
 975     @param [in] hComponent
 976         Handle of the component to be accessed.  This is the component
 977         handle returned by the call to the OMX_GetHandle function.
 978     @param [out] ppBuffer
 979         pointer to an OMX_BUFFERHEADERTYPE structure used to receive the
 980         pointer to the buffer header
 981     @return OMX_ERRORTYPE
 982         If the command successfully executes, the return code will be
 983         OMX_ErrorNone.  Otherwise the appropriate OMX error will be returned.
 984     @ingroup comp buf
 985  */
 986
 987 #define OMX_UseBuffer(                                      \
 988            hComponent,                                      \
 989            ppBufferHdr,                                     \
 990            nPortIndex,                                      \
 991            pAppPrivate,                                     \
 992            nSizeBytes,                                      \
 993            pBuffer)                                         \
 994     ((OMX_COMPONENTTYPE*)hComponent)->UseBuffer(            \
 995            hComponent,                                      \
 996            ppBufferHdr,                                     \
 997            nPortIndex,                                      \
 998            pAppPrivate,                                     \
 999            nSizeBytes,                                      \
1000            pBuffer)
1001
1002
1003 /** The OMX_AllocateBuffer macro will request that the component allocate
1004     a new buffer and buffer header.  The component will allocate the
1005     buffer and the buffer header and return a pointer to the buffer
1006     header.  This is a blocking call.
1007
1008     The component should return from this call within 5 msec.
1009
1010     @param [in] hComponent
1011         Handle of the component to be accessed.  This is the component
1012         handle returned by the call to the OMX_GetHandle function.
1013     @param [out] ppBuffer
1014         pointer to an OMX_BUFFERHEADERTYPE structure used to receive
1015         the pointer to the buffer header
1016     @param [in] nPortIndex
1017         nPortIndex is used to select the port on the component the buffer will
1018         be used with.  The port can be found by using the nPortIndex
1019         value as an index into the Port Definition array of the component.
1020     @param [in] pAppPrivate
1021         pAppPrivate is used to initialize the pAppPrivate member of the
1022         buffer header structure.
1023     @param [in] nSizeBytes
1024         size of the buffer to allocate.  Used when bAllocateNew is true.
1025     @return OMX_ERRORTYPE
1026         If the command successfully executes, the return code will be
1027         OMX_ErrorNone.  Otherwise the appropriate OMX error will be returned.
1028     @ingroup comp buf
1029  */
1030 #define OMX_AllocateBuffer(                                 \
1031         hComponent,                                         \
1032         ppBuffer,                                           \
1033         nPortIndex,                                         \
1034         pAppPrivate,                                        \
1035         nSizeBytes)                                         \
1036     ((OMX_COMPONENTTYPE*)hComponent)->AllocateBuffer(       \
1037         hComponent,                                         \
1038         ppBuffer,                                           \
1039         nPortIndex,                                         \
1040         pAppPrivate,                                        \
1041         nSizeBytes)                     /* Macro End */
1042
1043
1044 /** The OMX_FreeBuffer macro will release a buffer header from the component
1045     which was allocated using either OMX_AllocateBuffer or OMX_UseBuffer. If
1046     the component allocated the buffer (see the OMX_UseBuffer macro) then
1047     the component shall free the buffer and buffer header. This is a
1048     blocking call.
1049
1050     The component should return from this call within 20 msec.
1051
1052     @param [in] hComponent
1053         Handle of the component to be accessed.  This is the component
1054         handle returned by the call to the OMX_GetHandle function.
1055     @param [in] nPortIndex
1056         nPortIndex is used to select the port on the component the buffer will
1057         be used with.
1058     @param [in] pBuffer
1059         pointer to an OMX_BUFFERHEADERTYPE structure allocated with UseBuffer
1060         or AllocateBuffer.
1061     @return OMX_ERRORTYPE
1062         If the command successfully executes, the return code will be
1063         OMX_ErrorNone.  Otherwise the appropriate OMX error will be returned.
1064     @ingroup comp buf
1065  */
1066 #define OMX_FreeBuffer(                                     \
1067         hComponent,                                         \
1068         nPortIndex,                                         \
1069         pBuffer)                                            \
1070     ((OMX_COMPONENTTYPE*)hComponent)->FreeBuffer(           \
1071         hComponent,                                         \
1072         nPortIndex,                                         \
1073         pBuffer)                        /* Macro End */
1074
1075
1076 /** The OMX_EmptyThisBuffer macro will send a buffer full of data to an
1077     input port of a component.  The buffer will be emptied by the component
1078     and returned to the application via the EmptyBufferDone call back.
1079     This is a non-blocking call in that the component will record the buffer
1080     and return immediately and then empty the buffer, later, at the proper
1081     time.  As expected, this macro may be invoked only while the component
1082     is in the OMX_StateExecuting.  If nPortIndex does not specify an input
1083     port, the component shall return an error.
1084
1085     The component should return from this call within 5 msec.
1086
1087     @param [in] hComponent
1088         Handle of the component to be accessed.  This is the component
1089         handle returned by the call to the OMX_GetHandle function.
1090     @param [in] pBuffer
1091         pointer to an OMX_BUFFERHEADERTYPE structure allocated with UseBuffer
1092         or AllocateBuffer.
1093     @return OMX_ERRORTYPE
1094         If the command successfully executes, the return code will be
1095         OMX_ErrorNone.  Otherwise the appropriate OMX error will be returned.
1096     @ingroup comp buf
1097  */
1098 #define OMX_EmptyThisBuffer(                                \
1099         hComponent,                                         \
1100         pBuffer)                                            \
1101     ((OMX_COMPONENTTYPE*)hComponent)->EmptyThisBuffer(      \
1102         hComponent,                                         \
1103         pBuffer)                        /* Macro End */
1104
1105
1106 /** The OMX_FillThisBuffer macro will send an empty buffer to an
1107     output port of a component.  The buffer will be filled by the component
1108     and returned to the application via the FillBufferDone call back.
1109     This is a non-blocking call in that the component will record the buffer
1110     and return immediately and then fill the buffer, later, at the proper
1111     time.  As expected, this macro may be invoked only while the component
1112     is in the OMX_ExecutingState.  If nPortIndex does not specify an output
1113     port, the component shall return an error.
1114
1115     The component should return from this call within 5 msec.
1116
1117     @param [in] hComponent
1118         Handle of the component to be accessed.  This is the component
1119         handle returned by the call to the OMX_GetHandle function.
1120     @param [in] pBuffer
1121         pointer to an OMX_BUFFERHEADERTYPE structure allocated with UseBuffer
1122         or AllocateBuffer.
1123     @return OMX_ERRORTYPE
1124         If the command successfully executes, the return code will be
1125         OMX_ErrorNone.  Otherwise the appropriate OMX error will be returned.
1126     @ingroup comp buf
1127  */
1128 #define OMX_FillThisBuffer(                                 \
1129         hComponent,                                         \
1130         pBuffer)                                            \
1131     ((OMX_COMPONENTTYPE*)hComponent)->FillThisBuffer(       \
1132         hComponent,                                         \
1133         pBuffer)                        /* Macro End */
1134
1135
1136
1137 /** The OMX_UseEGLImage macro will request that the component use
1138     a EGLImage provided by EGL (and allocate its own buffer header)
1139     This is a blocking call.
1140
1141     The component should return from this call within 20 msec.
1142
1143     @param [in] hComponent
1144         Handle of the component to be accessed.  This is the component
1145         handle returned by the call to the OMX_GetHandle function.
1146     @param [out] ppBuffer
1147         pointer to an OMX_BUFFERHEADERTYPE structure used to receive the
1148         pointer to the buffer header.  Note that the memory location used
1149         for this buffer is NOT visible to the IL Client.
1150     @param [in] nPortIndex
1151         nPortIndex is used to select the port on the component the buffer will
1152         be used with.  The port can be found by using the nPortIndex
1153         value as an index into the Port Definition array of the component.
1154     @param [in] pAppPrivate
1155         pAppPrivate is used to initialize the pAppPrivate member of the
1156         buffer header structure.
1157     @param [in] eglImage
1158         eglImage contains the handle of the EGLImage to use as a buffer on the
1159         specified port.  The component is expected to validate properties of
1160         the EGLImage against the configuration of the port to ensure the component
1161         can use the EGLImage as a buffer.
1162     @return OMX_ERRORTYPE
1163         If the command successfully executes, the return code will be
1164         OMX_ErrorNone.  Otherwise the appropriate OMX error will be returned.
1165     @ingroup comp buf
1166  */
1167 #define OMX_UseEGLImage(                                    \
1168            hComponent,                                      \
1169            ppBufferHdr,                                     \
1170            nPortIndex,                                      \
1171            pAppPrivate,                                     \
1172            eglImage)                                        \
1173     ((OMX_COMPONENTTYPE*)hComponent)->UseEGLImage(          \
1174            hComponent,                                      \
1175            ppBufferHdr,                                     \
1176            nPortIndex,                                      \
1177            pAppPrivate,                                     \
1178            eglImage)
1179
1180 /** The OMX_Init method is used to initialize the OMX core.  It shall be the
1181     first call made into OMX and it should only be executed one time without
1182     an interviening OMX_Deinit call.
1183
1184     The core should return from this call within 20 msec.
1185
1186     @return OMX_ERRORTYPE
1187         If the command successfully executes, the return code will be
1188         OMX_ErrorNone.  Otherwise the appropriate OMX error will be returned.
1189     @ingroup core
1190  */
1191 OMX_API OMX_ERRORTYPE OMX_APIENTRY OMX_Init(void);
1192
1193
1194 /** The OMX_Deinit method is used to deinitialize the OMX core.  It shall be
1195     the last call made into OMX. In the event that the core determines that
1196     thare are components loaded when this call is made, the core may return
1197     with an error rather than try to unload the components.
1198
1199     The core should return from this call within 20 msec.
1200
1201     @return OMX_ERRORTYPE
1202         If the command successfully executes, the return code will be
1203         OMX_ErrorNone.  Otherwise the appropriate OMX error will be returned.
1204     @ingroup core
1205  */
1206 OMX_API OMX_ERRORTYPE OMX_APIENTRY OMX_Deinit(void);
1207
1208
1209 /** The OMX_ComponentNameEnum method will enumerate through all the names of
1210     recognised valid components in the system. This function is provided
1211     as a means to detect all the components in the system run-time. There is
1212     no strict ordering to the enumeration order of component names, although
1213     each name will only be enumerated once.  If the OMX core supports run-time
1214     installation of new components, it is only requried to detect newly
1215     installed components when the first call to enumerate component names
1216     is made (i.e. when nIndex is 0x0).
1217
1218     The core should return from this call in 20 msec.
1219
1220     @param [out] cComponentName
1221         pointer to a null terminated string with the component name.  The
1222         names of the components are strings less than 127 bytes in length
1223         plus the trailing null for a maximum size of 128 bytes.  An example
1224         of a valid component name is "OMX.TI.AUDIO.DSP.MIXER\0".  Names are
1225         assigned by the vendor, but shall start with "OMX." and then have
1226         the Vendor designation next.
1227     @param [in] nNameLength
1228         number of characters in the cComponentName string.  With all
1229         component name strings restricted to less than 128 characters
1230         (including the trailing null) it is recomended that the caller
1231         provide a input string for the cComponentName of 128 characters.
1232     @param [in] nIndex
1233         number containing the enumeration index for the component.
1234         Multiple calls to OMX_ComponentNameEnum with increasing values
1235         of nIndex will enumerate through the component names in the
1236         system until OMX_ErrorNoMore is returned.  The value of nIndex
1237         is 0 to (N-1), where N is the number of valid installed components
1238         in the system.
1239     @return OMX_ERRORTYPE
1240         If the command successfully executes, the return code will be
1241         OMX_ErrorNone.  When the value of nIndex exceeds the number of
1242         components in the system minus 1, OMX_ErrorNoMore will be
1243         returned. Otherwise the appropriate OMX error will be returned.
1244     @ingroup core
1245  */
1246 OMX_API OMX_ERRORTYPE OMX_APIENTRY OMX_ComponentNameEnum(
1247     OMX_OUT OMX_STRING cComponentName,
1248     OMX_IN  OMX_U32 nNameLength,
1249     OMX_IN  OMX_U32 nIndex);
1250
1251
1252 /** The OMX_GetHandle method will locate the component specified by the
1253     component name given, load that component into memory and then invoke
1254     the component's methods to create an instance of the component.
1255
1256     The core should return from this call within 20 msec.
1257
1258     @param [out] pHandle
1259         pointer to an OMX_HANDLETYPE pointer to be filled in by this method.
1260     @param [in] cComponentName
1261         pointer to a null terminated string with the component name.  The
1262         names of the components are strings less than 127 bytes in length
1263         plus the trailing null for a maximum size of 128 bytes.  An example
1264         of a valid component name is "OMX.TI.AUDIO.DSP.MIXER\0".  Names are
1265         assigned by the vendor, but shall start with "OMX." and then have
1266         the Vendor designation next.
1267     @param [in] pAppData
1268         pointer to an application defined value that will be returned
1269         during callbacks so that the application can identify the source
1270         of the callback.
1271     @param [in] pCallBacks
1272         pointer to a OMX_CALLBACKTYPE structure that will be passed to the
1273         component to initialize it with.
1274     @return OMX_ERRORTYPE
1275         If the command successfully executes, the return code will be
1276         OMX_ErrorNone.  Otherwise the appropriate OMX error will be returned.
1277     @ingroup core
1278  */
1279 OMX_API OMX_ERRORTYPE OMX_APIENTRY OMX_GetHandle(
1280     OMX_OUT OMX_HANDLETYPE* pHandle,
1281     OMX_IN  OMX_STRING cComponentName,
1282     OMX_IN  OMX_PTR pAppData,
1283     OMX_IN  OMX_CALLBACKTYPE* pCallBacks);
1284
1285
1286 /** The OMX_FreeHandle method will free a handle allocated by the OMX_GetHandle
1287     method.  If the component reference count goes to zero, the component will
1288     be unloaded from memory.
1289
1290     The core should return from this call within 20 msec when the component is
1291     in the OMX_StateLoaded state.
1292
1293     @param [in] hComponent
1294         Handle of the component to be accessed.  This is the component
1295         handle returned by the call to the GetHandle function.
1296     @return OMX_ERRORTYPE
1297         If the command successfully executes, the return code will be
1298         OMX_ErrorNone.  Otherwise the appropriate OMX error will be returned.
1299     @ingroup core
1300  */
1301 OMX_API OMX_ERRORTYPE OMX_APIENTRY OMX_FreeHandle(
1302     OMX_IN  OMX_HANDLETYPE hComponent);
1303
1304
1305
1306 /** The OMX_SetupTunnel method will handle the necessary calls to the components
1307     to setup the specified tunnel the two components.  NOTE: This is
1308     an actual method (not a #define macro).  This method will make calls into
1309     the component ComponentTunnelRequest method to do the actual tunnel
1310     connection.
1311
1312     The ComponentTunnelRequest method on both components will be called.
1313     This method shall not be called unless the component is in the
1314     OMX_StateLoaded state except when the ports used for the tunnel are
1315     disabled. In this case, the component may be in the OMX_StateExecuting,
1316     OMX_StatePause, or OMX_StateIdle states.
1317
1318     The core should return from this call within 20 msec.
1319
1320     @param [in] hOutput
1321         Handle of the component to be accessed.  Also this is the handle
1322         of the component whose port, specified in the nPortOutput parameter
1323         will be used the source for the tunnel. This is the component handle
1324         returned by the call to the OMX_GetHandle function.  There is a
1325         requirement that hOutput be the source for the data when
1326         tunelling (i.e. nPortOutput is an output port).  If 0x0, the component
1327         specified in hInput will have it's port specified in nPortInput
1328         setup for communication with the application / IL client.
1329     @param [in] nPortOutput
1330         nPortOutput is used to select the source port on component to be
1331         used in the tunnel.
1332     @param [in] hInput
1333         This is the component to setup the tunnel with. This is the handle
1334         of the component whose port, specified in the nPortInput parameter
1335         will be used the destination for the tunnel. This is the component handle
1336         returned by the call to the OMX_GetHandle function.  There is a
1337         requirement that hInput be the destination for the data when
1338         tunelling (i.e. nPortInut is an input port).   If 0x0, the component
1339         specified in hOutput will have it's port specified in nPortPOutput
1340         setup for communication with the application / IL client.
1341     @param [in] nPortInput
1342         nPortInput is used to select the destination port on component to be
1343         used in the tunnel.
1344     @return OMX_ERRORTYPE
1345         If the command successfully executes, the return code will be
1346         OMX_ErrorNone.  Otherwise the appropriate OMX error will be returned.
1347         When OMX_ErrorNotImplemented is returned, one or both components is
1348         a non-interop component and does not support tunneling.
1349
1350         On failure, the ports of both components are setup for communication
1351         with the application / IL Client.
1352     @ingroup core tun
1353  */
1354 OMX_API OMX_ERRORTYPE OMX_APIENTRY OMX_SetupTunnel(
1355     OMX_IN  OMX_HANDLETYPE hOutput,
1356     OMX_IN  OMX_U32 nPortOutput,
1357     OMX_IN  OMX_HANDLETYPE hInput,
1358     OMX_IN  OMX_U32 nPortInput);
1359
1360 /** @ingroup cp */
1361 OMX_API OMX_ERRORTYPE   OMX_GetContentPipe(
1362     OMX_OUT OMX_HANDLETYPE *hPipe,
1363     OMX_IN OMX_STRING szURI);
1364
1365 /** The OMX_GetComponentsOfRole method will return the number of components that support the given
1366     role and (if the compNames field is non-NULL) the names of those components. The call will fail if
1367     an insufficiently sized array of names is supplied. To ensure the array is sufficiently sized the
1368     client should:
1369         * first call this function with the compNames field NULL to determine the number of component names
1370         * second call this function with the compNames field pointing to an array of names allocated
1371           according to the number returned by the first call.
1372
1373     The core should return from this call within 5 msec.
1374
1375     @param [in] role
1376         This is generic standard component name consisting only of component class
1377         name and the type within that class (e.g. 'audio_decoder.aac').
1378     @param [inout] pNumComps
1379         This is used both as input and output.
1380
1381         If compNames is NULL, the input is ignored and the output specifies how many components support
1382         the given role.
1383
1384         If compNames is not NULL, on input it bounds the size of the input structure and
1385         on output, it specifies the number of components string names listed within the compNames parameter.
1386     @param [inout] compNames
1387         If NULL this field is ignored. If non-NULL this points to an array of 128-byte strings which accepts
1388         a list of the names of all physical components that implement the specified standard component name.
1389         Each name is NULL terminated. numComps indicates the number of names.
1390     @ingroup core
1391  */
1392 OMX_API OMX_ERRORTYPE OMX_GetComponentsOfRole (
1393         OMX_IN      OMX_STRING role,
1394     OMX_INOUT   OMX_U32 *pNumComps,
1395     OMX_INOUT   OMX_U8  **compNames);
1396
1397 /** The OMX_GetRolesOfComponent method will return the number of roles supported by the given
1398     component and (if the roles field is non-NULL) the names of those roles. The call will fail if
1399     an insufficiently sized array of names is supplied. To ensure the array is sufficiently sized the
1400     client should:
1401         * first call this function with the roles field NULL to determine the number of role names
1402         * second call this function with the roles field pointing to an array of names allocated
1403           according to the number returned by the first call.
1404
1405     The core should return from this call within 5 msec.
1406
1407     @param [in] compName
1408         This is the name of the component being queried about.
1409     @param [inout] pNumRoles
1410         This is used both as input and output.
1411
1412         If roles is NULL, the input is ignored and the output specifies how many roles the component supports.
1413
1414         If compNames is not NULL, on input it bounds the size of the input structure and
1415         on output, it specifies the number of roles string names listed within the roles parameter.
1416     @param [out] roles
1417         If NULL this field is ignored. If non-NULL this points to an array of 128-byte strings
1418         which accepts a list of the names of all standard components roles implemented on the
1419         specified component name. numComps indicates the number of names.
1420     @ingroup core
1421  */
1422 OMX_API OMX_ERRORTYPE OMX_GetRolesOfComponent (
1423         OMX_IN      OMX_STRING compName,
1424     OMX_INOUT   OMX_U32 *pNumRoles,
1425     OMX_OUT     OMX_U8 **roles);
1426
1427 #ifdef __cplusplus
1428 }
1429 #endif /* __cplusplus */
1430
1431 #endif
1432 /* File EOF */
1433