| /* |
| * 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 |
