src/third_party/libvpx/source/libvpx/vpx/vpx_codec.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 /*!\defgroup codec Common Algorithm Interface
  13  * This abstraction allows applications to easily support multiple video
  14  * formats with minimal code duplication. This section describes the interface
  15  * common to all codecs (both encoders and decoders).
  16  * @{
  17  */
  18
  19 /*!\file
  20  * \brief Describes the codec algorithm interface to applications.
  21  *
  22  * This file describes the interface between an application and a
  23  * video codec algorithm.
  24  *
  25  * An application instantiates a specific codec instance by using
  26  * vpx_codec_init() and a pointer to the algorithm's interface structure:
  27  *     <pre>
  28  *     my_app.c:
  29  *       extern vpx_codec_iface_t my_codec;
  30  *       {
  31  *           vpx_codec_ctx_t algo;
  32  *           res = vpx_codec_init(&algo, &my_codec);
  33  *       }
  34  *     </pre>
  35  *
  36  * Once initialized, the instance is manged using other functions from
  37  * the vpx_codec_* family.
  38  */
  39 #ifndef VPX_VPX_CODEC_H_
  40 #define VPX_VPX_CODEC_H_
  41
  42 #ifdef __cplusplus
  43 extern "C" {
  44 #endif
  45
  46 #include "./vpx_integer.h"
  47 #include "./vpx_image.h"
  48
  49   /*!\brief Decorator indicating a function is deprecated */
  50 #ifndef DEPRECATED
  51 #if defined(__GNUC__) && __GNUC__
  52 #define DEPRECATED          __attribute__ ((deprecated))
  53 #elif defined(_MSC_VER)
  54 #define DEPRECATED
  55 #else
  56 #define DEPRECATED
  57 #endif
  58 #endif  /* DEPRECATED */
  59
  60 #ifndef DECLSPEC_DEPRECATED
  61 #if defined(__GNUC__) && __GNUC__
  62 #define DECLSPEC_DEPRECATED /**< \copydoc #DEPRECATED */
  63 #elif defined(_MSC_VER)
  64 #define DECLSPEC_DEPRECATED __declspec(deprecated) /**< \copydoc #DEPRECATED */
  65 #else
  66 #define DECLSPEC_DEPRECATED /**< \copydoc #DEPRECATED */
  67 #endif
  68 #endif  /* DECLSPEC_DEPRECATED */
  69
  70   /*!\brief Decorator indicating a function is potentially unused */
  71 #ifdef UNUSED
  72 #elif __GNUC__
  73 #define UNUSED __attribute__ ((unused))
  74 #else
  75 #define UNUSED
  76 #endif
  77
  78   /*!\brief Current ABI version number
  79    *
  80    * \internal
  81    * If this file is altered in any way that changes the ABI, this value
  82    * must be bumped.  Examples include, but are not limited to, changing
  83    * types, removing or reassigning enums, adding/removing/rearranging
  84    * fields to structures
  85    */
  86 #define VPX_CODEC_ABI_VERSION (2 + VPX_IMAGE_ABI_VERSION) /**<\hideinitializer*/
  87
  88   /*!\brief Algorithm return codes */
  89   typedef enum {
  90     /*!\brief Operation completed without error */
  91     VPX_CODEC_OK,
  92
  93     /*!\brief Unspecified error */
  94     VPX_CODEC_ERROR,
  95
  96     /*!\brief Memory operation failed */
  97     VPX_CODEC_MEM_ERROR,
  98
  99     /*!\brief ABI version mismatch */
 100     VPX_CODEC_ABI_MISMATCH,
 101
 102     /*!\brief Algorithm does not have required capability */
 103     VPX_CODEC_INCAPABLE,
 104
 105     /*!\brief The given bitstream is not supported.
 106      *
 107      * The bitstream was unable to be parsed at the highest level. The decoder
 108      * is unable to proceed. This error \ref SHOULD be treated as fatal to the
 109      * stream. */
 110     VPX_CODEC_UNSUP_BITSTREAM,
 111
 112     /*!\brief Encoded bitstream uses an unsupported feature
 113      *
 114      * The decoder does not implement a feature required by the encoder. This
 115      * return code should only be used for features that prevent future
 116      * pictures from being properly decoded. This error \ref MAY be treated as
 117      * fatal to the stream or \ref MAY be treated as fatal to the current GOP.
 118      */
 119     VPX_CODEC_UNSUP_FEATURE,
 120
 121     /*!\brief The coded data for this stream is corrupt or incomplete
 122      *
 123      * There was a problem decoding the current frame.  This return code
 124      * should only be used for failures that prevent future pictures from
 125      * being properly decoded. This error \ref MAY be treated as fatal to the
 126      * stream or \ref MAY be treated as fatal to the current GOP. If decoding
 127      * is continued for the current GOP, artifacts may be present.
 128      */
 129     VPX_CODEC_CORRUPT_FRAME,
 130
 131     /*!\brief An application-supplied parameter is not valid.
 132      *
 133      */
 134     VPX_CODEC_INVALID_PARAM,
 135
 136     /*!\brief An iterator reached the end of list.
 137      *
 138      */
 139     VPX_CODEC_LIST_END
 140
 141   }
 142   vpx_codec_err_t;
 143
 144
 145   /*! \brief Codec capabilities bitfield
 146    *
 147    *  Each codec advertises the capabilities it supports as part of its
 148    *  ::vpx_codec_iface_t interface structure. Capabilities are extra interfaces
 149    *  or functionality, and are not required to be supported.
 150    *
 151    *  The available flags are specified by VPX_CODEC_CAP_* defines.
 152    */
 153   typedef long vpx_codec_caps_t;
 154 #define VPX_CODEC_CAP_DECODER 0x1 /**< Is a decoder */
 155 #define VPX_CODEC_CAP_ENCODER 0x2 /**< Is an encoder */
 156 #define VPX_CODEC_CAP_XMA     0x4 /**< Supports eXternal Memory Allocation */
 157
 158
 159   /*! \brief Initialization-time Feature Enabling
 160    *
 161    *  Certain codec features must be known at initialization time, to allow for
 162    *  proper memory allocation.
 163    *
 164    *  The available flags are specified by VPX_CODEC_USE_* defines.
 165    */
 166   typedef long vpx_codec_flags_t;
 167 #define VPX_CODEC_USE_XMA 0x00000001    /**< Use eXternal Memory Allocation mode */
 168
 169
 170   /*!\brief Codec interface structure.
 171    *
 172    * Contains function pointers and other data private to the codec
 173    * implementation. This structure is opaque to the application.
 174    */
 175   typedef const struct vpx_codec_iface vpx_codec_iface_t;
 176
 177
 178   /*!\brief Codec private data structure.
 179    *
 180    * Contains data private to the codec implementation. This structure is opaque
 181    * to the application.
 182    */
 183   typedef       struct vpx_codec_priv  vpx_codec_priv_t;
 184
 185
 186   /*!\brief Iterator
 187    *
 188    * Opaque storage used for iterating over lists.
 189    */
 190   typedef const void *vpx_codec_iter_t;
 191
 192
 193   /*!\brief Codec context structure
 194    *
 195    * All codecs \ref MUST support this context structure fully. In general,
 196    * this data should be considered private to the codec algorithm, and
 197    * not be manipulated or examined by the calling application. Applications
 198    * may reference the 'name' member to get a printable description of the
 199    * algorithm.
 200    */
 201   typedef struct vpx_codec_ctx {
 202     const char              *name;        /**< Printable interface name */
 203     vpx_codec_iface_t       *iface;       /**< Interface pointers */
 204     vpx_codec_err_t          err;         /**< Last returned error */
 205     const char              *err_detail;  /**< Detailed info, if available */
 206     vpx_codec_flags_t        init_flags;  /**< Flags passed at init time */
 207     union {
 208       struct vpx_codec_dec_cfg  *dec;   /**< Decoder Configuration Pointer */
 209       struct vpx_codec_enc_cfg  *enc;   /**< Encoder Configuration Pointer */
 210       void                      *raw;
 211     }                        config;      /**< Configuration pointer aliasing union */
 212     vpx_codec_priv_t        *priv;        /**< Algorithm private storage */
 213   } vpx_codec_ctx_t;
 214
 215   /*!\brief Bit depth for codec
 216    * *
 217    * This enumeration determines the bit depth of the codec.
 218    */
 219   typedef enum vpx_bit_depth {
 220     VPX_BITS_8,   /**< 8 bits  */
 221     VPX_BITS_10,  /**< 10 bits */
 222     VPX_BITS_12   /**< 12 bits */
 223   } vpx_bit_depth_t;
 224
 225   /*
 226    * Library Version Number Interface
 227    *
 228    * For example, see the following sample return values:
 229    *     vpx_codec_version()           (1<<16 | 2<<8 | 3)
 230    *     vpx_codec_version_str()       "v1.2.3-rc1-16-gec6a1ba"
 231    *     vpx_codec_version_extra_str() "rc1-16-gec6a1ba"
 232    */
 233
 234   /*!\brief Return the version information (as an integer)
 235    *
 236    * Returns a packed encoding of the library version number. This will only include
 237    * the major.minor.patch component of the version number. Note that this encoded
 238    * value should be accessed through the macros provided, as the encoding may change
 239    * in the future.
 240    *
 241    */
 242   int vpx_codec_version(void);
 243 #define VPX_VERSION_MAJOR(v) ((v>>16)&0xff) /**< extract major from packed version */
 244 #define VPX_VERSION_MINOR(v) ((v>>8)&0xff)  /**< extract minor from packed version */
 245 #define VPX_VERSION_PATCH(v) ((v>>0)&0xff)  /**< extract patch from packed version */
 246
 247   /*!\brief Return the version major number */
 248 #define vpx_codec_version_major() ((vpx_codec_version()>>16)&0xff)
 249
 250   /*!\brief Return the version minor number */
 251 #define vpx_codec_version_minor() ((vpx_codec_version()>>8)&0xff)
 252
 253   /*!\brief Return the version patch number */
 254 #define vpx_codec_version_patch() ((vpx_codec_version()>>0)&0xff)
 255
 256
 257   /*!\brief Return the version information (as a string)
 258    *
 259    * Returns a printable string containing the full library version number. This may
 260    * contain additional text following the three digit version number, as to indicate
 261    * release candidates, prerelease versions, etc.
 262    *
 263    */
 264   const char *vpx_codec_version_str(void);
 265
 266
 267   /*!\brief Return the version information (as a string)
 268    *
 269    * Returns a printable "extra string". This is the component of the string returned
 270    * by vpx_codec_version_str() following the three digit version number.
 271    *
 272    */
 273   const char *vpx_codec_version_extra_str(void);
 274
 275
 276   /*!\brief Return the build configuration
 277    *
 278    * Returns a printable string containing an encoded version of the build
 279    * configuration. This may be useful to vpx support.
 280    *
 281    */
 282   const char *vpx_codec_build_config(void);
 283
 284
 285   /*!\brief Return the name for a given interface
 286    *
 287    * Returns a human readable string for name of the given codec interface.
 288    *
 289    * \param[in]    iface     Interface pointer
 290    *
 291    */
 292   const char *vpx_codec_iface_name(vpx_codec_iface_t *iface);
 293
 294
 295   /*!\brief Convert error number to printable string
 296    *
 297    * Returns a human readable string for the last error returned by the
 298    * algorithm. The returned error will be one line and will not contain
 299    * any newline characters.
 300    *
 301    *
 302    * \param[in]    err     Error number.
 303    *
 304    */
 305   const char *vpx_codec_err_to_string(vpx_codec_err_t  err);
 306
 307
 308   /*!\brief Retrieve error synopsis for codec context
 309    *
 310    * Returns a human readable string for the last error returned by the
 311    * algorithm. The returned error will be one line and will not contain
 312    * any newline characters.
 313    *
 314    *
 315    * \param[in]    ctx     Pointer to this instance's context.
 316    *
 317    */
 318   const char *vpx_codec_error(vpx_codec_ctx_t  *ctx);
 319
 320
 321   /*!\brief Retrieve detailed error information for codec context
 322    *
 323    * Returns a human readable string providing detailed information about
 324    * the last error.
 325    *
 326    * \param[in]    ctx     Pointer to this instance's context.
 327    *
 328    * \retval NULL
 329    *     No detailed information is available.
 330    */
 331   const char *vpx_codec_error_detail(vpx_codec_ctx_t  *ctx);
 332
 333
 334   /* REQUIRED FUNCTIONS
 335    *
 336    * The following functions are required to be implemented for all codecs.
 337    * They represent the base case functionality expected of all codecs.
 338    */
 339
 340   /*!\brief Destroy a codec instance
 341    *
 342    * Destroys a codec context, freeing any associated memory buffers.
 343    *
 344    * \param[in] ctx   Pointer to this instance's context
 345    *
 346    * \retval #VPX_CODEC_OK
 347    *     The codec algorithm initialized.
 348    * \retval #VPX_CODEC_MEM_ERROR
 349    *     Memory allocation failed.
 350    */
 351   vpx_codec_err_t vpx_codec_destroy(vpx_codec_ctx_t *ctx);
 352
 353
 354   /*!\brief Get the capabilities of an algorithm.
 355    *
 356    * Retrieves the capabilities bitfield from the algorithm's interface.
 357    *
 358    * \param[in] iface   Pointer to the algorithm interface
 359    *
 360    */
 361   vpx_codec_caps_t vpx_codec_get_caps(vpx_codec_iface_t *iface);
 362
 363
 364   /*!\brief Control algorithm
 365    *
 366    * This function is used to exchange algorithm specific data with the codec
 367    * instance. This can be used to implement features specific to a particular
 368    * algorithm.
 369    *
 370    * This wrapper function dispatches the request to the helper function
 371    * associated with the given ctrl_id. It tries to call this function
 372    * transparently, but will return #VPX_CODEC_ERROR if the request could not
 373    * be dispatched.
 374    *
 375    * Note that this function should not be used directly. Call the
 376    * #vpx_codec_control wrapper macro instead.
 377    *
 378    * \param[in]     ctx              Pointer to this instance's context
 379    * \param[in]     ctrl_id          Algorithm specific control identifier
 380    *
 381    * \retval #VPX_CODEC_OK
 382    *     The control request was processed.
 383    * \retval #VPX_CODEC_ERROR
 384    *     The control request was not processed.
 385    * \retval #VPX_CODEC_INVALID_PARAM
 386    *     The data was not valid.
 387    */
 388   vpx_codec_err_t vpx_codec_control_(vpx_codec_ctx_t  *ctx,
 389                                      int               ctrl_id,
 390                                      ...);
 391 #if defined(VPX_DISABLE_CTRL_TYPECHECKS) && VPX_DISABLE_CTRL_TYPECHECKS
 392 #    define vpx_codec_control(ctx,id,data) vpx_codec_control_(ctx,id,data)
 393 #    define VPX_CTRL_USE_TYPE(id, typ)
 394 #    define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ)
 395 #    define VPX_CTRL_VOID(id, typ)
 396
 397 #else
 398   /*!\brief vpx_codec_control wrapper macro
 399    *
 400    * This macro allows for type safe conversions across the variadic parameter
 401    * to vpx_codec_control_().
 402    *
 403    * \internal
 404    * It works by dispatching the call to the control function through a wrapper
 405    * function named with the id parameter.
 406    */
 407 #    define vpx_codec_control(ctx,id,data) vpx_codec_control_##id(ctx,id,data)\
 408   /**<\hideinitializer*/
 409
 410
 411   /*!\brief vpx_codec_control type definition macro
 412    *
 413    * This macro allows for type safe conversions across the variadic parameter
 414    * to vpx_codec_control_(). It defines the type of the argument for a given
 415    * control identifier.
 416    *
 417    * \internal
 418    * It defines a static function with
 419    * the correctly typed arguments as a wrapper to the type-unsafe internal
 420    * function.
 421    */
 422 #    define VPX_CTRL_USE_TYPE(id, typ) \
 423   static vpx_codec_err_t \
 424   vpx_codec_control_##id(vpx_codec_ctx_t*, int, typ) UNUSED;\
 425   \
 426   static vpx_codec_err_t \
 427   vpx_codec_control_##id(vpx_codec_ctx_t  *ctx, int ctrl_id, typ data) {\
 428     return vpx_codec_control_(ctx, ctrl_id, data);\
 429   } /**<\hideinitializer*/
 430
 431
 432   /*!\brief vpx_codec_control deprecated type definition macro
 433    *
 434    * Like #VPX_CTRL_USE_TYPE, but indicates that the specified control is
 435    * deprecated and should not be used. Consult the documentation for your
 436    * codec for more information.
 437    *
 438    * \internal
 439    * It defines a static function with the correctly typed arguments as a
 440    * wrapper to the type-unsafe internal function.
 441    */
 442 #    define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) \
 443   DECLSPEC_DEPRECATED static vpx_codec_err_t \
 444   vpx_codec_control_##id(vpx_codec_ctx_t*, int, typ) DEPRECATED UNUSED;\
 445   \
 446   DECLSPEC_DEPRECATED static vpx_codec_err_t \
 447   vpx_codec_control_##id(vpx_codec_ctx_t  *ctx, int ctrl_id, typ data) {\
 448     return vpx_codec_control_(ctx, ctrl_id, data);\
 449   } /**<\hideinitializer*/
 450
 451
 452   /*!\brief vpx_codec_control void type definition macro
 453    *
 454    * This macro allows for type safe conversions across the variadic parameter
 455    * to vpx_codec_control_(). It indicates that a given control identifier takes
 456    * no argument.
 457    *
 458    * \internal
 459    * It defines a static function without a data argument as a wrapper to the
 460    * type-unsafe internal function.
 461    */
 462 #    define VPX_CTRL_VOID(id) \
 463   static vpx_codec_err_t \
 464   vpx_codec_control_##id(vpx_codec_ctx_t*, int) UNUSED;\
 465   \
 466   static vpx_codec_err_t \
 467   vpx_codec_control_##id(vpx_codec_ctx_t  *ctx, int ctrl_id) {\
 468     return vpx_codec_control_(ctx, ctrl_id);\
 469   } /**<\hideinitializer*/
 470
 471
 472 #endif
 473
 474
 475   /*!\defgroup cap_xma External Memory Allocation Functions
 476    *
 477    * The following functions are required to be implemented for all codecs
 478    * that advertise the VPX_CODEC_CAP_XMA capability. Calling these functions
 479    * for codecs that don't advertise this capability will result in an error
 480    * code being returned, usually VPX_CODEC_INCAPABLE
 481    * @{
 482    */
 483
 484
 485   /*!\brief Memory Map Entry
 486    *
 487    * This structure is used to contain the properties of a memory segment. It
 488    * is populated by the codec in the request phase, and by the calling
 489    * application once the requested allocation has been performed.
 490    */
 491   typedef struct vpx_codec_mmap {
 492     /*
 493      * The following members are set by the codec when requesting a segment
 494      */
 495     unsigned int   id;     /**< identifier for the segment's contents */
 496     unsigned long  sz;     /**< size of the segment, in bytes */
 497     unsigned int   align;  /**< required alignment of the segment, in bytes */
 498     unsigned int   flags;  /**< bitfield containing segment properties */
 499 #define VPX_CODEC_MEM_ZERO     0x1  /**< Segment must be zeroed by allocation */
 500 #define VPX_CODEC_MEM_WRONLY   0x2  /**< Segment need not be readable */
 501 #define VPX_CODEC_MEM_FAST     0x4  /**< Place in fast memory, if available */
 502
 503     /* The following members are to be filled in by the allocation function */
 504     void          *base;   /**< pointer to the allocated segment */
 505     void (*dtor)(struct vpx_codec_mmap *map);         /**< destructor to call */
 506     void          *priv;   /**< allocator private storage */
 507   } vpx_codec_mmap_t; /**< alias for struct vpx_codec_mmap */
 508
 509
 510   /*!\brief Iterate over the list of segments to allocate.
 511    *
 512    * Iterates over a list of the segments to allocate. The iterator storage
 513    * should be initialized to NULL to start the iteration. Iteration is complete
 514    * when this function returns VPX_CODEC_LIST_END. The amount of memory needed to
 515    * allocate is dependent upon the size of the encoded stream. In cases where the
 516    * stream is not available at allocation time, a fixed size must be requested.
 517    * The codec will not be able to operate on streams larger than the size used at
 518    * allocation time.
 519    *
 520    * \param[in]      ctx     Pointer to this instance's context.
 521    * \param[out]     mmap    Pointer to the memory map entry to populate.
 522    * \param[in,out]  iter    Iterator storage, initialized to NULL
 523    *
 524    * \retval #VPX_CODEC_OK
 525    *     The memory map entry was populated.
 526    * \retval #VPX_CODEC_ERROR
 527    *     Codec does not support XMA mode.
 528    * \retval #VPX_CODEC_MEM_ERROR
 529    *     Unable to determine segment size from stream info.
 530    */
 531   vpx_codec_err_t vpx_codec_get_mem_map(vpx_codec_ctx_t                *ctx,
 532                                         vpx_codec_mmap_t               *mmap,
 533                                         vpx_codec_iter_t               *iter);
 534
 535
 536   /*!\brief Identify allocated segments to codec instance
 537    *
 538    * Stores a list of allocated segments in the codec. Segments \ref MUST be
 539    * passed in the order they are read from vpx_codec_get_mem_map(), but may be
 540    * passed in groups of any size. Segments \ref MUST be set only once. The
 541    * allocation function \ref MUST ensure that the vpx_codec_mmap_t::base member
 542    * is non-NULL. If the segment requires cleanup handling (e.g., calling free()
 543    * or close()) then the vpx_codec_mmap_t::dtor member \ref MUST be populated.
 544    *
 545    * \param[in]      ctx     Pointer to this instance's context.
 546    * \param[in]      mmaps   Pointer to the first memory map entry in the list.
 547    * \param[in]      num_maps  Number of entries being set at this time
 548    *
 549    * \retval #VPX_CODEC_OK
 550    *     The segment was stored in the codec context.
 551    * \retval #VPX_CODEC_INCAPABLE
 552    *     Codec does not support XMA mode.
 553    * \retval #VPX_CODEC_MEM_ERROR
 554    *     Segment base address was not set, or segment was already stored.
 555
 556    */
 557   vpx_codec_err_t  vpx_codec_set_mem_map(vpx_codec_ctx_t   *ctx,
 558                                          vpx_codec_mmap_t  *mmaps,
 559                                          unsigned int       num_maps);
 560
 561   /*!@} - end defgroup cap_xma*/
 562   /*!@} - end defgroup codec*/
 563 #ifdef __cplusplus
 564 }
 565 #endif
 566 #endif  // VPX_VPX_CODEC_H_
 567