vp8_api1_migration.txt 5.75 KB
Newer Older
John Koleszar's avatar
John Koleszar committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198
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 `VPX_CODEC_DISABLE_COMPAT` 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.

The *TWO-PASS STATISTICS* sections detail the one section of code which is not
backwards compatable and will require code changes.


HEADER FILES
============
The following header files were renamed:

    vp8.h  -> vp8dx.h
    vp8e.h -> vp8cx.h


INTERFACE SYMBOLS
=================
The following interface symbols were renamed:

    vpx_codec_vp8_algo -> vpx_codec_vp8_dx_algo
    vpx_enc_vp8_algo   -> vpx_codec_vp8_cx_algo


TWO-PASS STATISTICS
===================
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 `vpx_codec_enc_cfg` structure. In this version, statistics are returned
though the application though the `vpx_codec_get_cx_data()` interface. The
application must concatenate these packets into a contiguous buffer and then
pass that buffer to the encoder through the `vpx_codec_enc_cfg` 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.


ENCODER CONTROLS
================

Renames
-------
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:

    VP8E_SET_REFERENCE  -> VP8_SET_REFERENCE
    VP8E_COPY_REFERENCE -> VP8_COPY_REFERENCE
    VP8E_SET_PREVIEWPP  -> VP8_SET_POSTPROC


VP8E_SET_FRAMETYPE
------------------
This control was removed in favor of the `flags` parameter to
`vpx_codec_encode()`. Existing code such as:

~~~
    vpx_codec_control(&encoder, VP8E_SET_FRAMETYPE, KEY_FRAME);
    ...
    vpx_codec_encode(&encoder, img, pts, 1, 0, 0);
~~~

becomes:

~~~
    vpx_codec_encode(&encoder, img, pts, 1, VPX_EFLAG_FORCE_KF,
    VPX_DL_REALTIME);
~~~



VP8E_SET_FLUSHFLAG
------------------
Flush is handled by passing `NULL` to the `img` parameter of
`vpx_codec_encode()`. 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.

~~~
    while(...) {
       ...
       vpx_codec_encode(&encoder, img, pts, 1, 0, 0);
       while( (pkt = vpx_codec_get_cx_data(&encoder, &iter)) ) {
          ...
       }
    }
    vpx_codec_control(&encoder, VP8E_SET_FLUSHFLAG, 1);
    while( (pkt = vpx_codec_get_cx_data(&encoder, &iter)) ) {
       ...
    }
    vpx_codec_encode(&encoder, img, pts, 1, 0, 0);
~~~

becomes

~~~
    while(new_image && ...) {
       ...
       vpx_codec_encode(&encoder, new_image?img:NULL, pts, 1, 0, 0);
       while( (pkt = vpx_codec_get_cx_data(&encoder, &iter)) ) {
          ...
       }
    }
~~~



VP8E_SET_ENCODING_MODE
----------------------
This control was removed in favor of the `deadline` parameter to
`vpx_codec_encode()`. 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:

~~~
    vpx_codec_control(&encoder, VP8E_SET_ENCODING_MODE, VP8_REAL_TIME_ENCODING);
    ...
    vpx_codec_encode(&encoder, img, pts, 1, 0, 0);
~~~

becomes:

~~~
    vpx_codec_encode(&encoder, img, pts, 1, 0, VPX_DL_REALTIME);
~~~


VP8E_UPD_ENTROPY
------------------
This control was deprecated in favor of the `flags` parameter to
`vpx_codec_encode()`. Existing code such as:

~~~
    vpx_codec_control(&encoder, VP8E_UPD_ENTROPY, 0);
~~~

becomes:

~~~
    vpx_codec_encode(&encoder, img, pts, 1, VP8_EFLAG_NO_UPD_ENTROPY,
                     VPX_DL_REALTIME);
~~~


VP8E_UPD_REFERENCE
------------------
This control was deprecated in favor of the `flags` parameter to
`vpx_codec_encode()`. 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:

~~~
    vpx_codec_control(&encoder, VP8E_UPD_REFERENCE,
                      VP8_LAST_FRAME | VP8_GOLD_FRAME);
    vpx_codec_control(&encoder, VP8E_UPD_REFERENCE, 0);
    ...
    vpx_codec_encode(&encoder, img, pts, 1, 0, VPX_DL_REALTIME);
~~~

becomes:

~~~
    vpx_codec_encode(&encoder, img, pts, 1, VP8_EFLAG_FORCE_GF,
                     VPX_DL_REALTIME);
    vpx_codec_encode(&encoder, img, pts, 1, VP8_EFLAG_NO_UPD_LAST
                     | VP8_EFLAG_NO_UPD_GF | VP8_EFLAG_NO_UPD_ARF,
                     VPX_DL_REALTIME);
~~~


VP8E_USE_REFERENCE
------------------
This control was deprecated in favor of the `flags` parameter to
`vpx_codec_encode()`. 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:

~~~
    vpx_codec_control(&encoder, VP8E_USE_REFERENCE,
                      VP8_ALTR_FRAME | VP8_GOLD_FRAME);
    ...
    vpx_codec_encode(&encoder, img, pts, 1, 0, VPX_DL_REALTIME);
~~~

becomes

~~~
    vpx_codec_encode(&encoder, img, pts, 1, VP8_EFLAG_NO_REF_LAST,
                     VPX_DL_REALTIME);
~~~