tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Gloss.     Arch.     IMS     UICC    |    Misc.    |    search     info

RFC 6386

 
 
 

VP8 Data Format and Decoding Guide

Part 10 of 11, p. 263 to 291
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 263 
20.20.  vpx_decoder.h

   ---- Begin code block --------------------------------------

   /*
    *  Copyright (c) 2010, 2011, Google Inc.  All rights reserved.
    *
    *  Use of this source code is governed by a BSD-style license
    *  that can be found in the LICENSE file in the root of the source
    *  tree.  An additional intellectual property rights grant can be
    *  found in the file PATENTS.  All contributing project authors may
    *  be found in the AUTHORS file in the root of the source tree.
    */


   /*!\defgroup decoder Decoder Algorithm Interface
    * \ingroup codec
    * This abstraction allows applications using this decoder to easily
    * support multiple video formats with minimal code duplication.
    * This section describes the interface common to all decoders.
    * @{
    */

   /*!\file vpx_decoder.h
    * \brief Describes the decoder algorithm interface to applications.
    *
    * This file describes the interface between an application and a
    * video decoder algorithm.
    *
    */
   #ifdef __cplusplus
   extern "C" {
   #endif
   #ifndef VPX_DECODER_H
   #define VPX_DECODER_H
   #include "vpx_codec.h"

Top      Up      ToC       Page 264 
       /*!\brief Current ABI version number
        *
        * \internal
        * If this file is altered in any way that changes the ABI, this
        * value must be bumped.  Examples include, but are not limited
        * to, changing types, removing or reassigning enums,
        * adding/removing/rearranging fields to structures
        */
   #define VPX_DECODER_ABI_VERSION (2 + VPX_CODEC_ABI_VERSION)

       /*! \brief Decoder capabilities bitfield
        *
        *  Each decoder advertises the capabilities it supports as part
        *  of its ::vpx_codec_iface_t interface structure.  Capabilities
        *  are extra interfaces or functionality, and are not required
        *  to be supported by a decoder.
        *
        *  The available flags are specified by VPX_CODEC_CAP_* defines.
        */
   #define VPX_CODEC_CAP_PUT_SLICE  0x10000 /**< Will issue put_slice
       callbacks */
   #define VPX_CODEC_CAP_PUT_FRAME  0x20000 /**< Will issue put_frame
       callbacks */
   #define VPX_CODEC_CAP_POSTPROC   0x40000 /**< Can postprocess decoded
       frame */

       /*! \brief Initialization-time Feature Enabling
        *
        *  Certain codec features must be known at initialization time,
        *  to allow for proper memory allocation.
        *
        *  The available flags are specified by VPX_CODEC_USE_* defines.
        */
   #define VPX_CODEC_USE_POSTPROC   0x10000 /**< Postprocess decoded
       frame */

       /*!\brief Stream properties
        *
        * This structure is used to query or set properties of the
        * decoded stream.  Algorithms may extend this structure with
        * data specific to their bitstream by setting the sz member
        * appropriately.
        */

Top      Up      ToC       Page 265 
       typedef struct vpx_codec_stream_info
       {
           unsigned int sz;    /**< Size of this structure */
           unsigned int w;     /**< Width (or 0 for unknown/default) */
           unsigned int h;     /**< Height (or 0 for unknown/default) */
           unsigned int is_kf; /**< Current frame is a keyframe */
       } vpx_codec_stream_info_t;

       /* REQUIRED FUNCTIONS
        *
        * The following functions are required to be implemented for all
        * decoders.  They represent the base case functionality expected
        * of all decoders.
        */


       /*!\brief Initialization Configurations
        *
        * This structure is used to pass init time configuration options
        * to the decoder.
        */
       typedef struct vpx_codec_dec_cfg
       {
           unsigned int threads; /**< Maximum number of threads to use,
               default 1 */
           unsigned int w;      /**< Width */
           unsigned int h;      /**< Height */
       } vpx_codec_dec_cfg_t; /**< alias for struct vpx_codec_dec_cfg */


       /*!\brief Initialize a decoder instance
        *
        * Initializes a decoder context using the given interface.
        * Applications should call the vpx_codec_dec_init convenience
        * macro instead of this function directly, to ensure that the
        * ABI version number parameter is properly initialized.
        *
        * In XMA mode (activated by setting VPX_CODEC_USE_XMA in the
        * flags parameter), the storage pointed to by the cfg parameter
        * must be kept readable and stable until all memory maps have
        * been set.
        *
        * \param[in]    ctx     Pointer to this instance's context.
        * \param[in]    iface   Pointer to the algorithm interface to
        *                       use.
        * \param[in]    cfg     Configuration to use, if known.  May be
        *                       NULL.

Top      Up      ToC       Page 266 
        * \param[in]    flags   Bitfield of VPX_CODEC_USE_* flags
        * \param[in]    ver     ABI version number.  Must be set to
        *                       VPX_DECODER_ABI_VERSION
        * \retval #VPX_CODEC_OK
        *     The decoder algorithm initialized.
        * \retval #VPX_CODEC_MEM_ERROR
        *     Memory allocation failed.
        */
       vpx_codec_err_t vpx_codec_dec_init_ver(
           vpx_codec_ctx_t      *ctx,
           vpx_codec_iface_t    *iface,
           vpx_codec_dec_cfg_t  *cfg,
           vpx_codec_flags_t     flags,
           int                   ver);

       /*!\brief Convenience macro for vpx_codec_dec_init_ver()
        *
        * Ensures the ABI version parameter is properly set.
        */
   #define vpx_codec_dec_init(ctx, iface, cfg, flags) \
       vpx_codec_dec_init_ver(ctx, iface, cfg, flags, \
       VPX_DECODER_ABI_VERSION)


       /*!\brief Parse stream info from a buffer
        *
        * Performs high level parsing of the bitstream.  Construction of
        * a decoder context is not necessary.  Can be used to determine
        * if the bitstream is of the proper format, and to extract
        * information from the stream.
        *
        * \param[in]      iface   Pointer to the algorithm interface
        * \param[in]      data    Pointer to a block of data to parse
        * \param[in]      data_sz Size of the data buffer
        * \param[in,out]  si      Pointer to stream info to update.  The
        *                         size member
        *                         \ref MUST be properly initialized, but
        *                         \ref MAY be clobbered by the
        *                         algorithm.  This parameter \ref MAY be
        *                         NULL.
        *
        * \retval #VPX_CODEC_OK
        *     Bitstream is parsable and stream information updated
        */

Top      Up      ToC       Page 267 
       vpx_codec_err_t vpx_codec_peek_stream_info(
           vpx_codec_iface_t       *iface,
           const uint8_t           *data,
           unsigned int             data_sz,
           vpx_codec_stream_info_t *si);

       /*!\brief Return information about the current stream.
        *
        * Returns information about the stream that has been parsed
        * during decoding.
        *
        * \param[in]      ctx     Pointer to this instance's context
        * \param[in,out]  si      Pointer to stream info to update.  The
        *                         size member \ref MUST be properly
        *                         initialized, but \ref MAY be clobbered
        *                         by the algorithm.  This parameter \ref
        *                         MAY be NULL.
        *
        * \retval #VPX_CODEC_OK
        *     Bitstream is parsable and stream information updated
        */
       vpx_codec_err_t vpx_codec_get_stream_info(
           vpx_codec_ctx_t         *ctx,
           vpx_codec_stream_info_t *si);


       /*!\brief Decode data
        *
        * Processes a buffer of coded data.  If the processing results
        * in a new decoded frame becoming available, PUT_SLICE and
        * PUT_FRAME events may be generated, as appropriate.  Encoded
        * data \ref MUST be passed in DTS (decode time stamp) order.
        * Frames produced will always be in PTS (presentation time
        * stamp) order.
        *
        * \param[in] ctx          Pointer to this instance's context
        * \param[in] data         Pointer to this block of new coded
        *                         data.  If NULL, a
        *                         VPX_CODEC_CB_PUT_FRAME event is posted
        *                         for the previously decoded frame.
        * \param[in] data_sz      Size of the coded data, in bytes.
        * \param[in] user_priv    Application-specific data to associate
        *                         with this frame.
        * \param[in] deadline     Soft deadline the decoder should
        *                         attempt to meet, in us.  Set to zero
        *                         for unlimited.
        *

Top      Up      ToC       Page 268 
        * \return Returns #VPX_CODEC_OK if the coded data was processed
        *         completely and future pictures can be decoded without
        *         error.  Otherwise, see the descriptions of the other
        *         error codes in ::vpx_codec_err_t for recoverability
        *         capabilities.
        */
       vpx_codec_err_t vpx_codec_decode(vpx_codec_ctx_t    *ctx,
                                        const uint8_t        *data,
                                        unsigned int            data_sz,
                                        void               *user_priv,
                                        long                deadline);


       /*!\brief Decoded frames iterator
        *
        * Iterates over a list of the frames available for display.  The
        * iterator storage should be initialized to NULL to start the
        * iteration.  Iteration is complete when this function returns
        * NULL.
        *
        * The list of available frames becomes valid upon completion of
        * the vpx_codec_decode call, and remains valid until the next
        * call to vpx_codec_decode.
        *
        * \param[in]     ctx      Pointer to this instance's context
        * \param[in,out] iter     Iterator storage, initialized to NULL
        *
        * \return Returns a pointer to an image, if one is ready for
        *         display.  Frames produced will always be in PTS
        *         (presentation time stamp) order.
        */
       vpx_image_t *vpx_codec_get_frame(vpx_codec_ctx_t  *ctx,
                                        vpx_codec_iter_t *iter);


       /*!\defgroup cap_put_frame Frame-Based Decoding Functions
        *
        * The following functions are required to be implemented for all
        * decoders that advertise the VPX_CODEC_CAP_PUT_FRAME
        * capability.  Calling these functions for codecs that don't
        * advertise this capability will result in an error code being
        * returned, usually VPX_CODEC_ERROR
        * @{
        */

Top      Up      ToC       Page 269 
       /*!\brief put frame callback prototype
        *
        * This callback is invoked by the decoder to notify the
        * application of the availability of decoded image data.
        */
       typedef void (*vpx_codec_put_frame_cb_fn_t)(
           void        *user_priv,
           const vpx_image_t *img);

       /*!\brief Register for notification of frame completion.
        *
        * Registers a given function to be called when a decoded frame
        * is available.
        *
        * \param[in] ctx          Pointer to this instance's context
        * \param[in] cb           Pointer to the callback function
        * \param[in] user_priv    User's private data
        *
        * \retval #VPX_CODEC_OK
        *     Callback successfully registered.
        * \retval #VPX_CODEC_ERROR
        *     Decoder context not initialized, or algorithm not capable
        *     of posting slice completion.
        */
       vpx_codec_err_t vpx_codec_register_put_frame_cb(
           vpx_codec_ctx_t             *ctx,
           vpx_codec_put_frame_cb_fn_t  cb,
           void                        *user_priv);


       /*!@} - end defgroup cap_put_frame */

       /*!\defgroup cap_put_slice Slice-Based Decoding Functions
        *
        * The following functions are required to be implemented for all
        * decoders that advertise the VPX_CODEC_CAP_PUT_SLICE
        * capability.  Calling these functions for codecs that don't
        * advertise this capability will result in an error code being
        * returned, usually VPX_CODEC_ERROR
        * @{
        */

       /*!\brief put slice callback prototype
        *
        * This callback is invoked by the decoder to notify the
        * application of the availability of partially decoded image
        * data.
        */

Top      Up      ToC       Page 270 
       typedef void (*vpx_codec_put_slice_cb_fn_t)(
           void         *user_priv,
           const vpx_image_t      *img,
           const vpx_image_rect_t *valid,
           const vpx_image_rect_t *update);


       /*!\brief Register for notification of slice completion.
        *
        * Registers a given function to be called when a decoded slice
        * is available.
        *
        * \param[in] ctx          Pointer to this instance's context
        * \param[in] cb           Pointer to the callback function
        * \param[in] user_priv    User's private data
        *
        * \retval #VPX_CODEC_OK
        *     Callback successfully registered.
        * \retval #VPX_CODEC_ERROR
        *     Decoder context not initialized, or algorithm not capable
        *     of posting slice completion.
        */
       vpx_codec_err_t vpx_codec_register_put_slice_cb(
           vpx_codec_ctx_t             *ctx,
           vpx_codec_put_slice_cb_fn_t  cb,
           void                        *user_priv);


       /*!@} - end defgroup cap_put_slice*/

       /*!@} - end defgroup decoder*/

   #endif

   #ifdef __cplusplus
   }
   #endif

   #if !defined(VPX_CODEC_DISABLE_COMPAT) || !VPX_CODEC_DISABLE_COMPAT
   #include "vpx_decoder_compat.h"
   #endif

   ---- End code block ----------------------------------------

