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     Fore more information on decoder and encoder specific usage, see the
  16     following pages:
  17     \if decoder
  18     - \subpage usage_decode
  19     \endif
  20     \if decoder
  21     - \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     Currently defined features available in both encoders and decoders include:
  61     - \subpage usage_xma
  62
  63     \if decoder
  64     Currently defined decoder features include:
  65     - \ref usage_cb
  66     - \ref usage_postproc
  67     \endif
  68
  69     \section usage_init Initialization
  70     To initialize a codec instance, the address of the codec context
  71     and interface structures are passed to an initialization function. Depending
  72     on the \ref usage_features that the codec supports, the codec could be
  73     initialized in different modes. Most notably, the application may choose to
  74     use \ref usage_xma mode to gain fine grained control over how and where
  75     memory is allocated for the codec.
  76
  77     To prevent cases of confusion where the ABI of the library changes,
  78     the ABI is versioned. The ABI version number must be passed at
  79     initialization time to ensure the application is using a header file that
  80     matches the library. The current ABI version number is stored in the
  81     preprocessor macros #VPX_CODEC_ABI_VERSION, #VPX_ENCODER_ABI_VERSION, and
  82     #VPX_DECODER_ABI_VERSION. For convenience, each initialization function has
  83     a wrapper macro that inserts the correct version number. These macros are
  84     named like the initialization methods, but without the _ver suffix.
  85
  86
  87     The available initialization methods are:
  88     \if encoder - #vpx_codec_enc_init (calls vpx_codec_enc_init_ver()) \endif
  89     \if multi-encoder - #vpx_codec_enc_init_multi (calls vpx_codec_enc_init_multi_ver()) \endif
  90     \if decoder - #vpx_codec_dec_init (calls vpx_codec_dec_init_ver()) \endif
  91
  92
  93
  94     \section usage_errors Error Handling
  95     Almost all codec functions return an error status of type #vpx_codec_err_t.
  96     The semantics of how each error condition should be processed is clearly
  97     defined in the definitions of each enumerated value. Error values can be
  98     converted into ASCII strings with the vpx_codec_error() and
  99     vpx_codec_err_to_string() methods. The difference between these two methods is
 100     that vpx_codec_error() returns the error state from an initialized context,
 101     whereas vpx_codec_err_to_string() can be used in cases where an error occurs
 102     outside any context. The enumerated value returned from the last call can be
 103     retrieved from the <code>err</code> member of the decoder context as well.
 104     Finally, more detailed error information may be able to be obtained by using
 105     the vpx_codec_error_detail() method. Not all errors produce detailed error
 106     information.
 107
 108     In addition to error information, the codec library's build configuration
 109     is available at runtime on some platforms. This information can be returned
 110     by calling vpx_codec_build_config(), and is formatted as a base64 coded string
 111     (comprised of characters in the set [a-z_a-Z0-9+/]). This information is not
 112     useful to an application at runtime, but may be of use to vpx for support.
 113
 114
 115     \section usage_deadline Deadline
 116     Both the encoding and decoding functions have a <code>deadline</code>
 117     parameter. This parameter indicates the amount of time, in microseconds
 118     (us), that the application wants the codec to spend processing before
 119     returning. This is a soft deadline -- that is, the semantics of the
 120     requested operation take precedence over meeting the deadline. If, for
 121     example, an application sets a <code>deadline</code> of 1000us, and the
 122     frame takes 2000us to decode, the call to vpx_codec_decode() will return
 123     after 2000us. In this case the deadline is not met, but the semantics of the
 124     function are preserved. If, for the same frame, an application instead sets
 125     a <code>deadline</code> of 5000us, the decoder will see that it has 3000us
 126     remaining in its time slice when decoding completes. It could then choose to
 127     run a set of \ref usage_postproc filters, and perhaps would return after
 128     4000us (instead of the allocated 5000us). In this case the deadline is met,
 129     and the semantics of the call are preserved, as before.
 130
 131     The special value <code>0</code> is reserved to represent an infinite
 132     deadline. In this case, the codec will perform as much processing as
 133     possible to yield the highest quality frame.
 134
 135     By convention, the value <code>1</code> is used to mean "return as fast as
 136     possible."
 137
 138 */
 139
 140
 141 /*! \page usage_xma External Memory Allocation
 142     Applications that wish to have fine grained control over how and where
 143     decoders allocate memory \ref MAY make use of the eXternal Memory Allocation
 144     (XMA) interface. Not all codecs support the XMA \ref usage_features.
 145
 146     To use a decoder in XMA mode, the decoder \ref MUST be initialized with the
 147     vpx_codec_xma_init_ver() function. The amount of memory a decoder needs to
 148     allocate is heavily dependent on the size of the encoded video frames. The
 149     size of the video must be known before requesting the decoder's memory map.
 150     This stream information can be obtained with the vpx_codec_peek_stream_info()
 151     function, which does not require a constructed decoder context. If the exact
 152     stream is not known, a stream info structure can be created that reflects
 153     the maximum size that the decoder instance is required to support.
 154
 155     Once the decoder instance has been initialized and the stream information
 156     determined, the application calls the vpx_codec_get_mem_map() iterator
 157     repeatedly to get a list of the memory segments requested by the decoder.
 158     The iterator value should be initialized to NULL to request the first
 159     element, and the function will return #VPX_CODEC_LIST_END to signal the end of
 160     the list.
 161
 162     After each segment is identified, it must be passed to the codec through the
 163     vpx_codec_set_mem_map() function. Segments \ref MUST be passed in the same
 164     order as they are returned from vpx_codec_get_mem_map(), but there is no
 165     requirement that vpx_codec_get_mem_map() must finish iterating before
 166     vpx_codec_set_mem_map() is called. For instance, some applications may choose
 167     to get a list of all requests, construct an optimal heap, and then set all
 168     maps at once with one call. Other applications may set one map at a time,
 169     allocating it immediately after it is returned from vpx_codec_get_mem_map().
 170
 171     After all segments have been set using vpx_codec_set_mem_map(), the codec may
 172     be used as it would be in normal internal allocation mode.
 173
 174     \section usage_xma_seg_id Segment Identifiers
 175     Each requested segment is identified by an identifier unique to
 176     that decoder type. Some of these identifiers are private, while others are
 177     enumerated for application use. Identifiers not enumerated publicly are
 178     subject to change. Identifiers are non-consecutive.
 179
 180     \section usage_xma_seg_szalign Segment Size and Alignment
 181     The sz (size) and align (alignment) parameters describe the required size
 182     and alignment of the requested segment. Alignment will always be a power of
 183     two. Applications \ref MUST honor the alignment requested. Failure to do so
 184     could result in program crashes or may incur a speed penalty.
 185
 186     \section usage_xma_seg_flags Segment Flags
 187     The flags member of the segment structure indicates any requirements or
 188     desires of the codec for the particular segment. The #VPX_CODEC_MEM_ZERO flag
 189     indicates that the segment \ref MUST be zeroed by the application prior to
 190     passing it to the application. The #VPX_CODEC_MEM_WRONLY flag indicates that
 191     the segment will only be written into by the decoder, not read. If this flag
 192     is not set, the application \ref MUST insure that the memory segment is
 193     readable. On some platforms, framebuffer memory is writable but not
 194     readable, for example. The #VPX_CODEC_MEM_FAST flag indicates that the segment
 195     will be frequently accessed, and that it should be placed into fast memory,
 196     if any is available. The application \ref MAY choose to place other segments
 197     in fast memory as well, but the most critical segments will be identified by
 198     this flag.
 199
 200     \section usage_xma_seg_basedtor Segment Base Address and Destructor
 201     For each requested memory segment, the application must determine the
 202     address of a memory segment that meets the requirements of the codec. This
 203     address is set in the <code>base</code> member of the #vpx_codec_mmap
 204     structure. If the application requires processing when the segment is no
 205     longer used by the codec (for instance to deallocate it or close an
 206     associated file descriptor) the <code>dtor</code> and <code>priv</code>
 207     members can be set.
 208 */