| /* | |
| * Copyright (c) 2010 The WebM project authors. All Rights Reserved. | |
| * | |
| * Use of this source code is governed by a BSD-style license | |
| * that can be found in the LICENSE file in the root of the source | |
| * tree. An additional intellectual property rights grant can be found | |
| * in the file PATENTS. All contributing project authors may | |
| * be found in the AUTHORS file in the root of the source tree. | |
| */ | |
| /*!\defgroup codec Common Algorithm Interface | |
| * This abstraction allows applications to easily support multiple video | |
| * formats with minimal code duplication. This section describes the interface | |
| * common to all codecs (both encoders and decoders). | |
| * @{ | |
| */ | |
| /*!\file | |
| * \brief Describes the codec algorithm interface to applications. | |
| * | |
| * This file describes the interface between an application and a | |
| * video codec algorithm. | |
| * | |
| * An application instantiates a specific codec instance by using | |
| * vpx_codec_init() and a pointer to the algorithm's interface structure: | |
| * <pre> | |
| * my_app.c: | |
| * extern vpx_codec_iface_t my_codec; | |
| * { | |
| * vpx_codec_ctx_t algo; | |
| * res = vpx_codec_init(&algo, &my_codec); | |
| * } | |
| * </pre> | |
| * | |
| * Once initialized, the instance is manged using other functions from | |
| * the vpx_codec_* family. | |
| */ | |
| #ifdef __cplusplus | |
| extern "C" { | |
| #endif | |
| #ifndef VPX_CODEC_H | |
| #define VPX_CODEC_H | |
| #include "vpx_integer.h" | |
| #include "vpx_image.h" | |
| /*!\brief Decorator indicating a function is deprecated */ | |
| #ifndef DEPRECATED | |
| #if defined(__GNUC__) && __GNUC__ | |
| #define DEPRECATED __attribute__ ((deprecated)) | |
| #define DECLSPEC_DEPRECATED /**< \copydoc #DEPRECATED */ | |
| #elif defined(_MSC_VER) | |
| #define DEPRECATED | |
| #define DECLSPEC_DEPRECATED __declspec(deprecated) /**< \copydoc #DEPRECATED */ | |
| #else | |
| #define DEPRECATED | |
| #define DECLSPEC_DEPRECATED /**< \copydoc #DEPRECATED */ | |
| #endif | |
| #endif | |
| /*!\brief Decorator indicating a function is potentially unused */ | |
| #ifdef UNUSED | |
| #elif __GNUC__ | |
| #define UNUSED __attribute__ ((unused)) | |
| #else | |
| #define UNUSED | |
| #endif | |
| /*!\brief Current ABI version number | |
| * | |
| * \internal | |
| * If this file is altered in any way that changes the ABI, this value | |
| * must be bumped. Examples include, but are not limited to, changing | |
| * types, removing or reassigning enums, adding/removing/rearranging | |
| * fields to structures | |
| */ | |
| #define VPX_CODEC_ABI_VERSION (2 + VPX_IMAGE_ABI_VERSION) /**<\hideinitializer*/ | |
| /*!\brief Algorithm return codes */ | |
| typedef enum { | |
| /*!\brief Operation completed without error */ | |
| VPX_CODEC_OK, | |
| /*!\brief Unspecified error */ | |
| VPX_CODEC_ERROR, | |
| /*!\brief Memory operation failed */ | |
| VPX_CODEC_MEM_ERROR, | |
| /*!\brief ABI version mismatch */ | |
| VPX_CODEC_ABI_MISMATCH, | |
| /*!\brief Algorithm does not have required capability */ | |
| VPX_CODEC_INCAPABLE, | |
| /*!\brief The given bitstream is not supported. | |
| * | |
| * The bitstream was unable to be parsed at the highest level. The decoder | |
| * is unable to proceed. This error \ref SHOULD be treated as fatal to the | |
| * stream. */ | |
| VPX_CODEC_UNSUP_BITSTREAM, | |
| /*!\brief Encoded bitstream uses an unsupported feature | |
| * | |
| * The decoder does not implement a feature required by the encoder. This | |
| * return code should only be used for features that prevent future | |
| * pictures from being properly decoded. This error \ref MAY be treated as | |
| * fatal to the stream or \ref MAY be treated as fatal to the current GOP. | |
| */ | |
| VPX_CODEC_UNSUP_FEATURE, | |
| /*!\brief The coded data for this stream is corrupt or incomplete | |
| * | |
| * There was a problem decoding the current frame. This return code | |
| * should only be used for failures that prevent future pictures from | |
| * being properly decoded. This error \ref MAY be treated as fatal to the | |
| * stream or \ref MAY be treated as fatal to the current GOP. If decoding | |
| * is continued for the current GOP, artifacts may be present. | |
| */ | |
| VPX_CODEC_CORRUPT_FRAME, | |
| /*!\brief An application-supplied parameter is not valid. | |
| * | |
| */ | |
| VPX_CODEC_INVALID_PARAM, | |
| /*!\brief An iterator reached the end of list. | |
| * | |
| */ | |
| VPX_CODEC_LIST_END | |
| } | |
| vpx_codec_err_t; | |
| /*! \brief Codec capabilities bitfield | |
| * | |
| * Each codec advertises the capabilities it supports as part of its | |
| * ::vpx_codec_iface_t interface structure. Capabilities are extra interfaces | |
| * or functionality, and are not required to be supported. | |
| * | |
| * The available flags are specified by VPX_CODEC_CAP_* defines. | |
| */ | |
| typedef long vpx_codec_caps_t; | |
| #define VPX_CODEC_CAP_DECODER 0x1 /**< Is a decoder */ | |
| #define VPX_CODEC_CAP_ENCODER 0x2 /**< Is an encoder */ | |
| #define VPX_CODEC_CAP_XMA 0x4 /**< Supports eXternal Memory Allocation */ | |
| /*! \brief Initialization-time Feature Enabling | |
| * | |
| * Certain codec features must be known at initialization time, to allow for | |
| * proper memory allocation. | |
| * | |
| * The available flags are specified by VPX_CODEC_USE_* defines. | |
| */ | |
| typedef long vpx_codec_flags_t; | |
| #define VPX_CODEC_USE_XMA 0x00000001 /**< Use eXternal Memory Allocation mode */ | |
| /*!\brief Codec interface structure. | |
| * | |
| * Contains function pointers and other data private to the codec | |
| * implementation. This structure is opaque to the application. | |
| */ | |
| typedef const struct vpx_codec_iface vpx_codec_iface_t; | |
| /*!\brief Codec private data structure. | |
| * | |
| * Contains data private to the codec implementation. This structure is opaque | |
| * to the application. | |
| */ | |
| typedef struct vpx_codec_priv vpx_codec_priv_t; | |
| /*!\brief Iterator | |
| * | |
| * Opaque storage used for iterating over lists. | |
| */ | |
| typedef const void *vpx_codec_iter_t; | |
| /*!\brief Codec context structure | |
| * | |
| * All codecs \ref MUST support this context structure fully. In general, | |
| * this data should be considered private to the codec algorithm, and | |
| * not be manipulated or examined by the calling application. Applications | |
| * may reference the 'name' member to get a printable description of the | |
| * algorithm. | |
| */ | |
| typedef struct vpx_codec_ctx | |
| { | |
| const char *name; /**< Printable interface name */ | |
| vpx_codec_iface_t *iface; /**< Interface pointers */ | |
| vpx_codec_err_t err; /**< Last returned error */ | |
| const char *err_detail; /**< Detailed info, if available */ | |
| vpx_codec_flags_t init_flags; /**< Flags passed at init time */ | |
| union | |
| { | |
| struct vpx_codec_dec_cfg *dec; /**< Decoder Configuration Pointer */ | |
| struct vpx_codec_enc_cfg *enc; /**< Encoder Configuration Pointer */ | |
| void *raw; | |
| } config; /**< Configuration pointer aliasing union */ | |
| vpx_codec_priv_t *priv; /**< Algorithm private storage */ | |
| } vpx_codec_ctx_t; | |
| /* | |
| * Library Version Number Interface | |
| * | |
| * For example, see the following sample return values: | |
| * vpx_codec_version() (1<<16 | 2<<8 | 3) | |
| * vpx_codec_version_str() "v1.2.3-rc1-16-gec6a1ba" | |
| * vpx_codec_version_extra_str() "rc1-16-gec6a1ba" | |
| */ | |
| /*!\brief Return the version information (as an integer) | |
| * | |
| * Returns a packed encoding of the library version number. This will only include | |
| * the major.minor.patch component of the version number. Note that this encoded | |
| * value should be accessed through the macros provided, as the encoding may change | |
| * in the future. | |
| * | |
| */ | |
| int vpx_codec_version(void); | |
| #define VPX_VERSION_MAJOR(v) ((v>>16)&0xff) /**< extract major from packed version */ | |
| #define VPX_VERSION_MINOR(v) ((v>>8)&0xff) /**< extract minor from packed version */ | |
| #define VPX_VERSION_PATCH(v) ((v>>0)&0xff) /**< extract patch from packed version */ | |
| /*!\brief Return the version major number */ | |
| #define vpx_codec_version_major() ((vpx_codec_version()>>16)&0xff) | |
| /*!\brief Return the version minor number */ | |
| #define vpx_codec_version_minor() ((vpx_codec_version()>>8)&0xff) | |
| /*!\brief Return the version patch number */ | |
| #define vpx_codec_version_patch() ((vpx_codec_version()>>0)&0xff) | |
| /*!\brief Return the version information (as a string) | |
| * | |
| * Returns a printable string containing the full library version number. This may | |
| * contain additional text following the three digit version number, as to indicate | |
| * release candidates, prerelease versions, etc. | |
| * | |
| */ | |
| const char *vpx_codec_version_str(void); | |
| /*!\brief Return the version information (as a string) | |
| * | |
| * Returns a printable "extra string". This is the component of the string returned | |
| * by vpx_codec_version_str() following the three digit version number. | |
| * | |
| */ | |
| const char *vpx_codec_version_extra_str(void); | |
| /*!\brief Return the build configuration | |
| * | |
| * Returns a printable string containing an encoded version of the build | |
| * configuration. This may be useful to vpx support. | |
| * | |
| */ | |
| const char *vpx_codec_build_config(void); | |
| /*!\brief Return the name for a given interface | |
| * | |
| * Returns a human readable string for name of the given codec interface. | |
| * | |
| * \param[in] iface Interface pointer | |
| * | |
| */ | |
| const char *vpx_codec_iface_name(vpx_codec_iface_t *iface); | |
| /*!\brief Convert error number to printable string | |
| * | |
| * Returns a human readable string for the last error returned by the | |
| * algorithm. The returned error will be one line and will not contain | |
| * any newline characters. | |
| * | |
| * | |
| * \param[in] err Error number. | |
| * | |
| */ | |
| const char *vpx_codec_err_to_string(vpx_codec_err_t err); | |
| /*!\brief Retrieve error synopsis for codec context | |
| * | |
| * Returns a human readable string for the last error returned by the | |
| * algorithm. The returned error will be one line and will not contain | |
| * any newline characters. | |
| * | |
| * | |
| * \param[in] ctx Pointer to this instance's context. | |
| * | |
| */ | |
| const char *vpx_codec_error(vpx_codec_ctx_t *ctx); | |
| /*!\brief Retrieve detailed error information for codec context | |
| * | |
| * Returns a human readable string providing detailed information about | |
| * the last error. | |
| * | |
| * \param[in] ctx Pointer to this instance's context. | |
| * | |
| * \retval NULL | |
| * No detailed information is available. | |
| */ | |
| const char *vpx_codec_error_detail(vpx_codec_ctx_t *ctx); | |
| /* REQUIRED FUNCTIONS | |
| * | |
| * The following functions are required to be implemented for all codecs. | |
| * They represent the base case functionality expected of all codecs. | |
| */ | |
| /*!\brief Destroy a codec instance | |
| * | |
| * Destroys a codec context, freeing any associated memory buffers. | |
| * | |
| * \param[in] ctx Pointer to this instance's context | |
| * | |
| * \retval #VPX_CODEC_OK | |
| * The codec algorithm initialized. | |
| * \retval #VPX_CODEC_MEM_ERROR | |
| * Memory allocation failed. | |
| */ | |
| vpx_codec_err_t vpx_codec_destroy(vpx_codec_ctx_t *ctx); | |
| /*!\brief Get the capabilities of an algorithm. | |
| * | |
| * Retrieves the capabilities bitfield from the algorithm's interface. | |
| * | |
| * \param[in] iface Pointer to the algorithm interface | |
| * | |
| */ | |
| vpx_codec_caps_t vpx_codec_get_caps(vpx_codec_iface_t *iface); | |
| /*!\brief Control algorithm | |
| * | |
| * This function is used to exchange algorithm specific data with the codec | |
| * instance. This can be used to implement features specific to a particular | |
| * algorithm. | |
| * | |
| * This wrapper function dispatches the request to the helper function | |
| * associated with the given ctrl_id. It tries to call this function | |
| * transparently, but will return #VPX_CODEC_ERROR if the request could not | |
| * be dispatched. | |
| * | |
| * Note that this function should not be used directly. Call the | |
| * #vpx_codec_control wrapper macro instead. | |
| * | |
| * \param[in] ctx Pointer to this instance's context | |
| * \param[in] ctrl_id Algorithm specific control identifier | |
| * | |
| * \retval #VPX_CODEC_OK | |
| * The control request was processed. | |
| * \retval #VPX_CODEC_ERROR | |
| * The control request was not processed. | |
| * \retval #VPX_CODEC_INVALID_PARAM | |
| * The data was not valid. | |
| */ | |
| vpx_codec_err_t vpx_codec_control_(vpx_codec_ctx_t *ctx, | |
| int ctrl_id, | |
| ...); | |
| #if defined(VPX_DISABLE_CTRL_TYPECHECKS) && VPX_DISABLE_CTRL_TYPECHECKS | |
| # define vpx_codec_control(ctx,id,data) vpx_codec_control_(ctx,id,data) | |
| # define VPX_CTRL_USE_TYPE(id, typ) | |
| # define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) | |
| # define VPX_CTRL_VOID(id, typ) | |
| #else | |
| /*!\brief vpx_codec_control wrapper macro | |
| * | |
| * This macro allows for type safe conversions across the variadic parameter | |
| * to vpx_codec_control_(). | |
| * | |
| * \internal | |
| * It works by dispatching the call to the control function through a wrapper | |
| * function named with the id parameter. | |
| */ | |
| # define vpx_codec_control(ctx,id,data) vpx_codec_control_##id(ctx,id,data)\ | |
| /**<\hideinitializer*/ | |
| /*!\brief vpx_codec_control type definition macro | |
| * | |
| * This macro allows for type safe conversions across the variadic parameter | |
| * to vpx_codec_control_(). It defines the type of the argument for a given | |
| * control identifier. | |
| * | |
| * \internal | |
| * It defines a static function with | |
| * the correctly typed arguments as a wrapper to the type-unsafe internal | |
| * function. | |
| */ | |
| # define VPX_CTRL_USE_TYPE(id, typ) \ | |
| static vpx_codec_err_t \ | |
| vpx_codec_control_##id(vpx_codec_ctx_t*, int, typ) UNUSED;\ | |
| \ | |
| static vpx_codec_err_t \ | |
| vpx_codec_control_##id(vpx_codec_ctx_t *ctx, int ctrl_id, typ data) {\ | |
| return vpx_codec_control_(ctx, ctrl_id, data);\ | |
| } /**<\hideinitializer*/ | |
| /*!\brief vpx_codec_control deprecated type definition macro | |
| * | |
| * Like #VPX_CTRL_USE_TYPE, but indicates that the specified control is | |
| * deprecated and should not be used. Consult the documentation for your | |
| * codec for more information. | |
| * | |
| * \internal | |
| * It defines a static function with the correctly typed arguments as a | |
| * wrapper to the type-unsafe internal function. | |
| */ | |
| # define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) \ | |
| DECLSPEC_DEPRECATED static vpx_codec_err_t \ | |
| vpx_codec_control_##id(vpx_codec_ctx_t*, int, typ) DEPRECATED UNUSED;\ | |
| \ | |
| DECLSPEC_DEPRECATED static vpx_codec_err_t \ | |
| vpx_codec_control_##id(vpx_codec_ctx_t *ctx, int ctrl_id, typ data) {\ | |
| return vpx_codec_control_(ctx, ctrl_id, data);\ | |
| } /**<\hideinitializer*/ | |
| /*!\brief vpx_codec_control void type definition macro | |
| * | |
| * This macro allows for type safe conversions across the variadic parameter | |
| * to vpx_codec_control_(). It indicates that a given control identifier takes | |
| * no argument. | |
| * | |
| * \internal | |
| * It defines a static function without a data argument as a wrapper to the | |
| * type-unsafe internal function. | |
| */ | |
| # define VPX_CTRL_VOID(id) \ | |
| static vpx_codec_err_t \ | |
| vpx_codec_control_##id(vpx_codec_ctx_t*, int) UNUSED;\ | |
| \ | |
| static vpx_codec_err_t \ | |
| vpx_codec_control_##id(vpx_codec_ctx_t *ctx, int ctrl_id) {\ | |
| return vpx_codec_control_(ctx, ctrl_id);\ | |
| } /**<\hideinitializer*/ | |
| #endif | |
| /*!\defgroup cap_xma External Memory Allocation Functions | |
| * | |
| * The following functions are required to be implemented for all codecs | |
| * that advertise the VPX_CODEC_CAP_XMA capability. Calling these functions | |
| * for codecs that don't advertise this capability will result in an error | |
| * code being returned, usually VPX_CODEC_INCAPABLE | |
| * @{ | |
| */ | |
| /*!\brief Memory Map Entry | |
| * | |
| * This structure is used to contain the properties of a memory segment. It | |
| * is populated by the codec in the request phase, and by the calling | |
| * application once the requested allocation has been performed. | |
| */ | |
| typedef struct vpx_codec_mmap | |
| { | |
| /* | |
| * The following members are set by the codec when requesting a segment | |
| */ | |
| unsigned int id; /**< identifier for the segment's contents */ | |
| unsigned long sz; /**< size of the segment, in bytes */ | |
| unsigned int align; /**< required alignment of the segment, in bytes */ | |
| unsigned int flags; /**< bitfield containing segment properties */ | |
| #define VPX_CODEC_MEM_ZERO 0x1 /**< Segment must be zeroed by allocation */ | |
| #define VPX_CODEC_MEM_WRONLY 0x2 /**< Segment need not be readable */ | |
| #define VPX_CODEC_MEM_FAST 0x4 /**< Place in fast memory, if available */ | |
| /* The following members are to be filled in by the allocation function */ | |
| void *base; /**< pointer to the allocated segment */ | |
| void (*dtor)(struct vpx_codec_mmap *map); /**< destructor to call */ | |
| void *priv; /**< allocator private storage */ | |
| } vpx_codec_mmap_t; /**< alias for struct vpx_codec_mmap */ | |
| /*!\brief Iterate over the list of segments to allocate. | |
| * | |
| * Iterates over a list of the segments to allocate. The iterator storage | |
| * should be initialized to NULL to start the iteration. Iteration is complete | |
| * when this function returns VPX_CODEC_LIST_END. The amount of memory needed to | |
| * allocate is dependent upon the size of the encoded stream. In cases where the | |
| * stream is not available at allocation time, a fixed size must be requested. | |
| * The codec will not be able to operate on streams larger than the size used at | |
| * allocation time. | |
| * | |
| * \param[in] ctx Pointer to this instance's context. | |
| * \param[out] mmap Pointer to the memory map entry to populate. | |
| * \param[in,out] iter Iterator storage, initialized to NULL | |
| * | |
| * \retval #VPX_CODEC_OK | |
| * The memory map entry was populated. | |
| * \retval #VPX_CODEC_ERROR | |
| * Codec does not support XMA mode. | |
| * \retval #VPX_CODEC_MEM_ERROR | |
| * Unable to determine segment size from stream info. | |
| */ | |
| vpx_codec_err_t vpx_codec_get_mem_map(vpx_codec_ctx_t *ctx, | |
| vpx_codec_mmap_t *mmap, | |
| vpx_codec_iter_t *iter); | |
| /*!\brief Identify allocated segments to codec instance | |
| * | |
| * Stores a list of allocated segments in the codec. Segments \ref MUST be | |
| * passed in the order they are read from vpx_codec_get_mem_map(), but may be | |
| * passed in groups of any size. Segments \ref MUST be set only once. The | |
| * allocation function \ref MUST ensure that the vpx_codec_mmap_t::base member | |
| * is non-NULL. If the segment requires cleanup handling (e.g., calling free() | |
| * or close()) then the vpx_codec_mmap_t::dtor member \ref MUST be populated. | |
| * | |
| * \param[in] ctx Pointer to this instance's context. | |
| * \param[in] mmaps Pointer to the first memory map entry in the list. | |
| * \param[in] num_maps Number of entries being set at this time | |
| * | |
| * \retval #VPX_CODEC_OK | |
| * The segment was stored in the codec context. | |
| * \retval #VPX_CODEC_INCAPABLE | |
| * Codec does not support XMA mode. | |
| * \retval #VPX_CODEC_MEM_ERROR | |
| * Segment base address was not set, or segment was already stored. | |
| */ | |
| vpx_codec_err_t vpx_codec_set_mem_map(vpx_codec_ctx_t *ctx, | |
| vpx_codec_mmap_t *mmaps, | |
| unsigned int num_maps); | |
| /*!@} - end defgroup cap_xma*/ | |
| /*!@} - end defgroup codec*/ | |
| #endif | |
| #ifdef __cplusplus | |
| } | |
| #endif |