Tech-invite3GPPspaceIETF RFCsSIP
93929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 6386

VP8 Data Format and Decoding Guide

Pages: 304
Informational
Errata
Part 10 of 11 – Pages 263 to 291
First   Prev   Next

Top   ToC   RFC6386 - Page 263   prevText

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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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   ToC   RFC6386 - 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 Section