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_integer.h"
46 #include "./vpx_image.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 (3 + 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 /*! \brief Initialization-time Feature Enabling
157 * Certain codec features must be known at initialization time, to allow for
158 * proper memory allocation.
160 * The available flags are specified by VPX_CODEC_USE_* defines.
162 typedef long vpx_codec_flags_t;
164 /*!\brief Codec interface structure.
166 * Contains function pointers and other data private to the codec
167 * implementation. This structure is opaque to the application.
169 typedef const struct vpx_codec_iface vpx_codec_iface_t;
171 /*!\brief Codec private data structure.
173 * Contains data private to the codec implementation. This structure is opaque
174 * to the application.
176 typedef struct vpx_codec_priv vpx_codec_priv_t;
180 * Opaque storage used for iterating over lists.
182 typedef const void *vpx_codec_iter_t;
184 /*!\brief Codec context structure
186 * All codecs \ref MUST support this context structure fully. In general,
187 * this data should be considered private to the codec algorithm, and
188 * not be manipulated or examined by the calling application. Applications
189 * may reference the 'name' member to get a printable description of the
192 typedef struct vpx_codec_ctx {
193 const char *name; /**< Printable interface name */
194 vpx_codec_iface_t *iface; /**< Interface pointers */
195 vpx_codec_err_t err; /**< Last returned error */
196 const char *err_detail; /**< Detailed info, if available */
197 vpx_codec_flags_t init_flags; /**< Flags passed at init time */
199 /**< Decoder Configuration Pointer */
200 const struct vpx_codec_dec_cfg *dec;
201 /**< Encoder Configuration Pointer */
202 const struct vpx_codec_enc_cfg *enc;
204 } config; /**< Configuration pointer aliasing union */
205 vpx_codec_priv_t *priv; /**< Algorithm private storage */
208 /*!\brief Bit depth for codec
210 * This enumeration determines the bit depth of the codec.
212 typedef enum vpx_bit_depth {
213 VPX_BITS_8 = 8, /**< 8 bits */
214 VPX_BITS_10 = 10, /**< 10 bits */
215 VPX_BITS_12 = 12, /**< 12 bits */
219 * Library Version Number Interface
221 * For example, see the following sample return values:
222 * vpx_codec_version() (1<<16 | 2<<8 | 3)
223 * vpx_codec_version_str() "v1.2.3-rc1-16-gec6a1ba"
224 * vpx_codec_version_extra_str() "rc1-16-gec6a1ba"
227 /*!\brief Return the version information (as an integer)
229 * Returns a packed encoding of the library version number. This will only
231 * the major.minor.patch component of the version number. Note that this encoded
232 * value should be accessed through the macros provided, as the encoding may
237 int vpx_codec_version(void);
238 #define VPX_VERSION_MAJOR(v) \
239 ((v >> 16) & 0xff) /**< extract major from packed version */
240 #define VPX_VERSION_MINOR(v) \
241 ((v >> 8) & 0xff) /**< extract minor from packed version */
242 #define VPX_VERSION_PATCH(v) \
243 ((v >> 0) & 0xff) /**< extract patch from packed version */
245 /*!\brief Return the version major number */
246 #define vpx_codec_version_major() ((vpx_codec_version() >> 16) & 0xff)
248 /*!\brief Return the version minor number */
249 #define vpx_codec_version_minor() ((vpx_codec_version() >> 8) & 0xff)
251 /*!\brief Return the version patch number */
252 #define vpx_codec_version_patch() ((vpx_codec_version() >> 0) & 0xff)
254 /*!\brief Return the version information (as a string)
256 * Returns a printable string containing the full library version number. This
258 * contain additional text following the three digit version number, as to
260 * release candidates, prerelease versions, etc.
263 const char *vpx_codec_version_str(void);
265 /*!\brief Return the version information (as a string)
267 * Returns a printable "extra string". This is the component of the string
269 * by vpx_codec_version_str() following the three digit version number.
272 const char *vpx_codec_version_extra_str(void);
274 /*!\brief Return the build configuration
276 * Returns a printable string containing an encoded version of the build
277 * configuration. This may be useful to vpx support.
280 const char *vpx_codec_build_config(void);
282 /*!\brief Return the name for a given interface
284 * Returns a human readable string for name of the given codec interface.
286 * \param[in] iface Interface pointer
289 const char *vpx_codec_iface_name(vpx_codec_iface_t *iface);
291 /*!\brief Convert error number to printable string
293 * Returns a human readable string for the last error returned by the
294 * algorithm. The returned error will be one line and will not contain
295 * any newline characters.
298 * \param[in] err Error number.
301 const char *vpx_codec_err_to_string(vpx_codec_err_t err);
303 /*!\brief Retrieve error synopsis for codec context
305 * Returns a human readable string for the last error returned by the
306 * algorithm. The returned error will be one line and will not contain
307 * any newline characters.
310 * \param[in] ctx Pointer to this instance's context.
313 const char *vpx_codec_error(vpx_codec_ctx_t *ctx);
315 /*!\brief Retrieve detailed error information for codec context
317 * Returns a human readable string providing detailed information about
320 * \param[in] ctx Pointer to this instance's context.
323 * No detailed information is available.
325 const char *vpx_codec_error_detail(vpx_codec_ctx_t *ctx);
327 /* REQUIRED FUNCTIONS
329 * The following functions are required to be implemented for all codecs.
330 * They represent the base case functionality expected of all codecs.
333 /*!\brief Destroy a codec instance
335 * Destroys a codec context, freeing any associated memory buffers.
337 * \param[in] ctx Pointer to this instance's context
339 * \retval #VPX_CODEC_OK
340 * The codec algorithm initialized.
341 * \retval #VPX_CODEC_MEM_ERROR
342 * Memory allocation failed.
344 vpx_codec_err_t vpx_codec_destroy(vpx_codec_ctx_t *ctx);
346 /*!\brief Get the capabilities of an algorithm.
348 * Retrieves the capabilities bitfield from the algorithm's interface.
350 * \param[in] iface Pointer to the algorithm interface
353 vpx_codec_caps_t vpx_codec_get_caps(vpx_codec_iface_t *iface);
355 /*!\brief Control algorithm
357 * This function is used to exchange algorithm specific data with the codec
358 * instance. This can be used to implement features specific to a particular
361 * This wrapper function dispatches the request to the helper function
362 * associated with the given ctrl_id. It tries to call this function
363 * transparently, but will return #VPX_CODEC_ERROR if the request could not
366 * Note that this function should not be used directly. Call the
367 * #vpx_codec_control wrapper macro instead.
369 * \param[in] ctx Pointer to this instance's context
370 * \param[in] ctrl_id Algorithm specific control identifier
372 * \retval #VPX_CODEC_OK
373 * The control request was processed.
374 * \retval #VPX_CODEC_ERROR
375 * The control request was not processed.
376 * \retval #VPX_CODEC_INVALID_PARAM
377 * The data was not valid.
379 vpx_codec_err_t vpx_codec_control_(vpx_codec_ctx_t *ctx, int ctrl_id, ...);
380 #if defined(VPX_DISABLE_CTRL_TYPECHECKS) && VPX_DISABLE_CTRL_TYPECHECKS
381 #define vpx_codec_control(ctx, id, data) vpx_codec_control_(ctx, id, data)
382 #define VPX_CTRL_USE_TYPE(id, typ)
383 #define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ)
384 #define VPX_CTRL_VOID(id, typ)
387 /*!\brief vpx_codec_control wrapper macro
389 * This macro allows for type safe conversions across the variadic parameter
390 * to vpx_codec_control_().
393 * It works by dispatching the call to the control function through a wrapper
394 * function named with the id parameter.
396 #define vpx_codec_control(ctx, id, data) \
397 vpx_codec_control_##id(ctx, id, data) /**<\hideinitializer*/
399 /*!\brief vpx_codec_control type definition macro
401 * This macro allows for type safe conversions across the variadic parameter
402 * to vpx_codec_control_(). It defines the type of the argument for a given
403 * control identifier.
406 * It defines a static function with
407 * the correctly typed arguments as a wrapper to the type-unsafe internal
410 #define VPX_CTRL_USE_TYPE(id, typ) \
411 static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *, int, typ) \
414 static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *ctx, \
415 int ctrl_id, typ data) { \
416 return vpx_codec_control_(ctx, ctrl_id, data); \
417 } /**<\hideinitializer*/
419 /*!\brief vpx_codec_control deprecated type definition macro
421 * Like #VPX_CTRL_USE_TYPE, but indicates that the specified control is
422 * deprecated and should not be used. Consult the documentation for your
423 * codec for more information.
426 * It defines a static function with the correctly typed arguments as a
427 * wrapper to the type-unsafe internal function.
429 #define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) \
430 DECLSPEC_DEPRECATED static vpx_codec_err_t vpx_codec_control_##id( \
431 vpx_codec_ctx_t *, int, typ) DEPRECATED UNUSED; \
433 DECLSPEC_DEPRECATED static vpx_codec_err_t vpx_codec_control_##id( \
434 vpx_codec_ctx_t *ctx, int ctrl_id, typ data) { \
435 return vpx_codec_control_(ctx, ctrl_id, data); \
436 } /**<\hideinitializer*/
438 /*!\brief vpx_codec_control void type definition macro
440 * This macro allows for type safe conversions across the variadic parameter
441 * to vpx_codec_control_(). It indicates that a given control identifier takes
445 * It defines a static function without a data argument as a wrapper to the
446 * type-unsafe internal function.
448 #define VPX_CTRL_VOID(id) \
449 static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *, int) \
452 static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *ctx, \
454 return vpx_codec_control_(ctx, ctrl_id); \
455 } /**<\hideinitializer*/
459 /*!@} - end defgroup codec*/
463 #endif // VPX_VPX_CODEC_H_