git.sesse.net Git - vlc/blob - modules/codec/omxil/OMX_Other.h

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