<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>WebM VP8 Codec SDK: Usage</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.7.3 -->
<div id="top">
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">WebM VP8 Codec SDK</div>
</td>
</tr>
</tbody>
</table>
</div>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div>
<div class="header">
<div class="headertitle">
<h1>Usage </h1> </div>
</div>
<div class="contents">
<div class="textblock"><p>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 <a class="el" href="group__codecs.html">Supported Codecs</a> page.</p>
<p>The following sections are common to all codecs:</p>
<ul>
<li><a class="el" href="usage.html#usage_types">Important Data Types</a></li>
<li><a class="el" href="usage.html#usage_features">Features</a></li>
<li><a class="el" href="usage.html#usage_init">Initialization</a></li>
<li><a class="el" href="usage.html#usage_errors">Error Handling</a></li>
</ul>
<p>Fore more information on decoder and encoder specific usage, see the following pages:</p>
<ul>
<li>usage_decode- <a class="el" href="usage_encode.html">Encode</a> </li>
</ul>
<h2><a class="anchor" id="usage_types"></a>
Important Data Types</h2>
<p>There are two important data structures to consider in this interface.</p>
<h3><a class="anchor" id="usage_ctxs"></a>
Contexts</h3>
<p>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.</p>
<p>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 <a class="el" href="group__codec.html#gad03e2dfa6ae511db7d25be6bbb336233" title="Codec context structure.">vpx_codec_ctx_t</a> for further information.</p>
<h3><a class="anchor" id="usage_ifaces"></a>
Interfaces</h3>
<p>A codec interface is an opaque structure that controls how function calls into the generic interface are dispatched to their codec-specific implementations. Applications <a class="el" href="rfc2119.html#MUSTNOT">MUST NOT</a> attempt to examine or override this storage, as it contains internal implementation details likely to change from release to release.</p>
<p>Each supported codec will expose an interface structure to the application as an <code>extern</code> reference to a structure of the incomplete type <a class="el" href="group__codec.html#gad654f3da60151f5dfef70aca00ef1e9e" title="Codec interface structure.">vpx_codec_iface_t</a>.</p>
<h2><a class="anchor" id="usage_features"></a>
Features</h2>
<p>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 <a class="el" href="group__codec.html#ga43adff58759093401235fb99247c82b8" title="Get the capabilities of an algorithm.">vpx_codec_get_caps()</a> method. Attempts to invoke features not supported by an algorithm will generally result in <a class="el" href="group__codec.html#ggada1084710837ad363b92f2379dd2b8d2a4470784ba5a3ef84dc0697d5489dd292" title="Algorithm does not have required capability.">VPX_CODEC_INCAPABLE</a>.</p>
<p>Currently defined features available in both encoders and decoders include:</p>
<ul>
<li><a class="el" href="usage_xma.html">External Memory Allocation</a></li>
</ul>
<p>Currently defined decoder features include:</p>
<ul>
<li><a class="el" href="usage_decode.html#usage_cb">Callback Based Decoding</a></li>
<li><a class="el" href="usage_decode.html#usage_postproc">Postprocessing</a></li>
</ul>
<h2><a class="anchor" id="usage_init"></a>
Initialization</h2>
<p>To initialize a codec instance, the address of the codec context and interface structures are passed to an initialization function. Depending on the <a class="el" href="usage.html#usage_features">Features</a> that the codec supports, the codec could be initialized in different modes. Most notably, the application may choose to use <a class="el" href="usage_xma.html">External Memory Allocation</a> mode to gain fine grained control over how and where memory is allocated for the codec.</p>
<p>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 <a class="el" href="group__codec.html#gaf7e9cad2df0f81679b881f46740ad097" title="Current ABI version number.">VPX_CODEC_ABI_VERSION</a>, <a class="el" href="group__encoder.html#gaa4f0b52293c08ba672429c3a03648b9d" title="Current ABI version number.">VPX_ENCODER_ABI_VERSION</a>, and <a class="el" href="group__decoder.html#ga462b459e7ae13937e1eae1776245db12" title="Current ABI version number.">VPX_DECODER_ABI_VERSION</a>. 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.</p>
<p>The available initialization methods are:</p>
<ul>
<li><a class="el" href="group__encoder.html#ga3d490a2a9a6acd7c9ef82a603155f3cf" title="Convenience macro for vpx_codec_enc_init_ver()">vpx_codec_enc_init</a> (calls <a class="el" href="group__encoder.html#ga6ed21b96c481c0b6e1b543ef958a57a4" title="Initialize an encoder instance.">vpx_codec_enc_init_ver()</a>)- <a class="el" href="group__decoder.html#ga8c2f0b12f1bd4927eb3c68b01eab19d3" title="Convenience macro for vpx_codec_dec_init_ver()">vpx_codec_dec_init</a> (calls <a class="el" href="group__decoder.html#ga26fe82cf8fd697f885935cea53be964f" title="Initialize a decoder instance.">vpx_codec_dec_init_ver()</a>)</li>
</ul>
<h2><a class="anchor" id="usage_errors"></a>
Error Handling</h2>
<p>Almost all codec functions return an error status of type <a class="el" href="group__codec.html#gada1084710837ad363b92f2379dd2b8d2" title="Algorithm return codes.">vpx_codec_err_t</a>. 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 <a class="el" href="group__codec.html#ga4d265df00d42b36a4f0e3eb83fc22c5e" title="Retrieve error synopsis for codec context.">vpx_codec_error()</a> and <a class="el" href="group__codec.html#gaaddf5c1f609ef18c7c8800d102fcefa6" title="Convert error number to printable string.">vpx_codec_err_to_string()</a> methods. The difference between these two methods is that <a class="el" href="group__codec.html#ga4d265df00d42b36a4f0e3eb83fc22c5e" title="Retrieve error synopsis for codec context.">vpx_codec_error()</a> returns the error state from an initialized context, whereas <a class="el" href="group__codec.html#gaaddf5c1f609ef18c7c8800d102fcefa6" title="Convert error number to printable string.">vpx_codec_err_to_string()</a> 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 <a class="el" href="group__codec.html#ga29273cb552ed1a437fe263c4a0a54300" title="Retrieve detailed error information for codec context.">vpx_codec_error_detail()</a> method. Not all errors produce detailed error information.</p>
<p>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 <a class="el" href="group__codec.html#ga20922bad85472e76d5f61c21cb423af7" title="Return the build configuration.">vpx_codec_build_config()</a>, 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.</p>
<h2><a class="anchor" id="usage_deadline"></a>
Deadline</h2>
<p>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 <a class="el" href="group__decoder.html#ga3441e157a7a69108bca9a069f2ee8e0d" title="Decode data.">vpx_codec_decode()</a> 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 <a class="el" href="usage_decode.html#usage_postproc">Postprocessing</a> 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.</p>
<p>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.</p>
<p>By convention, the value <code>1</code> is used to mean "return as fast as
possible." </p>
</div></div>
<hr class="footer"/><address class="footer"><small>Generated on Thu Mar 10 2011 for WebM VP8 Codec SDK by 
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.3 </small></address>
</body>
</html>
