diff options
Diffstat (limited to 'third_party/aom/usage.dox')
| -rw-r--r-- | third_party/aom/usage.dox | 111 |
1 files changed, 0 insertions, 111 deletions
diff --git a/third_party/aom/usage.dox b/third_party/aom/usage.dox deleted file mode 100644 index 062d35a838..0000000000 --- a/third_party/aom/usage.dox +++ /dev/null @@ -1,111 +0,0 @@ -/*!\page usage Usage - - The aom multi-format codec SDK provides a unified interface amongst its - supported codecs. This abstraction allows applications using this SDK to - easily support multiple video formats with minimal code duplication or - "special casing." This section describes the interface common to all codecs. - For codec-specific details, see the \ref codecs page. - - The following sections are common to all codecs: - - \ref usage_types - - \ref usage_features - - \ref usage_init - - \ref usage_errors - - For more information on decoder and encoder specific usage, see the - following pages: - \if decoder - \li \subpage usage_decode - \endif - \if encoder - \li \subpage usage_encode - \endif - - \section usage_types Important Data Types - There are two important data structures to consider in this interface. - - \subsection usage_ctxs Contexts - A context is a storage area allocated by the calling application that the - codec may write into to store details about a single instance of that codec. - Most of the context is implementation specific, and thus opaque to the - application. The context structure as seen by the application is of fixed - size, and thus can be allocated with automatic storage or dynamically - on the heap. - - Most operations require an initialized codec context. Codec context - instances are codec specific. That is, the codec to be used for the encoded - video must be known at initialization time. See #aom_codec_ctx_t for further - information. - - \subsection usage_ifaces Interfaces - A codec interface is an opaque structure that controls how function calls - into the generic interface are dispatched to their codec-specific - implementations. Applications \ref MUSTNOT attempt to examine or override - this storage, as it contains internal implementation details likely to - change from release to release. - - Each supported codec will expose an interface structure to the application - as an <code>extern</code> reference to a structure of the incomplete type - #aom_codec_iface_t. - - \section usage_features Features - Several "features" are defined that are optionally implemented by codec - algorithms. Indeed, the same algorithm may support different features on - different platforms. The purpose of defining these features is that when - they are implemented, they conform to a common interface. The features, or - capabilities, of an algorithm can be queried from it's interface by using - the aom_codec_get_caps() method. Attempts to invoke features not supported - by an algorithm will generally result in #AOM_CODEC_INCAPABLE. - - \if decoder - Currently defined decoder features include: - - \ref usage_cb - \endif - - \section usage_init Initialization - To initialize a codec instance, the address of the codec context - and interface structures are passed to an initialization function. Depending - on the \ref usage_features that the codec supports, the codec could be - initialized in different modes. - - To prevent cases of confusion where the ABI of the library changes, - the ABI is versioned. The ABI version number must be passed at - initialization time to ensure the application is using a header file that - matches the library. The current ABI version number is stored in the - preprocessor macros #AOM_CODEC_ABI_VERSION, #AOM_ENCODER_ABI_VERSION, and - #AOM_DECODER_ABI_VERSION. For convenience, each initialization function has - a wrapper macro that inserts the correct version number. These macros are - named like the initialization methods, but without the _ver suffix. - - - The available initialization methods are: - \if encoder - \li #aom_codec_enc_init (calls aom_codec_enc_init_ver()) - \li #aom_codec_enc_init_multi (calls aom_codec_enc_init_multi_ver()) - \endif - \if decoder - \li #aom_codec_dec_init (calls aom_codec_dec_init_ver()) - \endif - - - \section usage_errors Error Handling - Almost all codec functions return an error status of type #aom_codec_err_t. - The semantics of how each error condition should be processed is clearly - defined in the definitions of each enumerated value. Error values can be - converted into ASCII strings with the aom_codec_error() and - aom_codec_err_to_string() methods. The difference between these two methods is - that aom_codec_error() returns the error state from an initialized context, - whereas aom_codec_err_to_string() can be used in cases where an error occurs - outside any context. The enumerated value returned from the last call can be - retrieved from the <code>err</code> member of the decoder context as well. - Finally, more detailed error information may be able to be obtained by using - the aom_codec_error_detail() method. Not all errors produce detailed error - information. - - In addition to error information, the codec library's build configuration - is available at runtime on some platforms. This information can be returned - by calling aom_codec_build_config(), and is formatted as a base64 coded string - (comprised of characters in the set [a-z_a-Z0-9+/]). This information is not - useful to an application at runtime, but may be of use to aom for support. - -*/ |