vpx/vpx_decoder.h

   1 /*
   2  *  Copyright (c) 2010 The WebM project authors. All Rights Reserved.
   3  *
   4  *  Use of this source code is governed by a BSD-style license
   5  *  that can be found in the LICENSE file in the root of the source
   6  *  tree. An additional intellectual property rights grant can be found
   7  *  in the file PATENTS.  All contributing project authors may
   8  *  be found in the AUTHORS file in the root of the source tree.
   9  */
  10
  11
  12 /*!\defgroup decoder Decoder Algorithm Interface
  13  * \ingroup codec
  14  * This abstraction allows applications using this decoder to easily support
  15  * multiple video formats with minimal code duplication. This section describes
  16  * the interface common to all decoders.
  17  * @{
  18  */
  19
  20 /*!\file
  21  * \brief Describes the decoder algorithm interface to applications.
  22  *
  23  * This file describes the interface between an application and a
  24  * video decoder algorithm.
  25  *
  26  */
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31 #ifndef VPX_DECODER_H
  32 #define VPX_DECODER_H
  33 #include "vpx_codec.h"
  34
  35     /*!\brief Current ABI version number
  36      *
  37      * \internal
  38      * If this file is altered in any way that changes the ABI, this value
  39      * must be bumped.  Examples include, but are not limited to, changing
  40      * types, removing or reassigning enums, adding/removing/rearranging
  41      * fields to structures
  42      */
  43 #define VPX_DECODER_ABI_VERSION (2 + VPX_CODEC_ABI_VERSION) /**<\hideinitializer*/
  44
  45     /*! \brief Decoder capabilities bitfield
  46      *
  47      *  Each decoder advertises the capabilities it supports as part of its
  48      *  ::vpx_codec_iface_t interface structure. Capabilities are extra interfaces
  49      *  or functionality, and are not required to be supported by a decoder.
  50      *
  51      *  The available flags are specified by VPX_CODEC_CAP_* defines.
  52      */
  53 #define VPX_CODEC_CAP_PUT_SLICE  0x10000 /**< Will issue put_slice callbacks */
  54 #define VPX_CODEC_CAP_PUT_FRAME  0x20000 /**< Will issue put_frame callbacks */
  55 #define VPX_CODEC_CAP_POSTPROC   0x40000 /**< Can postprocess decoded frame */
  56 #define VPX_CODEC_CAP_ERROR_CONCEALMENT   0x80000 /**< Can conceal errors due to
  57                                                        packet loss */
  58 #define VPX_CODEC_CAP_INPUT_FRAGMENTS   0x100000 /**< Can receive encoded frames
  59                                                     one fragment at a time */
  60
  61     /*! \brief Initialization-time Feature Enabling
  62      *
  63      *  Certain codec features must be known at initialization time, to allow for
  64      *  proper memory allocation.
  65      *
  66      *  The available flags are specified by VPX_CODEC_USE_* defines.
  67      */
  68 #define VPX_CODEC_USE_POSTPROC   0x10000 /**< Postprocess decoded frame */
  69 #define VPX_CODEC_USE_ERROR_CONCEALMENT 0x20000 /**< Conceal errors in decoded
  70                                                      frames */
  71 #define VPX_CODEC_USE_INPUT_FRAGMENTS   0x40000 /**< The input frame should be
  72                                                     passed to the decoder one
  73                                                     fragment at a time */
  74
  75     /*!\brief Stream properties
  76      *
  77      * This structure is used to query or set properties of the decoded
  78      * stream. Algorithms may extend this structure with data specific
  79      * to their bitstream by setting the sz member appropriately.
  80      */
  81     typedef struct vpx_codec_stream_info
  82     {
  83         unsigned int sz;     /**< Size of this structure */
  84         unsigned int w;      /**< Width (or 0 for unknown/default) */
  85         unsigned int h;      /**< Height (or 0 for unknown/default) */
  86         unsigned int is_kf;  /**< Current frame is a keyframe */
  87     } vpx_codec_stream_info_t;
  88
  89     /* REQUIRED FUNCTIONS
  90      *
  91      * The following functions are required to be implemented for all decoders.
  92      * They represent the base case functionality expected of all decoders.
  93      */
  94
  95
  96     /*!\brief Initialization Configurations
  97      *
  98      * This structure is used to pass init time configuration options to the
  99      * decoder.
 100      */
 101     typedef struct vpx_codec_dec_cfg
 102     {
 103         unsigned int threads; /**< Maximum number of threads to use, default 1 */
 104         unsigned int w;      /**< Width */
 105         unsigned int h;      /**< Height */
 106     } vpx_codec_dec_cfg_t; /**< alias for struct vpx_codec_dec_cfg */
 107
 108
 109     /*!\brief Initialize a decoder instance
 110      *
 111      * Initializes a decoder context using the given interface. Applications
 112      * should call the vpx_codec_dec_init convenience macro instead of this
 113      * function directly, to ensure that the ABI version number parameter
 114      * is properly initialized.
 115      *
 116      * In XMA mode (activated by setting VPX_CODEC_USE_XMA in the flags
 117      * parameter), the storage pointed to by the cfg parameter must be
 118      * kept readable and stable until all memory maps have been set.
 119      *
 120      * \param[in]    ctx     Pointer to this instance's context.
 121      * \param[in]    iface   Pointer to the algorithm interface to use.
 122      * \param[in]    cfg     Configuration to use, if known. May be NULL.
 123      * \param[in]    flags   Bitfield of VPX_CODEC_USE_* flags
 124      * \param[in]    ver     ABI version number. Must be set to
 125      *                       VPX_DECODER_ABI_VERSION
 126      * \retval #VPX_CODEC_OK
 127      *     The decoder algorithm initialized.
 128      * \retval #VPX_CODEC_MEM_ERROR
 129      *     Memory allocation failed.
 130      */
 131     vpx_codec_err_t vpx_codec_dec_init_ver(vpx_codec_ctx_t      *ctx,
 132                                            vpx_codec_iface_t    *iface,
 133                                            vpx_codec_dec_cfg_t  *cfg,
 134                                            vpx_codec_flags_t     flags,
 135                                            int                   ver);
 136
 137     /*!\brief Convenience macro for vpx_codec_dec_init_ver()
 138      *
 139      * Ensures the ABI version parameter is properly set.
 140      */
 141 #define vpx_codec_dec_init(ctx, iface, cfg, flags) \
 142     vpx_codec_dec_init_ver(ctx, iface, cfg, flags, VPX_DECODER_ABI_VERSION)
 143
 144
 145     /*!\brief Parse stream info from a buffer
 146      *
 147      * Performs high level parsing of the bitstream. Construction of a decoder
 148      * context is not necessary. Can be used to determine if the bitstream is
 149      * of the proper format, and to extract information from the stream.
 150      *
 151      * \param[in]      iface   Pointer to the algorithm interface
 152      * \param[in]      data    Pointer to a block of data to parse
 153      * \param[in]      data_sz Size of the data buffer
 154      * \param[in,out]  si      Pointer to stream info to update. The size member
 155      *                         \ref MUST be properly initialized, but \ref MAY be
 156      *                         clobbered by the algorithm. This parameter \ref MAY
 157      *                         be NULL.
 158      *
 159      * \retval #VPX_CODEC_OK
 160      *     Bitstream is parsable and stream information updated
 161      */
 162     vpx_codec_err_t vpx_codec_peek_stream_info(vpx_codec_iface_t       *iface,
 163             const uint8_t           *data,
 164             unsigned int             data_sz,
 165             vpx_codec_stream_info_t *si);
 166
 167
 168     /*!\brief Return information about the current stream.
 169      *
 170      * Returns information about the stream that has been parsed during decoding.
 171      *
 172      * \param[in]      ctx     Pointer to this instance's context
 173      * \param[in,out]  si      Pointer to stream info to update. The size member
 174      *                         \ref MUST be properly initialized, but \ref MAY be
 175      *                         clobbered by the algorithm. This parameter \ref MAY
 176      *                         be NULL.
 177      *
 178      * \retval #VPX_CODEC_OK
 179      *     Bitstream is parsable and stream information updated
 180      */
 181     vpx_codec_err_t vpx_codec_get_stream_info(vpx_codec_ctx_t         *ctx,
 182             vpx_codec_stream_info_t *si);
 183
 184
 185     /*!\brief Decode data
 186      *
 187      * Processes a buffer of coded data. If the processing results in a new
 188      * decoded frame becoming available, PUT_SLICE and PUT_FRAME events may be
 189      * generated, as appropriate. Encoded data \ref MUST be passed in DTS (decode
 190      * time stamp) order. Frames produced will always be in PTS (presentation
 191      * time stamp) order.
 192      * If the decoder is configured with VPX_CODEC_USE_INPUT_FRAGMENTS enabled,
 193      * data and data_sz can contain a fragment of the encoded frame. Fragment
 194      * \#n must contain at least partition \#n, but can also contain subsequent
 195      * partitions (\#n+1 - \#n+i), and if so, fragments \#n+1, .., \#n+i must
 196      * be empty. When no more data is available, this function should be called
 197      * with NULL as data and 0 as data_sz. The memory passed to this function
 198      * must be available until the frame has been decoded.
 199      *
 200      * \param[in] ctx          Pointer to this instance's context
 201      * \param[in] data         Pointer to this block of new coded data. If
 202      *                         NULL, a VPX_CODEC_CB_PUT_FRAME event is posted
 203      *                         for the previously decoded frame.
 204      * \param[in] data_sz      Size of the coded data, in bytes.
 205      * \param[in] user_priv    Application specific data to associate with
 206      *                         this frame.
 207      * \param[in] deadline     Soft deadline the decoder should attempt to meet,
 208      *                         in us. Set to zero for unlimited.
 209      *
 210      * \return Returns #VPX_CODEC_OK if the coded data was processed completely
 211      *         and future pictures can be decoded without error. Otherwise,
 212      *         see the descriptions of the other error codes in ::vpx_codec_err_t
 213      *         for recoverability capabilities.
 214      */
 215     vpx_codec_err_t vpx_codec_decode(vpx_codec_ctx_t    *ctx,
 216                                      const uint8_t        *data,
 217                                      unsigned int            data_sz,
 218                                      void               *user_priv,
 219                                      long                deadline);
 220
 221
 222     /*!\brief Decoded frames iterator
 223      *
 224      * Iterates over a list of the frames available for display. The iterator
 225      * storage should be initialized to NULL to start the iteration. Iteration is
 226      * complete when this function returns NULL.
 227      *
 228      * The list of available frames becomes valid upon completion of the
 229      * vpx_codec_decode call, and remains valid until the next call to vpx_codec_decode.
 230      *
 231      * \param[in]     ctx      Pointer to this instance's context
 232      * \param[in,out] iter     Iterator storage, initialized to NULL
 233      *
 234      * \return Returns a pointer to an image, if one is ready for display. Frames
 235      *         produced will always be in PTS (presentation time stamp) order.
 236      */
 237     vpx_image_t *vpx_codec_get_frame(vpx_codec_ctx_t  *ctx,
 238                                      vpx_codec_iter_t *iter);
 239
 240
 241     /*!\defgroup cap_put_frame Frame-Based Decoding Functions
 242      *
 243      * The following functions are required to be implemented for all decoders
 244      * that advertise the VPX_CODEC_CAP_PUT_FRAME capability. Calling these functions
 245      * for codecs that don't advertise this capability will result in an error
 246      * code being returned, usually VPX_CODEC_ERROR
 247      * @{
 248      */
 249
 250     /*!\brief put frame callback prototype
 251      *
 252      * This callback is invoked by the decoder to notify the application of
 253      * the availability of decoded image data.
 254      */
 255     typedef void (*vpx_codec_put_frame_cb_fn_t)(void        *user_priv,
 256             const vpx_image_t *img);
 257
 258
 259     /*!\brief Register for notification of frame completion.
 260      *
 261      * Registers a given function to be called when a decoded frame is
 262      * available.
 263      *
 264      * \param[in] ctx          Pointer to this instance's context
 265      * \param[in] cb           Pointer to the callback function
 266      * \param[in] user_priv    User's private data
 267      *
 268      * \retval #VPX_CODEC_OK
 269      *     Callback successfully registered.
 270      * \retval #VPX_CODEC_ERROR
 271      *     Decoder context not initialized, or algorithm not capable of
 272      *     posting slice completion.
 273      */
 274     vpx_codec_err_t vpx_codec_register_put_frame_cb(vpx_codec_ctx_t             *ctx,
 275             vpx_codec_put_frame_cb_fn_t  cb,
 276             void                        *user_priv);
 277
 278
 279     /*!@} - end defgroup cap_put_frame */
 280
 281     /*!\defgroup cap_put_slice Slice-Based Decoding Functions
 282      *
 283      * The following functions are required to be implemented for all decoders
 284      * that advertise the VPX_CODEC_CAP_PUT_SLICE capability. Calling these functions
 285      * for codecs that don't advertise this capability will result in an error
 286      * code being returned, usually VPX_CODEC_ERROR
 287      * @{
 288      */
 289
 290     /*!\brief put slice callback prototype
 291      *
 292      * This callback is invoked by the decoder to notify the application of
 293      * the availability of partially decoded image data. The
 294      */
 295     typedef void (*vpx_codec_put_slice_cb_fn_t)(void         *user_priv,
 296             const vpx_image_t      *img,
 297             const vpx_image_rect_t *valid,
 298             const vpx_image_rect_t *update);
 299
 300
 301     /*!\brief Register for notification of slice completion.
 302      *
 303      * Registers a given function to be called when a decoded slice is
 304      * available.
 305      *
 306      * \param[in] ctx          Pointer to this instance's context
 307      * \param[in] cb           Pointer to the callback function
 308      * \param[in] user_priv    User's private data
 309      *
 310      * \retval #VPX_CODEC_OK
 311      *     Callback successfully registered.
 312      * \retval #VPX_CODEC_ERROR
 313      *     Decoder context not initialized, or algorithm not capable of
 314      *     posting slice completion.
 315      */
 316     vpx_codec_err_t vpx_codec_register_put_slice_cb(vpx_codec_ctx_t             *ctx,
 317             vpx_codec_put_slice_cb_fn_t  cb,
 318             void                        *user_priv);
 319
 320
 321     /*!@} - end defgroup cap_put_slice*/
 322
 323     /*!@} - end defgroup decoder*/
 324
 325 #endif
 326
 327 #ifdef __cplusplus
 328 }
 329 #endif