Home | History | Annotate | Download | only in internal
      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 decoder_impl.h
     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_CODEC_INTERNAL_H
     45 #define VPX_CODEC_INTERNAL_H
     46 #include "../vpx_decoder.h"
     47 #include "../vpx_encoder.h"
     48 #include <stdarg.h>
     49 
     50 
     51 /*!\brief Current ABI version number
     52  *
     53  * \internal
     54  * If this file is altered in any way that changes the ABI, this value
     55  * must be bumped.  Examples include, but are not limited to, changing
     56  * types, removing or reassigning enums, adding/removing/rearranging
     57  * fields to structures
     58  */
     59 #define VPX_CODEC_INTERNAL_ABI_VERSION (3) /**<\hideinitializer*/
     60 
     61 typedef struct vpx_codec_alg_priv  vpx_codec_alg_priv_t;
     62 
     63 /*!\brief init function pointer prototype
     64  *
     65  * Performs algorithm-specific initialization of the decoder context. This
     66  * function is called by the generic vpx_codec_init() wrapper function, so
     67  * plugins implementing this interface may trust the input parameters to be
     68  * properly initialized.
     69  *
     70  * \param[in] ctx   Pointer to this instance's context
     71  * \retval #VPX_CODEC_OK
     72  *     The input stream was recognized and decoder initialized.
     73  * \retval #VPX_CODEC_MEM_ERROR
     74  *     Memory operation failed.
     75  */
     76 typedef vpx_codec_err_t (*vpx_codec_init_fn_t)(vpx_codec_ctx_t *ctx);
     77 
     78 /*!\brief destroy function pointer prototype
     79  *
     80  * Performs algorithm-specific destruction of the decoder context. This
     81  * function is called by the generic vpx_codec_destroy() wrapper function,
     82  * so plugins implementing this interface may trust the input parameters
     83  * to be properly initialized.
     84  *
     85  * \param[in] ctx   Pointer to this instance's context
     86  * \retval #VPX_CODEC_OK
     87  *     The input stream was recognized and decoder initialized.
     88  * \retval #VPX_CODEC_MEM_ERROR
     89  *     Memory operation failed.
     90  */
     91 typedef vpx_codec_err_t (*vpx_codec_destroy_fn_t)(vpx_codec_alg_priv_t *ctx);
     92 
     93 /*!\brief parse stream info function pointer prototype
     94  *
     95  * Performs high level parsing of the bitstream. This function is called by
     96  * the generic vpx_codec_parse_stream() wrapper function, so plugins implementing
     97  * this interface may trust the input parameters to be properly initialized.
     98  *
     99  * \param[in]      data    Pointer to a block of data to parse
    100  * \param[in]      data_sz Size of the data buffer
    101  * \param[in,out]  si      Pointer to stream info to update. The size member
    102  *                         \ref MUST be properly initialized, but \ref MAY be
    103  *                         clobbered by the algorithm. This parameter \ref MAY
    104  *                         be NULL.
    105  *
    106  * \retval #VPX_CODEC_OK
    107  *     Bitstream is parsable and stream information updated
    108  */
    109 typedef vpx_codec_err_t (*vpx_codec_peek_si_fn_t)(const uint8_t         *data,
    110         unsigned int           data_sz,
    111         vpx_codec_stream_info_t *si);
    112 
    113 /*!\brief Return information about the current stream.
    114  *
    115  * Returns information about the stream that has been parsed during decoding.
    116  *
    117  * \param[in]      ctx     Pointer to this instance's context
    118  * \param[in,out]  si      Pointer to stream info to update. The size member
    119  *                         \ref MUST be properly initialized, but \ref MAY be
    120  *                         clobbered by the algorithm. This parameter \ref MAY
    121  *                         be NULL.
    122  *
    123  * \retval #VPX_CODEC_OK
    124  *     Bitstream is parsable and stream information updated
    125  */
    126 typedef vpx_codec_err_t (*vpx_codec_get_si_fn_t)(vpx_codec_alg_priv_t    *ctx,
    127         vpx_codec_stream_info_t *si);
    128 
    129 /*!\brief control function pointer prototype
    130  *
    131  * This function is used to exchange algorithm specific data with the decoder
    132  * instance. This can be used to implement features specific to a particular
    133  * algorithm.
    134  *
    135  * This function is called by the generic vpx_codec_control() wrapper
    136  * function, so plugins implementing this interface may trust the input
    137  * parameters to be properly initialized. However,  this interface does not
    138  * provide type safety for the exchanged data or assign meanings to the
    139  * control codes. Those details should be specified in the algorithm's
    140  * header file. In particular, the ctrl_id parameter is guaranteed to exist
    141  * in the algorithm's control mapping table, and the data parameter may be NULL.
    142  *
    143  *
    144  * \param[in]     ctx              Pointer to this instance's context
    145  * \param[in]     ctrl_id          Algorithm specific control identifier
    146  * \param[in,out] data             Data to exchange with algorithm instance.
    147  *
    148  * \retval #VPX_CODEC_OK
    149  *     The internal state data was deserialized.
    150  */
    151 typedef vpx_codec_err_t (*vpx_codec_control_fn_t)(vpx_codec_alg_priv_t  *ctx,
    152         int                  ctrl_id,
    153         va_list              ap);
    154 
    155 /*!\brief control function pointer mapping
    156  *
    157  * This structure stores the mapping between control identifiers and
    158  * implementing functions. Each algorithm provides a list of these
    159  * mappings. This list is searched by the vpx_codec_control() wrapper
    160  * function to determine which function to invoke. The special
    161  * value {0, NULL} is used to indicate end-of-list, and must be
    162  * present. The special value {0, <non-null>} can be used as a catch-all
    163  * mapping. This implies that ctrl_id values chosen by the algorithm
    164  * \ref MUST be non-zero.
    165  */
    166 typedef const struct
    167 {
    168     int                    ctrl_id;
    169     vpx_codec_control_fn_t   fn;
    170 } vpx_codec_ctrl_fn_map_t;
    171 
    172 /*!\brief decode data function pointer prototype
    173  *
    174  * Processes a buffer of coded data. If the processing results in a new
    175  * decoded frame becoming available, #VPX_CODEC_CB_PUT_SLICE and
    176  * #VPX_CODEC_CB_PUT_FRAME events are generated as appropriate. This
    177  * function is called by the generic vpx_codec_decode() wrapper function,
    178  * so plugins implementing this interface may trust the input parameters
    179  * to be properly initialized.
    180  *
    181  * \param[in] ctx          Pointer to this instance's context
    182  * \param[in] data         Pointer to this block of new coded data. If
    183  *                         NULL, a #VPX_CODEC_CB_PUT_FRAME event is posted
    184  *                         for the previously decoded frame.
    185  * \param[in] data_sz      Size of the coded data, in bytes.
    186  *
    187  * \return Returns #VPX_CODEC_OK if the coded data was processed completely
    188  *         and future pictures can be decoded without error. Otherwise,
    189  *         see the descriptions of the other error codes in ::vpx_codec_err_t
    190  *         for recoverability capabilities.
    191  */
    192 typedef vpx_codec_err_t (*vpx_codec_decode_fn_t)(vpx_codec_alg_priv_t  *ctx,
    193         const uint8_t         *data,
    194         unsigned int     data_sz,
    195         void        *user_priv,
    196         long         deadline);
    197 
    198 /*!\brief Decoded frames iterator
    199  *
    200  * Iterates over a list of the frames available for display. The iterator
    201  * storage should be initialized to NULL to start the iteration. Iteration is
    202  * complete when this function returns NULL.
    203  *
    204  * The list of available frames becomes valid upon completion of the
    205  * vpx_codec_decode call, and remains valid until the next call to vpx_codec_decode.
    206  *
    207  * \param[in]     ctx      Pointer to this instance's context
    208  * \param[in out] iter     Iterator storage, initialized to NULL
    209  *
    210  * \return Returns a pointer to an image, if one is ready for display. Frames
    211  *         produced will always be in PTS (presentation time stamp) order.
    212  */
    213 typedef vpx_image_t*(*vpx_codec_get_frame_fn_t)(vpx_codec_alg_priv_t *ctx,
    214         vpx_codec_iter_t     *iter);
    215 
    216 
    217 /*\brief e_xternal Memory Allocation memory map get iterator
    218  *
    219  * Iterates over a list of the memory maps requested by the decoder. The
    220  * iterator storage should be initialized to NULL to start the iteration.
    221  * Iteration is complete when this function returns NULL.
    222  *
    223  * \param[in out] iter     Iterator storage, initialized to NULL
    224  *
    225  * \return Returns a pointer to an memory segment descriptor, or NULL to
    226  *         indicate end-of-list.
    227  */
    228 typedef vpx_codec_err_t (*vpx_codec_get_mmap_fn_t)(const vpx_codec_ctx_t      *ctx,
    229         vpx_codec_mmap_t           *mmap,
    230         vpx_codec_iter_t           *iter);
    231 
    232 
    233 /*\brief e_xternal Memory Allocation memory map set iterator
    234  *
    235  * Sets a memory descriptor inside the decoder instance.
    236  *
    237  * \param[in] ctx      Pointer to this instance's context
    238  * \param[in] mmap     Memory map to store.
    239  *
    240  * \retval #VPX_CODEC_OK
    241  *     The memory map was accepted and stored.
    242  * \retval #VPX_CODEC_MEM_ERROR
    243  *     The memory map was rejected.
    244  */
    245 typedef vpx_codec_err_t (*vpx_codec_set_mmap_fn_t)(vpx_codec_ctx_t         *ctx,
    246         const vpx_codec_mmap_t  *mmap);
    247 
    248 
    249 typedef vpx_codec_err_t (*vpx_codec_encode_fn_t)(vpx_codec_alg_priv_t  *ctx,
    250         const vpx_image_t     *img,
    251         vpx_codec_pts_t        pts,
    252         unsigned long          duration,
    253         vpx_enc_frame_flags_t  flags,
    254         unsigned long          deadline);
    255 typedef const vpx_codec_cx_pkt_t*(*vpx_codec_get_cx_data_fn_t)(vpx_codec_alg_priv_t *ctx,
    256         vpx_codec_iter_t     *iter);
    257 
    258 typedef vpx_codec_err_t
    259 (*vpx_codec_enc_config_set_fn_t)(vpx_codec_alg_priv_t       *ctx,
    260                                  const vpx_codec_enc_cfg_t  *cfg);
    261 typedef vpx_fixed_buf_t *
    262 (*vpx_codec_get_global_headers_fn_t)(vpx_codec_alg_priv_t   *ctx);
    263 
    264 typedef vpx_image_t *
    265 (*vpx_codec_get_preview_frame_fn_t)(vpx_codec_alg_priv_t   *ctx);
    266 
    267 /*!\brief usage configuration mapping
    268  *
    269  * This structure stores the mapping between usage identifiers and
    270  * configuration structures. Each algorithm provides a list of these
    271  * mappings. This list is searched by the vpx_codec_enc_config_default()
    272  * wrapper function to determine which config to return. The special value
    273  * {-1, {0}} is used to indicate end-of-list, and must be present. At least
    274  * one mapping must be present, in addition to the end-of-list.
    275  *
    276  */
    277 typedef const struct
    278 {
    279     int                 usage;
    280     vpx_codec_enc_cfg_t cfg;
    281 } vpx_codec_enc_cfg_map_t;
    282 
    283 #define NOT_IMPLEMENTED 0
    284 
    285 /*!\brief Decoder algorithm interface interface
    286  *
    287  * All decoders \ref MUST expose a variable of this type.
    288  */
    289 struct vpx_codec_iface
    290 {
    291     const char               *name;        /**< Identification String  */
    292     int                       abi_version; /**< Implemented ABI version */
    293     vpx_codec_caps_t          caps;    /**< Decoder capabilities */
    294     vpx_codec_init_fn_t       init;    /**< \copydoc ::vpx_codec_init_fn_t */
    295     vpx_codec_destroy_fn_t    destroy;     /**< \copydoc ::vpx_codec_destroy_fn_t */
    296     vpx_codec_ctrl_fn_map_t  *ctrl_maps;   /**< \copydoc ::vpx_codec_ctrl_fn_map_t */
    297     vpx_codec_get_mmap_fn_t   get_mmap;    /**< \copydoc ::vpx_codec_get_mmap_fn_t */
    298     vpx_codec_set_mmap_fn_t   set_mmap;    /**< \copydoc ::vpx_codec_set_mmap_fn_t */
    299     struct
    300     {
    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_peek_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     } dec;
    306     struct
    307     {
    308         vpx_codec_enc_cfg_map_t           *cfg_maps;      /**< \copydoc ::vpx_codec_enc_cfg_map_t */
    309         vpx_codec_encode_fn_t              encode;        /**< \copydoc ::vpx_codec_encode_fn_t */
    310         vpx_codec_get_cx_data_fn_t         get_cx_data;   /**< \copydoc ::vpx_codec_get_cx_data_fn_t */
    311         vpx_codec_enc_config_set_fn_t      cfg_set;       /**< \copydoc ::vpx_codec_enc_config_set_fn_t */
    312         vpx_codec_get_global_headers_fn_t  get_glob_hdrs; /**< \copydoc ::vpx_codec_enc_config_set_fn_t */
    313         vpx_codec_get_preview_frame_fn_t   get_preview;   /**< \copydoc ::vpx_codec_get_preview_frame_fn_t */
    314     } enc;
    315 };
    316 
    317 /*!\brief Callback function pointer / user data pair storage */
    318 typedef struct vpx_codec_priv_cb_pair
    319 {
    320     union
    321     {
    322         vpx_codec_put_frame_cb_fn_t    put_frame;
    323         vpx_codec_put_slice_cb_fn_t    put_slice;
    324     };
    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 casted to the proper type.
    336  */
    337 struct vpx_codec_priv
    338 {
    339     unsigned int                    sz;
    340     vpx_codec_iface_t              *iface;
    341     struct vpx_codec_alg_priv      *alg_priv;
    342     const char                     *err_detail;
    343     vpx_codec_flags_t               init_flags;
    344     struct
    345     {
    346         vpx_codec_priv_cb_pair_t    put_frame_cb;
    347         vpx_codec_priv_cb_pair_t    put_slice_cb;
    348     } dec;
    349     struct
    350     {
    351         int                         tbd;
    352         struct vpx_fixed_buf        cx_data_dst_buf;
    353         unsigned int                cx_data_pad_before;
    354         unsigned int                cx_data_pad_after;
    355         vpx_codec_cx_pkt_t          cx_data_pkt;
    356     } enc;
    357 };
    358 
    359 #undef VPX_CTRL_USE_TYPE
    360 #define VPX_CTRL_USE_TYPE(id, typ) \
    361     static typ id##__value(va_list args) {return va_arg(args, typ);} \
    362     static typ id##__convert(void *x)\
    363     {\
    364         union\
    365         {\
    366             void *x;\
    367             typ   d;\
    368         } u;\
    369         u.x = x;\
    370         return u.d;\
    371     }
    372 
    373 
    374 #undef VPX_CTRL_USE_TYPE_DEPRECATED
    375 #define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) \
    376     static typ id##__value(va_list args) {return va_arg(args, typ);} \
    377     static typ id##__convert(void *x)\
    378     {\
    379         union\
    380         {\
    381             void *x;\
    382             typ   d;\
    383         } u;\
    384         u.x = x;\
    385         return u.d;\
    386     }
    387 
    388 #define CAST(id, arg) id##__value(arg)
    389 #define RECAST(id, x) id##__convert(x)
    390 
    391 
    392 /* CODEC_INTERFACE convenience macro
    393  *
    394  * By convention, each codec interface is a struct with extern linkage, where
    395  * the symbol is suffixed with _algo. A getter function is also defined to
    396  * return a pointer to the struct, since in some cases it's easier to work
    397  * with text symbols than data symbols (see issue #169). This function has
    398  * the same name as the struct, less the _algo suffix. The CODEC_INTERFACE
    399  * macro is provided to define this getter function automatically.
    400  */
    401 #define CODEC_INTERFACE(id)\
    402 vpx_codec_iface_t* id(void) { return &id##_algo; }\
    403 vpx_codec_iface_t  id##_algo
    404 
    405 
    406 /* Internal Utility Functions
    407  *
    408  * The following functions are indended to be used inside algorithms as
    409  * utilities for manipulating vpx_codec_* data structures.
    410  */
    411 struct vpx_codec_pkt_list
    412 {
    413     unsigned int            cnt;
    414     unsigned int            max;
    415     struct vpx_codec_cx_pkt pkts[1];
    416 };
    417 
    418 #define vpx_codec_pkt_list_decl(n)\
    419     union {struct vpx_codec_pkt_list head;\
    420         struct {struct vpx_codec_pkt_list head;\
    421             struct vpx_codec_cx_pkt    pkts[n];} alloc;}
    422 
    423 #define vpx_codec_pkt_list_init(m)\
    424     (m)->alloc.head.cnt = 0,\
    425                           (m)->alloc.head.max = sizeof((m)->alloc.pkts) / sizeof((m)->alloc.pkts[0])
    426 
    427 int
    428 vpx_codec_pkt_list_add(struct vpx_codec_pkt_list *,
    429                        const struct vpx_codec_cx_pkt *);
    430 
    431 const vpx_codec_cx_pkt_t*
    432 vpx_codec_pkt_list_get(struct vpx_codec_pkt_list *list,
    433                        vpx_codec_iter_t           *iter);
    434 
    435 
    436 #include <stdio.h>
    437 #include <setjmp.h>
    438 struct vpx_internal_error_info
    439 {
    440     vpx_codec_err_t  error_code;
    441     int              has_detail;
    442     char             detail[80];
    443     int              setjmp;
    444     jmp_buf          jmp;
    445 };
    446 
    447 static void vpx_internal_error(struct vpx_internal_error_info *info,
    448                                vpx_codec_err_t                 error,
    449                                const char                     *fmt,
    450                                ...)
    451 {
    452     va_list ap;
    453 
    454     info->error_code = error;
    455     info->has_detail = 0;
    456 
    457     if (fmt)
    458     {
    459         size_t  sz = sizeof(info->detail);
    460 
    461         info->has_detail = 1;
    462         va_start(ap, fmt);
    463         vsnprintf(info->detail, sz - 1, fmt, ap);
    464         va_end(ap);
    465         info->detail[sz-1] = '\0';
    466     }
    467 
    468     if (info->setjmp)
    469         longjmp(info->jmp, info->error_code);
    470 }
    471 #endif
    472