1Version 2.x of this library has deprecated or removed a number of interfaces to 2the VP8 codec. Where possible, the old interfaces have been left in place in a 3deprecated state, and will generate compiler warnings when they are referenced. 4All users are encouraged to update their code to the new interfaces as soon as 5possible. To assist in this effort, the `VPX_CODEC_DISABLE_COMPAT` symbol can 6be #defined to 1 prior to including vpx headers. This will disable the 7backwards compatability workarounds and ensure that you are using only the 8latest API. 9 10The *TWO-PASS STATISTICS* sections detail the one section of code which is not 11backwards compatable and will require code changes. 12 13 14HEADER FILES 15============ 16The following header files were renamed: 17 18 vp8.h -> vp8dx.h 19 vp8e.h -> vp8cx.h 20 21 22INTERFACE SYMBOLS 23================= 24The 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 30TWO-PASS STATISTICS 31=================== 32Two-pass statistics are handled significantly differently. The version 1 API 33stored statistics in a file, and the application passed the name of that file 34in the `vpx_codec_enc_cfg` structure. In this version, statistics are returned 35though the application though the `vpx_codec_get_cx_data()` interface. The 36application must concatenate these packets into a contiguous buffer and then 37pass that buffer to the encoder through the `vpx_codec_enc_cfg` structure on 38the second pass initialization. The application may choose to keep these packets 39in memory or write them to disk. Statistics packets are approximately 112 bytes 40per frame. See the example code for more detailed examples. 41 42 43ENCODER CONTROLS 44================ 45 46Renames 47------- 48The following controls are duplicated between the encoder and the decoder, but 49the encoder unnecessarily introduced unique identifiers for them. These 50identifiers 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 57VP8E_SET_FRAMETYPE 58------------------ 59This 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 68becomes: 69 70~~~ 71 vpx_codec_encode(&encoder, img, pts, 1, VPX_EFLAG_FORCE_KF, 72 VPX_DL_REALTIME); 73~~~ 74 75 76 77VP8E_SET_FLUSHFLAG 78------------------ 79Flush 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 81configuration. i.e. it's not specific to g_lag_in_frames. This control was 82removed. 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 99becomes 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 113VP8E_SET_ENCODING_MODE 114---------------------- 115This 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 117equivalent behavior: VPX_DL_REALTIME, VPX_DL_GOOD_QUALITY, 118VPX_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 126becomes: 127 128~~~ 129 vpx_codec_encode(&encoder, img, pts, 1, 0, VPX_DL_REALTIME); 130~~~ 131 132 133VP8E_UPD_ENTROPY 134------------------ 135This 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 142becomes: 143 144~~~ 145 vpx_codec_encode(&encoder, img, pts, 1, VP8_EFLAG_NO_UPD_ENTROPY, 146 VPX_DL_REALTIME); 147~~~ 148 149 150VP8E_UPD_REFERENCE 151------------------ 152This control was deprecated in favor of the `flags` parameter to 153`vpx_codec_encode()`. A set bit on the VP8E_UPD_REFERENCE bitfield is 154analogous to setting the VP8_EFLAG_FORCE_* flag. A cleared bit is analogous 155to setting the VP8_EFLAG_NO_UPD_* flag. If neither the FORCE or NO_UPD bit 156is set, the encoder will make its decision automatically, as usual. Setting 157both 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 167becomes: 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 178VP8E_USE_REFERENCE 179------------------ 180This control was deprecated in favor of the `flags` parameter to 181`vpx_codec_encode()`. A cleared bit on the VP8E_USE_REFERENCE bitfield is 182analogous to setting the VP8_EFLAG_NO_REF* flag. A set bit indicates that 183the encoder will make its decision automatically, as usual. 184Existing 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 193becomes 194 195~~~ 196 vpx_codec_encode(&encoder, img, pts, 1, VP8_EFLAG_NO_REF_LAST, 197 VPX_DL_REALTIME); 198~~~ 199