vpx_codec/vpx_decoder.h

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