usage.dox 5.19 KB
Newer Older
John Koleszar's avatar
John Koleszar committed
1 2
/*!\page usage Usage

3
    The aom multi-format codec SDK provides a unified interface amongst its
John Koleszar's avatar
John Koleszar committed
4 5 6 7 8 9 10 11 12 13 14
    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

15
    For more information on decoder and encoder specific usage, see the
John Koleszar's avatar
John Koleszar committed
16
    following pages:
17
    \if decoder
18
    \li \subpage usage_decode
19
    \endif
20 21
    \if encoder
    \li \subpage usage_encode
22
    \endif
John Koleszar's avatar
John Koleszar committed
23 24 25 26 27 28 29 30 31

    \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
James Zern's avatar
James Zern committed
32
    size, and thus can be allocated with automatic storage or dynamically
John Koleszar's avatar
John Koleszar committed
33 34 35 36
    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
37
    video must be known at initialization time. See #aom_codec_ctx_t for further
John Koleszar's avatar
John Koleszar committed
38 39 40 41 42 43 44 45 46 47 48
    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
49
    #aom_codec_iface_t.
John Koleszar's avatar
John Koleszar committed
50 51 52 53 54 55 56

    \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
57 58
    the aom_codec_get_caps() method. Attempts to invoke features not supported
    by an algorithm will generally result in #AOM_CODEC_INCAPABLE.
John Koleszar's avatar
John Koleszar committed
59 60 61 62 63 64 65 66 67 68

    \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
69
    initialized in different modes.
John Koleszar's avatar
John Koleszar committed
70 71 72 73 74

    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
75 76
    preprocessor macros #AOM_CODEC_ABI_VERSION, #AOM_ENCODER_ABI_VERSION, and
    #AOM_DECODER_ABI_VERSION. For convenience, each initialization function has
John Koleszar's avatar
John Koleszar committed
77 78 79 80 81
    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:
82
    \if encoder
83 84
    \li #aom_codec_enc_init (calls aom_codec_enc_init_ver())
    \li #aom_codec_enc_init_multi (calls aom_codec_enc_init_multi_ver())
85 86
    \endif
    \if decoder
87
    \li #aom_codec_dec_init (calls aom_codec_dec_init_ver())
88
    \endif
John Koleszar's avatar
John Koleszar committed
89 90 91


    \section usage_errors Error Handling
92
    Almost all codec functions return an error status of type #aom_codec_err_t.
John Koleszar's avatar
John Koleszar committed
93 94
    The semantics of how each error condition should be processed is clearly
    defined in the definitions of each enumerated value. Error values can be
95 96 97 98
    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
John Koleszar's avatar
John Koleszar committed
99 100 101
    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
102
    the aom_codec_error_detail() method. Not all errors produce detailed error
John Koleszar's avatar
John Koleszar committed
103 104 105 106
    information.

    In addition to error information, the codec library's build configuration
    is available at runtime on some platforms. This information can be returned
107
    by calling aom_codec_build_config(), and is formatted as a base64 coded string
John Koleszar's avatar
John Koleszar committed
108
    (comprised of characters in the set [a-z_a-Z0-9+/]). This information is not
109
    useful to an application at runtime, but may be of use to aom for support.
John Koleszar's avatar
John Koleszar committed
110 111

*/