• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (c) 2016, Alliance for Open Media. All rights reserved
3  *
4  * This source code is subject to the terms of the BSD 2 Clause License and
5  * the Alliance for Open Media Patent License 1.0. If the BSD 2 Clause License
6  * was not distributed with this source code in the LICENSE file, you can
7  * obtain it at www.aomedia.org/license/software. If the Alliance for Open
8  * Media Patent License 1.0 was not distributed with this source code in the
9  * PATENTS file, you can obtain it at www.aomedia.org/license/patent.
10  */
11 #ifndef AOM_AOM_AOM_DECODER_H_
12 #define AOM_AOM_AOM_DECODER_H_
13 
14 /*!\defgroup decoder Decoder Algorithm Interface
15  * \ingroup codec
16  * This abstraction allows applications using this decoder to easily support
17  * multiple video formats with minimal code duplication. This section describes
18  * the interface common to all decoders.
19  * @{
20  */
21 
22 /*!\file
23  * \brief Describes the decoder algorithm interface to applications.
24  *
25  * This file describes the interface between an application and a
26  * video decoder algorithm.
27  *
28  */
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32 
33 #include "aom/aom_codec.h"
34 #include "aom/aom_frame_buffer.h"
35 
36 /*!\brief Current ABI version number
37  *
38  * \internal
39  * If this file is altered in any way that changes the ABI, this value
40  * must be bumped.  Examples include, but are not limited to, changing
41  * types, removing or reassigning enums, adding/removing/rearranging
42  * fields to structures
43  */
44 #define AOM_DECODER_ABI_VERSION \
45   (3 + AOM_CODEC_ABI_VERSION) /**<\hideinitializer*/
46 
47 /*! \brief Decoder capabilities bitfield
48  *
49  *  Each decoder advertises the capabilities it supports as part of its
50  *  ::aom_codec_iface_t interface structure. Capabilities are extra interfaces
51  *  or functionality, and are not required to be supported by a decoder.
52  *
53  *  The available flags are specified by AOM_CODEC_CAP_* defines.
54  */
55 #define AOM_CODEC_CAP_PUT_SLICE 0x10000 /**< Will issue put_slice callbacks */
56 #define AOM_CODEC_CAP_PUT_FRAME 0x20000 /**< Will issue put_frame callbacks */
57 #define AOM_CODEC_CAP_POSTPROC 0x40000  /**< Can postprocess decoded frame */
58 
59 /*! \brief Initialization-time Feature Enabling
60  *
61  *  Certain codec features must be known at initialization time, to allow for
62  *  proper memory allocation.
63  *
64  *  The available flags are specified by AOM_CODEC_USE_* defines.
65  */
66 /*!brief Can support external frame buffers */
67 #define AOM_CODEC_CAP_EXTERNAL_FRAME_BUFFER 0x200000
68 
69 #define AOM_CODEC_USE_POSTPROC 0x10000 /**< Postprocess decoded frame */
70 
71 /*!\brief Stream properties
72  *
73  * This structure is used to query or set properties of the decoded
74  * stream.
75  */
76 typedef struct aom_codec_stream_info {
77   unsigned int w;                      /**< Width (or 0 for unknown/default) */
78   unsigned int h;                      /**< Height (or 0 for unknown/default) */
79   unsigned int is_kf;                  /**< Current frame is a keyframe */
80   unsigned int number_spatial_layers;  /**< Number of spatial layers */
81   unsigned int number_temporal_layers; /**< Number of temporal layers */
82   unsigned int is_annexb;              /**< Is Bitstream in Annex-B format */
83 } aom_codec_stream_info_t;
84 
85 /* REQUIRED FUNCTIONS
86  *
87  * The following functions are required to be implemented for all decoders.
88  * They represent the base case functionality expected of all decoders.
89  */
90 
91 /*!\brief Initialization Configurations
92  *
93  * This structure is used to pass init time configuration options to the
94  * decoder.
95  */
96 typedef struct aom_codec_dec_cfg {
97   unsigned int threads; /**< Maximum number of threads to use, default 1 */
98   unsigned int w;       /**< Width */
99   unsigned int h;       /**< Height */
100   unsigned int allow_lowbitdepth; /**< Allow use of low-bitdepth coding path */
101   cfg_options_t cfg;              /**< Options defined per config attributes */
102 } aom_codec_dec_cfg_t;            /**< alias for struct aom_codec_dec_cfg */
103 
104 /*!\brief Initialize a decoder instance
105  *
106  * Initializes a decoder context using the given interface. Applications
107  * should call the aom_codec_dec_init convenience macro instead of this
108  * function directly, to ensure that the ABI version number parameter
109  * is properly initialized.
110  *
111  * If the library was configured with --disable-multithread, this call
112  * is not thread safe and should be guarded with a lock if being used
113  * in a multithreaded context.
114  *
115  * \param[in]    ctx     Pointer to this instance's context.
116  * \param[in]    iface   Pointer to the algorithm interface to use.
117  * \param[in]    cfg     Configuration to use, if known. May be NULL.
118  * \param[in]    flags   Bitfield of AOM_CODEC_USE_* flags
119  * \param[in]    ver     ABI version number. Must be set to
120  *                       AOM_DECODER_ABI_VERSION
121  * \retval #AOM_CODEC_OK
122  *     The decoder algorithm initialized.
123  * \retval #AOM_CODEC_MEM_ERROR
124  *     Memory allocation failed.
125  */
126 aom_codec_err_t aom_codec_dec_init_ver(aom_codec_ctx_t *ctx,
127                                        aom_codec_iface_t *iface,
128                                        const aom_codec_dec_cfg_t *cfg,
129                                        aom_codec_flags_t flags, int ver);
130 
131 /*!\brief Convenience macro for aom_codec_dec_init_ver()
132  *
133  * Ensures the ABI version parameter is properly set.
134  */
135 #define aom_codec_dec_init(ctx, iface, cfg, flags) \
136   aom_codec_dec_init_ver(ctx, iface, cfg, flags, AOM_DECODER_ABI_VERSION)
137 
138 /*!\brief Parse stream info from a buffer
139  *
140  * Performs high level parsing of the bitstream. Construction of a decoder
141  * context is not necessary. Can be used to determine if the bitstream is
142  * of the proper format, and to extract information from the stream.
143  *
144  * \param[in]      iface   Pointer to the algorithm interface
145  * \param[in]      data    Pointer to a block of data to parse
146  * \param[in]      data_sz Size of the data buffer
147  * \param[in,out]  si      Pointer to stream info to update. The is_annexb
148  *                         member \ref MUST be properly initialized. This
149  *                         function sets the rest of the members.
150  *
151  * \retval #AOM_CODEC_OK
152  *     Bitstream is parsable and stream information updated.
153  * \retval #AOM_CODEC_INVALID_PARAM
154  *     One of the arguments is invalid, for example a NULL pointer.
155  * \retval #AOM_CODEC_UNSUP_BITSTREAM
156  *     The decoder didn't recognize the coded data, or the
157  *     buffer was too short.
158  */
159 aom_codec_err_t aom_codec_peek_stream_info(aom_codec_iface_t *iface,
160                                            const uint8_t *data, size_t data_sz,
161                                            aom_codec_stream_info_t *si);
162 
163 /*!\brief Return information about the current stream.
164  *
165  * Returns information about the stream that has been parsed during decoding.
166  *
167  * \param[in]      ctx     Pointer to this instance's context
168  * \param[in,out]  si      Pointer to stream info to update.
169  *
170  * \retval #AOM_CODEC_OK
171  *     Bitstream is parsable and stream information updated.
172  * \retval #AOM_CODEC_INVALID_PARAM
173  *     One of the arguments is invalid, for example a NULL pointer.
174  * \retval #AOM_CODEC_UNSUP_BITSTREAM
175  *     The decoder couldn't parse the submitted data.
176  */
177 aom_codec_err_t aom_codec_get_stream_info(aom_codec_ctx_t *ctx,
178                                           aom_codec_stream_info_t *si);
179 
180 /*!\brief Decode data
181  *
182  * Processes a buffer of coded data. If the processing results in a new
183  * decoded frame becoming available, PUT_SLICE and PUT_FRAME events may be
184  * generated, as appropriate. Encoded data \ref MUST be passed in DTS (decode
185  * time stamp) order. Frames produced will always be in PTS (presentation
186  * time stamp) order.
187  *
188  * \param[in] ctx          Pointer to this instance's context
189  * \param[in] data         Pointer to this block of new coded data. If
190  *                         NULL, a AOM_CODEC_CB_PUT_FRAME event is posted
191  *                         for the previously decoded frame.
192  * \param[in] data_sz      Size of the coded data, in bytes.
193  * \param[in] user_priv    Application specific data to associate with
194  *                         this frame.
195  *
196  * \return Returns #AOM_CODEC_OK if the coded data was processed completely
197  *         and future pictures can be decoded without error. Otherwise,
198  *         see the descriptions of the other error codes in ::aom_codec_err_t
199  *         for recoverability capabilities.
200  */
201 aom_codec_err_t aom_codec_decode(aom_codec_ctx_t *ctx, const uint8_t *data,
202                                  size_t data_sz, void *user_priv);
203 
204 /*!\brief Decoded frames iterator
205  *
206  * Iterates over a list of the frames available for display. The iterator
207  * storage should be initialized to NULL to start the iteration. Iteration is
208  * complete when this function returns NULL.
209  *
210  * The list of available frames becomes valid upon completion of the
211  * aom_codec_decode call, and remains valid until the next call to
212  * aom_codec_decode.
213  *
214  * \param[in]     ctx      Pointer to this instance's context
215  * \param[in,out] iter     Iterator storage, initialized to NULL
216  *
217  * \return Returns a pointer to an image, if one is ready for display. Frames
218  *         produced will always be in PTS (presentation time stamp) order.
219  */
220 aom_image_t *aom_codec_get_frame(aom_codec_ctx_t *ctx, aom_codec_iter_t *iter);
221 
222 /*!\defgroup cap_put_frame Frame-Based Decoding Functions
223  *
224  * The following functions are required to be implemented for all decoders
225  * that advertise the AOM_CODEC_CAP_PUT_FRAME capability. Calling these
226  * functions
227  * for codecs that don't advertise this capability will result in an error
228  * code being returned, usually AOM_CODEC_ERROR
229  * @{
230  */
231 
232 /*!\brief put frame callback prototype
233  *
234  * This callback is invoked by the decoder to notify the application of
235  * the availability of decoded image data.
236  */
237 typedef void (*aom_codec_put_frame_cb_fn_t)(void *user_priv,
238                                             const aom_image_t *img);
239 
240 /*!\brief Register for notification of frame completion.
241  *
242  * Registers a given function to be called when a decoded frame is
243  * available.
244  *
245  * \param[in] ctx          Pointer to this instance's context
246  * \param[in] cb           Pointer to the callback function
247  * \param[in] user_priv    User's private data
248  *
249  * \retval #AOM_CODEC_OK
250  *     Callback successfully registered.
251  * \retval #AOM_CODEC_ERROR
252  *     Decoder context not initialized, or algorithm not capable of
253  *     posting slice completion.
254  */
255 aom_codec_err_t aom_codec_register_put_frame_cb(aom_codec_ctx_t *ctx,
256                                                 aom_codec_put_frame_cb_fn_t cb,
257                                                 void *user_priv);
258 
259 /*!@} - end defgroup cap_put_frame */
260 
261 /*!\defgroup cap_put_slice Slice-Based Decoding Functions
262  *
263  * The following functions are required to be implemented for all decoders
264  * that advertise the AOM_CODEC_CAP_PUT_SLICE capability. Calling these
265  * functions
266  * for codecs that don't advertise this capability will result in an error
267  * code being returned, usually AOM_CODEC_ERROR
268  * @{
269  */
270 
271 /*!\brief put slice callback prototype
272  *
273  * This callback is invoked by the decoder to notify the application of
274  * the availability of partially decoded image data. The
275  */
276 typedef void (*aom_codec_put_slice_cb_fn_t)(void *user_priv,
277                                             const aom_image_t *img,
278                                             const aom_image_rect_t *valid,
279                                             const aom_image_rect_t *update);
280 
281 /*!\brief Register for notification of slice completion.
282  *
283  * Registers a given function to be called when a decoded slice is
284  * available.
285  *
286  * \param[in] ctx          Pointer to this instance's context
287  * \param[in] cb           Pointer to the callback function
288  * \param[in] user_priv    User's private data
289  *
290  * \retval #AOM_CODEC_OK
291  *     Callback successfully registered.
292  * \retval #AOM_CODEC_ERROR
293  *     Decoder context not initialized, or algorithm not capable of
294  *     posting slice completion.
295  */
296 aom_codec_err_t aom_codec_register_put_slice_cb(aom_codec_ctx_t *ctx,
297                                                 aom_codec_put_slice_cb_fn_t cb,
298                                                 void *user_priv);
299 
300 /*!@} - end defgroup cap_put_slice*/
301 
302 /*!\defgroup cap_external_frame_buffer External Frame Buffer Functions
303  *
304  * The following section is required to be implemented for all decoders
305  * that advertise the AOM_CODEC_CAP_EXTERNAL_FRAME_BUFFER capability.
306  * Calling this function for codecs that don't advertise this capability
307  * will result in an error code being returned, usually AOM_CODEC_ERROR.
308  *
309  * \note
310  * Currently this only works with AV1.
311  * @{
312  */
313 
314 /*!\brief Pass in external frame buffers for the decoder to use.
315  *
316  * Registers functions to be called when libaom needs a frame buffer
317  * to decode the current frame and a function to be called when libaom does
318  * not internally reference the frame buffer. This set function must
319  * be called before the first call to decode or libaom will assume the
320  * default behavior of allocating frame buffers internally.
321  *
322  * \param[in] ctx          Pointer to this instance's context
323  * \param[in] cb_get       Pointer to the get callback function
324  * \param[in] cb_release   Pointer to the release callback function
325  * \param[in] cb_priv      Callback's private data
326  *
327  * \retval #AOM_CODEC_OK
328  *     External frame buffers will be used by libaom.
329  * \retval #AOM_CODEC_INVALID_PARAM
330  *     One or more of the callbacks were NULL.
331  * \retval #AOM_CODEC_ERROR
332  *     Decoder context not initialized, or algorithm not capable of
333  *     using external frame buffers.
334  *
335  * \note
336  * When decoding AV1, the application may be required to pass in at least
337  * #AOM_MAXIMUM_WORK_BUFFERS external frame
338  * buffers.
339  */
340 aom_codec_err_t aom_codec_set_frame_buffer_functions(
341     aom_codec_ctx_t *ctx, aom_get_frame_buffer_cb_fn_t cb_get,
342     aom_release_frame_buffer_cb_fn_t cb_release, void *cb_priv);
343 
344 /*!@} - end defgroup cap_external_frame_buffer */
345 
346 /*!@} - end defgroup decoder*/
347 #ifdef __cplusplus
348 }
349 #endif
350 #endif  // AOM_AOM_AOM_DECODER_H_
351