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