Home | History | Annotate | Download | only in openmax
      1 /* ------------------------------------------------------------------
      2  * Copyright (C) 1998-2009 PacketVideo
      3  *
      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
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     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
     13  * express or implied.
     14  * See the License for the specific language governing permissions
     15  * and limitations under the License.
     16  * -------------------------------------------------------------------
     17  */
     18 /*
     19  * Copyright (c) 2008 The Khronos Group Inc.
     20  *
     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.
     30  *
     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.
     38  *
     39  */
     40 
     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.
     44  */
     45 
     46 #ifndef OMX_Other_h
     47 #define OMX_Other_h
     48 
     49 #ifdef __cplusplus
     50 extern "C" {
     51 #endif /* __cplusplus */
     52 
     53 
     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
     57  */
     58 
     59 #include <OMX_Core.h>
     60 
     61 
     62 /**
     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.
     66  */
     67 typedef enum OMX_OTHER_FORMATTYPE {
     68     OMX_OTHER_FormatTime = 0, /**< Transmission of various timestamps, elapsed time,
     69                                    time deltas, etc */
     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
     73                                    dropped, etc */
     74     OMX_OTHER_FormatBinary,   /**< Arbitrary binary data */
     75     OMX_OTHER_FormatVendorReserved = 1000, /**< Starting value for vendor specific
     76                                                 formats */
     77 
     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;
     82 
     83 /**
     84  * Enumeration of seek modes.
     85  */
     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;
     99 
    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;
    106 
    107 /** Structure representing a time stamp used with the following configs
    108  * on the Clock Component (CC):
    109  *
    110  * OMX_IndexConfigTimeCurrentWallTime: query of the CCs current wall
    111  *     time
    112  * OMX_IndexConfigTimeCurrentMediaTime: query of the CCs current media
    113  *     time
    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.
    122  *
    123  * Its also used with the following config on components in general:
    124  *
    125  * OMX_IndexConfigTimePosition: IL client querying component position
    126  * (GetConfig) or commanding a component to seek to the given location
    127  * (SetConfig)
    128  */
    129 typedef struct OMX_TIME_CONFIG_TIMESTAMPTYPE {
    130     OMX_U32 nSize;               /**< size of the structure in bytes */
    131     OMX_VERSIONTYPE nVersion;    /**< OMX specification version
    132                                   *   information */
    133     OMX_U32 nPortIndex;     /**< port that this structure applies to */
    134     OMX_TICKS nTimestamp;  	     /**< timestamp .*/
    135 } OMX_TIME_CONFIG_TIMESTAMPTYPE;
    136 
    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;
    146 
    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;
    156 
    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
    162                                                *   start time. */
    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;
    168 
    169 /** Structure representing a media time request to the clock component.
    170  *
    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
    175  *  timestamp.
    176  *
    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
    181  *  fulfilled.
    182  *
    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).
    190  */
    191 
    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
    200                                  *   updates. */
    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;
    205 
    206 /**< Structure sent from the clock component client either when fulfilling
    207  *   a media time request or when the time scale has changed.
    208  *
    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.
    214  *
    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.
    221  *
    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.
    226  *
    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.
    231  */
    232 
    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 */
    244 
    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
    249                                      *   current. */
    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;
    254 
    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.
    259  */
    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;
    266 
    267 /** Bits used to identify a clock port. Used in OMX_TIME_CONFIG_CLOCKSTATETYPEs 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
    276 
    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
    280  *  component.
    281  *
    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
    292                                  *   information */
    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.
    298                                  */
    299     OMX_U32 nWaitMask;          /**< Mask of OMX_CLOCKPORT values. */
    300 } OMX_TIME_CONFIG_CLOCKSTATETYPE;
    301 
    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;
    310 
    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;
    318 
    319 
    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 */
    325     /* what goes here */
    326 } OMX_OTHER_CONFIG_STATSTYPE;
    327 
    328 
    329 /**
    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
    332  * path.
    333  */
    334 typedef struct OMX_OTHER_PORTDEFINITIONTYPE {
    335     OMX_OTHER_FORMATTYPE eFormat;  /**< Type of data expected for this channel */
    336 } OMX_OTHER_PORTDEFINITIONTYPE;
    337 
    338 /**  Port format parameter.  This structure is used to enumerate
    339   *  the various data input/output format supported by the port.
    340   */
    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;
    348 
    349 #ifdef __cplusplus
    350 }
    351 #endif /* __cplusplus */
    352 
    353 #endif
    354 /* File EOF */
    355