usage.dox

   1 /*!\page usage Usage
   2
   3     The vpx 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 #vpx_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     #vpx_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 vpx_codec_get_caps() method. Attempts to invoke features not supported
  58     by an algorithm will generally result in #VPX_CODEC_INCAPABLE.
  59
  60     \if decoder
  61     Currently defined decoder features include:
  62     - \ref usage_cb
  63     - \ref usage_postproc
  64     \endif
  65
  66     \section usage_init Initialization
  67     To initialize a codec instance, the address of the codec context
  68     and interface structures are passed to an initialization function. Depending
  69     on the \ref usage_features that the codec supports, the codec could be
  70     initialized in different modes.
  71
  72     To prevent cases of confusion where the ABI of the library changes,
  73     the ABI is versioned. The ABI version number must be passed at
  74     initialization time to ensure the application is using a header file that
  75     matches the library. The current ABI version number is stored in the
  76     preprocessor macros #VPX_CODEC_ABI_VERSION, #VPX_ENCODER_ABI_VERSION, and
  77     #VPX_DECODER_ABI_VERSION. For convenience, each initialization function has
  78     a wrapper macro that inserts the correct version number. These macros are
  79     named like the initialization methods, but without the _ver suffix.
  80
  81
  82     The available initialization methods are:
  83     \if encoder
  84     \li #vpx_codec_enc_init (calls vpx_codec_enc_init_ver())
  85     \li #vpx_codec_enc_init_multi (calls vpx_codec_enc_init_multi_ver())
  86     \endif
  87     \if decoder
  88     \li #vpx_codec_dec_init (calls vpx_codec_dec_init_ver())
  89     \endif
  90
  91
  92     \section usage_errors Error Handling
  93     Almost all codec functions return an error status of type #vpx_codec_err_t.
  94     The semantics of how each error condition should be processed is clearly
  95     defined in the definitions of each enumerated value. Error values can be
  96     converted into ASCII strings with the vpx_codec_error() and
  97     vpx_codec_err_to_string() methods. The difference between these two methods is
  98     that vpx_codec_error() returns the error state from an initialized context,
  99     whereas vpx_codec_err_to_string() can be used in cases where an error occurs
 100     outside any context. The enumerated value returned from the last call can be
 101     retrieved from the <code>err</code> member of the decoder context as well.
 102     Finally, more detailed error information may be able to be obtained by using
 103     the vpx_codec_error_detail() method. Not all errors produce detailed error
 104     information.
 105
 106     In addition to error information, the codec library's build configuration
 107     is available at runtime on some platforms. This information can be returned
 108     by calling vpx_codec_build_config(), and is formatted as a base64 coded string
 109     (comprised of characters in the set [a-z_a-Z0-9+/]). This information is not
 110     useful to an application at runtime, but may be of use to vpx for support.
 111
 112
 113     \section usage_deadline Deadline
 114     Both the encoding and decoding functions have a <code>deadline</code>
 115     parameter. This parameter indicates the amount of time, in microseconds
 116     (us), that the application wants the codec to spend processing before
 117     returning. This is a soft deadline -- that is, the semantics of the
 118     requested operation take precedence over meeting the deadline. If, for
 119     example, an application sets a <code>deadline</code> of 1000us, and the
 120     frame takes 2000us to decode, the call to vpx_codec_decode() will return
 121     after 2000us. In this case the deadline is not met, but the semantics of the
 122     function are preserved. If, for the same frame, an application instead sets
 123     a <code>deadline</code> of 5000us, the decoder will see that it has 3000us
 124     remaining in its time slice when decoding completes. It could then choose to
 125     run a set of \ref usage_postproc filters, and perhaps would return after
 126     4000us (instead of the allocated 5000us). In this case the deadline is met,
 127     and the semantics of the call are preserved, as before.
 128
 129     The special value <code>0</code> is reserved to represent an infinite
 130     deadline. In this case, the codec will perform as much processing as
 131     possible to yield the highest quality frame.
 132
 133     By convention, the value <code>1</code> is used to mean "return as fast as
 134     possible."
 135
 136 */