/* * Copyright (c) 2016, Alliance for Open Media. All rights reserved. * * This source code is subject to the terms of the BSD 2 Clause License and * the Alliance for Open Media Patent License 1.0. If the BSD 2 Clause License * was not distributed with this source code in the LICENSE file, you can * obtain it at www.aomedia.org/license/software. If the Alliance for Open * Media Patent License 1.0 was not distributed with this source code in the * PATENTS file, you can obtain it at www.aomedia.org/license/patent. */ /////////////////////////////////////////////////////////////////////////////// // Internal implementation details /////////////////////////////////////////////////////////////////////////////// // // There are two levels of interfaces used to access the AOM codec: the // aom_codec_iface and the aom_codec_ctx. // // 1. aom_codec_iface_t // (Related files: aom/aom_codec.h, aom/src/aom_codec.c, // aom/internal/aom_codec_internal.h, av1/av1_cx_iface.c, // av1/av1_dx_iface.c) // // Used to initialize the codec context, which contains the configuration for // for modifying the encoder/decoder during run-time. See the other // documentation in this header file for more details. For the most part, // users will call helper functions, such as aom_codec_iface_name, // aom_codec_get_caps, etc., to interact with it. // // The main purpose of the aom_codec_iface_t is to provide a way to generate // a default codec config, find out what capabilities the implementation has, // and create an aom_codec_ctx_t (which is actually used to interact with the // codec). // // Note that the implementations for the AV1 algorithm are located in // av1/av1_cx_iface.c and av1/av1_dx_iface.c // // // 2. aom_codec_ctx_t // (Related files: aom/aom_codec.h, av1/av1_cx_iface.c, av1/av1_dx_iface.c, // aom/aomcx.h, aom/aomdx.h, aom/src/aom_encoder.c, aom/src/aom_decoder.c) // // The actual interface between user code and the codec. It stores the name // of the codec, a pointer back to the aom_codec_iface_t that initialized it, // initialization flags, a config for either encoder or the decoder, and a // pointer to internal data. // // The codec is configured / queried through calls to aom_codec_control, // which takes a control ID (listed in aomcx.h and aomdx.h) and a parameter. // In the case of "getter" control IDs, the parameter is modified to have // the requested value; in the case of "setter" control IDs, the codec's // configuration is changed based on the parameter. Note that a aom_codec_err_t // is returned, which indicates if the operation was successful or not. // // Note that for the encoder, the aom_codec_alg_priv_t points to the // the aom_codec_alg_priv structure in av1/av1_cx_iface.c, and for the decoder, // the struct in av1/av1_dx_iface.c. Variables such as AV1_COMP cpi are stored // here and also used in the core algorithm. // // At the end, aom_codec_destroy should be called for each initialized // aom_codec_ctx_t. /*!\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 * aom_codec_dec_init() or aom_codec_enc_init() and a pointer to the * algorithm's interface structure: * <pre> * my_app.c: * extern aom_codec_iface_t my_codec; * { * aom_codec_ctx_t algo; * int threads = 4; * aom_codec_dec_cfg_t cfg = { threads, 0, 0, 1 }; * res = aom_codec_dec_init(&algo, &my_codec, &cfg, 0); * } * </pre> * * Once initialized, the instance is managed using other functions from * the aom_codec_* family. */ #ifndef AOM_AOM_AOM_CODEC_H_ #define AOM_AOM_AOM_CODEC_H_ #ifdef __cplusplus extern "C" { #endif #include "aom/aom_image.h" #include "aom/aom_integer.h" /*!\brief Decorator indicating a function is deprecated */ #ifndef AOM_DEPRECATED #if defined(__GNUC__) #define AOM_DEPRECATED … #elif defined(_MSC_VER) #define AOM_DEPRECATED #else #define AOM_DEPRECATED #endif #endif /* AOM_DEPRECATED */ #ifndef AOM_DECLSPEC_DEPRECATED #if defined(__GNUC__) #define AOM_DECLSPEC_DEPRECATED … #elif defined(_MSC_VER) /*!\brief \copydoc #AOM_DEPRECATED */ #define AOM_DECLSPEC_DEPRECATED … #else #define AOM_DECLSPEC_DEPRECATED … #endif #endif /* AOM_DECLSPEC_DEPRECATED */ /*!\brief Decorator indicating a function is potentially unused */ #ifdef AOM_UNUSED #elif defined(__GNUC__) || defined(__clang__) #define AOM_UNUSED … #else #define AOM_UNUSED #endif /*!\brief Decorator indicating that given struct/union/enum is packed */ #ifndef ATTRIBUTE_PACKED #if defined(__GNUC__) #define ATTRIBUTE_PACKED … #elif defined(_MSC_VER) #define ATTRIBUTE_PACKED #else #define ATTRIBUTE_PACKED #endif #endif /* ATTRIBUTE_PACKED */ /*!\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 AOM_CODEC_ABI_VERSION … /*!\brief Algorithm return codes */ aom_codec_err_t; /*! \brief Codec capabilities bitfield * * Each codec advertises the capabilities it supports as part of its * ::aom_codec_iface_t interface structure. Capabilities are extra interfaces * or functionality, and are not required to be supported. * * The available flags are specified by AOM_CODEC_CAP_* defines. */ aom_codec_caps_t; #define AOM_CODEC_CAP_DECODER … #define AOM_CODEC_CAP_ENCODER … /*! \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 AOM_CODEC_USE_* defines. */ aom_codec_flags_t; /*!\brief Time Stamp Type * * An integer, which when multiplied by the stream's time base, provides * the absolute time of a sample. */ aom_codec_pts_t; /*!\brief Codec interface structure. * * Contains function pointers and other data private to the codec * implementation. This structure is opaque to the application. Common * functions used with this structure: * - aom_codec_iface_name(aom_codec_iface_t *iface): get the * name of the codec * - aom_codec_get_caps(aom_codec_iface_t *iface): returns * the capabilities of the codec * - aom_codec_enc_config_default: generate the default config for * initializing the encoder (see documentation in aom_encoder.h) * - aom_codec_dec_init, aom_codec_enc_init: initialize the codec context * structure (see documentation on aom_codec_ctx). * * To get access to the AV1 encoder and decoder, use aom_codec_av1_cx() and * aom_codec_av1_dx(). */ aom_codec_iface_t; /*!\brief Codec private data structure. * * Contains data private to the codec implementation. This structure is opaque * to the application. */ aom_codec_priv_t; /*!\brief Compressed Frame Flags * * This type represents a bitfield containing information about a compressed * frame that may be useful to an application. The most significant 16 bits * can be used by an algorithm to provide additional detail, for example to * support frame types that are codec specific (MPEG-1 D-frames for example) */ aom_codec_frame_flags_t; #define AOM_FRAME_IS_KEY … /*!\brief frame can be dropped without affecting the stream (no future frame * depends on this one) */ #define AOM_FRAME_IS_DROPPABLE … /*!\brief this is an INTRA_ONLY frame */ #define AOM_FRAME_IS_INTRAONLY … /*!\brief this is an S-frame */ #define AOM_FRAME_IS_SWITCH … /*!\brief this is an error-resilient frame */ #define AOM_FRAME_IS_ERROR_RESILIENT … /*!\brief this is a key-frame dependent recovery-point frame */ #define AOM_FRAME_IS_DELAYED_RANDOM_ACCESS_POINT … /*!\brief Iterator * * Opaque storage used for iterating over lists. */ aom_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. */ aom_codec_ctx_t; /*!\brief Bit depth for codec * * * This enumeration determines the bit depth of the codec. */ aom_bit_depth_t; /*!\brief Superblock size selection. * * Defines the superblock size used for encoding. The superblock size can * either be fixed at 64x64 or 128x128 pixels, or it can be dynamically * selected by the encoder for each frame. */ aom_superblock_size_t; /* * Library Version Number Interface * * For example, see the following sample return values: * aom_codec_version() (1<<16 | 2<<8 | 3) * aom_codec_version_str() "v1.2.3-rc1-16-gec6a1ba" * aom_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 aom_codec_version(void); /*!\brief Return the major version number */ #define aom_codec_version_major() … /*!\brief Return the minor version number */ #define aom_codec_version_minor() … /*!\brief Return the patch version number */ #define aom_codec_version_patch() … /*!\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, pre-release versions, etc. * */ const char *aom_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 aom_codec_version_str() following the three digit version number. * */ const char *aom_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 aom support. * */ const char *aom_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 *aom_codec_iface_name(aom_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 *aom_codec_err_to_string(aom_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 *aom_codec_error(const aom_codec_ctx_t *ctx); /*!\brief Retrieve detailed error information for codec context * * Returns a human readable string providing detailed information about * the last error. The returned string is only valid until the next * aom_codec_* function call (except aom_codec_error and * aom_codec_error_detail) on the codec context. * * \param[in] ctx Pointer to this instance's context. * * \retval NULL * No detailed information is available. */ const char *aom_codec_error_detail(const aom_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 #AOM_CODEC_OK * The codec instance has been destroyed. * \retval #AOM_CODEC_INVALID_PARAM * ctx is a null pointer. * \retval #AOM_CODEC_ERROR * Codec context not initialized. */ aom_codec_err_t aom_codec_destroy(aom_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 * */ aom_codec_caps_t aom_codec_get_caps(aom_codec_iface_t *iface); /*!\name Codec Control * * The aom_codec_control function exchanges algorithm specific data with the * codec instance. Additionally, the macro AOM_CODEC_CONTROL_TYPECHECKED is * provided, which will type-check the parameter against the control ID before * calling aom_codec_control - note that this macro requires the control ID * to be directly encoded in it, e.g., * AOM_CODEC_CONTROL_TYPECHECKED(&ctx, AOME_SET_CPUUSED, 8). * * The codec control IDs can be found in aom.h, aomcx.h, and aomdx.h * (defined as aom_com_control_id, aome_enc_control_id, and aom_dec_control_id). * @{ */ /*!\brief Algorithm Control * * aom_codec_control takes a context, a control ID, and a third parameter * (with varying type). If the context is non-null and an error occurs, * ctx->err will be set to the same value as the return value. * * \param[in] ctx Pointer to this instance's context * \param[in] ctrl_id Algorithm specific control identifier. * Must be nonzero. * * \retval #AOM_CODEC_OK * The control request was processed. * \retval #AOM_CODEC_ERROR * The control request was not processed. * \retval #AOM_CODEC_INVALID_PARAM * The control ID was zero, or the data was not valid. */ aom_codec_err_t aom_codec_control(aom_codec_ctx_t *ctx, int ctrl_id, ...); /*!\brief Key & Value API * * aom_codec_set_option() takes a context, a key (option name) and a value. If * the context is non-null and an error occurs, ctx->err will be set to the same * value as the return value. * * \param[in] ctx Pointer to this instance's context * \param[in] name The name of the option (key) * \param[in] value The value of the option * * \retval #AOM_CODEC_OK * The value of the option was set. * \retval #AOM_CODEC_INVALID_PARAM * The data was not valid. * \retval #AOM_CODEC_ERROR * The option was not successfully set. */ aom_codec_err_t aom_codec_set_option(aom_codec_ctx_t *ctx, const char *name, const char *value); /*!\brief aom_codec_control wrapper macro (adds type-checking, less flexible) * * This macro allows for type safe conversions across the variadic parameter * to aom_codec_control(). However, it requires the explicit control ID * be passed in (it cannot be passed in via a variable) -- otherwise a compiler * error will occur. After the type checking, it calls aom_codec_control. */ #define AOM_CODEC_CONTROL_TYPECHECKED(ctx, id, data) … /*!\brief Creates type checking mechanisms for aom_codec_control * * It defines a static function with the correctly typed arguments as a wrapper * to the type-unsafe aom_codec_control function. It also creates a typedef * for each type. */ #define AOM_CTRL_USE_TYPE(id, typ) … /*!@} end Codec Control group */ /*!\brief OBU types. */ OBU_TYPE; /*!\brief OBU metadata types. */ OBU_METADATA_TYPE; /*!\brief Returns string representation of OBU_TYPE. * * \param[in] type The OBU_TYPE to convert to string. */ const char *aom_obu_type_to_string(OBU_TYPE type); /*!@} - end defgroup codec*/ #ifdef __cplusplus } #endif #endif // AOM_AOM_AOM_CODEC_H_
Codebase Browser
chromium