vpx/internal/vpx_codec_internal.h

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