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 /*!\defgroup codec Common Algorithm Interface
  12  * This abstraction allows applications to easily support multiple video
  13  * formats with minimal code duplication. This section describes the interface
  14  * common to all codecs (both encoders and decoders).
  15  * @{
  16  */
  17
  18 /*!\file
  19  * \brief Describes the codec algorithm interface to applications.
  20  *
  21  * This file describes the interface between an application and a
  22  * video codec algorithm.
  23  *
  24  * An application instantiates a specific codec instance by using
  25  * vpx_codec_dec_init() or vpx_codec_enc_init() and a pointer to the
  26  * 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  *           int threads = 4;
  33  *           vpx_codec_dec_cfg_t cfg = { threads, 0, 0 };
  34  *           res = vpx_codec_dec_init(&algo, &my_codec, &cfg, 0);
  35  *       }
  36  *     </pre>
  37  *
  38  * Once initialized, the instance is manged using other functions from
  39  * the vpx_codec_* family.
  40  */
  41 #ifndef VPX_VPX_VPX_CODEC_H_
  42 #define VPX_VPX_VPX_CODEC_H_
  43
  44 #ifdef __cplusplus
  45 extern "C" {
  46 #endif
  47
  48 #include "./vpx_image.h"
  49 #include "./vpx_integer.h"
  50
  51 /*!\brief Decorator indicating a function is deprecated */
  52 #ifndef VPX_DEPRECATED
  53 #if defined(__GNUC__) && __GNUC__
  54 #define VPX_DEPRECATED __attribute__((deprecated))
  55 #elif defined(_MSC_VER)
  56 #define VPX_DEPRECATED
  57 #else
  58 #define VPX_DEPRECATED
  59 #endif
  60 #endif /* VPX_DEPRECATED */
  61
  62 #ifndef VPX_DECLSPEC_DEPRECATED
  63 #if defined(__GNUC__) && __GNUC__
  64 #define VPX_DECLSPEC_DEPRECATED /**< \copydoc #VPX_DEPRECATED */
  65 #elif defined(_MSC_VER)
  66 /*!\brief \copydoc #VPX_DEPRECATED */
  67 #define VPX_DECLSPEC_DEPRECATED __declspec(deprecated)
  68 #else
  69 #define VPX_DECLSPEC_DEPRECATED /**< \copydoc #VPX_DEPRECATED */
  70 #endif
  71 #endif /* VPX_DECLSPEC_DEPRECATED */
  72
  73 /*!\brief Decorator indicating a function is potentially unused */
  74 #ifndef VPX_UNUSED
  75 #if defined(__GNUC__) || defined(__clang__)
  76 #define VPX_UNUSED __attribute__((unused))
  77 #else
  78 #define VPX_UNUSED
  79 #endif
  80 #endif /* VPX_UNUSED */
  81
  82 /*!\brief Current ABI version number
  83  *
  84  * \internal
  85  * If this file is altered in any way that changes the ABI, this value
  86  * must be bumped.  Examples include, but are not limited to, changing
  87  * types, removing or reassigning enums, adding/removing/rearranging
  88  * fields to structures
  89  */
  90 #define VPX_CODEC_ABI_VERSION (4 + VPX_IMAGE_ABI_VERSION) /**<\hideinitializer*/
  91
  92 /*!\brief Algorithm return codes */
  93 typedef enum {
  94   /*!\brief Operation completed without error */
  95   VPX_CODEC_OK,
  96
  97   /*!\brief Unspecified error */
  98   VPX_CODEC_ERROR,
  99
 100   /*!\brief Memory operation failed */
 101   VPX_CODEC_MEM_ERROR,
 102
 103   /*!\brief ABI version mismatch */
 104   VPX_CODEC_ABI_MISMATCH,
 105
 106   /*!\brief Algorithm does not have required capability */
 107   VPX_CODEC_INCAPABLE,
 108
 109   /*!\brief The given bitstream is not supported.
 110    *
 111    * The bitstream was unable to be parsed at the highest level. The decoder
 112    * is unable to proceed. This error \ref SHOULD be treated as fatal to the
 113    * stream. */
 114   VPX_CODEC_UNSUP_BITSTREAM,
 115
 116   /*!\brief Encoded bitstream uses an unsupported feature
 117    *
 118    * The decoder does not implement a feature required by the encoder. This
 119    * return code should only be used for features that prevent future
 120    * pictures from being properly decoded. This error \ref MAY be treated as
 121    * fatal to the stream or \ref MAY be treated as fatal to the current GOP.
 122    */
 123   VPX_CODEC_UNSUP_FEATURE,
 124
 125   /*!\brief The coded data for this stream is corrupt or incomplete
 126    *
 127    * There was a problem decoding the current frame.  This return code
 128    * should only be used for failures that prevent future pictures from
 129    * being properly decoded. This error \ref MAY be treated as fatal to the
 130    * stream or \ref MAY be treated as fatal to the current GOP. If decoding
 131    * is continued for the current GOP, artifacts may be present.
 132    */
 133   VPX_CODEC_CORRUPT_FRAME,
 134
 135   /*!\brief An application-supplied parameter is not valid.
 136    *
 137    */
 138   VPX_CODEC_INVALID_PARAM,
 139
 140   /*!\brief An iterator reached the end of list.
 141    *
 142    */
 143   VPX_CODEC_LIST_END
 144
 145 } vpx_codec_err_t;
 146
 147 /*! \brief Codec capabilities bitfield
 148  *
 149  *  Each codec advertises the capabilities it supports as part of its
 150  *  ::vpx_codec_iface_t interface structure. Capabilities are extra interfaces
 151  *  or functionality, and are not required to be supported.
 152  *
 153  *  The available flags are specified by VPX_CODEC_CAP_* defines.
 154  */
 155 typedef long vpx_codec_caps_t;
 156 #define VPX_CODEC_CAP_DECODER 0x1 /**< Is a decoder */
 157 #define VPX_CODEC_CAP_ENCODER 0x2 /**< Is an encoder */
 158
 159 /*! Can support images at greater than 8 bitdepth.
 160  */
 161 #define VPX_CODEC_CAP_HIGHBITDEPTH 0x4
 162
 163 /*! \brief Initialization-time Feature Enabling
 164  *
 165  *  Certain codec features must be known at initialization time, to allow for
 166  *  proper memory allocation.
 167  *
 168  *  The available flags are specified by VPX_CODEC_USE_* defines.
 169  */
 170 typedef long vpx_codec_flags_t;
 171
 172 /*!\brief Codec interface structure.
 173  *
 174  * Contains function pointers and other data private to the codec
 175  * implementation. This structure is opaque to the application.
 176  */
 177 typedef const struct vpx_codec_iface vpx_codec_iface_t;
 178
 179 /*!\brief Codec private data structure.
 180  *
 181  * Contains data private to the codec implementation. This structure is opaque
 182  * to the application.
 183  */
 184 typedef struct vpx_codec_priv vpx_codec_priv_t;
 185
 186 /*!\brief Iterator
 187  *
 188  * Opaque storage used for iterating over lists.
 189  */
 190 typedef const void *vpx_codec_iter_t;
 191
 192 /*!\brief Codec context structure
 193  *
 194  * All codecs \ref MUST support this context structure fully. In general,
 195  * this data should be considered private to the codec algorithm, and
 196  * not be manipulated or examined by the calling application. Applications
 197  * may reference the 'name' member to get a printable description of the
 198  * algorithm.
 199  */
 200 typedef struct vpx_codec_ctx {
 201   const char *name;             /**< Printable interface name */
 202   vpx_codec_iface_t *iface;     /**< Interface pointers */
 203   vpx_codec_err_t err;          /**< Last returned error */
 204   const char *err_detail;       /**< Detailed info, if available */
 205   vpx_codec_flags_t init_flags; /**< Flags passed at init time */
 206   union {
 207     /**< Decoder Configuration Pointer */
 208     const struct vpx_codec_dec_cfg *dec;
 209     /**< Encoder Configuration Pointer */
 210     const struct vpx_codec_enc_cfg *enc;
 211     const void *raw;
 212   } config;               /**< Configuration pointer aliasing union */
 213   vpx_codec_priv_t *priv; /**< Algorithm private storage */
 214 } vpx_codec_ctx_t;
 215
 216 /*!\brief Bit depth for codec
 217  * *
 218  * This enumeration determines the bit depth of the codec.
 219  */
 220 typedef enum vpx_bit_depth {
 221   VPX_BITS_8 = 8,   /**<  8 bits */
 222   VPX_BITS_10 = 10, /**< 10 bits */
 223   VPX_BITS_12 = 12, /**< 12 bits */
 224 } vpx_bit_depth_t;
 225
 226 /*
 227  * Library Version Number Interface
 228  *
 229  * For example, see the following sample return values:
 230  *     vpx_codec_version()           (1<<16 | 2<<8 | 3)
 231  *     vpx_codec_version_str()       "v1.2.3-rc1-16-gec6a1ba"
 232  *     vpx_codec_version_extra_str() "rc1-16-gec6a1ba"
 233  */
 234
 235 /*!\brief Return the version information (as an integer)
 236  *
 237  * Returns a packed encoding of the library version number. This will only
 238  * include
 239  * the major.minor.patch component of the version number. Note that this encoded
 240  * value should be accessed through the macros provided, as the encoding may
 241  * change
 242  * in the future.
 243  *
 244  */
 245 int vpx_codec_version(void);
 246 #define VPX_VERSION_MAJOR(v) \
 247   (((v) >> 16) & 0xff) /**< extract major from packed version */
 248 #define VPX_VERSION_MINOR(v) \
 249   (((v) >> 8) & 0xff) /**< extract minor from packed version */
 250 #define VPX_VERSION_PATCH(v) \
 251   (((v) >> 0) & 0xff) /**< extract patch from packed version */
 252
 253 /*!\brief Return the version major number */
 254 #define vpx_codec_version_major() ((vpx_codec_version() >> 16) & 0xff)
 255
 256 /*!\brief Return the version minor number */
 257 #define vpx_codec_version_minor() ((vpx_codec_version() >> 8) & 0xff)
 258
 259 /*!\brief Return the version patch number */
 260 #define vpx_codec_version_patch() ((vpx_codec_version() >> 0) & 0xff)
 261
 262 /*!\brief Return the version information (as a string)
 263  *
 264  * Returns a printable string containing the full library version number. This
 265  * may
 266  * contain additional text following the three digit version number, as to
 267  * indicate
 268  * release candidates, prerelease versions, etc.
 269  *
 270  */
 271 const char *vpx_codec_version_str(void);
 272
 273 /*!\brief Return the version information (as a string)
 274  *
 275  * Returns a printable "extra string". This is the component of the string
 276  * returned
 277  * by vpx_codec_version_str() following the three digit version number.
 278  *
 279  */
 280 const char *vpx_codec_version_extra_str(void);
 281
 282 /*!\brief Return the build configuration
 283  *
 284  * Returns a printable string containing an encoded version of the build
 285  * configuration. This may be useful to vpx support.
 286  *
 287  */
 288 const char *vpx_codec_build_config(void);
 289
 290 /*!\brief Return the name for a given interface
 291  *
 292  * Returns a human readable string for name of the given codec interface.
 293  *
 294  * \param[in]    iface     Interface pointer
 295  *
 296  */
 297 const char *vpx_codec_iface_name(vpx_codec_iface_t *iface);
 298
 299 /*!\brief Convert error number to printable string
 300  *
 301  * Returns a human readable string for the last error returned by the
 302  * algorithm. The returned error will be one line and will not contain
 303  * any newline characters.
 304  *
 305  *
 306  * \param[in]    err     Error number.
 307  *
 308  */
 309 const char *vpx_codec_err_to_string(vpx_codec_err_t err);
 310
 311 /*!\brief Retrieve error synopsis for codec context
 312  *
 313  * Returns a human readable string for the last error returned by the
 314  * algorithm. The returned error will be one line and will not contain
 315  * any newline characters.
 316  *
 317  *
 318  * \param[in]    ctx     Pointer to this instance's context.
 319  *
 320  */
 321 const char *vpx_codec_error(vpx_codec_ctx_t *ctx);
 322
 323 /*!\brief Retrieve detailed error information for codec context
 324  *
 325  * Returns a human readable string providing detailed information about
 326  * the last error.
 327  *
 328  * \param[in]    ctx     Pointer to this instance's context.
 329  *
 330  * \retval NULL
 331  *     No detailed information is available.
 332  */
 333 const char *vpx_codec_error_detail(vpx_codec_ctx_t *ctx);
 334
 335 /* REQUIRED FUNCTIONS
 336  *
 337  * The following functions are required to be implemented for all codecs.
 338  * They represent the base case functionality expected of all codecs.
 339  */
 340
 341 /*!\brief Destroy a codec instance
 342  *
 343  * Destroys a codec context, freeing any associated memory buffers.
 344  *
 345  * \param[in] ctx   Pointer to this instance's context
 346  *
 347  * \retval #VPX_CODEC_OK
 348  *     The codec algorithm initialized.
 349  * \retval #VPX_CODEC_MEM_ERROR
 350  *     Memory allocation failed.
 351  */
 352 vpx_codec_err_t vpx_codec_destroy(vpx_codec_ctx_t *ctx);
 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 /*!\brief Control algorithm
 364  *
 365  * This function is used to exchange algorithm specific data with the codec
 366  * instance. This can be used to implement features specific to a particular
 367  * algorithm.
 368  *
 369  * This wrapper function dispatches the request to the helper function
 370  * associated with the given ctrl_id. It tries to call this function
 371  * transparently, but will return #VPX_CODEC_ERROR if the request could not
 372  * be dispatched.
 373  *
 374  * Note that this function should not be used directly. Call the
 375  * #vpx_codec_control wrapper macro instead.
 376  *
 377  * \param[in]     ctx              Pointer to this instance's context
 378  * \param[in]     ctrl_id          Algorithm specific control identifier
 379  *
 380  * \retval #VPX_CODEC_OK
 381  *     The control request was processed.
 382  * \retval #VPX_CODEC_ERROR
 383  *     The control request was not processed.
 384  * \retval #VPX_CODEC_INVALID_PARAM
 385  *     The data was not valid.
 386  */
 387 vpx_codec_err_t vpx_codec_control_(vpx_codec_ctx_t *ctx, int ctrl_id, ...);
 388 #if defined(VPX_DISABLE_CTRL_TYPECHECKS) && VPX_DISABLE_CTRL_TYPECHECKS
 389 #define vpx_codec_control(ctx, id, data) vpx_codec_control_(ctx, id, data)
 390 #define VPX_CTRL_USE_TYPE(id, typ)
 391 #define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ)
 392 #define VPX_CTRL_VOID(id, typ)
 393
 394 #else
 395 /*!\brief vpx_codec_control wrapper macro
 396  *
 397  * This macro allows for type safe conversions across the variadic parameter
 398  * to vpx_codec_control_().
 399  *
 400  * \internal
 401  * It works by dispatching the call to the control function through a wrapper
 402  * function named with the id parameter.
 403  */
 404 #define vpx_codec_control(ctx, id, data) \
 405   vpx_codec_control_##id(ctx, id, data) /**<\hideinitializer*/
 406
 407 /*!\brief vpx_codec_control type definition macro
 408  *
 409  * This macro allows for type safe conversions across the variadic parameter
 410  * to vpx_codec_control_(). It defines the type of the argument for a given
 411  * control identifier.
 412  *
 413  * \internal
 414  * It defines a static function with
 415  * the correctly typed arguments as a wrapper to the type-unsafe internal
 416  * function.
 417  */
 418 #define VPX_CTRL_USE_TYPE(id, typ)                                           \
 419   static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *, int, typ) \
 420       VPX_UNUSED;                                                            \
 421                                                                              \
 422   static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *ctx,        \
 423                                                 int ctrl_id, typ data) {     \
 424     return vpx_codec_control_(ctx, ctrl_id, data);                           \
 425   } /**<\hideinitializer*/
 426
 427 /*!\brief vpx_codec_control deprecated type definition macro
 428  *
 429  * Like #VPX_CTRL_USE_TYPE, but indicates that the specified control is
 430  * deprecated and should not be used. Consult the documentation for your
 431  * codec for more information.
 432  *
 433  * \internal
 434  * It defines a static function with the correctly typed arguments as a
 435  * wrapper to the type-unsafe internal function.
 436  */
 437 #define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ)                            \
 438   VPX_DECLSPEC_DEPRECATED static vpx_codec_err_t vpx_codec_control_##id( \
 439       vpx_codec_ctx_t *, int, typ) VPX_DEPRECATED VPX_UNUSED;            \
 440                                                                          \
 441   VPX_DECLSPEC_DEPRECATED static vpx_codec_err_t vpx_codec_control_##id( \
 442       vpx_codec_ctx_t *ctx, int ctrl_id, typ data) {                     \
 443     return vpx_codec_control_(ctx, ctrl_id, data);                       \
 444   } /**<\hideinitializer*/
 445
 446 /*!\brief vpx_codec_control void type definition macro
 447  *
 448  * This macro allows for type safe conversions across the variadic parameter
 449  * to vpx_codec_control_(). It indicates that a given control identifier takes
 450  * no argument.
 451  *
 452  * \internal
 453  * It defines a static function without a data argument as a wrapper to the
 454  * type-unsafe internal function.
 455  */
 456 #define VPX_CTRL_VOID(id)                                               \
 457   static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *, int) \
 458       VPX_UNUSED;                                                       \
 459                                                                         \
 460   static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *ctx,   \
 461                                                 int ctrl_id) {          \
 462     return vpx_codec_control_(ctx, ctrl_id);                            \
 463   } /**<\hideinitializer*/
 464
 465 #endif
 466
 467 /*!@} - end defgroup codec*/
 468 #ifdef __cplusplus
 469 }
 470 #endif
 471 #endif  // VPX_VPX_VPX_CODEC_H_