1 /* ------------------------------------------------------------------
2 * Copyright (C) 1998-2009 PacketVideo
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
14 * See the License for the specific language governing permissions
15 * and limitations under the License.
16 * -------------------------------------------------------------------
19 * Copyright (c) 2008 The Khronos Group Inc.
21 * Permission is hereby granted, free of charge, to any person obtaining
22 * a copy of this software and associated documentation files (the
23 * "Software"), to deal in the Software without restriction, including
24 * without limitation the rights to use, copy, modify, merge, publish,
25 * distribute, sublicense, and/or sell copies of the Software, and to
26 * permit persons to whom the Software is furnished to do so, subject
27 * to the following conditions:
28 * The above copyright notice and this permission notice shall be included
29 * in all copies or substantial portions of the Software.
31 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
32 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
33 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
34 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
35 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
36 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
37 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
41 /** @file OMX_Other.h - OpenMax IL version 1.1.2
42 * The structures needed by Other components to exchange
43 * parameters and configuration data with the components.
51 #endif /* __cplusplus */
54 /* Each OMX header must include all required header files to allow the
55 * header to compile without errors. The includes below are required
56 * for this header file to compile successfully
63 * Enumeration of possible data types which match to multiple domains or no
64 * domain at all. For types which are vendor specific, a value above
65 * OMX_OTHER_VENDORTSTART should be used.
67 typedef enum OMX_OTHER_FORMATTYPE {
68 OMX_OTHER_FormatTime = 0, /**< Transmission of various timestamps, elapsed time,
70 OMX_OTHER_FormatPower, /**< Perhaps used for enabling/disabling power
71 management, setting clocks? */
72 OMX_OTHER_FormatStats, /**< Could be things such as frame rate, frames
74 OMX_OTHER_FormatBinary, /**< Arbitrary binary data */
75 OMX_OTHER_FormatVendorReserved = 1000, /**< Starting value for vendor specific
78 OMX_OTHER_FormatKhronosExtensions = 0x6F000000, /**< Reserved region for introducing Khronos Standard Extensions */
79 OMX_OTHER_FormatVendorStartUnused = 0x7F000000, /**< Reserved region for introducing Vendor Extensions */
80 OMX_OTHER_FormatMax = 0x7FFFFFFF
81 } OMX_OTHER_FORMATTYPE;
84 * Enumeration of seek modes.
86 typedef enum OMX_TIME_SEEKMODETYPE {
87 OMX_TIME_SeekModeFast = 0, /**< Prefer seeking to an approximation
88 * of the requested seek position over
89 * the actual seek position if it
90 * results in a faster seek. */
91 OMX_TIME_SeekModeAccurate, /**< Prefer seeking to the actual seek
92 * position over an approximation
93 * of the requested seek position even
94 * if it results in a slower seek. */
95 OMX_TIME_SeekModeKhronosExtensions = 0x6F000000, /**< Reserved region for introducing Khronos Standard Extensions */
96 OMX_TIME_SeekModeVendorStartUnused = 0x7F000000, /**< Reserved region for introducing Vendor Extensions */
97 OMX_TIME_SeekModeMax = 0x7FFFFFFF
98 } OMX_TIME_SEEKMODETYPE;
100 /* Structure representing the seekmode of the component */
101 typedef struct OMX_TIME_CONFIG_SEEKMODETYPE {
102 OMX_U32 nSize; /**< size of the structure in bytes */
103 OMX_VERSIONTYPE nVersion; /**< OMX specification version information */
104 OMX_TIME_SEEKMODETYPE eType; /**< The seek mode */
105 } OMX_TIME_CONFIG_SEEKMODETYPE;
107 /** Structure representing a time stamp used with the following configs
108 * on the Clock Component (CC):
110 * OMX_IndexConfigTimeCurrentWallTime: query of the CC
\92s current wall
112 * OMX_IndexConfigTimeCurrentMediaTime: query of the CC
\92s current media
114 * OMX_IndexConfigTimeCurrentAudioReference and
115 * OMX_IndexConfigTimeCurrentVideoReference: audio/video reference
116 * clock sending SC its reference time
117 * OMX_IndexConfigTimeClientStartTime: a Clock Component client sends
118 * this structure to the Clock Component via a SetConfig on its
119 * client port when it receives a buffer with
120 * OMX_BUFFERFLAG_STARTTIME set. It must use the timestamp
121 * specified by that buffer for nStartTimestamp.
123 * It
\92s also used with the following config on components in general:
125 * OMX_IndexConfigTimePosition: IL client querying component position
126 * (GetConfig) or commanding a component to seek to the given location
129 typedef struct OMX_TIME_CONFIG_TIMESTAMPTYPE {
130 OMX_U32 nSize; /**< size of the structure in bytes */
131 OMX_VERSIONTYPE nVersion; /**< OMX specification version
133 OMX_U32 nPortIndex; /**< port that this structure applies to */
134 OMX_TICKS nTimestamp; /**< timestamp .*/
135 } OMX_TIME_CONFIG_TIMESTAMPTYPE;
137 /** Enumeration of possible reference clocks to the media time. */
138 typedef enum OMX_TIME_UPDATETYPE {
139 OMX_TIME_UpdateRequestFulfillment, /**< Update is the fulfillment of a media time request. */
140 OMX_TIME_UpdateScaleChanged, /**< Update was generated because the scale chagned. */
141 OMX_TIME_UpdateClockStateChanged, /**< Update was generated because the clock state changed. */
142 OMX_TIME_UpdateKhronosExtensions = 0x6F000000, /**< Reserved region for introducing Khronos Standard Extensions */
143 OMX_TIME_UpdateVendorStartUnused = 0x7F000000, /**< Reserved region for introducing Vendor Extensions */
144 OMX_TIME_UpdateMax = 0x7FFFFFFF
145 } OMX_TIME_UPDATETYPE;
147 /** Enumeration of possible reference clocks to the media time. */
148 typedef enum OMX_TIME_REFCLOCKTYPE {
149 OMX_TIME_RefClockNone, /**< Use no references. */
150 OMX_TIME_RefClockAudio, /**< Use references sent through OMX_IndexConfigTimeCurrentAudioReference */
151 OMX_TIME_RefClockVideo, /**< Use references sent through OMX_IndexConfigTimeCurrentVideoReference */
152 OMX_TIME_RefClockKhronosExtensions = 0x6F000000, /**< Reserved region for introducing Khronos Standard Extensions */
153 OMX_TIME_RefClockVendorStartUnused = 0x7F000000, /**< Reserved region for introducing Vendor Extensions */
154 OMX_TIME_RefClockMax = 0x7FFFFFFF
155 } OMX_TIME_REFCLOCKTYPE;
157 /** Enumeration of clock states. */
158 typedef enum OMX_TIME_CLOCKSTATE {
159 OMX_TIME_ClockStateRunning, /**< Clock running. */
160 OMX_TIME_ClockStateWaitingForStartTime, /**< Clock waiting until the
161 * prescribed clients emit their
163 OMX_TIME_ClockStateStopped, /**< Clock stopped. */
164 OMX_TIME_ClockStateKhronosExtensions = 0x6F000000, /**< Reserved region for introducing Khronos Standard Extensions */
165 OMX_TIME_ClockStateVendorStartUnused = 0x7F000000, /**< Reserved region for introducing Vendor Extensions */
166 OMX_TIME_ClockStateMax = 0x7FFFFFFF
167 } OMX_TIME_CLOCKSTATE;
169 /** Structure representing a media time request to the clock component.
171 * A client component sends this structure to the Clock Component via a SetConfig
172 * on its client port to specify a media timestamp the Clock Component
173 * should emit. The Clock Component should fulfill the request by sending a
174 * OMX_TIME_MEDIATIMETYPE when its media clock matches the requested
177 * The client may require a media time request be fulfilled slightly
178 * earlier than the media time specified. In this case the client specifies
179 * an offset which is equal to the difference between wall time corresponding
180 * to the requested media time and the wall time when it will be
183 * A client component may uses these requests and the OMX_TIME_MEDIATIMETYPE to
184 * time events according to timestamps. If a client must perform an operation O at
185 * a time T (e.g. deliver a video frame at its corresponding timestamp), it makes a
186 * media time request at T (perhaps specifying an offset to ensure the request fulfillment
187 * is a little early). When the clock component passes the resulting OMX_TIME_MEDIATIMETYPE
188 * structure back to the client component, the client may perform operation O (perhaps having
189 * to wait a slight amount more time itself as specified by the return values).
192 typedef struct OMX_TIME_CONFIG_MEDIATIMEREQUESTTYPE {
193 OMX_U32 nSize; /**< size of the structure in bytes */
194 OMX_VERSIONTYPE nVersion; /**< OMX specification version information */
195 OMX_U32 nPortIndex; /**< port that this structure applies to */
196 OMX_PTR pClientPrivate; /**< Client private data to disabiguate this media time
197 * from others (e.g. the number of the frame to deliver).
198 * Duplicated in the media time structure that fulfills
199 * this request. A value of zero is reserved for time scale
201 OMX_TICKS nMediaTimestamp; /**< Media timestamp requested.*/
202 OMX_TICKS nOffset; /**< Amount of wall clock time by which this
203 * request should be fulfilled early */
204 } OMX_TIME_CONFIG_MEDIATIMEREQUESTTYPE;
206 /**< Structure sent from the clock component client either when fulfilling
207 * a media time request or when the time scale has changed.
209 * In the former case the Clock Component fills this structure and times its emission
210 * to a client component (via the client port) according to the corresponding media
211 * time request sent by the client. The Clock Component should time the emission to occur
212 * when the requested timestamp matches the Clock Component's media time but also the
213 * prescribed offset early.
215 * Upon scale changes the clock component clears the nClientPrivate data, sends the current
216 * media time and sets the nScale to the new scale via the client port. It emits a
217 * OMX_TIME_MEDIATIMETYPE to all clients independent of any requests. This allows clients to
218 * alter processing to accomodate scaling. For instance a video component might skip inter-frames
219 * in the case of extreme fastforward. Likewise an audio component might add or remove samples
220 * from an audio frame to scale audio data.
222 * It is expected that some clock components may not be able to fulfill requests
223 * at exactly the prescribed time. This is acceptable so long as the request is
224 * fulfilled at least as early as described and not later. This structure provides
225 * fields the client may use to wait for the remaining time.
227 * The client may use either the nOffset or nWallTimeAtMedia fields to determine the
228 * wall time until the nMediaTimestamp actually occurs. In the latter case the
229 * client can get a more accurate value for offset by getting the current wall
230 * from the cloc component and subtracting it from nWallTimeAtMedia.
233 typedef struct OMX_TIME_MEDIATIMETYPE {
234 OMX_U32 nSize; /**< size of the structure in bytes */
235 OMX_VERSIONTYPE nVersion; /**< OMX specification version information */
236 OMX_U32 nClientPrivate; /**< Client private data to disabiguate this media time
237 * from others. Copied from the media time request.
238 * A value of zero is reserved for time scale updates. */
239 OMX_TIME_UPDATETYPE eUpdateType; /**< Reason for the update */
240 OMX_TICKS nMediaTimestamp; /**< Media time requested. If no media time was
241 * requested then this is the current media time. */
242 OMX_TICKS nOffset; /**< Amount of wall clock time by which this
243 * request was actually fulfilled early */
245 OMX_TICKS nWallTimeAtMediaTime; /**< Wall time corresponding to nMediaTimeStamp.
246 * A client may compare this value to current
247 * media time obtained from the Clock Component to determine
248 * the wall time until the media timestamp is really
250 OMX_S32 xScale; /**< Current media time scale in Q16 format. */
251 OMX_TIME_CLOCKSTATE eState; /* Seeking Change. Added 7/12.*/
252 /**< State of the media time. */
253 } OMX_TIME_MEDIATIMETYPE;
255 /** Structure representing the current media time scale factor. Applicable only to clock
256 * component, other components see scale changes via OMX_TIME_MEDIATIMETYPE buffers sent via
257 * the clock component client ports. Upon recieving this config the clock component changes
258 * the rate by which the media time increases or decreases effectively implementing trick modes.
260 typedef struct OMX_TIME_CONFIG_SCALETYPE {
261 OMX_U32 nSize; /**< size of the structure in bytes */
262 OMX_VERSIONTYPE nVersion; /**< OMX specification version information */
263 OMX_S32 xScale; /**< This is a value in Q16 format which is used for
264 * scaling the media time */
265 } OMX_TIME_CONFIG_SCALETYPE;
267 /** Bits used to identify a clock port. Used in OMX_TIME_CONFIG_CLOCKSTATETYPE
\92s nWaitMask field */
268 #define OMX_CLOCKPORT0 0x00000001
269 #define OMX_CLOCKPORT1 0x00000002
270 #define OMX_CLOCKPORT2 0x00000004
271 #define OMX_CLOCKPORT3 0x00000008
272 #define OMX_CLOCKPORT4 0x00000010
273 #define OMX_CLOCKPORT5 0x00000020
274 #define OMX_CLOCKPORT6 0x00000040
275 #define OMX_CLOCKPORT7 0x00000080
277 /** Structure representing the current mode of the media clock.
278 * IL Client uses this config to change or query the mode of the
279 * media clock of the clock component. Applicable only to clock
282 * On a SetConfig if eState is OMX_TIME_ClockStateRunning media time
283 * starts immediately at the prescribed start time. If
284 * OMX_TIME_ClockStateWaitingForStartTime the Clock Component ignores
285 * the given nStartTime and waits for all clients specified in the
286 * nWaitMask to send starttimes (via
287 * OMX_IndexConfigTimeClientStartTime). The Clock Component then starts
288 * the media clock using the earliest start time supplied. */
289 typedef struct OMX_TIME_CONFIG_CLOCKSTATETYPE {
290 OMX_U32 nSize; /**< size of the structure in bytes */
291 OMX_VERSIONTYPE nVersion; /**< OMX specification version
293 OMX_TIME_CLOCKSTATE eState; /**< State of the media time. */
294 OMX_TICKS nStartTime; /**< Start time of the media time. */
295 OMX_TICKS nOffset; /**< Time to offset the media time by
296 * (e.g. preroll). Media time will be
297 * reported to be nOffset ticks earlier.
299 OMX_U32 nWaitMask; /**< Mask of OMX_CLOCKPORT values. */
300 } OMX_TIME_CONFIG_CLOCKSTATETYPE;
302 /** Structure representing the reference clock currently being used to
303 * compute media time. IL client uses this config to change or query the
304 * clock component's active reference clock */
305 typedef struct OMX_TIME_CONFIG_ACTIVEREFCLOCKTYPE {
306 OMX_U32 nSize; /**< size of the structure in bytes */
307 OMX_VERSIONTYPE nVersion; /**< OMX specification version information */
308 OMX_TIME_REFCLOCKTYPE eClock; /**< Reference clock used to compute media time */
309 } OMX_TIME_CONFIG_ACTIVEREFCLOCKTYPE;
311 /** Descriptor for setting specifics of power type.
312 * Note: this structure is listed for backwards compatibility. */
313 typedef struct OMX_OTHER_CONFIG_POWERTYPE {
314 OMX_U32 nSize; /**< size of the structure in bytes */
315 OMX_VERSIONTYPE nVersion; /**< OMX specification version information */
316 OMX_BOOL bEnablePM; /**< Flag to enable Power Management */
317 } OMX_OTHER_CONFIG_POWERTYPE;
320 /** Descriptor for setting specifics of stats type.
321 * Note: this structure is listed for backwards compatibility. */
322 typedef struct OMX_OTHER_CONFIG_STATSTYPE {
323 OMX_U32 nSize; /**< size of the structure in bytes */
324 OMX_VERSIONTYPE nVersion; /**< OMX specification version information */
326 } OMX_OTHER_CONFIG_STATSTYPE;
330 * The PortDefinition structure is used to define all of the parameters
331 * necessary for the compliant component to setup an input or an output other
334 typedef struct OMX_OTHER_PORTDEFINITIONTYPE {
335 OMX_OTHER_FORMATTYPE eFormat; /**< Type of data expected for this channel */
336 } OMX_OTHER_PORTDEFINITIONTYPE;
338 /** Port format parameter. This structure is used to enumerate
339 * the various data input/output format supported by the port.
341 typedef struct OMX_OTHER_PARAM_PORTFORMATTYPE {
342 OMX_U32 nSize; /**< size of the structure in bytes */
343 OMX_VERSIONTYPE nVersion; /**< OMX specification version information */
344 OMX_U32 nPortIndex; /**< Indicates which port to set */
345 OMX_U32 nIndex; /**< Indicates the enumeration index for the format from 0x0 to N-1 */
346 OMX_OTHER_FORMATTYPE eFormat; /**< Type of data expected for this channel */
347 } OMX_OTHER_PARAM_PORTFORMATTYPE;
351 #endif /* __cplusplus */