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
  57     /*! \brief Initialization-time Feature Enabling
  58      *
  59      *  Certain codec features must be known at initialization time, to allow for
  60      *  proper memory allocation.
  61      *
  62      *  The available flags are specified by VPX_CODEC_USE_* defines.
  63      */
  64 #define VPX_CODEC_USE_POSTPROC   0x10000 /**< Postprocess decoded frame */
  65
  66     /*!\brief Stream properties
  67      *
  68      * This structure is used to query or set properties of the decoded
  69      * stream. Algorithms may extend this structure with data specific
  70      * to their bitstream by setting the sz member appropriately.
  71      */
  72     typedef struct vpx_codec_stream_info
  73     {
  74         unsigned int sz;     /**< Size of this structure */
  75         unsigned int w;      /**< Width (or 0 for unknown/default) */
  76         unsigned int h;      /**< Height (or 0 for unknown/default) */
  77         unsigned int is_kf;  /**< Current frame is a keyframe */
  78     } vpx_codec_stream_info_t;
  79
  80     /* REQUIRED FUNCTIONS
  81      *
  82      * The following functions are required to be implemented for all decoders.
  83      * They represent the base case functionality expected of all decoders.
  84      */
  85
  86
  87     /*!\brief Initialization Configurations
  88      *
  89      * This structure is used to pass init time configuration options to the
  90      * decoder.
  91      */
  92     typedef struct vpx_codec_dec_cfg
  93     {
  94         unsigned int threads; /**< Maximum number of threads to use, default 1 */
  95         unsigned int w;      /**< Width */
  96         unsigned int h;      /**< Height */
  97     } vpx_codec_dec_cfg_t; /**< alias for struct vpx_codec_dec_cfg */
  98
  99
 100     /*!\brief Initialize a decoder instance
 101      *
 102      * Initializes a decoder context using the given interface. Applications
 103      * should call the vpx_codec_dec_init convenience macro instead of this
 104      * function directly, to ensure that the ABI version number parameter
 105      * is properly initialized.
 106      *
 107      * In XMA mode (activated by setting VPX_CODEC_USE_XMA in the flags
 108      * parameter), the storage pointed to by the cfg parameter must be
 109      * kept readable and stable until all memory maps have been set.
 110      *
 111      * \param[in]    ctx     Pointer to this instance's context.
 112      * \param[in]    iface   Pointer to the algorithm interface to use.
 113      * \param[in]    cfg     Configuration to use, if known. May be NULL.
 114      * \param[in]    flags   Bitfield of VPX_CODEC_USE_* flags
 115      * \param[in]    ver     ABI version number. Must be set to
 116      *                       VPX_DECODER_ABI_VERSION
 117      * \retval #VPX_CODEC_OK
 118      *     The decoder algorithm initialized.
 119      * \retval #VPX_CODEC_MEM_ERROR
 120      *     Memory allocation failed.
 121      */
 122     vpx_codec_err_t vpx_codec_dec_init_ver(vpx_codec_ctx_t      *ctx,
 123                                            vpx_codec_iface_t    *iface,
 124                                            vpx_codec_dec_cfg_t  *cfg,
 125                                            vpx_codec_flags_t     flags,
 126                                            int                   ver);
 127
 128     /*!\brief Convenience macro for vpx_codec_dec_init_ver()
 129      *
 130      * Ensures the ABI version parameter is properly set.
 131      */
 132 #define vpx_codec_dec_init(ctx, iface, cfg, flags) \
 133     vpx_codec_dec_init_ver(ctx, iface, cfg, flags, VPX_DECODER_ABI_VERSION)
 134
 135
 136     /*!\brief Parse stream info from a buffer
 137      *
 138      * Performs high level parsing of the bitstream. Construction of a decoder
 139      * context is not necessary. Can be used to determine if the bitstream is
 140      * of the proper format, and to extract information from the stream.
 141      *
 142      * \param[in]      iface   Pointer to the algorithm interface
 143      * \param[in]      data    Pointer to a block of data to parse
 144      * \param[in]      data_sz Size of the data buffer
 145      * \param[in,out]  si      Pointer to stream info to update. The size member
 146      *                         \ref MUST be properly initialized, but \ref MAY be
 147      *                         clobbered by the algorithm. This parameter \ref MAY
 148      *                         be NULL.
 149      *
 150      * \retval #VPX_CODEC_OK
 151      *     Bitstream is parsable and stream information updated
 152      */
 153     vpx_codec_err_t vpx_codec_peek_stream_info(vpx_codec_iface_t       *iface,
 154             const uint8_t           *data,
 155             unsigned int             data_sz,
 156             vpx_codec_stream_info_t *si);
 157
 158
 159     /*!\brief Return information about the current stream.
 160      *
 161      * Returns information about the stream that has been parsed during decoding.
 162      *
 163      * \param[in]      ctx     Pointer to this instance's context
 164      * \param[in,out]  si      Pointer to stream info to update. The size member
 165      *                         \ref MUST be properly initialized, but \ref MAY be
 166      *                         clobbered by the algorithm. This parameter \ref MAY
 167      *                         be NULL.
 168      *
 169      * \retval #VPX_CODEC_OK
 170      *     Bitstream is parsable and stream information updated
 171      */
 172     vpx_codec_err_t vpx_codec_get_stream_info(vpx_codec_ctx_t         *ctx,
 173             vpx_codec_stream_info_t *si);
 174
 175
 176     /*!\brief Decode data
 177      *
 178      * Processes a buffer of coded data. If the processing results in a new
 179      * decoded frame becoming available, PUT_SLICE and PUT_FRAME events may be
 180      * generated, as appropriate. Encoded data \ref MUST be passed in DTS (decode
 181      * time stamp) order. Frames produced will always be in PTS (presentation
 182      * time stamp) order.
 183      *
 184      * \param[in] ctx          Pointer to this instance's context
 185      * \param[in] data         Pointer to this block of new coded data. If
 186      *                         NULL, a VPX_CODEC_CB_PUT_FRAME event is posted
 187      *                         for the previously decoded frame.
 188      * \param[in] data_sz      Size of the coded data, in bytes.
 189      * \param[in] user_priv    Application specific data to associate with
 190      *                         this frame.
 191      * \param[in] deadline     Soft deadline the decoder should attempt to meet,
 192      *                         in us. Set to zero for unlimited.
 193      *
 194      * \return Returns #VPX_CODEC_OK if the coded data was processed completely
 195      *         and future pictures can be decoded without error. Otherwise,
 196      *         see the descriptions of the other error codes in ::vpx_codec_err_t
 197      *         for recoverability capabilities.
 198      */
 199     vpx_codec_err_t vpx_codec_decode(vpx_codec_ctx_t    *ctx,
 200                                      const uint8_t        *data,
 201                                      unsigned int            data_sz,
 202                                      void               *user_priv,
 203                                      long                deadline);
 204
 205
 206     /*!\brief Decoded frames iterator
 207      *
 208      * Iterates over a list of the frames available for display. The iterator
 209      * storage should be initialized to NULL to start the iteration. Iteration is
 210      * complete when this function returns NULL.
 211      *
 212      * The list of available frames becomes valid upon completion of the
 213      * vpx_codec_decode call, and remains valid until the next call to vpx_codec_decode.
 214      *
 215      * \param[in]     ctx      Pointer to this instance's context
 216      * \param[in,out] iter     Iterator storage, initialized to NULL
 217      *
 218      * \return Returns a pointer to an image, if one is ready for display. Frames
 219      *         produced will always be in PTS (presentation time stamp) order.
 220      */
 221     vpx_image_t *vpx_codec_get_frame(vpx_codec_ctx_t  *ctx,
 222                                      vpx_codec_iter_t *iter);
 223
 224
 225     /*!\defgroup cap_put_frame Frame-Based Decoding Functions
 226      *
 227      * The following functions are required to be implemented for all decoders
 228      * that advertise the VPX_CODEC_CAP_PUT_FRAME capability. Calling these functions
 229      * for codecs that don't advertise this capability will result in an error
 230      * code being returned, usually VPX_CODEC_ERROR
 231      * @{
 232      */
 233
 234     /*!\brief put frame callback prototype
 235      *
 236      * This callback is invoked by the decoder to notify the application of
 237      * the availability of decoded image data.
 238      */
 239     typedef void (*vpx_codec_put_frame_cb_fn_t)(void        *user_priv,
 240             const vpx_image_t *img);
 241
 242
 243     /*!\brief Register for notification of frame completion.
 244      *
 245      * Registers a given function to be called when a decoded frame is
 246      * available.
 247      *
 248      * \param[in] ctx          Pointer to this instance's context
 249      * \param[in] cb           Pointer to the callback function
 250      * \param[in] user_priv    User's private data
 251      *
 252      * \retval #VPX_CODEC_OK
 253      *     Callback successfully registered.
 254      * \retval #VPX_CODEC_ERROR
 255      *     Decoder context not initialized, or algorithm not capable of
 256      *     posting slice completion.
 257      */
 258     vpx_codec_err_t vpx_codec_register_put_frame_cb(vpx_codec_ctx_t             *ctx,
 259             vpx_codec_put_frame_cb_fn_t  cb,
 260             void                        *user_priv);
 261
 262
 263     /*!@} - end defgroup cap_put_frame */
 264
 265     /*!\defgroup cap_put_slice Slice-Based Decoding Functions
 266      *
 267      * The following functions are required to be implemented for all decoders
 268      * that advertise the VPX_CODEC_CAP_PUT_SLICE capability. Calling these functions
 269      * for codecs that don't advertise this capability will result in an error
 270      * code being returned, usually VPX_CODEC_ERROR
 271      * @{
 272      */
 273
 274     /*!\brief put slice callback prototype
 275      *
 276      * This callback is invoked by the decoder to notify the application of
 277      * the availability of partially decoded image data. The
 278      */
 279     typedef void (*vpx_codec_put_slice_cb_fn_t)(void         *user_priv,
 280             const vpx_image_t      *img,
 281             const vpx_image_rect_t *valid,
 282             const vpx_image_rect_t *update);
 283
 284
 285     /*!\brief Register for notification of slice completion.
 286      *
 287      * Registers a given function to be called when a decoded slice is
 288      * available.
 289      *
 290      * \param[in] ctx          Pointer to this instance's context
 291      * \param[in] cb           Pointer to the callback function
 292      * \param[in] user_priv    User's private data
 293      *
 294      * \retval #VPX_CODEC_OK
 295      *     Callback successfully registered.
 296      * \retval #VPX_CODEC_ERROR
 297      *     Decoder context not initialized, or algorithm not capable of
 298      *     posting slice completion.
 299      */
 300     vpx_codec_err_t vpx_codec_register_put_slice_cb(vpx_codec_ctx_t             *ctx,
 301             vpx_codec_put_slice_cb_fn_t  cb,
 302             void                        *user_priv);
 303
 304
 305     /*!@} - end defgroup cap_put_slice*/
 306
 307     /*!@} - end defgroup decoder*/
 308
 309 #endif
 310
 311 #ifdef __cplusplus
 312 }
 313 #endif
 314
 315 #if !defined(VPX_CODEC_DISABLE_COMPAT) || !VPX_CODEC_DISABLE_COMPAT
 316 #include "vpx_decoder_compat.h"
 317 #endif