usage.dox

/*!\page usage Usage

    The vpx 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

    Fore more information on decoder and encoder specific usage, see the
    following pages:
    \if decoder
    - \subpage usage_decode
    \endif
    \if decoder
    - \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 #vpx_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
    #vpx_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 vpx_codec_get_caps() method. Attempts to invoke features not supported
    by an algorithm will generally result in #VPX_CODEC_INCAPABLE.

    Currently defined features available in both encoders and decoders include:
    - \subpage usage_xma

    \if decoder
    Currently defined decoder features include:
    - \ref usage_cb
    - \ref usage_postproc
    \endif

    \section usage_init Initialization
    To initialize a codec instance, the address of the codec context