Top      Up      ToC       Page 271 
20.21.  vpx_decoder_compat.h

   ---- Begin code block --------------------------------------

   /*
    * Copyright (c) 2010, 2011, Google Inc.  All rights reserved.
    *
    * Use of this source code is governed by a BSD-style license
    * that can be found in the LICENSE file in the root of the source
    * tree.  An additional intellectual property rights grant can be
    * found in the file PATENTS.  All contributing project authors may
    * be found in the AUTHORS file in the root of the source tree.
    */

   /*!\defgroup decoder Common Decoder Algorithm Interface
    * This abstraction allows applications using this decoder to easily
    * support multiple video formats with minimal code duplication.
    * This section describes the interface common to all codecs.
    * @{
    */

   /*!\file
    * \brief Provides a compatibility layer between version 1 and 2 of
    * this API.
    *
    * This interface has been deprecated.  Only existing code should
    * make use of this interface, and therefore, it is only thinly
    * documented.  Existing code should be ported to the vpx_codec_*
    * API.
    */
   #ifdef __cplusplus
   extern "C" {
   #endif

   #ifndef VPX_DECODER_COMPAT_H
   #define VPX_DECODER_COMPAT_H

Top      Up      ToC       Page 272 
       /*!\brief Decoder algorithm return codes */
       typedef enum {
           /*!\brief Operation completed without error */
           VPX_DEC_OK = VPX_CODEC_OK,

           /*!\brief Unspecified error */
           VPX_DEC_ERROR = VPX_CODEC_ERROR,

           /*!\brief Memory operation failed */
           VPX_DEC_MEM_ERROR = VPX_CODEC_MEM_ERROR,

           /*!\brief ABI version mismatch */
           VPX_DEC_ABI_MISMATCH = VPX_CODEC_ABI_MISMATCH,

           /*!\brief The given bitstream is not supported.
            *
            * The bitstream was unable to be parsed at the highest
            * level.  The decoder is unable to proceed.  This error \ref
            * SHOULD be treated as fatal to the stream.
            */
           VPX_DEC_UNSUP_BITSTREAM = VPX_CODEC_UNSUP_BITSTREAM,

           /*!\brief Encoded bitstream uses an unsupported feature
            *
            * The decoder does not implement a feature required by the
            * encoder.  This return code should only be used for
            * features that prevent future pictures from being properly
            * decoded.  This error \ref MAY be treated as fatal to the
            * stream or \ref MAY be treated as fatal to the current
            * Group of Pictures (GOP).
            */
           VPX_DEC_UNSUP_FEATURE = VPX_CODEC_UNSUP_FEATURE,

           /*!\brief The coded data for this stream is corrupt or
            * incomplete
            *
            * There was a problem decoding the current frame.  This
            * return code should only be used for failures that prevent
            * future pictures from being properly decoded.  This error
            * \ref MAY be treated as fatal to the stream or \ref MAY be
            * treated as fatal to the current GOP.  If decoding is
            * continued for the current GOP, artifacts may be present.
            */
           VPX_DEC_CORRUPT_FRAME = VPX_CODEC_CORRUPT_FRAME,

Top      Up      ToC       Page 273 
           /*!\brief An application-supplied parameter is not valid.
            *
            */
           VPX_DEC_INVALID_PARAM = VPX_CODEC_INVALID_PARAM,

           /*!\brief An iterator reached the end of list.
            *
            */
           VPX_DEC_LIST_END = VPX_CODEC_LIST_END

       }
       vpx_dec_err_t;

       /*! \brief Decoder capabilities bitfield
        *
        *  Each decoder advertises the capabilities it supports as part
        *  of its ::vpx_dec_iface_t interface structure.  Capabilities
        *  are extra interfaces or functionality, and are not required
        *  to be supported by a decoder.
        *
        *  The available flags are specified by VPX_DEC_CAP_* defines.
        */
       typedef int vpx_dec_caps_t;
   #define VPX_DEC_CAP_PUT_SLICE  0x0001 /**< Will issue put_slice
                                            callbacks */
   #define VPX_DEC_CAP_PUT_FRAME  0x0002 /**< Will issue put_frame
                                            callbacks */

   #define VPX_DEC_CAP_XMA        0x0004 /**< Supports External Memory
                                            Allocation */

       /*!\brief Stream properties
        *
        * This structure is used to query or set properties of the
        * decoded stream.  Algorithms may extend this structure with
        * data specific to their bitstream by setting the sz member
        * appropriately.
        */
   #if 1
       typedef vpx_codec_stream_info_t vpx_dec_stream_info_t;
   #else
       typedef struct
       {
           unsigned int sz;    /**< Size of this structure */
           unsigned int w;     /**< Width (or 0 for unknown/default) */
           unsigned int h;     /**< Height (or 0 for unknown/default) */
           unsigned int is_kf; /**< Current frame is a keyframe */
       } vpx_dec_stream_info_t;

Top      Up      ToC       Page 274 
   #endif


       /*!\brief Decoder interface structure.
        *
        * Contains function pointers and other data private to the
        * decoder implementation.  This structure is opaque to the
        * application.
        */
       typedef const struct vpx_codec_iface vpx_dec_iface_t;
       typedef       struct vpx_codec_priv  vpx_dec_priv_t;

       /*!\brief Iterator
        *
        * Opaque storage used for iterating over lists.
        */
       typedef vpx_codec_iter_t vpx_dec_iter_t;

       /*!\brief Decoder context structure
        *
        * All decoders \ref MUST support this context structure fully.
        * In general, this data should be considered private to the
        * decoder algorithm, and not be manipulated or examined by the
        * calling application.  Applications may reference the 'name'
        * member to get a printable description of the algorithm.
        */
   #if 1
       typedef vpx_codec_ctx_t vpx_dec_ctx_t;
   #else
       typedef struct
       {
           const char          *name;  /**< Printable interface name */
           vpx_dec_iface_t     *iface; /**< Interface pointers */
           vpx_dec_err_t        err;   /**< Last returned error */
           vpx_dec_priv_t      *priv;  /**< Algorithm private storage */
       } vpx_dec_ctx_t;
   #endif


       /*!\brief Return the build configuration
        *
        * Returns a printable string containing an encoded version of
        * the build configuration.  This may be useful to vpx support.
        *
        */
       const char *vpx_dec_build_config(void) DEPRECATED;

Top      Up      ToC       Page 275 
       /*!\brief Return the name for a given interface
        *
        * Returns a human readable string for name of the given decoder
        * interface.
        *
        * \param[in]    iface     Interface pointer
        *
        */
       const char *vpx_dec_iface_name(
           vpx_dec_iface_t *iface) DEPRECATED;


       /*!\brief Convert error number to printable string
        *
        * Returns a human readable string for the last error returned
        * by the algorithm.  The returned error will be one line and
        * will not contain any newline characters.
        *
        *
        * \param[in]    err     Error number.
        *
        */
       const char *vpx_dec_err_to_string(vpx_dec_err_t  err) DEPRECATED;


       /*!\brief Retrieve error synopsis for decoder context
        *
        * Returns a human readable string for the last error returned by
        * the algorithm.  The returned error will be one line and will
        * not contain any newline characters.
        *
        *
        * \param[in]    ctx     Pointer to this instance's context.
        *
        */
       const char *vpx_dec_error(vpx_dec_ctx_t  *ctx) DEPRECATED;


       /*!\brief Retrieve detailed error information for decoder context
        *
        * Returns a human readable string providing detailed information
        * about the last error.
        *
        * \param[in]    ctx     Pointer to this instance's context.
        *

Top      Up      ToC       Page 276 
        * \retval NULL
        *     No detailed information is available.
        */
       const char *vpx_dec_error_detail(vpx_dec_ctx_t  *ctx) DEPRECATED;


       /* REQUIRED FUNCTIONS
        *
        * The following functions are required to be implemented for all
        * decoders.  They represent the base case functionality expected
        * of all decoders.
        */


       /*!\brief Initialize a decoder instance
        *
        * Initializes a decoder context using the given interface.
        * Applications should call the vpx_dec_init convenience macro
        * instead of this function directly, to ensure that the ABI
        * version number parameter is properly initialized.
        *
        * \param[in]   ctx    Pointer to this instance's context.
        * \param[in]   iface  Pointer to the algorithm interface to use.
        * \param[in]   ver    ABI version number.  Must be set to
        *                       VPX_DECODER_ABI_VERSION
        * \retval #VPX_DEC_OK
        *     The decoder algorithm initialized.
        * \retval #VPX_DEC_MEM_ERROR
        *     Memory allocation failed.
        */
       vpx_dec_err_t vpx_dec_init_ver(
           vpx_dec_ctx_t    *ctx,
           vpx_dec_iface_t  *iface,
           int               ver) DEPRECATED;

   #define vpx_dec_init(ctx, iface) \
       vpx_dec_init_ver(ctx, iface, VPX_DECODER_ABI_VERSION)


       /*!\brief Destroy a decoder instance
        *
        * Destroys a decoder context, freeing any associated memory
        * buffers.
        *
        * \param[in] ctx   Pointer to this instance's context
        *
        * \retval #VPX_DEC_OK
        *     The decoder algorithm initialized.

Top      Up      ToC       Page 277 
        * \retval #VPX_DEC_MEM_ERROR
        *     Memory allocation failed.
        */
       vpx_dec_err_t vpx_dec_destroy(vpx_dec_ctx_t *ctx) DEPRECATED;


       /*!\brief Get the capabilities of an algorithm.
        *
        * Retrieves the capabilities bitfield from the algorithm's
        * interface.
        *
        * \param[in] iface   Pointer to the algorithm interface
        *
        */
       vpx_dec_caps_t vpx_dec_get_caps(
           vpx_dec_iface_t *iface) DEPRECATED;


       /*!\brief Parse stream info from a buffer
        *
        * Performs high level parsing of the bitstream.  Construction of
        * a decoder context is not necessary.  Can be used to determine
        * if the bitstream is of the proper format, and to extract
        * information from the stream.
        *
        * \param[in]      iface   Pointer to the algorithm interface
        * \param[in]      data    Pointer to a block of data to parse
        * \param[in]      data_sz Size of the data buffer
        * \param[in,out]  si      Pointer to stream info to update.  The
        *                         size member \ref MUST be properly
        *                         initialized, but \ref MAY be
        *                         clobbered by the algorithm.  This
        *                         parameter \ref MAY be NULL.
        *
        * \retval #VPX_DEC_OK
        *     Bitstream is parsable and stream information updated
        */
       vpx_dec_err_t vpx_dec_peek_stream_info(
                                vpx_dec_iface_t       *iface,
                                const uint8_t         *data,
                                unsigned int           data_sz,
                                vpx_dec_stream_info_t *si) DEPRECATED;

Top      Up      ToC       Page 278 
       /*!\brief Return information about the current stream.
        *
        * Returns information about the stream that has been parsed
        * during decoding.
        *
        * \param[in]      ctx     Pointer to this instance's context
        * \param[in,out]  si      Pointer to stream info to update.
        *                         The size member \ref MUST be properly
        *                         initialized, but \ref MAY be clobbered
        *                         by the algorithm.  This parameter \ref
        *                         MAY be NULL.
        *
        * \retval #VPX_DEC_OK
        *     Bitstream is parsable and stream information updated
        */
       vpx_dec_err_t vpx_dec_get_stream_info(
           vpx_dec_ctx_t         *ctx,
           vpx_dec_stream_info_t *si) DEPRECATED;


       /*!\brief Control algorithm
        *
        * This function is used to exchange algorithm-specific data with
        * the decoder instance.  This can be used to implement features
        * specific to a particular algorithm.
        *
        * This wrapper function dispatches the request to the helper
        * function associated with the given ctrl_id.  It tries to call
        * this function transparently, but will return #VPX_DEC_ERROR if
        * the request could not be dispatched.
        *
        * \param[in]     ctx          Pointer to this instance's context
        * \param[in]     ctrl_id      Algorithm-specific control
        *                             identifier
        * \param[in,out] data         Data to exchange with algorithm
        *                             instance.
        *
        * \retval #VPX_DEC_OK
        *     The control request was processed.
        * \retval #VPX_DEC_ERROR
        *     The control request was not processed.
        * \retval #VPX_DEC_INVALID_PARAM
        *     The data was not valid.
        */
       vpx_dec_err_t vpx_dec_control(vpx_dec_ctx_t  *ctx,
                                     int             ctrl_id,
                                     void           *data) DEPRECATED;

Top      Up      ToC       Page 279 
       /*!\brief Decode data
        *
        * Processes a buffer of coded data.  If the processing results
        * in a new decoded frame becoming available,
        * #VPX_DEC_CB_PUT_SLICE and #VPX_DEC_CB_PUT_FRAME events may be
        * generated, as appropriate.  Encoded data \ref MUST be passed
        * in DTS (decode time stamp) order.  Frames produced will always
        * be in PTS (presentation time stamp) order.
        *
        * \param[in] ctx          Pointer to this instance's context
        * \param[in] data         Pointer to this block of new coded
        *                         data.  If NULL, a VPX_DEC_CB_PUT_FRAME
        *                         event is posted for the previously
        *                         decoded frame.
        * \param[in] data_sz      Size of the coded data, in bytes.
        * \param[in] user_priv    Application-specific data to associate
        *                         with this frame.
        * \param[in] rel_pts      PTS relative to the previous frame, in
        *                         us.  If unknown or unavailable, set to
        *                         zero.
        *
        * \return Returns #VPX_DEC_OK if the coded data was processed
        *         completely and future pictures can be decoded without
        *         error.  Otherwise, see the descriptions of the other
        *         error codes in ::vpx_dec_err_t for recoverability
        *         capabilities.
        */
       vpx_dec_err_t vpx_dec_decode(
           vpx_dec_ctx_t  *ctx,
           uint8_t        *data,
           unsigned int    data_sz,
           void           *user_priv,
           int             rel_pts) DEPRECATED;


       /*!\brief Decoded frames iterator
        *
        * Iterates over a list of the frames available for display.  The
        * iterator storage should be initialized to NULL to start the
        * iteration.  Iteration is complete when this function returns
        * NULL.
        *
        * The list of available frames becomes valid upon completion of
        * the vpx_dec_decode call, and remains valid until the next call
        * to vpx_dec_decode.
        *
        * \param[in]     ctx      Pointer to this instance's context
        * \param[in out] iter     Iterator storage, initialized to NULL

Top      Up      ToC       Page 280 
        *
        * \return Returns a pointer to an image, if one is ready for
        *         display.  Frames produced will always be in PTS
        *         (presentation time stamp) order.
        */
       vpx_image_t *vpx_dec_get_frame(vpx_dec_ctx_t  *ctx,
                                      vpx_dec_iter_t *iter) DEPRECATED;


       /*!\defgroup cap_put_frame Frame-Based Decoding Functions
        *
        * The following functions are required to be implemented for all
        * decoders that advertise the VPX_DEC_CAP_PUT_FRAME capability.
        * Calling these functions for codecs that don't advertise this
        * capability will result in an error code being returned,
        * usually VPX_DEC_ERROR @{
        */

       /*!\brief put frame callback prototype
        *
        * This callback is invoked by the decoder to notify the
        * application of the availability of decoded image data.
        */
       typedef void (*vpx_dec_put_frame_cb_fn_t)(
               void          *user_priv,
               const vpx_image_t *img);


       /*!\brief Register for notification of frame completion.
        *
        * Registers a given function to be called when a decoded frame
        * is available.
        *
        * \param[in] ctx          Pointer to this instance's context
        * \param[in] cb           Pointer to the callback function
        * \param[in] user_priv    User's private data
        *
        * \retval #VPX_DEC_OK
        *     Callback successfully registered.
        * \retval #VPX_DEC_ERROR
        *     Decoder context not initialized, or algorithm not capable
        *     of posting slice completion.
        */
       vpx_dec_err_t vpx_dec_register_put_frame_cb(
               vpx_dec_ctx_t             *ctx,
               vpx_dec_put_frame_cb_fn_t  cb,
               void                      *user_priv) DEPRECATED;

Top      Up      ToC       Page 281 
       /*!@} - end defgroup cap_put_frame */

       /*!\defgroup cap_put_slice Slice-Based Decoding Functions
        *
        * The following functions are required to be implemented for all
        * decoders that advertise the VPX_DEC_CAP_PUT_SLICE capability.
        * Calling these functions for codecs that don't advertise this
        * capability will result in an error code being returned,
        * usually VPX_DEC_ERROR
        * @{
        */

       /*!\brief put slice callback prototype
        *
        * This callback is invoked by the decoder to notify the
        * application of the availability of partially decoded image
        * data.
        */
       typedef void (*vpx_dec_put_slice_cb_fn_t)(void        *user_priv,
               const vpx_image_t      *img,
               const vpx_image_rect_t *valid,
               const vpx_image_rect_t *update);


       /*!\brief Register for notification of slice completion.
        *
        * Registers a given function to be called when a decoded slice
        * is available.
        *
        * \param[in] ctx          Pointer to this instance's context
        * \param[in] cb           Pointer to the callback function
        * \param[in] user_priv    User's private data
        *
        * \retval #VPX_DEC_OK
        *     Callback successfully registered.
        * \retval #VPX_DEC_ERROR
        *     Decoder context not initialized, or algorithm not capable
        *     of posting slice completion.
        */
       vpx_dec_err_t vpx_dec_register_put_slice_cb(vpx_dec_ctx_t   *ctx,
               vpx_dec_put_slice_cb_fn_t  cb,
               void                      *user_priv) DEPRECATED;


       /*!@} - end defgroup cap_put_slice*/

Top      Up      ToC       Page 282 
       /*!\defgroup cap_xma External Memory Allocation Functions
        *
        * The following functions are required to be implemented for all
        * decoders that advertise the VPX_DEC_CAP_XMA capability.
        * Calling these functions for codecs that don't advertise this
        * capability will result in an error code being returned,
        * usually VPX_DEC_ERROR
        * @{
        */

       /*!\brief Memory Map Entry
        *
        * This structure is used to contain the properties of a memory
        * segment.  It is populated by the decoder in the request phase,
        * and by the calling application once the requested allocation
        * has been performed.
        */
   #if 1
   #define VPX_DEC_MEM_ZERO     0x1  /**< Segment must be zeroed by
                                          allocation */
   #define VPX_DEC_MEM_WRONLY   0x2  /**< Segment need not be
                                          readable */
   #define VPX_DEC_MEM_FAST     0x4  /**< Place in fast memory, if
                                          available */
       typedef struct vpx_codec_mmap vpx_dec_mmap_t;
   #else
       typedef struct vpx_dec_mmap
       {
           /*
            * The following members are set by the codec when requesting
            * a segment
            */
           unsigned int   id;     /**< identifier for the segment's
                                       contents */
           unsigned long  sz;     /**< size of the segment, in bytes */
           unsigned int   align;  /**< required alignment of the
                                       segment, in bytes */
           unsigned int   flags;  /**< bitfield containing segment
                                       properties */
   #define VPX_DEC_MEM_ZERO     0x1  /**< Segment must be zeroed by
                                          allocation */
   #define VPX_DEC_MEM_WRONLY   0x2  /**< Segment need not be
                                          readable */
   #define VPX_DEC_MEM_FAST     0x4  /**< Place in fast memory, if
                                          available */

Top      Up      ToC       Page 283 
           /* The following members are to be filled in by the
            * allocation function */
           void          *base;   /**< pointer to the allocated
                                       segment */
           void (*dtor)(struct vpx_dec_mmap *map);  /**< destructor to
                                                         call */
           void          *priv;   /**< allocator private storage */
       } vpx_dec_mmap_t;
   #endif

       /*!\brief Initialize a decoder instance in external allocation
        * mode
        *
        * Initializes a decoder context using the given interface.
        * Applications should call the vpx_dec_xma_init convenience
        * macro instead of this function directly, to ensure that the
        * ABI version number parameter is properly initialized.
        *
        * \param[in]    ctx     Pointer to this instance's context.
        * \param[in]    iface   Pointer to the algorithm interface to
        *                       use.
        * \param[in]    ver     ABI version number.  Must be set to
        *                       VPX_DECODER_ABI_VERSION
        * \retval #VPX_DEC_OK
        *     The decoder algorithm initialized.
        * \retval #VPX_DEC_ERROR
        *     Decoder does not support XMA mode.
        */
       vpx_dec_err_t vpx_dec_xma_init_ver(vpx_dec_ctx_t    *ctx,
                                          vpx_dec_iface_t  *iface,
                                          int           ver) DEPRECATED;
   #define vpx_dec_xma_init(ctx, iface) \
       vpx_dec_xma_init_ver(ctx, iface, VPX_DECODER_ABI_VERSION)


       /*!\brief Iterate over the list of segments to allocate.
        *
        * Iterates over a list of the segments to allocate.  The
        * iterator storage should be initialized to NULL to start the
        * iteration.  Iteration is complete when this function returns
        * VPX_DEC_LIST_END.  The amount of memory needed to allocate is
        * dependent upon the size of the encoded stream.  This means
        * that the stream info structure must be known at allocation
        * time.  It can be populated with the vpx_dec_peek_stream_info()
        * function.  In cases where the stream to be decoded is not
        * available at allocation time, a fixed size must be requested.
        * The decoder will not be able to decode streams larger than the
        * size used at allocation time.

Top      Up      ToC       Page 284 
        *
        * \param[in]      ctx     Pointer to this instance's context.
        * \param[out]     mmap    Pointer to the memory map entry to
        *                         populate.
        * \param[in]      si      Pointer to the stream info.
        * \param[in out]  iter    Iterator storage, initialized to NULL
        *
        * \retval #VPX_DEC_OK
        *     The memory map entry was populated.
        * \retval #VPX_DEC_ERROR
        *     Decoder does not support XMA mode.
        * \retval #VPX_DEC_MEM_ERROR
        *     Unable to determine segment size from stream info.
        */
       vpx_dec_err_t vpx_dec_get_mem_map(
           vpx_dec_ctx_t                *ctx,
           vpx_dec_mmap_t               *mmap,
           const vpx_dec_stream_info_t  *si,
           vpx_dec_iter_t               *iter) DEPRECATED;


       /*!\brief Identify allocated segments to decoder instance
        *
        * Stores a list of allocated segments in the decoder.  Segments
        * \ref MUST be passed in the order they are read from
        * vpx_dec_get_mem_map(), but may be passed in groups of any
        * size.  Segments \ref MUST be set only once.  The allocation
        * function \ref MUST ensure that the vpx_dec_mmap_t::base member
        * is non-NULL.  If the segment requires cleanup handling (e.g.,
        * calling free() or close()) then the vpx_dec_mmap_t::dtor
        * member \ref MUST be populated.
        *
        * \param[in]      ctx       Pointer to this instance's context.
        * \param[in]      mmaps     Pointer to the first memory map
        *                           entry in the list.
        * \param[in]      num_maps  Number of entries being set at this
        *                           time
        *
        * \retval #VPX_DEC_OK
        *     The segment was stored in the decoder context.
        * \retval #VPX_DEC_ERROR
        *     Decoder does not support XMA mode.
        * \retval #VPX_DEC_MEM_ERROR
        *     Segment base address was not set, or segment was already
        * stored.

        */

Top      Up      ToC       Page 285 
       vpx_dec_err_t  vpx_dec_set_mem_map(
           vpx_dec_ctx_t   *ctx,
           vpx_dec_mmap_t  *mmaps,
           unsigned int     num_maps) DEPRECATED;

       /*!@} - end defgroup cap_xma*/
       /*!@} - end defgroup decoder*/


   #endif
   #ifdef __cplusplus
   }
   #endif

   ---- End code block ----------------------------------------

