137 строки
6.6 KiB
Plaintext
137 строки
6.6 KiB
Plaintext
/*!\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
|
|
|
|
For more information on decoder and encoder specific usage, see the
|
|
following pages:
|
|
\if decoder
|
|
\li \subpage usage_decode
|
|
\endif
|
|
\if encoder
|
|
\li \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.
|
|
|
|
\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
|
|
and interface structures are passed to an initialization function. Depending
|
|
on the \ref usage_features that the codec supports, the codec could be
|
|
initialized in different modes.
|
|
|
|
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
|
|
preprocessor macros #VPX_CODEC_ABI_VERSION, #VPX_ENCODER_ABI_VERSION, and
|
|
#VPX_DECODER_ABI_VERSION. For convenience, each initialization function has
|
|
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:
|
|
\if encoder
|
|
\li #vpx_codec_enc_init (calls vpx_codec_enc_init_ver())
|
|
\li #vpx_codec_enc_init_multi (calls vpx_codec_enc_init_multi_ver())
|
|
\endif
|
|
\if decoder
|
|
\li #vpx_codec_dec_init (calls vpx_codec_dec_init_ver())
|
|
\endif
|
|
|
|
|
|
\section usage_errors Error Handling
|
|
Almost all codec functions return an error status of type #vpx_codec_err_t.
|
|
The semantics of how each error condition should be processed is clearly
|
|
defined in the definitions of each enumerated value. Error values can be
|
|
converted into ASCII strings with the vpx_codec_error() and
|
|
vpx_codec_err_to_string() methods. The difference between these two methods is
|
|
that vpx_codec_error() returns the error state from an initialized context,
|
|
whereas vpx_codec_err_to_string() can be used in cases where an error occurs
|
|
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
|
|
the vpx_codec_error_detail() method. Not all errors produce detailed error
|
|
information.
|
|
|
|
In addition to error information, the codec library's build configuration
|
|
is available at runtime on some platforms. This information can be returned
|
|
by calling vpx_codec_build_config(), and is formatted as a base64 coded string
|
|
(comprised of characters in the set [a-z_a-Z0-9+/]). This information is not
|
|
useful to an application at runtime, but may be of use to vpx for support.
|
|
|
|
|
|
\section usage_deadline Deadline
|
|
Both the encoding and decoding functions have a <code>deadline</code>
|
|
parameter. This parameter indicates the amount of time, in microseconds
|
|
(us), that the application wants the codec to spend processing before
|
|
returning. This is a soft deadline -- that is, the semantics of the
|
|
requested operation take precedence over meeting the deadline. If, for
|
|
example, an application sets a <code>deadline</code> of 1000us, and the
|
|
frame takes 2000us to decode, the call to vpx_codec_decode() will return
|
|
after 2000us. In this case the deadline is not met, but the semantics of the
|
|
function are preserved. If, for the same frame, an application instead sets
|
|
a <code>deadline</code> of 5000us, the decoder will see that it has 3000us
|
|
remaining in its time slice when decoding completes. It could then choose to
|
|
run a set of \ref usage_postproc filters, and perhaps would return after
|
|
4000us (instead of the allocated 5000us). In this case the deadline is met,
|
|
and the semantics of the call are preserved, as before.
|
|
|
|
The special value <code>0</code> is reserved to represent an infinite
|
|
deadline. In this case, the codec will perform as much processing as
|
|
possible to yield the highest quality frame.
|
|
|
|
By convention, the value <code>1</code> is used to mean "return as fast as
|
|
possible."
|
|
|
|
*/
|