granicus.if.org Git - libvpx/blob - 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_init() and a pointer to the algorithm's interface structure:
  26  *     <pre>
  27  *     my_app.c:
  28  *       extern vpx_codec_iface_t my_codec;
  29  *       {
  30  *           vpx_codec_ctx_t algo;
  31  *           res = vpx_codec_init(&algo, &my_codec);
  32  *       }
  33  *     </pre>
  34  *
  35  * Once initialized, the instance is manged using other functions from
  36  * the vpx_codec_* family.
  37  */
  38 #ifndef VPX_VPX_CODEC_H_
  39 #define VPX_VPX_CODEC_H_
  40
  41 #ifdef __cplusplus
  42 extern "C" {
  43 #endif
  44
  45 #include "./vpx_image.h"
  46 #include "./vpx_integer.h"
  47
  48 /*!\brief Decorator indicating a function is deprecated */
  49 #ifndef DEPRECATED
  50 #if defined(__GNUC__) && __GNUC__
  51 #define DEPRECATED __attribute__((deprecated))
  52 #elif defined(_MSC_VER)
  53 #define DEPRECATED
  54 #else
  55 #define DEPRECATED
  56 #endif
  57 #endif /* DEPRECATED */
  58
  59 #ifndef DECLSPEC_DEPRECATED
  60 #if defined(__GNUC__) && __GNUC__
  61 #define DECLSPEC_DEPRECATED /**< \copydoc #DEPRECATED */
  62 #elif defined(_MSC_VER)
  63 /*!\brief \copydoc #DEPRECATED */
  64 #define DECLSPEC_DEPRECATED __declspec(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 defined(__GNUC__) || defined(__clang__)
  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 (4 + 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 } vpx_codec_err_t;
 142
 143 /*! \brief Codec capabilities bitfield
 144  *
 145  *  Each codec advertises the capabilities it supports as part of its
 146  *  ::vpx_codec_iface_t interface structure. Capabilities are extra interfaces
 147  *  or functionality, and are not required to be supported.
 148  *
 149  *  The available flags are specified by VPX_CODEC_CAP_* defines.
 150  */
 151 typedef long vpx_codec_caps_t;
 152 #define VPX_CODEC_CAP_DECODER 0x1 /**< Is a decoder */
 153 #define VPX_CODEC_CAP_ENCODER 0x2 /**< Is an encoder */
 154
 155 /*! Can support images at greater than 8 bitdepth.
 156  */
 157 #define VPX_CODEC_CAP_HIGHBITDEPTH 0x4
 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
 168 /*!\brief Codec interface structure.
 169  *
 170  * Contains function pointers and other data private to the codec
 171  * implementation. This structure is opaque to the application.
 172  */
 173 typedef const struct vpx_codec_iface vpx_codec_iface_t;
 174
 175 /*!\brief Codec private data structure.
 176  *
 177  * Contains data private to the codec implementation. This structure is opaque
 178  * to the application.
 179  */
 180 typedef struct vpx_codec_priv vpx_codec_priv_t;
 181
 182 /*!\brief Iterator
 183  *
 184  * Opaque storage used for iterating over lists.
 185  */
 186 typedef const void *vpx_codec_iter_t;
 187
 188 /*!\brief Codec context structure
 189  *
 190  * All codecs \ref MUST support this context structure fully. In general,
 191  * this data should be considered private to the codec algorithm, and
 192  * not be manipulated or examined by the calling application. Applications
 193  * may reference the 'name' member to get a printable description of the
 194  * algorithm.
 195  */
 196 typedef struct vpx_codec_ctx {
 197   const char *name;             /**< Printable interface name */
 198   vpx_codec_iface_t *iface;     /**< Interface pointers */
 199   vpx_codec_err_t err;          /**< Last returned error */
 200   const char *err_detail;       /**< Detailed info, if available */
 201   vpx_codec_flags_t init_flags; /**< Flags passed at init time */
 202   union {
 203     /**< Decoder Configuration Pointer */
 204     const struct vpx_codec_dec_cfg *dec;
 205     /**< Encoder Configuration Pointer */
 206     const struct vpx_codec_enc_cfg *enc;
 207     const void *raw;
 208   } config;               /**< Configuration pointer aliasing union */
 209   vpx_codec_priv_t *priv; /**< Algorithm private storage */
 210 } vpx_codec_ctx_t;
 211
 212 /*!\brief Bit depth for codec
 213  * *
 214  * This enumeration determines the bit depth of the codec.
 215  */
 216 typedef enum vpx_bit_depth {
 217   VPX_BITS_8 = 8,   /**<  8 bits */
 218   VPX_BITS_10 = 10, /**< 10 bits */
 219   VPX_BITS_12 = 12, /**< 12 bits */
 220 } vpx_bit_depth_t;
 221
 222 /*
 223  * Library Version Number Interface
 224  *
 225  * For example, see the following sample return values:
 226  *     vpx_codec_version()           (1<<16 | 2<<8 | 3)
 227  *     vpx_codec_version_str()       "v1.2.3-rc1-16-gec6a1ba"
 228  *     vpx_codec_version_extra_str() "rc1-16-gec6a1ba"
 229  */
 230
 231 /*!\brief Return the version information (as an integer)
 232  *
 233  * Returns a packed encoding of the library version number. This will only
 234  * include
 235  * the major.minor.patch component of the version number. Note that this encoded
 236  * value should be accessed through the macros provided, as the encoding may
 237  * change
 238  * in the future.
 239  *
 240  */
 241 int vpx_codec_version(void);
 242 #define VPX_VERSION_MAJOR(v) \
 243   ((v >> 16) & 0xff) /**< extract major from packed version */
 244 #define VPX_VERSION_MINOR(v) \
 245   ((v >> 8) & 0xff) /**< extract minor from packed version */
 246 #define VPX_VERSION_PATCH(v) \
 247   ((v >> 0) & 0xff) /**< extract patch from packed version */
 248
 249 /*!\brief Return the version major number */
 250 #define vpx_codec_version_major() ((vpx_codec_version() >> 16) & 0xff)
 251
 252 /*!\brief Return the version minor number */
 253 #define vpx_codec_version_minor() ((vpx_codec_version() >> 8) & 0xff)
 254
 255 /*!\brief Return the version patch number */
 256 #define vpx_codec_version_patch() ((vpx_codec_version() >> 0) & 0xff)
 257
 258 /*!\brief Return the version information (as a string)
 259  *
 260  * Returns a printable string containing the full library version number. This
 261  * may
 262  * contain additional text following the three digit version number, as to
 263  * indicate
 264  * release candidates, prerelease versions, etc.
 265  *
 266  */
 267 const char *vpx_codec_version_str(void);
 268
 269 /*!\brief Return the version information (as a string)
 270  *
 271  * Returns a printable "extra string". This is the component of the string
 272  * returned
 273  * by vpx_codec_version_str() following the three digit version number.
 274  *
 275  */
 276 const char *vpx_codec_version_extra_str(void);
 277
 278 /*!\brief Return the build configuration
 279  *
 280  * Returns a printable string containing an encoded version of the build
 281  * configuration. This may be useful to vpx support.
 282  *
 283  */
 284 const char *vpx_codec_build_config(void);
 285
 286 /*!\brief Return the name for a given interface
 287  *
 288  * Returns a human readable string for name of the given codec interface.
 289  *
 290  * \param[in]    iface     Interface pointer
 291  *
 292  */
 293 const char *vpx_codec_iface_name(vpx_codec_iface_t *iface);
 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 /*!\brief Retrieve error synopsis for codec context
 308  *
 309  * Returns a human readable string for the last error returned by the
 310  * algorithm. The returned error will be one line and will not contain
 311  * any newline characters.
 312  *
 313  *
 314  * \param[in]    ctx     Pointer to this instance's context.
 315  *
 316  */
 317 const char *vpx_codec_error(vpx_codec_ctx_t *ctx);
 318
 319 /*!\brief Retrieve detailed error information for codec context
 320  *
 321  * Returns a human readable string providing detailed information about
 322  * the last error.
 323  *
 324  * \param[in]    ctx     Pointer to this instance's context.
 325  *
 326  * \retval NULL
 327  *     No detailed information is available.
 328  */
 329 const char *vpx_codec_error_detail(vpx_codec_ctx_t *ctx);
 330
 331 /* REQUIRED FUNCTIONS
 332  *
 333  * The following functions are required to be implemented for all codecs.
 334  * They represent the base case functionality expected of all codecs.
 335  */
 336
 337 /*!\brief Destroy a codec instance
 338  *
 339  * Destroys a codec context, freeing any associated memory buffers.
 340  *
 341  * \param[in] ctx   Pointer to this instance's context
 342  *
 343  * \retval #VPX_CODEC_OK
 344  *     The codec algorithm initialized.
 345  * \retval #VPX_CODEC_MEM_ERROR
 346  *     Memory allocation failed.
 347  */
 348 vpx_codec_err_t vpx_codec_destroy(vpx_codec_ctx_t *ctx);
 349
 350 /*!\brief Get the capabilities of an algorithm.
 351  *
 352  * Retrieves the capabilities bitfield from the algorithm's interface.
 353  *
 354  * \param[in] iface   Pointer to the algorithm interface
 355  *
 356  */
 357 vpx_codec_caps_t vpx_codec_get_caps(vpx_codec_iface_t *iface);
 358
 359 /*!\brief Control algorithm
 360  *
 361  * This function is used to exchange algorithm specific data with the codec
 362  * instance. This can be used to implement features specific to a particular
 363  * algorithm.
 364  *
 365  * This wrapper function dispatches the request to the helper function
 366  * associated with the given ctrl_id. It tries to call this function
 367  * transparently, but will return #VPX_CODEC_ERROR if the request could not
 368  * be dispatched.
 369  *
 370  * Note that this function should not be used directly. Call the
 371  * #vpx_codec_control wrapper macro instead.
 372  *
 373  * \param[in]     ctx              Pointer to this instance's context
 374  * \param[in]     ctrl_id          Algorithm specific control identifier
 375  *
 376  * \retval #VPX_CODEC_OK
 377  *     The control request was processed.
 378  * \retval #VPX_CODEC_ERROR
 379  *     The control request was not processed.
 380  * \retval #VPX_CODEC_INVALID_PARAM
 381  *     The data was not valid.
 382  */
 383 vpx_codec_err_t vpx_codec_control_(vpx_codec_ctx_t *ctx, int ctrl_id, ...);
 384 #if defined(VPX_DISABLE_CTRL_TYPECHECKS) && VPX_DISABLE_CTRL_TYPECHECKS
 385 #define vpx_codec_control(ctx, id, data) vpx_codec_control_(ctx, id, data)
 386 #define VPX_CTRL_USE_TYPE(id, typ)
 387 #define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ)
 388 #define VPX_CTRL_VOID(id, typ)
 389
 390 #else
 391 /*!\brief vpx_codec_control wrapper macro
 392  *
 393  * This macro allows for type safe conversions across the variadic parameter
 394  * to vpx_codec_control_().
 395  *
 396  * \internal
 397  * It works by dispatching the call to the control function through a wrapper
 398  * function named with the id parameter.
 399  */
 400 #define vpx_codec_control(ctx, id, data) \
 401   vpx_codec_control_##id(ctx, id, data) /**<\hideinitializer*/
 402
 403 /*!\brief vpx_codec_control type definition macro
 404  *
 405  * This macro allows for type safe conversions across the variadic parameter
 406  * to vpx_codec_control_(). It defines the type of the argument for a given
 407  * control identifier.
 408  *
 409  * \internal
 410  * It defines a static function with
 411  * the correctly typed arguments as a wrapper to the type-unsafe internal
 412  * function.
 413  */
 414 #define VPX_CTRL_USE_TYPE(id, typ)                                           \
 415   static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *, int, typ) \
 416       UNUSED;                                                                \
 417                                                                              \
 418   static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *ctx,        \
 419                                                 int ctrl_id, typ data) {     \
 420     return vpx_codec_control_(ctx, ctrl_id, data);                           \
 421   } /**<\hideinitializer*/
 422
 423 /*!\brief vpx_codec_control deprecated type definition macro
 424  *
 425  * Like #VPX_CTRL_USE_TYPE, but indicates that the specified control is
 426  * deprecated and should not be used. Consult the documentation for your
 427  * codec for more information.
 428  *
 429  * \internal
 430  * It defines a static function with the correctly typed arguments as a
 431  * wrapper to the type-unsafe internal function.
 432  */
 433 #define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ)                        \
 434   DECLSPEC_DEPRECATED static vpx_codec_err_t vpx_codec_control_##id( \
 435       vpx_codec_ctx_t *, int, typ) DEPRECATED UNUSED;                \
 436                                                                      \
 437   DECLSPEC_DEPRECATED static vpx_codec_err_t vpx_codec_control_##id( \
 438       vpx_codec_ctx_t *ctx, int ctrl_id, typ data) {                 \
 439     return vpx_codec_control_(ctx, ctrl_id, data);                   \
 440   } /**<\hideinitializer*/
 441
 442 /*!\brief vpx_codec_control void type definition macro
 443  *
 444  * This macro allows for type safe conversions across the variadic parameter
 445  * to vpx_codec_control_(). It indicates that a given control identifier takes
 446  * no argument.
 447  *
 448  * \internal
 449  * It defines a static function without a data argument as a wrapper to the
 450  * type-unsafe internal function.
 451  */
 452 #define VPX_CTRL_VOID(id)                                               \
 453   static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *, int) \
 454       UNUSED;                                                           \
 455                                                                         \
 456   static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *ctx,   \
 457                                                 int ctrl_id) {          \
 458     return vpx_codec_control_(ctx, ctrl_id);                            \
 459   } /**<\hideinitializer*/
 460
 461 #endif
 462
 463 /*!@} - end defgroup codec*/
 464 #ifdef __cplusplus
 465 }
 466 #endif
 467 #endif  // VPX_VPX_CODEC_H_