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 /** @file OMX_Other.h - OpenMax IL version 1.1.2
25  *  The structures needed by Other components to exchange
26  *  parameters and configuration data with the components.
27  */
28 
29 #ifndef OMX_Other_h
30 #define OMX_Other_h
31 
32 #ifdef __cplusplus
33 extern "C" {
34 #endif /* __cplusplus */
35 
36 
37 /* Each OMX header must 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_Core.h>
43 
44 
45 /**
46  * Enumeration of possible data types which match to multiple domains or no
47  * domain at all.  For types which are vendor specific, a value above
48  * OMX_OTHER_VENDORTSTART should be used.
49  */
50 typedef enum OMX_OTHER_FORMATTYPE {
51     OMX_OTHER_FormatTime = 0, /**< Transmission of various timestamps, elapsed time,
52                                    time deltas, etc */
53     OMX_OTHER_FormatPower,    /**< Perhaps used for enabling/disabling power
54                                    management, setting clocks? */
55     OMX_OTHER_FormatStats,    /**< Could be things such as frame rate, frames
56                                    dropped, etc */
57     OMX_OTHER_FormatBinary,   /**< Arbitrary binary data */
58     OMX_OTHER_FormatVendorReserved = 1000, /**< Starting value for vendor specific
59                                                 formats */
60 
61     OMX_OTHER_FormatKhronosExtensions = 0x6F000000, /**< Reserved region for introducing Khronos Standard Extensions */
62     OMX_OTHER_FormatVendorStartUnused = 0x7F000000, /**< Reserved region for introducing Vendor Extensions */
63     OMX_OTHER_FormatMax = 0x7FFFFFFF
64 } OMX_OTHER_FORMATTYPE;
65 
66 /**
67  * Enumeration of seek modes.
68  */
69 typedef enum OMX_TIME_SEEKMODETYPE {
70     OMX_TIME_SeekModeFast = 0, /**< Prefer seeking to an approximation
71                                 * of the requested seek position over
72                                 * the actual seek position if it
73                                 * results in a faster seek. */
74     OMX_TIME_SeekModeAccurate, /**< Prefer seeking to the actual seek
75                                 * position over an approximation
76                                 * of the requested seek position even
77                                 * if it results in a slower seek. */
78     OMX_TIME_SeekModeKhronosExtensions = 0x6F000000, /**< Reserved region for introducing Khronos Standard Extensions */
79     OMX_TIME_SeekModeVendorStartUnused = 0x7F000000, /**< Reserved region for introducing Vendor Extensions */
80     OMX_TIME_SeekModeMax = 0x7FFFFFFF
81 } OMX_TIME_SEEKMODETYPE;
82 
83 /* Structure representing the seekmode of the component */
84 typedef struct OMX_TIME_CONFIG_SEEKMODETYPE {
85     OMX_U32 nSize;                  /**< size of the structure in bytes */
86     OMX_VERSIONTYPE nVersion;       /**< OMX specification version information */
87     OMX_TIME_SEEKMODETYPE eType;    /**< The seek mode */
88 } OMX_TIME_CONFIG_SEEKMODETYPE;
89 
90 /** Structure representing a time stamp used with the following configs
91  * on the Clock Component (CC):
92  *
93  * OMX_IndexConfigTimeCurrentWallTime: query of the CC�s current wall
94  *     time
95  * OMX_IndexConfigTimeCurrentMediaTime: query of the CC�s current media
96  *     time
97  * OMX_IndexConfigTimeCurrentAudioReference and
98  * OMX_IndexConfigTimeCurrentVideoReference: audio/video reference
99  *     clock sending SC its reference time
100  * OMX_IndexConfigTimeClientStartTime: a Clock Component client sends
101  *     this structure to the Clock Component via a SetConfig on its
102  *     client port when it receives a buffer with
103  *     OMX_BUFFERFLAG_STARTTIME set. It must use the timestamp
104  *     specified by that buffer for nStartTimestamp.
105  *
106  * It�s also used with the following config on components in general:
107  *
108  * OMX_IndexConfigTimePosition: IL client querying component position
109  * (GetConfig) or commanding a component to seek to the given location
110  * (SetConfig)
111  */
112 typedef struct OMX_TIME_CONFIG_TIMESTAMPTYPE {
113     OMX_U32 nSize;               /**< size of the structure in bytes */
114     OMX_VERSIONTYPE nVersion;    /**< OMX specification version
115                                   *   information */
116     OMX_U32 nPortIndex;     /**< port that this structure applies to */
117     OMX_TICKS nTimestamp;  	     /**< timestamp .*/
118 } OMX_TIME_CONFIG_TIMESTAMPTYPE;
119 
120 /** Enumeration of possible reference clocks to the media time. */
121 typedef enum OMX_TIME_UPDATETYPE {
122       OMX_TIME_UpdateRequestFulfillment,    /**< Update is the fulfillment of a media time request. */
123       OMX_TIME_UpdateScaleChanged,	        /**< Update was generated because the scale chagned. */
124       OMX_TIME_UpdateClockStateChanged,     /**< Update was generated because the clock state changed. */
125       OMX_TIME_UpdateKhronosExtensions = 0x6F000000, /**< Reserved region for introducing Khronos Standard Extensions */
126       OMX_TIME_UpdateVendorStartUnused = 0x7F000000, /**< Reserved region for introducing Vendor Extensions */
127       OMX_TIME_UpdateMax = 0x7FFFFFFF
128 } OMX_TIME_UPDATETYPE;
129 
130 /** Enumeration of possible reference clocks to the media time. */
131 typedef enum OMX_TIME_REFCLOCKTYPE {
132       OMX_TIME_RefClockNone,    /**< Use no references. */
133       OMX_TIME_RefClockAudio,	/**< Use references sent through OMX_IndexConfigTimeCurrentAudioReference */
134       OMX_TIME_RefClockVideo,   /**< Use references sent through OMX_IndexConfigTimeCurrentVideoReference */
135       OMX_TIME_RefClockKhronosExtensions = 0x6F000000, /**< Reserved region for introducing Khronos Standard Extensions */
136       OMX_TIME_RefClockVendorStartUnused = 0x7F000000, /**< Reserved region for introducing Vendor Extensions */
137       OMX_TIME_RefClockMax = 0x7FFFFFFF
138 } OMX_TIME_REFCLOCKTYPE;
139 
140 /** Enumeration of clock states. */
141 typedef enum OMX_TIME_CLOCKSTATE {
142       OMX_TIME_ClockStateRunning,             /**< Clock running. */
143       OMX_TIME_ClockStateWaitingForStartTime, /**< Clock waiting until the
144                                                *   prescribed clients emit their
145                                                *   start time. */
146       OMX_TIME_ClockStateStopped,             /**< Clock stopped. */
147       OMX_TIME_ClockStateKhronosExtensions = 0x6F000000, /**< Reserved region for introducing Khronos Standard Extensions */
148       OMX_TIME_ClockStateVendorStartUnused = 0x7F000000, /**< Reserved region for introducing Vendor Extensions */
149       OMX_TIME_ClockStateMax = 0x7FFFFFFF
150 } OMX_TIME_CLOCKSTATE;
151 
152 /** Structure representing a media time request to the clock component.
153  *
154  *  A client component sends this structure to the Clock Component via a SetConfig
155  *  on its client port to specify a media timestamp the Clock Component
156  *  should emit.  The Clock Component should fulfill the request by sending a
157  *  OMX_TIME_MEDIATIMETYPE when its media clock matches the requested
158  *  timestamp.
159  *
160  *  The client may require a media time request be fulfilled slightly
161  *  earlier than the media time specified. In this case the client specifies
162  *  an offset which is equal to the difference between wall time corresponding
163  *  to the requested media time and the wall time when it will be
164  *  fulfilled.
165  *
166  *  A client component may uses these requests and the OMX_TIME_MEDIATIMETYPE to
167  *  time events according to timestamps. If a client must perform an operation O at
168  *  a time T (e.g. deliver a video frame at its corresponding timestamp), it makes a
169  *  media time request at T (perhaps specifying an offset to ensure the request fulfillment
170  *  is a little early). When the clock component passes the resulting OMX_TIME_MEDIATIMETYPE
171  *  structure back to the client component, the client may perform operation O (perhaps having
172  *  to wait a slight amount more time itself as specified by the return values).
173  */
174 
175 typedef struct OMX_TIME_CONFIG_MEDIATIMEREQUESTTYPE {
176     OMX_U32 nSize;              /**< size of the structure in bytes */
177     OMX_VERSIONTYPE nVersion;   /**< OMX specification version information */
178     OMX_U32 nPortIndex;         /**< port that this structure applies to */
179     OMX_PTR pClientPrivate;     /**< Client private data to disabiguate this media time
180                                  *   from others (e.g. the number of the frame to deliver).
181                                  *   Duplicated in the media time structure that fulfills
182                                  *   this request. A value of zero is reserved for time scale
183                                  *   updates. */
184     OMX_TICKS nMediaTimestamp;  /**< Media timestamp requested.*/
185     OMX_TICKS nOffset;          /**< Amount of wall clock time by which this
186                                  *   request should be fulfilled early */
187 } OMX_TIME_CONFIG_MEDIATIMEREQUESTTYPE;
188 
189 /**< Structure sent from the clock component client either when fulfilling
190  *   a media time request or when the time scale has changed.
191  *
192  *   In the former case the Clock Component fills this structure and times its emission
193  *   to a client component (via the client port) according to the corresponding media
194  *   time request sent by the client. The Clock Component should time the emission to occur
195  *   when the requested timestamp matches the Clock Component's media time but also the
196  *   prescribed offset early.
197  *
198  *   Upon scale changes the clock component clears the nClientPrivate data, sends the current
199  *   media time and sets the nScale to the new scale via the client port. It emits a
200  *   OMX_TIME_MEDIATIMETYPE to all clients independent of any requests. This allows clients to
201  *   alter processing to accomodate scaling. For instance a video component might skip inter-frames
202  *   in the case of extreme fastforward. Likewise an audio component might add or remove samples
203  *   from an audio frame to scale audio data.
204  *
205  *   It is expected that some clock components may not be able to fulfill requests
206  *   at exactly the prescribed time. This is acceptable so long as the request is
207  *   fulfilled at least as early as described and not later. This structure provides
208  *   fields the client may use to wait for the remaining time.
209  *
210  *   The client may use either the nOffset or nWallTimeAtMedia fields to determine the
211  *   wall time until the nMediaTimestamp actually occurs. In the latter case the
212  *   client can get a more accurate value for offset by getting the current wall
213  *   from the cloc component and subtracting it from nWallTimeAtMedia.
214  */
215 
216 typedef struct OMX_TIME_MEDIATIMETYPE {
217     OMX_U32 nSize;                  /**< size of the structure in bytes */
218     OMX_VERSIONTYPE nVersion;       /**< OMX specification version information */
219     OMX_U32 nClientPrivate;         /**< Client private data to disabiguate this media time
220                                      *   from others. Copied from the media time request.
221                                      *   A value of zero is reserved for time scale updates. */
222     OMX_TIME_UPDATETYPE eUpdateType; /**< Reason for the update */
223     OMX_TICKS nMediaTimestamp;      /**< Media time requested. If no media time was
224                                      *   requested then this is the current media time. */
225     OMX_TICKS nOffset;              /**< Amount of wall clock time by which this
226                                      *   request was actually fulfilled early */
227 
228     OMX_TICKS nWallTimeAtMediaTime; /**< Wall time corresponding to nMediaTimeStamp.
229                                      *   A client may compare this value to current
230                                      *   media time obtained from the Clock Component to determine
231                                      *   the wall time until the media timestamp is really
232                                      *   current. */
233     OMX_S32 xScale;                 /**< Current media time scale in Q16 format. */
234     OMX_TIME_CLOCKSTATE eState;     /* Seeking Change. Added 7/12.*/
235                                     /**< State of the media time. */
236 } OMX_TIME_MEDIATIMETYPE;
237 
238 /** Structure representing the current media time scale factor. Applicable only to clock
239  *  component, other components see scale changes via OMX_TIME_MEDIATIMETYPE buffers sent via
240  *  the clock component client ports. Upon recieving this config the clock component changes
241  *  the rate by which the media time increases or decreases effectively implementing trick modes.
242  */
243 typedef struct OMX_TIME_CONFIG_SCALETYPE {
244     OMX_U32 nSize;                  /**< size of the structure in bytes */
245     OMX_VERSIONTYPE nVersion;       /**< OMX specification version information */
246     OMX_S32 xScale;                 /**< This is a value in Q16 format which is used for
247                                      * scaling the media time */
248 } OMX_TIME_CONFIG_SCALETYPE;
249 
250 /** Bits used to identify a clock port. Used in OMX_TIME_CONFIG_CLOCKSTATETYPE�s nWaitMask field */
251 #define OMX_CLOCKPORT0 0x00000001
252 #define OMX_CLOCKPORT1 0x00000002
253 #define OMX_CLOCKPORT2 0x00000004
254 #define OMX_CLOCKPORT3 0x00000008
255 #define OMX_CLOCKPORT4 0x00000010
256 #define OMX_CLOCKPORT5 0x00000020
257 #define OMX_CLOCKPORT6 0x00000040
258 #define OMX_CLOCKPORT7 0x00000080
259 
260 /** Structure representing the current mode of the media clock.
261  *  IL Client uses this config to change or query the mode of the
262  *  media clock of the clock component. Applicable only to clock
263  *  component.
264  *
265  *  On a SetConfig if eState is OMX_TIME_ClockStateRunning media time
266  *  starts immediately at the prescribed start time. If
267  *  OMX_TIME_ClockStateWaitingForStartTime the Clock Component ignores
268  *  the given nStartTime and waits for all clients specified in the
269  *  nWaitMask to send starttimes (via
270  *  OMX_IndexConfigTimeClientStartTime). The Clock Component then starts
271  *  the media clock using the earliest start time supplied. */
272 typedef struct OMX_TIME_CONFIG_CLOCKSTATETYPE {
273     OMX_U32 nSize;              /**< size of the structure in bytes */
274     OMX_VERSIONTYPE nVersion;   /**< OMX specification version
275                                  *   information */
276     OMX_TIME_CLOCKSTATE eState; /**< State of the media time. */
277     OMX_TICKS nStartTime;       /**< Start time of the media time. */
278     OMX_TICKS nOffset;          /**< Time to offset the media time by
279                                  * (e.g. preroll). Media time will be
280                                  * reported to be nOffset ticks earlier.
281                                  */
282     OMX_U32 nWaitMask;          /**< Mask of OMX_CLOCKPORT values. */
283 } OMX_TIME_CONFIG_CLOCKSTATETYPE;
284 
285 /** Structure representing the reference clock currently being used to
286  *  compute media time. IL client uses this config to change or query the
287  *  clock component's active reference clock */
288 typedef struct OMX_TIME_CONFIG_ACTIVEREFCLOCKTYPE {
289     OMX_U32 nSize;                  /**< size of the structure in bytes */
290     OMX_VERSIONTYPE nVersion;       /**< OMX specification version information */
291     OMX_TIME_REFCLOCKTYPE eClock;   /**< Reference clock used to compute media time */
292 } OMX_TIME_CONFIG_ACTIVEREFCLOCKTYPE;
293 
294 /** Descriptor for setting specifics of power type.
295  *  Note: this structure is listed for backwards compatibility. */
296 typedef struct OMX_OTHER_CONFIG_POWERTYPE {
297     OMX_U32 nSize;            /**< size of the structure in bytes */
298     OMX_VERSIONTYPE nVersion; /**< OMX specification version information */
299     OMX_BOOL bEnablePM;       /**< Flag to enable Power Management */
300 } OMX_OTHER_CONFIG_POWERTYPE;
301 
302 
303 /** Descriptor for setting specifics of stats type.
304  *  Note: this structure is listed for backwards compatibility. */
305 typedef struct OMX_OTHER_CONFIG_STATSTYPE {
306     OMX_U32 nSize;            /**< size of the structure in bytes */
307     OMX_VERSIONTYPE nVersion; /**< OMX specification version information */
308     /* what goes here */
309 } OMX_OTHER_CONFIG_STATSTYPE;
310 
311 
312 /**
313  * The PortDefinition structure is used to define all of the parameters
314  * necessary for the compliant component to setup an input or an output other
315  * path.
316  */
317 typedef struct OMX_OTHER_PORTDEFINITIONTYPE {
318     OMX_OTHER_FORMATTYPE eFormat;  /**< Type of data expected for this channel */
319 } OMX_OTHER_PORTDEFINITIONTYPE;
320 
321 /**  Port format parameter.  This structure is used to enumerate
322   *  the various data input/output format supported by the port.
323   */
324 typedef struct OMX_OTHER_PARAM_PORTFORMATTYPE {
325     OMX_U32 nSize; /**< size of the structure in bytes */
326     OMX_VERSIONTYPE nVersion; /**< OMX specification version information */
327     OMX_U32 nPortIndex; /**< Indicates which port to set */
328     OMX_U32 nIndex; /**< Indicates the enumeration index for the format from 0x0 to N-1 */
329     OMX_OTHER_FORMATTYPE eFormat; /**< Type of data expected for this channel */
330 } OMX_OTHER_PARAM_PORTFORMATTYPE;
331 
332 #ifdef __cplusplus
333 }
334 #endif /* __cplusplus */
335 
336 #endif
337 /* File EOF */
338