Subversion Repositories eduke32

Rev

Rev 4319 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
2036 helixhorne 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
 */
4319 hendricks2 10
#ifndef VPX_VPX_DECODER_H_
11
#define VPX_VPX_DECODER_H_
2036 helixhorne 12
 
13
/*!\defgroup decoder Decoder Algorithm Interface
14
 * \ingroup codec
15
 * This abstraction allows applications using this decoder to easily support
16
 * multiple video formats with minimal code duplication. This section describes
17
 * the interface common to all decoders.
18
 * @{
19
 */
20
 
21
/*!\file
22
 * \brief Describes the decoder algorithm interface to applications.
23
 *
24
 * This file describes the interface between an application and a
25
 * video decoder algorithm.
26
 *
27
 */
28
#ifdef __cplusplus
29
extern "C" {
30
#endif
31
 
4319 hendricks2 32
#include "./vpx_codec.h"
6006 hendricks2 33
#include "./vpx_frame_buffer.h"
2036 helixhorne 34
 
4319 hendricks2 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
   */
6006 hendricks2 43
#define VPX_DECODER_ABI_VERSION (3 + VPX_CODEC_ABI_VERSION) /**<\hideinitializer*/
2036 helixhorne 44
 
4319 hendricks2 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 specified by VPX_CODEC_CAP_* defines.
52
   */
2036 helixhorne 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
#define VPX_CODEC_CAP_ERROR_CONCEALMENT   0x80000 /**< Can conceal errors due to
4319 hendricks2 57
  packet loss */
2831 helixhorne 58
#define VPX_CODEC_CAP_INPUT_FRAGMENTS   0x100000 /**< Can receive encoded frames
4319 hendricks2 59
  one fragment at a time */
2036 helixhorne 60
 
4319 hendricks2 61
  /*! \brief Initialization-time Feature Enabling
62
   *
63
   *  Certain codec features must be known at initialization time, to allow for
64
   *  proper memory allocation.
65
   *
66
   *  The available flags are specified by VPX_CODEC_USE_* defines.
67
   */
68
#define VPX_CODEC_CAP_FRAME_THREADING   0x200000 /**< Can support frame-based
69
                                                      multi-threading */
6006 hendricks2 70
#define VPX_CODEC_CAP_EXTERNAL_FRAME_BUFFER 0x400000 /**< Can support external
71
                                                          frame buffers */
4319 hendricks2 72
 
2036 helixhorne 73
#define VPX_CODEC_USE_POSTPROC   0x10000 /**< Postprocess decoded frame */
74
#define VPX_CODEC_USE_ERROR_CONCEALMENT 0x20000 /**< Conceal errors in decoded
4319 hendricks2 75
  frames */
2831 helixhorne 76
#define VPX_CODEC_USE_INPUT_FRAGMENTS   0x40000 /**< The input frame should be
4319 hendricks2 77
  passed to the decoder one
78
  fragment at a time */
79
#define VPX_CODEC_USE_FRAME_THREADING   0x80000 /**< Enable frame-based
80
                                                     multi-threading */
2036 helixhorne 81
 
4319 hendricks2 82
  /*!\brief Stream properties
83
   *
84
   * This structure is used to query or set properties of the decoded
85
   * stream. Algorithms may extend this structure with data specific
86
   * to their bitstream by setting the sz member appropriately.
87
   */
88
  typedef struct vpx_codec_stream_info {
89
    unsigned int sz;     /**< Size of this structure */
90
    unsigned int w;      /**< Width (or 0 for unknown/default) */
91
    unsigned int h;      /**< Height (or 0 for unknown/default) */
92
    unsigned int is_kf;  /**< Current frame is a keyframe */
93
  } vpx_codec_stream_info_t;
2036 helixhorne 94
 
4319 hendricks2 95
  /* REQUIRED FUNCTIONS
96
   *
97
   * The following functions are required to be implemented for all decoders.
98
   * They represent the base case functionality expected of all decoders.
99
   */
2036 helixhorne 100
 
101
 
4319 hendricks2 102
  /*!\brief Initialization Configurations
103
   *
104
   * This structure is used to pass init time configuration options to the
105
   * decoder.
106
   */
107
  typedef struct vpx_codec_dec_cfg {
108
    unsigned int threads; /**< Maximum number of threads to use, default 1 */
109
    unsigned int w;      /**< Width */
110
    unsigned int h;      /**< Height */
111
  } vpx_codec_dec_cfg_t; /**< alias for struct vpx_codec_dec_cfg */
2036 helixhorne 112
 
113
 
4319 hendricks2 114
  /*!\brief Initialize a decoder instance
115
   *
116
   * Initializes a decoder context using the given interface. Applications
117
   * should call the vpx_codec_dec_init convenience macro instead of this
118
   * function directly, to ensure that the ABI version number parameter
119
   * is properly initialized.
120
   *
121
   * If the library was configured with --disable-multithread, this call
122
   * is not thread safe and should be guarded with a lock if being used
123
   * in a multithreaded context.
124
   *
125
   * \param[in]    ctx     Pointer to this instance's context.
126
   * \param[in]    iface   Pointer to the algorithm interface to use.
127
   * \param[in]    cfg     Configuration to use, if known. May be NULL.
128
   * \param[in]    flags   Bitfield of VPX_CODEC_USE_* flags
129
   * \param[in]    ver     ABI version number. Must be set to
130
   *                       VPX_DECODER_ABI_VERSION
131
   * \retval #VPX_CODEC_OK
132
   *     The decoder algorithm initialized.
133
   * \retval #VPX_CODEC_MEM_ERROR
134
   *     Memory allocation failed.
135
   */
136
  vpx_codec_err_t vpx_codec_dec_init_ver(vpx_codec_ctx_t      *ctx,
137
                                         vpx_codec_iface_t    *iface,
6006 hendricks2 138
                                         const vpx_codec_dec_cfg_t *cfg,
4319 hendricks2 139
                                         vpx_codec_flags_t     flags,
140
                                         int                   ver);
2036 helixhorne 141
 
4319 hendricks2 142
  /*!\brief Convenience macro for vpx_codec_dec_init_ver()
143
   *
144
   * Ensures the ABI version parameter is properly set.
145
   */
2036 helixhorne 146
#define vpx_codec_dec_init(ctx, iface, cfg, flags) \
4319 hendricks2 147
  vpx_codec_dec_init_ver(ctx, iface, cfg, flags, VPX_DECODER_ABI_VERSION)
2036 helixhorne 148
 
149
 
4319 hendricks2 150
  /*!\brief Parse stream info from a buffer
151
   *
152
   * Performs high level parsing of the bitstream. Construction of a decoder
153
   * context is not necessary. Can be used to determine if the bitstream is
154
   * of the proper format, and to extract information from the stream.
155
   *
156
   * \param[in]      iface   Pointer to the algorithm interface
157
   * \param[in]      data    Pointer to a block of data to parse
158
   * \param[in]      data_sz Size of the data buffer
159
   * \param[in,out]  si      Pointer to stream info to update. The size member
160
   *                         \ref MUST be properly initialized, but \ref MAY be
161
   *                         clobbered by the algorithm. This parameter \ref MAY
162
   *                         be NULL.
163
   *
164
   * \retval #VPX_CODEC_OK
165
   *     Bitstream is parsable and stream information updated
166
   */
167
  vpx_codec_err_t vpx_codec_peek_stream_info(vpx_codec_iface_t       *iface,
168
                                             const uint8_t           *data,
169
                                             unsigned int             data_sz,
170
                                             vpx_codec_stream_info_t *si);
2036 helixhorne 171
 
172
 
4319 hendricks2 173
  /*!\brief Return information about the current stream.
174
   *
175
   * Returns information about the stream that has been parsed during decoding.
176
   *
177
   * \param[in]      ctx     Pointer to this instance's context
178
   * \param[in,out]  si      Pointer to stream info to update. The size member
179
   *                         \ref MUST be properly initialized, but \ref MAY be
180
   *                         clobbered by the algorithm. This parameter \ref MAY
181
   *                         be NULL.
182
   *
183
   * \retval #VPX_CODEC_OK
184
   *     Bitstream is parsable and stream information updated
185
   */
186
  vpx_codec_err_t vpx_codec_get_stream_info(vpx_codec_ctx_t         *ctx,
187
                                            vpx_codec_stream_info_t *si);
2036 helixhorne 188
 
189
 
4319 hendricks2 190
  /*!\brief Decode data
191
   *
192
   * Processes a buffer of coded data. If the processing results in a new
193
   * decoded frame becoming available, PUT_SLICE and PUT_FRAME events may be
194
   * generated, as appropriate. Encoded data \ref MUST be passed in DTS (decode
195
   * time stamp) order. Frames produced will always be in PTS (presentation
196
   * time stamp) order.
197
   * If the decoder is configured with VPX_CODEC_USE_INPUT_FRAGMENTS enabled,
198
   * data and data_sz can contain a fragment of the encoded frame. Fragment
199
   * \#n must contain at least partition \#n, but can also contain subsequent
200
   * partitions (\#n+1 - \#n+i), and if so, fragments \#n+1, .., \#n+i must
201
   * be empty. When no more data is available, this function should be called
202
   * with NULL as data and 0 as data_sz. The memory passed to this function
203
   * must be available until the frame has been decoded.
204
   *
205
   * \param[in] ctx          Pointer to this instance's context
206
   * \param[in] data         Pointer to this block of new coded data. If
207
   *                         NULL, a VPX_CODEC_CB_PUT_FRAME event is posted
208
   *                         for the previously decoded frame.
209
   * \param[in] data_sz      Size of the coded data, in bytes.
210
   * \param[in] user_priv    Application specific data to associate with
211
   *                         this frame.
212
   * \param[in] deadline     Soft deadline the decoder should attempt to meet,
213
   *                         in us. Set to zero for unlimited.
214
   *
215
   * \return Returns #VPX_CODEC_OK if the coded data was processed completely
216
   *         and future pictures can be decoded without error. Otherwise,
217
   *         see the descriptions of the other error codes in ::vpx_codec_err_t
218
   *         for recoverability capabilities.
219
   */
220
  vpx_codec_err_t vpx_codec_decode(vpx_codec_ctx_t    *ctx,
221
                                   const uint8_t        *data,
222
                                   unsigned int            data_sz,
223
                                   void               *user_priv,
224
                                   long                deadline);
2036 helixhorne 225
 
226
 
4319 hendricks2 227
  /*!\brief Decoded frames iterator
228
   *
229
   * Iterates over a list of the frames available for display. The iterator
230
   * storage should be initialized to NULL to start the iteration. Iteration is
231
   * complete when this function returns NULL.
232
   *
233
   * The list of available frames becomes valid upon completion of the
234
   * vpx_codec_decode call, and remains valid until the next call to vpx_codec_decode.
235
   *
236
   * \param[in]     ctx      Pointer to this instance's context
237
   * \param[in,out] iter     Iterator storage, initialized to NULL
238
   *
239
   * \return Returns a pointer to an image, if one is ready for display. Frames
240
   *         produced will always be in PTS (presentation time stamp) order.
241
   */
242
  vpx_image_t *vpx_codec_get_frame(vpx_codec_ctx_t  *ctx,
243
                                   vpx_codec_iter_t *iter);
2036 helixhorne 244
 
245
 
4319 hendricks2 246
  /*!\defgroup cap_put_frame Frame-Based Decoding Functions
247
   *
248
   * The following functions are required to be implemented for all decoders
249
   * that advertise the VPX_CODEC_CAP_PUT_FRAME capability. Calling these functions
250
   * for codecs that don't advertise this capability will result in an error
251
   * code being returned, usually VPX_CODEC_ERROR
252
   * @{
253
   */
2036 helixhorne 254
 
4319 hendricks2 255
  /*!\brief put frame callback prototype
256
   *
257
   * This callback is invoked by the decoder to notify the application of
258
   * the availability of decoded image data.
259
   */
260
  typedef void (*vpx_codec_put_frame_cb_fn_t)(void        *user_priv,
261
                                              const vpx_image_t *img);
2036 helixhorne 262
 
263
 
4319 hendricks2 264
  /*!\brief Register for notification of frame completion.
265
   *
266
   * Registers a given function to be called when a decoded frame is
267
   * available.
268
   *
269
   * \param[in] ctx          Pointer to this instance's context
270
   * \param[in] cb           Pointer to the callback function
271
   * \param[in] user_priv    User's private data
272
   *
273
   * \retval #VPX_CODEC_OK
274
   *     Callback successfully registered.
275
   * \retval #VPX_CODEC_ERROR
276
   *     Decoder context not initialized, or algorithm not capable of
277
   *     posting slice completion.
278
   */
279
  vpx_codec_err_t vpx_codec_register_put_frame_cb(vpx_codec_ctx_t             *ctx,
280
                                                  vpx_codec_put_frame_cb_fn_t  cb,
281
                                                  void                        *user_priv);
2036 helixhorne 282
 
283
 
4319 hendricks2 284
  /*!@} - end defgroup cap_put_frame */
2036 helixhorne 285
 
4319 hendricks2 286
  /*!\defgroup cap_put_slice Slice-Based Decoding Functions
287
   *
288
   * The following functions are required to be implemented for all decoders
289
   * that advertise the VPX_CODEC_CAP_PUT_SLICE capability. Calling these functions
290
   * for codecs that don't advertise this capability will result in an error
291
   * code being returned, usually VPX_CODEC_ERROR
292
   * @{
293
   */
2036 helixhorne 294
 
4319 hendricks2 295
  /*!\brief put slice callback prototype
296
   *
297
   * This callback is invoked by the decoder to notify the application of
298
   * the availability of partially decoded image data. The
299
   */
300
  typedef void (*vpx_codec_put_slice_cb_fn_t)(void         *user_priv,
301
                                              const vpx_image_t      *img,
302
                                              const vpx_image_rect_t *valid,
303
                                              const vpx_image_rect_t *update);
2036 helixhorne 304
 
305
 
4319 hendricks2 306
  /*!\brief Register for notification of slice completion.
307
   *
308
   * Registers a given function to be called when a decoded slice is
309
   * available.
310
   *
311
   * \param[in] ctx          Pointer to this instance's context
312
   * \param[in] cb           Pointer to the callback function
313
   * \param[in] user_priv    User's private data
314
   *
315
   * \retval #VPX_CODEC_OK
316
   *     Callback successfully registered.
317
   * \retval #VPX_CODEC_ERROR
318
   *     Decoder context not initialized, or algorithm not capable of
319
   *     posting slice completion.
320
   */
321
  vpx_codec_err_t vpx_codec_register_put_slice_cb(vpx_codec_ctx_t             *ctx,
322
                                                  vpx_codec_put_slice_cb_fn_t  cb,
323
                                                  void                        *user_priv);
2036 helixhorne 324
 
325
 
4319 hendricks2 326
  /*!@} - end defgroup cap_put_slice*/
2036 helixhorne 327
 
6006 hendricks2 328
  /*!\defgroup cap_external_frame_buffer External Frame Buffer Functions
329
   *
330
   * The following section is required to be implemented for all decoders
331
   * that advertise the VPX_CODEC_CAP_EXTERNAL_FRAME_BUFFER capability.
332
   * Calling this function for codecs that don't advertise this capability
333
   * will result in an error code being returned, usually VPX_CODEC_ERROR.
334
   *
335
   * \note
336
   * Currently this only works with VP9.
337
   * @{
338
   */
339
 
340
  /*!\brief Pass in external frame buffers for the decoder to use.
341
   *
342
   * Registers functions to be called when libvpx needs a frame buffer
343
   * to decode the current frame and a function to be called when libvpx does
344
   * not internally reference the frame buffer. This set function must
345
   * be called before the first call to decode or libvpx will assume the
346
   * default behavior of allocating frame buffers internally.
347
   *
348
   * \param[in] ctx          Pointer to this instance's context
349
   * \param[in] cb_get       Pointer to the get callback function
350
   * \param[in] cb_release   Pointer to the release callback function
351
   * \param[in] cb_priv      Callback's private data
352
   *
353
   * \retval #VPX_CODEC_OK
354
   *     External frame buffers will be used by libvpx.
355
   * \retval #VPX_CODEC_INVALID_PARAM
356
   *     One or more of the callbacks were NULL.
357
   * \retval #VPX_CODEC_ERROR
358
   *     Decoder context not initialized, or algorithm not capable of
359
   *     using external frame buffers.
360
   *
361
   * \note
362
   * When decoding VP9, the application may be required to pass in at least
363
   * #VP9_MAXIMUM_REF_BUFFERS + #VPX_MAXIMUM_WORK_BUFFERS external frame
364
   * buffers.
365
   */
366
  vpx_codec_err_t vpx_codec_set_frame_buffer_functions(
367
      vpx_codec_ctx_t *ctx,
368
      vpx_get_frame_buffer_cb_fn_t cb_get,
369
      vpx_release_frame_buffer_cb_fn_t cb_release, void *cb_priv);
370
 
371
  /*!@} - end defgroup cap_external_frame_buffer */
372
 
4319 hendricks2 373
  /*!@} - end defgroup decoder*/
2036 helixhorne 374
#ifdef __cplusplus
375
}
376
#endif
4319 hendricks2 377
#endif  // VPX_VPX_DECODER_H_
378