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