<!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: VP8 API 1.x Migration</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>VP8 API 1.x Migration </h1> </div> </div> <div class="contents"> <div class="textblock"> <p>Version 2.x of this library has deprecated or removed a number of interfaces to the VP8 codec. Where possible, the old interfaces have been left in place in a deprecated state, and will generate compiler warnings when they are referenced. All users are encouraged to update their code to the new interfaces as soon as possible. To assist in this effort, the <code>VPX_CODEC_DISABLE_COMPAT</code> symbol can be #defined to 1 prior to including vpx headers. This will disable the backwards compatability workarounds and ensure that you are using only the latest API.</p> <p>The <em>TWO-PASS STATISTICS</em> sections detail the one section of code which is not backwards compatable and will require code changes.</p> <h1>HEADER FILES</h1> <p>The following header files were renamed:</p> <pre class="c">vp8.<span style="color: #202020;">h</span> <span style="color: #339933;">-></span> vp8dx.<span style="color: #202020;">h</span> vp8e.<span style="color: #202020;">h</span> <span style="color: #339933;">-></span> vp8cx.<span style="color: #202020;">h</span></pre> <h1>INTERFACE SYMBOLS</h1> <p>The following interface symbols were renamed:</p> <pre class="c">vpx_codec_vp8_algo <span style="color: #339933;">-></span> vpx_codec_vp8_dx_algo vpx_enc_vp8_algo <span style="color: #339933;">-></span> vpx_codec_vp8_cx_algo</pre> <h1>TWO-PASS STATISTICS</h1> <p>Two-pass statistics are handled significantly differently. The version 1 API stored statistics in a file, and the application passed the name of that file in the <code>vpx_codec_enc_cfg</code> structure. In this version, statistics are returned though the application though the <code>vpx_codec_get_cx_data()</code> interface. The application must concatenate these packets into a contiguous buffer and then pass that buffer to the encoder through the <code>vpx_codec_enc_cfg</code> structure on the second pass initialization. The application may choose to keep these packets in memory or write them to disk. Statistics packets are approximately 112 bytes per frame. See the example code for more detailed examples.</p> <h1>ENCODER CONTROLS</h1> <h2>Renames</h2> <p>The following controls are duplicated between the encoder and the decoder, but the encoder unnecessarily introduced unique identifiers for them. These identifiers were removed in favor of the ones used by the decoder:</p> <pre class="c">VP8E_SET_REFERENCE <span style="color: #339933;">-></span> VP8_SET_REFERENCE VP8E_COPY_REFERENCE <span style="color: #339933;">-></span> VP8_COPY_REFERENCE VP8E_SET_PREVIEWPP <span style="color: #339933;">-></span> VP8_SET_POSTPROC</pre> <h2>VP8E_SET_FRAMETYPE</h2> <p>This control was removed in favor of the <code>flags</code> parameter to <code>vpx_codec_encode()</code>. Existing code such as:</p> <pre class="c"> vpx_codec_control<span style="color: #009900;">(</span><span style="color: #339933;">&</span>encoder<span style="color: #339933;">,</span> VP8E_SET_FRAMETYPE<span style="color: #339933;">,</span> KEY_FRAME<span style="color: #009900;">)</span><span style="color: #339933;">;</span> ... <span style="color: #202020;">vpx_codec_encode</span><span style="color: #009900;">(</span><span style="color: #339933;">&</span>encoder<span style="color: #339933;">,</span> img<span style="color: #339933;">,</span> pts<span style="color: #339933;">,</span> <span style="color: #0000dd;">1</span><span style="color: #339933;">,</span> <span style="color: #0000dd;">0</span><span style="color: #339933;">,</span> <span style="color: #0000dd;">0</span><span style="color: #009900;">)</span><span style="color: #339933;">;</span></pre> <p>becomes:</p> <pre class="c"> vpx_codec_encode<span style="color: #009900;">(</span><span style="color: #339933;">&</span>encoder<span style="color: #339933;">,</span> img<span style="color: #339933;">,</span> pts<span style="color: #339933;">,</span> <span style="color: #0000dd;">1</span><span style="color: #339933;">,</span> VPX_EFLAG_FORCE_KF<span style="color: #339933;">,</span> VPX_DL_REALTIME<span style="color: #009900;">)</span><span style="color: #339933;">;</span></pre> <h2>VP8E_SET_FLUSHFLAG</h2> <p>Flush is handled by passing <code>NULL</code> to the <code>img</code> parameter of <code>vpx_codec_encode()</code>. You must do this at least once, regardless of your encoder configuration. i.e. it’s not specific to g_lag_in_frames. This control was removed.</p> <pre class="c"> <span style="color: #b1b100;">while</span><span style="color: #009900;">(</span>...<span style="color: #009900;">)</span> <span style="color: #009900;">{</span> ... <span style="color: #202020;">vpx_codec_encode</span><span style="color: #009900;">(</span><span style="color: #339933;">&</span>encoder<span style="color: #339933;">,</span> img<span style="color: #339933;">,</span> pts<span style="color: #339933;">,</span> <span style="color: #0000dd;">1</span><span style="color: #339933;">,</span> <span style="color: #0000dd;">0</span><span style="color: #339933;">,</span> <span style="color: #0000dd;">0</span><span style="color: #009900;">)</span><span style="color: #339933;">;</span> <span style="color: #b1b100;">while</span><span style="color: #009900;">(</span> <span style="color: #009900;">(</span>pkt <span style="color: #339933;">=</span> vpx_codec_get_cx_data<span style="color: #009900;">(</span><span style="color: #339933;">&</span>encoder<span style="color: #339933;">,</span> <span style="color: #339933;">&</span>iter<span style="color: #009900;">)</span><span style="color: #009900;">)</span> <span style="color: #009900;">)</span> <span style="color: #009900;">{</span> ... <span style="color: #009900;">}</span> <span style="color: #009900;">}</span> vpx_codec_control<span style="color: #009900;">(</span><span style="color: #339933;">&</span>encoder<span style="color: #339933;">,</span> VP8E_SET_FLUSHFLAG<span style="color: #339933;">,</span> <span style="color: #0000dd;">1</span><span style="color: #009900;">)</span><span style="color: #339933;">;</span> <span style="color: #b1b100;">while</span><span style="color: #009900;">(</span> <span style="color: #009900;">(</span>pkt <span style="color: #339933;">=</span> vpx_codec_get_cx_data<span style="color: #009900;">(</span><span style="color: #339933;">&</span>encoder<span style="color: #339933;">,</span> <span style="color: #339933;">&</span>iter<span style="color: #009900;">)</span><span style="color: #009900;">)</span> <span style="color: #009900;">)</span> <span style="color: #009900;">{</span> ... <span style="color: #009900;">}</span> vpx_codec_encode<span style="color: #009900;">(</span><span style="color: #339933;">&</span>encoder<span style="color: #339933;">,</span> img<span style="color: #339933;">,</span> pts<span style="color: #339933;">,</span> <span style="color: #0000dd;">1</span><span style="color: #339933;">,</span> <span style="color: #0000dd;">0</span><span style="color: #339933;">,</span> <span style="color: #0000dd;">0</span><span style="color: #009900;">)</span><span style="color: #339933;">;</span></pre> <p>becomes</p> <pre class="c"> <span style="color: #b1b100;">while</span><span style="color: #009900;">(</span>new_image <span style="color: #339933;">&&</span> ...<span style="color: #009900;">)</span> <span style="color: #009900;">{</span> ... <span style="color: #202020;">vpx_codec_encode</span><span style="color: #009900;">(</span><span style="color: #339933;">&</span>encoder<span style="color: #339933;">,</span> new_image<span style="color: #339933;">?</span>img<span style="color: #339933;">:</span>NULL<span style="color: #339933;">,</span> pts<span style="color: #339933;">,</span> <span style="color: #0000dd;">1</span><span style="color: #339933;">,</span> <span style="color: #0000dd;">0</span><span style="color: #339933;">,</span> <span style="color: #0000dd;">0</span><span style="color: #009900;">)</span><span style="color: #339933;">;</span> <span style="color: #b1b100;">while</span><span style="color: #009900;">(</span> <span style="color: #009900;">(</span>pkt <span style="color: #339933;">=</span> vpx_codec_get_cx_data<span style="color: #009900;">(</span><span style="color: #339933;">&</span>encoder<span style="color: #339933;">,</span> <span style="color: #339933;">&</span>iter<span style="color: #009900;">)</span><span style="color: #009900;">)</span> <span style="color: #009900;">)</span> <span style="color: #009900;">{</span> ... <span style="color: #009900;">}</span> <span style="color: #009900;">}</span></pre> <h2>VP8E_SET_ENCODING_MODE</h2> <p>This control was removed in favor of the <code>deadline</code> parameter to <code>vpx_codec_encode()</code>. There are three macros that can be used to get the equivalent behavior: VPX_DL_REALTIME, VPX_DL_GOOD_QUALITY, VPX_DL_BEST_QUALITY. Existing code such as:</p> <pre class="c"> vpx_codec_control<span style="color: #009900;">(</span><span style="color: #339933;">&</span>encoder<span style="color: #339933;">,</span> VP8E_SET_ENCODING_MODE<span style="color: #339933;">,</span> VP8_REAL_TIME_ENCODING<span style="color: #009900;">)</span><span style="color: #339933;">;</span> ... <span style="color: #202020;">vpx_codec_encode</span><span style="color: #009900;">(</span><span style="color: #339933;">&</span>encoder<span style="color: #339933;">,</span> img<span style="color: #339933;">,</span> pts<span style="color: #339933;">,</span> <span style="color: #0000dd;">1</span><span style="color: #339933;">,</span> <span style="color: #0000dd;">0</span><span style="color: #339933;">,</span> <span style="color: #0000dd;">0</span><span style="color: #009900;">)</span><span style="color: #339933;">;</span></pre> <p>becomes:</p> <pre class="c"> vpx_codec_encode<span style="color: #009900;">(</span><span style="color: #339933;">&</span>encoder<span style="color: #339933;">,</span> img<span style="color: #339933;">,</span> pts<span style="color: #339933;">,</span> <span style="color: #0000dd;">1</span><span style="color: #339933;">,</span> <span style="color: #0000dd;">0</span><span style="color: #339933;">,</span> VPX_DL_REALTIME<span style="color: #009900;">)</span><span style="color: #339933;">;</span></pre> <h2>VP8E_UPD_ENTROPY</h2> <p>This control was deprecated in favor of the <code>flags</code> parameter to <code>vpx_codec_encode()</code>. Existing code such as:</p> <pre class="c"> vpx_codec_control<span style="color: #009900;">(</span><span style="color: #339933;">&</span>encoder<span style="color: #339933;">,</span> VP8E_UPD_ENTROPY<span style="color: #339933;">,</span> <span style="color: #0000dd;">0</span><span style="color: #009900;">)</span><span style="color: #339933;">;</span></pre> <p>becomes:</p> <pre class="c"> vpx_codec_encode<span style="color: #009900;">(</span><span style="color: #339933;">&</span>encoder<span style="color: #339933;">,</span> img<span style="color: #339933;">,</span> pts<span style="color: #339933;">,</span> <span style="color: #0000dd;">1</span><span style="color: #339933;">,</span> VP8_EFLAG_NO_UPD_ENTROPY<span style="color: #339933;">,</span> VPX_DL_REALTIME<span style="color: #009900;">)</span><span style="color: #339933;">;</span></pre> <h2>VP8E_UPD_REFERENCE</h2> <p>This control was deprecated in favor of the <code>flags</code> parameter to <code>vpx_codec_encode()</code>. A set bit on the VP8E_UPD_REFERENCE bitfield is analogous to setting the VP8_EFLAG_FORCE_* flag. A cleared bit is analogous to setting the VP8_EFLAG_NO_UPD_* flag. If neither the FORCE or NO_UPD bit is set, the encoder will make its decision automatically, as usual. Setting both bits will result in an error being returned. Existing code such as:</p> <pre class="c"> vpx_codec_control<span style="color: #009900;">(</span><span style="color: #339933;">&</span>encoder<span style="color: #339933;">,</span> VP8E_UPD_REFERENCE<span style="color: #339933;">,</span> VP8_LAST_FRAME <span style="color: #339933;">|</span> VP8_GOLD_FRAME<span style="color: #009900;">)</span><span style="color: #339933;">;</span> vpx_codec_control<span style="color: #009900;">(</span><span style="color: #339933;">&</span>encoder<span style="color: #339933;">,</span> VP8E_UPD_REFERENCE<span style="color: #339933;">,</span> <span style="color: #0000dd;">0</span><span style="color: #009900;">)</span><span style="color: #339933;">;</span> ... <span style="color: #202020;">vpx_codec_encode</span><span style="color: #009900;">(</span><span style="color: #339933;">&</span>encoder<span style="color: #339933;">,</span> img<span style="color: #339933;">,</span> pts<span style="color: #339933;">,</span> <span style="color: #0000dd;">1</span><span style="color: #339933;">,</span> <span style="color: #0000dd;">0</span><span style="color: #339933;">,</span> VPX_DL_REALTIME<span style="color: #009900;">)</span><span style="color: #339933;">;</span></pre> <p>becomes:</p> <pre class="c"> vpx_codec_encode<span style="color: #009900;">(</span><span style="color: #339933;">&</span>encoder<span style="color: #339933;">,</span> img<span style="color: #339933;">,</span> pts<span style="color: #339933;">,</span> <span style="color: #0000dd;">1</span><span style="color: #339933;">,</span> VP8_EFLAG_FORCE_GF<span style="color: #339933;">,</span> VPX_DL_REALTIME<span style="color: #009900;">)</span><span style="color: #339933;">;</span> vpx_codec_encode<span style="color: #009900;">(</span><span style="color: #339933;">&</span>encoder<span style="color: #339933;">,</span> img<span style="color: #339933;">,</span> pts<span style="color: #339933;">,</span> <span style="color: #0000dd;">1</span><span style="color: #339933;">,</span> VP8_EFLAG_NO_UPD_LAST <span style="color: #339933;">|</span> VP8_EFLAG_NO_UPD_GF <span style="color: #339933;">|</span> VP8_EFLAG_NO_UPD_ARF<span style="color: #339933;">,</span> VPX_DL_REALTIME<span style="color: #009900;">)</span><span style="color: #339933;">;</span></pre> <h2>VP8E_USE_REFERENCE</h2> <p>This control was deprecated in favor of the <code>flags</code> parameter to <code>vpx_codec_encode()</code>. A cleared bit on the VP8E_USE_REFERENCE bitfield is analogous to setting the VP8_EFLAG_NO_REF* flag. A set bit indicates that the encoder will make its decision automatically, as usual. Existing code such as:</p> <pre class="c"> vpx_codec_control<span style="color: #009900;">(</span><span style="color: #339933;">&</span>encoder<span style="color: #339933;">,</span> VP8E_USE_REFERENCE<span style="color: #339933;">,</span> VP8_ALTR_FRAME <span style="color: #339933;">|</span> VP8_GOLD_FRAME<span style="color: #009900;">)</span><span style="color: #339933;">;</span> ... <span style="color: #202020;">vpx_codec_encode</span><span style="color: #009900;">(</span><span style="color: #339933;">&</span>encoder<span style="color: #339933;">,</span> img<span style="color: #339933;">,</span> pts<span style="color: #339933;">,</span> <span style="color: #0000dd;">1</span><span style="color: #339933;">,</span> <span style="color: #0000dd;">0</span><span style="color: #339933;">,</span> VPX_DL_REALTIME<span style="color: #009900;">)</span><span style="color: #339933;">;</span></pre> <p>becomes</p> <pre class="c"> vpx_codec_encode<span style="color: #009900;">(</span><span style="color: #339933;">&</span>encoder<span style="color: #339933;">,</span> img<span style="color: #339933;">,</span> pts<span style="color: #339933;">,</span> <span style="color: #0000dd;">1</span><span style="color: #339933;">,</span> VP8_EFLAG_NO_REF_LAST<span style="color: #339933;">,</span> VPX_DL_REALTIME<span style="color: #009900;">)</span><span style="color: #339933;">;</span></pre> </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>