20.22.  vpx_image.c

   ---- Begin code block --------------------------------------

   /*
    * Copyright (c) 2010, 2011, Google Inc.  All rights reserved.
    *
    * Use of this source code is governed by a BSD-style license
    * that can be found in the LICENSE file in the root of the source
    * tree.  An additional intellectual property rights grant can be
    * found in the file PATENTS.  All contributing project authors may
    * be found in the AUTHORS file in the root of the source tree.
    */


   #include <stdlib.h>
   #include <string.h>
   #include "vpx/vpx_image.h"

   static vpx_image_t *img_alloc_helper(vpx_image_t  *img,
                                        vpx_img_fmt_t fmt,
                                        unsigned int  d_w,
                                        unsigned int  d_h,
                                        unsigned int  stride_align,
                                        unsigned char      *img_data)
   {

Top      Up      ToC       Page 286 
       unsigned int  h, w, s, xcs, ycs, bps;
       int           align;

       /* Treat align==0 like align==1 */
       if (!stride_align)
           stride_align = 1;

       /* Validate alignment (must be power of 2) */
       if (stride_align & (stride_align - 1))
           goto fail;

       /* Get sample size for this format */
       switch (fmt)
       {
       case VPX_IMG_FMT_RGB32:
       case VPX_IMG_FMT_RGB32_LE:
       case VPX_IMG_FMT_ARGB:
       case VPX_IMG_FMT_ARGB_LE:
           bps = 32;
           break;
       case VPX_IMG_FMT_RGB24:
       case VPX_IMG_FMT_BGR24:
           bps = 24;
           break;
       case VPX_IMG_FMT_RGB565:
       case VPX_IMG_FMT_RGB565_LE:
       case VPX_IMG_FMT_RGB555:
       case VPX_IMG_FMT_RGB555_LE:
       case VPX_IMG_FMT_UYVY:
       case VPX_IMG_FMT_YUY2:
       case VPX_IMG_FMT_YVYU:
           bps = 16;
           break;
       case VPX_IMG_FMT_I420:
       case VPX_IMG_FMT_YV12:
       case VPX_IMG_FMT_VPXI420:
       case VPX_IMG_FMT_VPXYV12:
           bps = 12;
           break;
       default:
           bps = 16;
           break;
       }

Top      Up      ToC       Page 287 
       /* Get chroma shift values for this format */
       switch (fmt)
       {
       case VPX_IMG_FMT_I420:
       case VPX_IMG_FMT_YV12:
       case VPX_IMG_FMT_VPXI420:
       case VPX_IMG_FMT_VPXYV12:
           xcs = 1;
           break;
       default:
           xcs = 0;
           break;
       }

       switch (fmt)
       {
       case VPX_IMG_FMT_I420:
       case VPX_IMG_FMT_YV12:
       case VPX_IMG_FMT_VPXI420:
       case VPX_IMG_FMT_VPXYV12:
           ycs = 1;
           break;
       default:
           ycs = 0;
           break;
       }

       /* Calculate storage sizes given the chroma subsampling */
       align = (1 << xcs) - 1;
       w = (d_w + align) & ~align;
       align = (1 << ycs) - 1;
       h = (d_h + align) & ~align;
       s = (fmt & VPX_IMG_FMT_PLANAR) ? w : bps * w / 8;
       s = (s + stride_align - 1) & ~(stride_align - 1);

       /* Allocate the new image */
       if (!img)
       {
           img = (vpx_image_t *)calloc(1, sizeof(vpx_image_t));

           if (!img)
               goto fail;

           img->self_allocd = 1;
       }

Top      Up      ToC       Page 288 
       else
       {
           memset(img, 0, sizeof(vpx_image_t));
       }

       img->img_data = img_data;

       if (!img_data)
       {
           img->img_data = malloc((fmt & VPX_IMG_FMT_PLANAR) ?
             h * w * bps / 8 : h * s);
           img->img_data_owner = 1;
       }

       if (!img->img_data)
           goto fail;

       img->fmt = fmt;
       img->w = w;
       img->h = h;
       img->x_chroma_shift = xcs;
       img->y_chroma_shift = ycs;
       img->bps = bps;

       /* Calculate strides */
       img->stride[VPX_PLANE_Y] = img->stride[VPX_PLANE_ALPHA] = s;
       img->stride[VPX_PLANE_U] = img->stride[VPX_PLANE_V] = s >> xcs;

       /* Default viewport to entire image */
       if (!vpx_img_set_rect(img, 0, 0, d_w, d_h))
           return img;

   fail:
       vpx_img_free(img);
       return NULL;
   }

   vpx_image_t *vpx_img_alloc(vpx_image_t  *img,
                              vpx_img_fmt_t fmt,
                              unsigned int  d_w,
                              unsigned int  d_h,
                              unsigned int  stride_align)
   {
       return img_alloc_helper(img, fmt, d_w, d_h, stride_align, NULL);
   }

