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