usage.dox (5218B)
1 /*!\page usage Usage 2 3 The aom multi-format codec SDK provides a unified interface amongst its 4 supported codecs. This abstraction allows applications using this SDK to 5 easily support multiple video formats with minimal code duplication or 6 "special casing." This section describes the interface common to all codecs. 7 For codec-specific details, see the \ref codecs page. 8 9 The following sections are common to all codecs: 10 - \ref usage_types 11 - \ref usage_features 12 - \ref usage_init 13 - \ref usage_errors 14 15 For more information on decoder and encoder specific usage, see the 16 following pages: 17 \if decoder 18 \li \subpage usage_decode 19 \endif 20 \if encoder 21 \li \subpage usage_encode 22 \endif 23 24 \section usage_types Important Data Types 25 There are two important data structures to consider in this interface. 26 27 \subsection usage_ctxs Contexts 28 A context is a storage area allocated by the calling application that the 29 codec may write into to store details about a single instance of that codec. 30 Most of the context is implementation specific, and thus opaque to the 31 application. The context structure as seen by the application is of fixed 32 size, and thus can be allocated with automatic storage or dynamically 33 on the heap. 34 35 Most operations require an initialized codec context. Codec context 36 instances are codec specific. That is, the codec to be used for the encoded 37 video must be known at initialization time. See #aom_codec_ctx_t for further 38 information. 39 40 \subsection usage_ifaces Interfaces 41 A codec interface is an opaque structure that controls how function calls 42 into the generic interface are dispatched to their codec-specific 43 implementations. Applications \ref MUSTNOT attempt to examine or override 44 this storage, as it contains internal implementation details likely to 45 change from release to release. 46 47 Each supported codec will expose an interface structure to the application 48 as an <code>extern</code> reference to a structure of the incomplete type 49 #aom_codec_iface_t. 50 51 \section usage_features Features 52 Several "features" are defined that are optionally implemented by codec 53 algorithms. Indeed, the same algorithm may support different features on 54 different platforms. The purpose of defining these features is that when 55 they are implemented, they conform to a common interface. The features, or 56 capabilities, of an algorithm can be queried from it's interface by using 57 the aom_codec_get_caps() method. Attempts to invoke features not supported 58 by an algorithm will generally result in #AOM_CODEC_INCAPABLE. 59 60 \if decoder 61 Currently defined decoder features include: 62 \endif 63 64 \section usage_init Initialization 65 To initialize a codec instance, the address of the codec context 66 and interface structures are passed to an initialization function. Depending 67 on the \ref usage_features that the codec supports, the codec could be 68 initialized in different modes. 69 70 To prevent cases of confusion where the ABI of the library changes, 71 the ABI is versioned. The ABI version number must be passed at 72 initialization time to ensure the application is using a header file that 73 matches the library. The current ABI version number is stored in the 74 preprocessor macros #AOM_CODEC_ABI_VERSION, #AOM_ENCODER_ABI_VERSION, and 75 #AOM_DECODER_ABI_VERSION. For convenience, each initialization function has 76 a wrapper macro that inserts the correct version number. These macros are 77 named like the initialization methods, but without the _ver suffix. 78 79 80 The available initialization methods are: 81 \if encoder 82 \li #aom_codec_enc_init (calls aom_codec_enc_init_ver()) 83 \endif 84 \if decoder 85 \li #aom_codec_dec_init (calls aom_codec_dec_init_ver()) 86 \endif 87 88 89 \section usage_errors Error Handling 90 Almost all codec functions return an error status of type #aom_codec_err_t. 91 The semantics of how each error condition should be processed is clearly 92 defined in the definitions of each enumerated value. Error values can be 93 converted into ASCII strings with the aom_codec_error() and 94 aom_codec_err_to_string() methods. The difference between these two methods is 95 that aom_codec_error() returns the error state from an initialized context, 96 whereas aom_codec_err_to_string() can be used in cases where an error occurs 97 outside any context. The enumerated value returned from the last call can be 98 retrieved from the <code>err</code> member of the decoder context as well. 99 Finally, more detailed error information may be able to be obtained by using 100 the aom_codec_error_detail() method. Not all errors produce detailed error 101 information. 102 103 In addition to error information, the codec library's build configuration 104 is available at runtime on some platforms. This information can be returned 105 by calling aom_codec_build_config(), and is formatted as a base64 coded string 106 (comprised of characters in the set [a-z_a-Z0-9+/]). This information is not 107 useful to an application at runtime, but may be of use to aom for support. 108 109 */