• 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  /*!\file
13   * \brief Describes the decoder algorithm interface for algorithm
14   *        implementations.
15   *
16   * This file defines the private structures and data types that are only
17   * relevant to implementing an algorithm, as opposed to using it.
18   *
19   * To create a decoder algorithm class, an interface structure is put
20   * into the global namespace:
21   *     <pre>
22   *     my_codec.c:
23   *       vpx_codec_iface_t my_codec = {
24   *           "My Codec v1.0",
25   *           VPX_CODEC_ALG_ABI_VERSION,
26   *           ...
27   *       };
28   *     </pre>
29   *
30   * An application instantiates a specific decoder instance by using
31   * vpx_codec_init() and a pointer to the algorithm's interface structure:
32   *     <pre>
33   *     my_app.c:
34   *       extern vpx_codec_iface_t my_codec;
35   *       {
36   *           vpx_codec_ctx_t algo;
37   *           res = vpx_codec_init(&algo, &my_codec);
38   *       }
39   *     </pre>
40   *
41   * Once initialized, the instance is manged using other functions from
42   * the vpx_codec_* family.
43   */
44  #ifndef VPX_INTERNAL_VPX_CODEC_INTERNAL_H_
45  #define VPX_INTERNAL_VPX_CODEC_INTERNAL_H_
46  #include "../vpx_decoder.h"
47  #include "../vpx_encoder.h"
48  #include <stdarg.h>
49  
50  #ifdef __cplusplus
51  extern "C" {
52  #endif
53  
54  /*!\brief Current ABI version number
55   *
56   * \internal
57   * If this file is altered in any way that changes the ABI, this value
58   * must be bumped.  Examples include, but are not limited to, changing
59   * types, removing or reassigning enums, adding/removing/rearranging
60   * fields to structures
61   */
62  #define VPX_CODEC_INTERNAL_ABI_VERSION (5) /**<\hideinitializer*/
63  
64  typedef struct vpx_codec_alg_priv  vpx_codec_alg_priv_t;
65  typedef struct vpx_codec_priv_enc_mr_cfg vpx_codec_priv_enc_mr_cfg_t;
66  
67  /*!\brief init function pointer prototype
68   *
69   * Performs algorithm-specific initialization of the decoder context. This
70   * function is called by the generic vpx_codec_init() wrapper function, so
71   * plugins implementing this interface may trust the input parameters to be
72   * properly initialized.
73   *
74   * \param[in] ctx   Pointer to this instance's context
75   * \retval #VPX_CODEC_OK
76   *     The input stream was recognized and decoder initialized.
77   * \retval #VPX_CODEC_MEM_ERROR
78   *     Memory operation failed.
79   */
80  typedef vpx_codec_err_t (*vpx_codec_init_fn_t)(vpx_codec_ctx_t *ctx,
81                                                 vpx_codec_priv_enc_mr_cfg_t *data);
82  
83  /*!\brief destroy function pointer prototype
84   *
85   * Performs algorithm-specific destruction of the decoder context. This
86   * function is called by the generic vpx_codec_destroy() wrapper function,
87   * so plugins implementing this interface may trust the input parameters
88   * to be properly initialized.
89   *
90   * \param[in] ctx   Pointer to this instance's context
91   * \retval #VPX_CODEC_OK
92   *     The input stream was recognized and decoder initialized.
93   * \retval #VPX_CODEC_MEM_ERROR
94   *     Memory operation failed.
95   */
96  typedef vpx_codec_err_t (*vpx_codec_destroy_fn_t)(vpx_codec_alg_priv_t *ctx);
97  
98  /*!\brief parse stream info function pointer prototype
99   *
100   * Performs high level parsing of the bitstream. This function is called by the
101   * generic vpx_codec_peek_stream_info() wrapper function, so plugins
102   * implementing this interface may trust the input parameters to be properly
103   * initialized.
104   *
105   * \param[in]      data    Pointer to a block of data to parse
106   * \param[in]      data_sz Size of the data buffer
107   * \param[in,out]  si      Pointer to stream info to update. The size member
108   *                         \ref MUST be properly initialized, but \ref MAY be
109   *                         clobbered by the algorithm. This parameter \ref MAY
110   *                         be NULL.
111   *
112   * \retval #VPX_CODEC_OK
113   *     Bitstream is parsable and stream information updated
114   */
115  typedef vpx_codec_err_t (*vpx_codec_peek_si_fn_t)(const uint8_t         *data,
116                                                    unsigned int           data_sz,
117                                                    vpx_codec_stream_info_t *si);
118  
119  /*!\brief Return information about the current stream.
120   *
121   * Returns information about the stream that has been parsed during decoding.
122   *
123   * \param[in]      ctx     Pointer to this instance's context
124   * \param[in,out]  si      Pointer to stream info to update. The size member
125   *                         \ref MUST be properly initialized, but \ref MAY be
126   *                         clobbered by the algorithm. This parameter \ref MAY
127   *                         be NULL.
128   *
129   * \retval #VPX_CODEC_OK
130   *     Bitstream is parsable and stream information updated
131   */
132  typedef vpx_codec_err_t (*vpx_codec_get_si_fn_t)(vpx_codec_alg_priv_t    *ctx,
133                                                   vpx_codec_stream_info_t *si);
134  
135  /*!\brief control function pointer prototype
136   *
137   * This function is used to exchange algorithm specific data with the decoder
138   * instance. This can be used to implement features specific to a particular
139   * algorithm.
140   *
141   * This function is called by the generic vpx_codec_control() wrapper
142   * function, so plugins implementing this interface may trust the input
143   * parameters to be properly initialized. However,  this interface does not
144   * provide type safety for the exchanged data or assign meanings to the
145   * control codes. Those details should be specified in the algorithm's
146   * header file. In particular, the ctrl_id parameter is guaranteed to exist
147   * in the algorithm's control mapping table, and the data parameter may be NULL.
148   *
149   *
150   * \param[in]     ctx              Pointer to this instance's context
151   * \param[in]     ctrl_id          Algorithm specific control identifier
152   * \param[in,out] data             Data to exchange with algorithm instance.
153   *
154   * \retval #VPX_CODEC_OK
155   *     The internal state data was deserialized.
156   */
157  typedef vpx_codec_err_t (*vpx_codec_control_fn_t)(vpx_codec_alg_priv_t *ctx,
158                                                    va_list ap);
159  
160  /*!\brief control function pointer mapping
161   *
162   * This structure stores the mapping between control identifiers and
163   * implementing functions. Each algorithm provides a list of these
164   * mappings. This list is searched by the vpx_codec_control() wrapper
165   * function to determine which function to invoke. The special
166   * value {0, NULL} is used to indicate end-of-list, and must be
167   * present. The special value {0, <non-null>} can be used as a catch-all
168   * mapping. This implies that ctrl_id values chosen by the algorithm
169   * \ref MUST be non-zero.
170   */
171  typedef const struct vpx_codec_ctrl_fn_map {
172    int ctrl_id;
173    vpx_codec_control_fn_t fn;
174  } vpx_codec_ctrl_fn_map_t;
175  
176  /*!\brief decode data function pointer prototype
177   *
178   * Processes a buffer of coded data. If the processing results in a new
179   * decoded frame becoming available, #VPX_CODEC_CB_PUT_SLICE and
180   * #VPX_CODEC_CB_PUT_FRAME events are generated as appropriate. This
181   * function is called by the generic vpx_codec_decode() wrapper function,
182   * so plugins implementing this interface may trust the input parameters
183   * to be properly initialized.
184   *
185   * \param[in] ctx          Pointer to this instance's context
186   * \param[in] data         Pointer to this block of new coded data. If
187   *                         NULL, a #VPX_CODEC_CB_PUT_FRAME event is posted
188   *                         for the previously decoded frame.
189   * \param[in] data_sz      Size of the coded data, in bytes.
190   *
191   * \return Returns #VPX_CODEC_OK if the coded data was processed completely
192   *         and future pictures can be decoded without error. Otherwise,
193   *         see the descriptions of the other error codes in ::vpx_codec_err_t
194   *         for recoverability capabilities.
195   */
196  typedef vpx_codec_err_t (*vpx_codec_decode_fn_t)(vpx_codec_alg_priv_t  *ctx,
197                                                   const uint8_t         *data,
198                                                   unsigned int     data_sz,
199                                                   void        *user_priv,
200                                                   long         deadline);
201  
202  /*!\brief Decoded frames iterator
203   *
204   * Iterates over a list of the frames available for display. The iterator
205   * storage should be initialized to NULL to start the iteration. Iteration is
206   * complete when this function returns NULL.
207   *
208   * The list of available frames becomes valid upon completion of the
209   * vpx_codec_decode call, and remains valid until the next call to vpx_codec_decode.
210   *
211   * \param[in]     ctx      Pointer to this instance's context
212   * \param[in out] iter     Iterator storage, initialized to NULL
213   *
214   * \return Returns a pointer to an image, if one is ready for display. Frames
215   *         produced will always be in PTS (presentation time stamp) order.
216   */
217  typedef vpx_image_t *(*vpx_codec_get_frame_fn_t)(vpx_codec_alg_priv_t *ctx,
218                                                   vpx_codec_iter_t     *iter);
219  
220  /*!\brief Pass in external frame buffers for the decoder to use.
221   *
222   * Registers functions to be called when libvpx needs a frame buffer
223   * to decode the current frame and a function to be called when libvpx does
224   * not internally reference the frame buffer. This set function must
225   * be called before the first call to decode or libvpx will assume the
226   * default behavior of allocating frame buffers internally.
227   *
228   * \param[in] ctx          Pointer to this instance's context
229   * \param[in] cb_get       Pointer to the get callback function
230   * \param[in] cb_release   Pointer to the release callback function
231   * \param[in] cb_priv      Callback's private data
232   *
233   * \retval #VPX_CODEC_OK
234   *     External frame buffers will be used by libvpx.
235   * \retval #VPX_CODEC_INVALID_PARAM
236   *     One or more of the callbacks were NULL.
237   * \retval #VPX_CODEC_ERROR
238   *     Decoder context not initialized, or algorithm not capable of
239   *     using external frame buffers.
240   *
241   * \note
242   * When decoding VP9, the application may be required to pass in at least
243   * #VP9_MAXIMUM_REF_BUFFERS + #VPX_MAXIMUM_WORK_BUFFERS external frame
244   * buffers.
245   */
246  typedef vpx_codec_err_t (*vpx_codec_set_fb_fn_t)(
247      vpx_codec_alg_priv_t *ctx,
248      vpx_get_frame_buffer_cb_fn_t cb_get,
249      vpx_release_frame_buffer_cb_fn_t cb_release, void *cb_priv);
250  
251  
252  typedef vpx_codec_err_t (*vpx_codec_encode_fn_t)(vpx_codec_alg_priv_t  *ctx,
253                                                   const vpx_image_t     *img,
254                                                   vpx_codec_pts_t        pts,
255                                                   unsigned long          duration,
256                                                   vpx_enc_frame_flags_t  flags,
257                                                   unsigned long          deadline);
258  typedef const vpx_codec_cx_pkt_t *(*vpx_codec_get_cx_data_fn_t)(vpx_codec_alg_priv_t *ctx,
259                                                                  vpx_codec_iter_t     *iter);
260  
261  typedef vpx_codec_err_t
262  (*vpx_codec_enc_config_set_fn_t)(vpx_codec_alg_priv_t       *ctx,
263                                   const vpx_codec_enc_cfg_t  *cfg);
264  typedef vpx_fixed_buf_t *
265  (*vpx_codec_get_global_headers_fn_t)(vpx_codec_alg_priv_t   *ctx);
266  
267  typedef vpx_image_t *
268  (*vpx_codec_get_preview_frame_fn_t)(vpx_codec_alg_priv_t   *ctx);
269  
270  typedef vpx_codec_err_t
271  (*vpx_codec_enc_mr_get_mem_loc_fn_t)(const vpx_codec_enc_cfg_t     *cfg,
272                                       void **mem_loc);
273  
274  /*!\brief usage configuration mapping
275   *
276   * This structure stores the mapping between usage identifiers and
277   * configuration structures. Each algorithm provides a list of these
278   * mappings. This list is searched by the vpx_codec_enc_config_default()
279   * wrapper function to determine which config to return. The special value
280   * {-1, {0}} is used to indicate end-of-list, and must be present. At least
281   * one mapping must be present, in addition to the end-of-list.
282   *
283   */
284  typedef const struct vpx_codec_enc_cfg_map {
285    int                 usage;
286    vpx_codec_enc_cfg_t cfg;
287  } vpx_codec_enc_cfg_map_t;
288  
289  /*!\brief Decoder algorithm interface interface
290   *
291   * All decoders \ref MUST expose a variable of this type.
292   */
293  struct vpx_codec_iface {
294    const char               *name;        /**< Identification String  */
295    int                       abi_version; /**< Implemented ABI version */
296    vpx_codec_caps_t          caps;    /**< Decoder capabilities */
297    vpx_codec_init_fn_t       init;    /**< \copydoc ::vpx_codec_init_fn_t */
298    vpx_codec_destroy_fn_t    destroy;     /**< \copydoc ::vpx_codec_destroy_fn_t */
299    vpx_codec_ctrl_fn_map_t  *ctrl_maps;   /**< \copydoc ::vpx_codec_ctrl_fn_map_t */
300    struct vpx_codec_dec_iface {
301      vpx_codec_peek_si_fn_t    peek_si;     /**< \copydoc ::vpx_codec_peek_si_fn_t */
302      vpx_codec_get_si_fn_t     get_si;      /**< \copydoc ::vpx_codec_get_si_fn_t */
303      vpx_codec_decode_fn_t     decode;      /**< \copydoc ::vpx_codec_decode_fn_t */
304      vpx_codec_get_frame_fn_t  get_frame;   /**< \copydoc ::vpx_codec_get_frame_fn_t */
305      vpx_codec_set_fb_fn_t     set_fb_fn;   /**< \copydoc ::vpx_codec_set_fb_fn_t */
306    } dec;
307    struct vpx_codec_enc_iface {
308      int                                cfg_map_count;
309      vpx_codec_enc_cfg_map_t           *cfg_maps;      /**< \copydoc ::vpx_codec_enc_cfg_map_t */
310      vpx_codec_encode_fn_t              encode;        /**< \copydoc ::vpx_codec_encode_fn_t */
311      vpx_codec_get_cx_data_fn_t         get_cx_data;   /**< \copydoc ::vpx_codec_get_cx_data_fn_t */
312      vpx_codec_enc_config_set_fn_t      cfg_set;       /**< \copydoc ::vpx_codec_enc_config_set_fn_t */
313      vpx_codec_get_global_headers_fn_t  get_glob_hdrs; /**< \copydoc ::vpx_codec_get_global_headers_fn_t */
314      vpx_codec_get_preview_frame_fn_t   get_preview;   /**< \copydoc ::vpx_codec_get_preview_frame_fn_t */
315      vpx_codec_enc_mr_get_mem_loc_fn_t  mr_get_mem_loc;   /**< \copydoc ::vpx_codec_enc_mr_get_mem_loc_fn_t */
316    } enc;
317  };
318  
319  /*!\brief Callback function pointer / user data pair storage */
320  typedef struct vpx_codec_priv_cb_pair {
321    union {
322      vpx_codec_put_frame_cb_fn_t    put_frame;
323      vpx_codec_put_slice_cb_fn_t    put_slice;
324    } u;
325    void                            *user_priv;
326  } vpx_codec_priv_cb_pair_t;
327  
328  
329  /*!\brief Instance private storage
330   *
331   * This structure is allocated by the algorithm's init function. It can be
332   * extended in one of two ways. First, a second, algorithm specific structure
333   * can be allocated and the priv member pointed to it. Alternatively, this
334   * structure can be made the first member of the algorithm specific structure,
335   * and the pointer cast to the proper type.
336   */
337  struct vpx_codec_priv {
338    const char                     *err_detail;
339    vpx_codec_flags_t               init_flags;
340    struct {
341      vpx_codec_priv_cb_pair_t    put_frame_cb;
342      vpx_codec_priv_cb_pair_t    put_slice_cb;
343    } dec;
344    struct {
345      vpx_fixed_buf_t             cx_data_dst_buf;
346      unsigned int                cx_data_pad_before;
347      unsigned int                cx_data_pad_after;
348      vpx_codec_cx_pkt_t          cx_data_pkt;
349      unsigned int                total_encoders;
350    } enc;
351  };
352  
353  /*
354   * Multi-resolution encoding internal configuration
355   */
356  struct vpx_codec_priv_enc_mr_cfg
357  {
358      unsigned int           mr_total_resolutions;
359      unsigned int           mr_encoder_id;
360      struct vpx_rational    mr_down_sampling_factor;
361      void*                  mr_low_res_mode_info;
362  };
363  
364  #undef VPX_CTRL_USE_TYPE
365  #define VPX_CTRL_USE_TYPE(id, typ) \
366    static VPX_INLINE typ id##__value(va_list args) {return va_arg(args, typ);}
367  
368  #undef VPX_CTRL_USE_TYPE_DEPRECATED
369  #define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) \
370    static VPX_INLINE typ id##__value(va_list args) {return va_arg(args, typ);}
371  
372  #define CAST(id, arg) id##__value(arg)
373  
374  /* CODEC_INTERFACE convenience macro
375   *
376   * By convention, each codec interface is a struct with extern linkage, where
377   * the symbol is suffixed with _algo. A getter function is also defined to
378   * return a pointer to the struct, since in some cases it's easier to work
379   * with text symbols than data symbols (see issue #169). This function has
380   * the same name as the struct, less the _algo suffix. The CODEC_INTERFACE
381   * macro is provided to define this getter function automatically.
382   */
383  #define CODEC_INTERFACE(id)\
384    vpx_codec_iface_t* id(void) { return &id##_algo; }\
385    vpx_codec_iface_t  id##_algo
386  
387  
388  /* Internal Utility Functions
389   *
390   * The following functions are intended to be used inside algorithms as
391   * utilities for manipulating vpx_codec_* data structures.
392   */
393  struct vpx_codec_pkt_list {
394    unsigned int            cnt;
395    unsigned int            max;
396    struct vpx_codec_cx_pkt pkts[1];
397  };
398  
399  #define vpx_codec_pkt_list_decl(n)\
400    union {struct vpx_codec_pkt_list head;\
401      struct {struct vpx_codec_pkt_list head;\
402        struct vpx_codec_cx_pkt    pkts[n];} alloc;}
403  
404  #define vpx_codec_pkt_list_init(m)\
405    (m)->alloc.head.cnt = 0,\
406                          (m)->alloc.head.max = sizeof((m)->alloc.pkts) / sizeof((m)->alloc.pkts[0])
407  
408  int
409  vpx_codec_pkt_list_add(struct vpx_codec_pkt_list *,
410                         const struct vpx_codec_cx_pkt *);
411  
412  const vpx_codec_cx_pkt_t *
413  vpx_codec_pkt_list_get(struct vpx_codec_pkt_list *list,
414                         vpx_codec_iter_t           *iter);
415  
416  
417  #include <stdio.h>
418  #include <setjmp.h>
419  
420  struct vpx_internal_error_info {
421    vpx_codec_err_t  error_code;
422    int              has_detail;
423    char             detail[80];
424    int              setjmp;
425    jmp_buf          jmp;
426  };
427  
428  #define CLANG_ANALYZER_NORETURN
429  #if defined(__has_feature)
430  #if __has_feature(attribute_analyzer_noreturn)
431  #undef CLANG_ANALYZER_NORETURN
432  #define CLANG_ANALYZER_NORETURN __attribute__((analyzer_noreturn))
433  #endif
434  #endif
435  
436  void vpx_internal_error(struct vpx_internal_error_info *info,
437                          vpx_codec_err_t                 error,
438                          const char                     *fmt,
439                          ...) CLANG_ANALYZER_NORETURN;
440  
441  #ifdef __cplusplus
442  }  // extern "C"
443  #endif
444  
445  #endif  // VPX_INTERNAL_VPX_CODEC_INTERNAL_H_
446