Top      Up      ToC       Page 289 
   vpx_image_t *vpx_img_wrap(vpx_image_t  *img,
                             vpx_img_fmt_t fmt,
                             unsigned int  d_w,
                             unsigned int  d_h,
                             unsigned int  stride_align,
                             unsigned char       *img_data)
   {
       return img_alloc_helper(img, fmt, d_w, d_h, stride_align,
         img_data);
   }

   int vpx_img_set_rect(vpx_image_t  *img,
                        unsigned int  x,
                        unsigned int  y,
                        unsigned int  w,
                        unsigned int  h)
   {
       unsigned char      *data;

       if (x + w <= img->w && y + h <= img->h)
       {
           img->d_w = w;
           img->d_h = h;

           /* Calculate plane pointers */
           if (!(img->fmt & VPX_IMG_FMT_PLANAR))
           {
               img->planes[VPX_PLANE_PACKED] =
                   img->img_data + x * img->bps / 8 + y *
                     img->stride[VPX_PLANE_PACKED];
           }
           else
           {
               data = img->img_data;

               if (img->fmt & VPX_IMG_FMT_HAS_ALPHA)
               {
                   img->planes[VPX_PLANE_ALPHA] =
                       data + x + y * img->stride[VPX_PLANE_ALPHA];
                   data += img->h * img->stride[VPX_PLANE_ALPHA];
               }

               img->planes[VPX_PLANE_Y] =
                 data + x + y * img->stride[VPX_PLANE_Y];
               data += img->h * img->stride[VPX_PLANE_Y];

Top      Up      ToC       Page 290 
               if (!(img->fmt & VPX_IMG_FMT_UV_FLIP))
               {
                   img->planes[VPX_PLANE_U] = data
                                          + (x >> img->x_chroma_shift)
                                          + (y >> img->y_chroma_shift) *
                                            img->stride[VPX_PLANE_U];
                   data += (img->h >> img->y_chroma_shift) *
                                            img->stride[VPX_PLANE_U];
                   img->planes[VPX_PLANE_V] = data
                                          + (x >> img->x_chroma_shift)
                                          + (y >> img->y_chroma_shift) *
                                            img->stride[VPX_PLANE_V];
               }
               else
               {
                   img->planes[VPX_PLANE_V] = data
                                          + (x >> img->x_chroma_shift)
                                          + (y >> img->y_chroma_shift) *
                                            img->stride[VPX_PLANE_V];
                   data += (img->h >> img->y_chroma_shift) *
                                            img->stride[VPX_PLANE_V];
                   img->planes[VPX_PLANE_U] = data
                                          + (x >> img->x_chroma_shift)
                                          + (y >> img->y_chroma_shift) *
                                            img->stride[VPX_PLANE_U];
               }
           }

           return 0;
       }

       return -1;
   }

   void vpx_img_flip(vpx_image_t *img)
   {
       /* Note: In the calculation pointer adjustment calculation, we
        * want the rhs to be promoted to a signed type.  Section 6.3.1.8
        * of the ISO C99 standard [ISO-C99] indicates that if the
        * adjustment parameter is unsigned, the stride parameter will be
        * promoted to unsigned, causing errors when the lhs is a larger
        * type than the rhs.
        */
       img->planes[VPX_PLANE_Y] += (signed)
         (img->d_h - 1) * img->stride[VPX_PLANE_Y];
       img->stride[VPX_PLANE_Y] = -img->stride[VPX_PLANE_Y];

Top      Up      ToC       Page 291 
       img->planes[VPX_PLANE_U] += (signed)
         ((img->d_h >> img->y_chroma_shift) - 1)
                               * img->stride[VPX_PLANE_U];
       img->stride[VPX_PLANE_U] = -img->stride[VPX_PLANE_U];

       img->planes[VPX_PLANE_V] += (signed)
                               ((img->d_h >> img->y_chroma_shift) - 1) *
                               img->stride[VPX_PLANE_V];
       img->stride[VPX_PLANE_V] = -img->stride[VPX_PLANE_V];

       img->planes[VPX_PLANE_ALPHA] += (signed)
         (img->d_h - 1) * img->stride[VPX_PLANE_ALPHA];
       img->stride[VPX_PLANE_ALPHA] = -img->stride[VPX_PLANE_ALPHA];
   }

   void vpx_img_free(vpx_image_t *img)
   {
       if (img)
       {
           if (img->img_data && img->img_data_owner)
               free(img->img_data);

           if (img->self_allocd)
               free(img);
       }
   }

   ---- End code block ----------------------------------------



(page 291 continued on part 11)

Next RFC Part