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 ~~~ 199
