2 * Copyright (c) 2010 The WebM project authors. All Rights Reserved.
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.
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).
19 * \brief Describes the codec algorithm interface to applications.
21 * This file describes the interface between an application and a
22 * video codec algorithm.
24 * An application instantiates a specific codec instance by using
25 * vpx_codec_init() and a pointer to the algorithm's interface structure:
28 * extern vpx_codec_iface_t my_codec;
30 * vpx_codec_ctx_t algo;
31 * res = vpx_codec_init(&algo, &my_codec);
35 * Once initialized, the instance is manged using other functions from
36 * the vpx_codec_* family.
38 #ifndef VPX_VPX_CODEC_H_
39 #define VPX_VPX_CODEC_H_
45 #include "vpx/vpx_image.h"
46 #include "vpx/vpx_integer.h"
48 /*!\brief Decorator indicating a function is deprecated */
50 #if defined(__GNUC__) && __GNUC__
51 #define DEPRECATED __attribute__((deprecated))
52 #elif defined(_MSC_VER)
57 #endif /* DEPRECATED */
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)
66 #define DECLSPEC_DEPRECATED /**< \copydoc #DEPRECATED */
68 #endif /* DECLSPEC_DEPRECATED */
70 /*!\brief Decorator indicating a function is potentially unused */
72 #elif defined(__GNUC__) || defined(__clang__)
73 #define UNUSED __attribute__((unused))
78 /*!\brief Current ABI version number
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
86 #define VPX_CODEC_ABI_VERSION (4 + VPX_IMAGE_ABI_VERSION) /**<\hideinitializer*/
88 /*!\brief Algorithm return codes */
90 /*!\brief Operation completed without error */
93 /*!\brief Unspecified error */
96 /*!\brief Memory operation failed */
99 /*!\brief ABI version mismatch */
100 VPX_CODEC_ABI_MISMATCH,
102 /*!\brief Algorithm does not have required capability */
105 /*!\brief The given bitstream is not supported.
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
110 VPX_CODEC_UNSUP_BITSTREAM,
112 /*!\brief Encoded bitstream uses an unsupported feature
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.
119 VPX_CODEC_UNSUP_FEATURE,
121 /*!\brief The coded data for this stream is corrupt or incomplete
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.
129 VPX_CODEC_CORRUPT_FRAME,
131 /*!\brief An application-supplied parameter is not valid.
134 VPX_CODEC_INVALID_PARAM,
136 /*!\brief An iterator reached the end of list.
143 /*! \brief Codec capabilities bitfield
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.
149 * The available flags are specified by VPX_CODEC_CAP_* defines.
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 */
155 /*! Can support images at greater than 8 bitdepth.
157 #define VPX_CODEC_CAP_HIGHBITDEPTH 0x4
159 /*! \brief Initialization-time Feature Enabling
161 * Certain codec features must be known at initialization time, to allow for
162 * proper memory allocation.
164 * The available flags are specified by VPX_CODEC_USE_* defines.
166 typedef long vpx_codec_flags_t;
168 /*!\brief Codec interface structure.
170 * Contains function pointers and other data private to the codec
171 * implementation. This structure is opaque to the application.
173 typedef const struct vpx_codec_iface vpx_codec_iface_t;
175 /*!\brief Codec private data structure.
177 * Contains data private to the codec implementation. This structure is opaque
178 * to the application.
180 typedef struct vpx_codec_priv vpx_codec_priv_t;
184 * Opaque storage used for iterating over lists.
186 typedef const void *vpx_codec_iter_t;
188 /*!\brief Codec context structure
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
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 */
203 /**< Decoder Configuration Pointer */
204 const struct vpx_codec_dec_cfg *dec;
205 /**< Encoder Configuration Pointer */
206 const struct vpx_codec_enc_cfg *enc;
208 } config; /**< Configuration pointer aliasing union */
209 vpx_codec_priv_t *priv; /**< Algorithm private storage */
212 /*!\brief Bit depth for codec
214 * This enumeration determines the bit depth of the codec.
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 */
223 * Library Version Number Interface
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"
231 /*!\brief Return the version information (as an integer)
233 * Returns a packed encoding of the library version number. This will only
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
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 */
249 /*!\brief Return the version major number */
250 #define vpx_codec_version_major() ((vpx_codec_version() >> 16) & 0xff)
252 /*!\brief Return the version minor number */
253 #define vpx_codec_version_minor() ((vpx_codec_version() >> 8) & 0xff)
255 /*!\brief Return the version patch number */
256 #define vpx_codec_version_patch() ((vpx_codec_version() >> 0) & 0xff)
258 /*!\brief Return the version information (as a string)
260 * Returns a printable string containing the full library version number. This
262 * contain additional text following the three digit version number, as to
264 * release candidates, prerelease versions, etc.
267 const char *vpx_codec_version_str(void);
269 /*!\brief Return the version information (as a string)
271 * Returns a printable "extra string". This is the component of the string
273 * by vpx_codec_version_str() following the three digit version number.
276 const char *vpx_codec_version_extra_str(void);
278 /*!\brief Return the build configuration
280 * Returns a printable string containing an encoded version of the build
281 * configuration. This may be useful to vpx support.
284 const char *vpx_codec_build_config(void);
286 /*!\brief Return the name for a given interface
288 * Returns a human readable string for name of the given codec interface.
290 * \param[in] iface Interface pointer
293 const char *vpx_codec_iface_name(vpx_codec_iface_t *iface);
295 /*!\brief Convert error number to printable string
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.
302 * \param[in] err Error number.
305 const char *vpx_codec_err_to_string(vpx_codec_err_t err);
307 /*!\brief Retrieve error synopsis for codec context
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.
314 * \param[in] ctx Pointer to this instance's context.
317 const char *vpx_codec_error(vpx_codec_ctx_t *ctx);
319 /*!\brief Retrieve detailed error information for codec context
321 * Returns a human readable string providing detailed information about
324 * \param[in] ctx Pointer to this instance's context.
327 * No detailed information is available.
329 const char *vpx_codec_error_detail(vpx_codec_ctx_t *ctx);
331 /* REQUIRED FUNCTIONS
333 * The following functions are required to be implemented for all codecs.
334 * They represent the base case functionality expected of all codecs.
337 /*!\brief Destroy a codec instance
339 * Destroys a codec context, freeing any associated memory buffers.
341 * \param[in] ctx Pointer to this instance's context
343 * \retval #VPX_CODEC_OK
344 * The codec algorithm initialized.
345 * \retval #VPX_CODEC_MEM_ERROR
346 * Memory allocation failed.
348 vpx_codec_err_t vpx_codec_destroy(vpx_codec_ctx_t *ctx);
350 /*!\brief Get the capabilities of an algorithm.
352 * Retrieves the capabilities bitfield from the algorithm's interface.
354 * \param[in] iface Pointer to the algorithm interface
357 vpx_codec_caps_t vpx_codec_get_caps(vpx_codec_iface_t *iface);
359 /*!\brief Control algorithm
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
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
370 * Note that this function should not be used directly. Call the
371 * #vpx_codec_control wrapper macro instead.
373 * \param[in] ctx Pointer to this instance's context
374 * \param[in] ctrl_id Algorithm specific control identifier
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.
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)
391 /*!\brief vpx_codec_control wrapper macro
393 * This macro allows for type safe conversions across the variadic parameter
394 * to vpx_codec_control_().
397 * It works by dispatching the call to the control function through a wrapper
398 * function named with the id parameter.
400 #define vpx_codec_control(ctx, id, data) \
401 vpx_codec_control_##id(ctx, id, data) /**<\hideinitializer*/
403 /*!\brief vpx_codec_control type definition macro
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.
410 * It defines a static function with
411 * the correctly typed arguments as a wrapper to the type-unsafe internal
414 #define VPX_CTRL_USE_TYPE(id, typ) \
415 static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *, int, typ) \
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*/
423 /*!\brief vpx_codec_control deprecated type definition macro
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.
430 * It defines a static function with the correctly typed arguments as a
431 * wrapper to the type-unsafe internal function.
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; \
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*/
442 /*!\brief vpx_codec_control void type definition macro
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
449 * It defines a static function without a data argument as a wrapper to the
450 * type-unsafe internal function.
452 #define VPX_CTRL_VOID(id) \
453 static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *, int) \
456 static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *ctx, \
458 return vpx_codec_control_(ctx, ctrl_id); \
459 } /**<\hideinitializer*/
463 /*!@} - end defgroup codec*/
467 #endif // VPX_VPX_CODEC_H_