Add some comments for the entropy decoder.
Most of these comments were based on private email communication from
Timothy B. Terriberry <tterriberry@mozilla.com>.
Change-Id: I997833c0c032d58c7a44e63175531507e473cebf
diff --git a/aom_dsp/entcode.h b/aom_dsp/entcode.h
index 7ba2b1c..7518879 100644
--- a/aom_dsp/entcode.h
+++ b/aom_dsp/entcode.h
@@ -24,6 +24,7 @@
on a larger type, you can speed up the decoder by using it here.*/
typedef uint32_t od_ec_window;
+/*The size in bits of od_ec_window.*/
#define OD_EC_WINDOW_SIZE ((int)sizeof(od_ec_window) * CHAR_BIT)
/*The resolution of fractional-precision bit usage measurements, i.e.,
diff --git a/aom_dsp/entdec.c b/aom_dsp/entdec.c
index d1764c4..c42582f 100644
--- a/aom_dsp/entdec.c
+++ b/aom_dsp/entdec.c
@@ -87,11 +87,25 @@
end = dec->end;
s = OD_EC_WINDOW_SIZE - 9 - (cnt + 15);
for (; s >= 0 && bptr < end; s -= 8, bptr++) {
+ /*Each time a byte is inserted into the window (dif), bptr advances and cnt
+ is incremented by 8, so the total number of consumed bits (the return
+ value of od_ec_dec_tell) does not change.*/
assert(s <= OD_EC_WINDOW_SIZE - 8);
dif ^= (od_ec_window)bptr[0] << s;
cnt += 8;
}
if (bptr >= end) {
+ /*We've reached the end of the buffer. It is perfectly valid for us to need
+ to fill the window with additional bits past the end of the buffer (and
+ this happens in normal operation). These bits should all just be taken
+ as zero. But we cannot increment bptr past 'end' (this is undefined
+ behavior), so we start to increment dec->tell_offs. We also don't want
+ to keep testing bptr against 'end', so we set cnt to OD_EC_LOTS_OF_BITS
+ and adjust dec->tell_offs so that the total number of unconsumed bits in
+ the window (dec->cnt - dec->tell_offs) does not change. This effectively
+ puts lots of zero bits into the window, and means we won't try to refill
+ it from the buffer for a very long time (at which point we'll put lots
+ of zero bits into the window again).*/
dec->tell_offs += OD_EC_LOTS_OF_BITS - cnt;
cnt = OD_EC_LOTS_OF_BITS;
}
@@ -112,8 +126,9 @@
int ret) {
int d;
assert(rng <= 65535U);
- // The number of leading zeros in the 16-bit binary representation of rng.
+ /*The number of leading zeros in the 16-bit binary representation of rng.*/
d = 16 - OD_ILOG_NZ(rng);
+ /*d bits in dec->dif are consumed.*/
dec->cnt -= d;
/*This is equivalent to shifting in 1's instead of 0's.*/
dec->dif = ((dif + 1) << d) - 1;
@@ -215,6 +230,10 @@
This will always be slightly larger than the exact value (e.g., all
rounding error is in the positive direction).*/
int od_ec_dec_tell(const od_ec_dec *dec) {
+ /*There is a window of bits stored in dec->dif. The difference
+ (dec->bptr - dec->buf) tells us how many bytes have been read into this
+ window. The difference (dec->cnt - dec->tell_offs) tells us how many of
+ the bits in that window remain unconsumed.*/
return (int)((dec->bptr - dec->buf) * 8 - dec->cnt + dec->tell_offs);
}
diff --git a/aom_dsp/entdec.h b/aom_dsp/entdec.h
index 283bf18..1939f27 100644
--- a/aom_dsp/entdec.h
+++ b/aom_dsp/entdec.h
@@ -34,7 +34,7 @@
const unsigned char *buf;
/*An offset used to keep track of tell after reaching the end of the stream.
This is constant throughout most of the decoding process, but becomes
- important once we hit the end of the buffer and stop incrementing pointers
+ important once we hit the end of the buffer and stop incrementing bptr
(and instead pretend cnt has lots of bits).*/
int32_t tell_offs;
/*The end of the current input buffer.*/
diff --git a/aom_dsp/entenc.c b/aom_dsp/entenc.c
index a61da26..2fd4493 100644
--- a/aom_dsp/entenc.c
+++ b/aom_dsp/entenc.c
@@ -60,7 +60,7 @@
int s;
c = enc->cnt;
assert(rng <= 65535U);
- // The number of leading zeros in the 16-bit binary representation of rng.
+ /*The number of leading zeros in the 16-bit binary representation of rng.*/
d = 16 - OD_ILOG_NZ(rng);
s = c + d;
/*TODO: Right now we flush every time we have at least one byte available.
