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