vp8_api1_migration.txt

   1 Version 2.x of this library has deprecated or removed a number of interfaces to
   2 the VP8 codec. Where possible, the old interfaces have been left in place in a
   3 deprecated state, and will generate compiler warnings when they are referenced.
   4 All users are encouraged to update their code to the new interfaces as soon as
   5 possible. To assist in this effort, the `VPX_CODEC_DISABLE_COMPAT` symbol can
   6 be #defined to 1 prior to including vpx headers. This will disable the
   7 backwards compatability workarounds and ensure that you are using only the
   8 latest API.
   9
  10 The *TWO-PASS STATISTICS* sections detail the one section of code which is not
  11 backwards compatable and will require code changes.
  12
  13
  14 HEADER FILES
  15 ============
  16 The following header files were renamed:
  17
  18     vp8.h  -> vp8dx.h
  19     vp8e.h -> vp8cx.h
  20
  21
  22 INTERFACE SYMBOLS
  23 =================
  24 The following interface symbols were renamed:
  25
  26     vpx_codec_vp8_algo -> vpx_codec_vp8_dx_algo
  27     vpx_enc_vp8_algo   -> vpx_codec_vp8_cx_algo
  28
  29
  30 TWO-PASS STATISTICS
  31 ===================
  32 Two-pass statistics are handled significantly differently. The version 1 API
  33 stored statistics in a file, and the application passed the name of that file
  34 in the `vpx_codec_enc_cfg` structure. In this version, statistics are returned
  35 though the application though the `vpx_codec_get_cx_data()` interface. The
  36 application must concatenate these packets into a contiguous buffer and then
  37 pass that buffer to the encoder through the `vpx_codec_enc_cfg` structure on
  38 the second pass initialization. The application may choose to keep these packets
  39 in memory or write them to disk. Statistics packets are approximately 112 bytes
  40 per frame. See the example code for more detailed examples.
  41
  42
  43 ENCODER CONTROLS
  44 ================
  45
  46 Renames
  47 -------
  48 The following controls are duplicated between the encoder and the decoder, but
  49 the encoder unnecessarily introduced unique identifiers for them. These
  50 identifiers were removed in favor of the ones used by the decoder:
  51
  52     VP8E_SET_REFERENCE  -> VP8_SET_REFERENCE
  53     VP8E_COPY_REFERENCE -> VP8_COPY_REFERENCE
  54     VP8E_SET_PREVIEWPP  -> VP8_SET_POSTPROC
  55
  56
  57 VP8E_SET_FRAMETYPE
  58 ------------------
  59 This control was removed in favor of the `flags` parameter to
  60 `vpx_codec_encode()`. Existing code such as:
  61
  62 ~~~
  63     vpx_codec_control(&encoder, VP8E_SET_FRAMETYPE, KEY_FRAME);
  64     ...
  65     vpx_codec_encode(&encoder, img, pts, 1, 0, 0);
  66 ~~~
  67
  68 becomes:
  69
  70 ~~~
  71     vpx_codec_encode(&encoder, img, pts, 1, VPX_EFLAG_FORCE_KF,
  72     VPX_DL_REALTIME);
  73 ~~~
  74
  75
  76
  77 VP8E_SET_FLUSHFLAG
  78 ------------------
  79 Flush is handled by passing `NULL` to the `img` parameter of
  80 `vpx_codec_encode()`. You must do this at least once, regardless of your encoder
  81 configuration. i.e. it's not specific to g_lag_in_frames. This control was
  82 removed.
  83
  84 ~~~
  85     while(...) {
  86        ...
  87        vpx_codec_encode(&encoder, img, pts, 1, 0, 0);
  88        while( (pkt = vpx_codec_get_cx_data(&encoder, &iter)) ) {
  89           ...
  90        }
  91     }
  92     vpx_codec_control(&encoder, VP8E_SET_FLUSHFLAG, 1);
  93     while( (pkt = vpx_codec_get_cx_data(&encoder, &iter)) ) {
  94        ...
  95     }
  96     vpx_codec_encode(&encoder, img, pts, 1, 0, 0);
  97 ~~~
  98
  99 becomes
 100
 101 ~~~
 102     while(new_image && ...) {
 103        ...
 104        vpx_codec_encode(&encoder, new_image?img:NULL, pts, 1, 0, 0);
 105        while( (pkt = vpx_codec_get_cx_data(&encoder, &iter)) ) {
 106           ...
 107        }
 108     }
 109 ~~~
 110
 111
 112
 113 VP8E_SET_ENCODING_MODE
 114 ----------------------
 115 This control was removed in favor of the `deadline` parameter to
 116 `vpx_codec_encode()`. There are three macros that can be used to get the
 117 equivalent behavior: VPX_DL_REALTIME, VPX_DL_GOOD_QUALITY,
 118 VPX_DL_BEST_QUALITY. Existing code such as:
 119
 120 ~~~
 121     vpx_codec_control(&encoder, VP8E_SET_ENCODING_MODE, VP8_REAL_TIME_ENCODING);
 122     ...
 123     vpx_codec_encode(&encoder, img, pts, 1, 0, 0);
 124 ~~~
 125
 126 becomes:
 127
 128 ~~~
 129     vpx_codec_encode(&encoder, img, pts, 1, 0, VPX_DL_REALTIME);
 130 ~~~
 131
 132
 133 VP8E_UPD_ENTROPY
 134 ------------------
 135 This control was deprecated in favor of the `flags` parameter to
 136 `vpx_codec_encode()`. Existing code such as:
 137
 138 ~~~
 139     vpx_codec_control(&encoder, VP8E_UPD_ENTROPY, 0);
 140 ~~~
 141
 142 becomes:
 143
 144 ~~~
 145     vpx_codec_encode(&encoder, img, pts, 1, VP8_EFLAG_NO_UPD_ENTROPY,
 146                      VPX_DL_REALTIME);
 147 ~~~
 148
 149
 150 VP8E_UPD_REFERENCE
 151 ------------------
 152 This control was deprecated in favor of the `flags` parameter to
 153 `vpx_codec_encode()`. A set bit on the VP8E_UPD_REFERENCE bitfield is
 154 analogous to setting the VP8_EFLAG_FORCE_* flag. A cleared bit is analogous
 155 to setting the VP8_EFLAG_NO_UPD_* flag. If neither the FORCE or NO_UPD bit
 156 is set, the encoder will make its decision automatically, as usual. Setting
 157 both bits will result in an error being returned. Existing code such as:
 158
 159 ~~~
 160     vpx_codec_control(&encoder, VP8E_UPD_REFERENCE,
 161                       VP8_LAST_FRAME | VP8_GOLD_FRAME);
 162     vpx_codec_control(&encoder, VP8E_UPD_REFERENCE, 0);
 163     ...
 164     vpx_codec_encode(&encoder, img, pts, 1, 0, VPX_DL_REALTIME);
 165 ~~~
 166
 167 becomes:
 168
 169 ~~~
 170     vpx_codec_encode(&encoder, img, pts, 1, VP8_EFLAG_FORCE_GF,
 171                      VPX_DL_REALTIME);
 172     vpx_codec_encode(&encoder, img, pts, 1, VP8_EFLAG_NO_UPD_LAST
 173                      | VP8_EFLAG_NO_UPD_GF | VP8_EFLAG_NO_UPD_ARF,
 174                      VPX_DL_REALTIME);
 175 ~~~
 176
 177
 178 VP8E_USE_REFERENCE
 179 ------------------
 180 This control was deprecated in favor of the `flags` parameter to
 181 `vpx_codec_encode()`. A cleared bit on the VP8E_USE_REFERENCE bitfield is
 182 analogous to setting the VP8_EFLAG_NO_REF* flag. A set bit indicates that
 183 the encoder will make its decision automatically, as usual.
 184 Existing code such as:
 185
 186 ~~~
 187     vpx_codec_control(&encoder, VP8E_USE_REFERENCE,
 188                       VP8_ALTR_FRAME | VP8_GOLD_FRAME);
 189     ...
 190     vpx_codec_encode(&encoder, img, pts, 1, 0, VPX_DL_REALTIME);
 191 ~~~
 192
 193 becomes
 194
 195 ~~~
 196     vpx_codec_encode(&encoder, img, pts, 1, VP8_EFLAG_NO_REF_LAST,
 197                      VPX_DL_REALTIME);
 198 ~~~