RFC 6386
VP8 Data Format and Decoding Guide
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"
/*!\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.
*/
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.
* \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
*/
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.
*
* \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
* @{
*/
/*!\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.
*/
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 ----------------------------------------
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
/*!\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,
/*!\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;
#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;
/*!\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.
*
* \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.
* \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;
/*!\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;
/*!\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
*
* \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;
/*!@} - 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*/
/*!\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 */
/* 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.
*
* \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.
*/
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)
{
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;
}
/* 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;
}
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);
}
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];
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];
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)
