std/jpeg: comments for "read Huffman LUT earlier"

This commit is the second of two. It just adds comments to the code
added by the previous commit.
This commit is contained in:
Nigel Tao committed 2023-06-21 22:51:22 +10:00
1 parent d9c7740ea6
commit 255516bc21
5 files changed
+74 -6

No files matched your search

+36 -2
View File
@@ -75,7 +75,7 @@ pri func decoder.decode_mcu!(workbuf: slice base.u8, mx: base.u32[..= 0x1FFF], m
{
this.mcu_blocks[.. 1].bulk_memset!(byte_value: 0)
// Load at least 31 bits, by keeping 56 .. 64 loaded.
// Load at least 47 bits, by keeping 56 .. 64 loaded.
if r.length() < 8 {
ret = 1 // Request another fill_bitstream call.
break.goto_done
@@ -149,8 +149,16 @@ pri func decoder.decode_mcu!(workbuf: slice base.u8, mx: base.u32[..= 0x1FFF], m
break.goto_done
}
// Ensure the informal "the lower bound on the number of loaded
// bits is at least 16" loop pre-condition below.
if n_bits < 16 {
bits |= r.peek_u64be() >> (n_bits & 63)
// Skip these lines that are normally part of "load more bits".
// It's unnecessary, just for the informal (NB > 16) below, and
// skipping it avoids a small but negative performance impact.
//
// r.skip_u32_fast!( etc )
// n_bits |= 56
}
z = 1
@@ -161,9 +169,32 @@ pri func decoder.decode_mcu!(workbuf: slice base.u8, mx: base.u32[..= 0x1FFF], m
inv this.mcu_current_block < 10,
inv ac_huff_table_fast <> nullptr,
{
// Use the high bits of the bits variable to look up the
// Huffman table. Conceptually, we should do this *after*
// "Load at least 47 bits" below (at "LOOK-UP" further below),
// but it is noticably faster to do it beforehand:
// https://github.com/google/wuffs/commit/d9c7740ea6c4a450401c393787838436895b87bb
//
// Earlier look-up is OK because there is a informal loop
// pre-condition (informal means not enforced by the Wuffs
// compiler) that (NB >= 16) here, where NB is "the number of
// loaded bits in the bits variable". It is literally n_bits
// for almost all loop iterations, but it can be higher on the
// first iteration, set up by "Ensure the informal" above.
//
// For subsequent iterations, the "Load at least 47 bits" below
// does what it says. The Huffman code consumes up to 16 bits
// and processing the Huffman symbol's ssss nibble consumes up
// to 15 bits. (47 - 16 - 15) = 16 so at the end of the loop
// body, (n_bits >= 16).
//
// This 16 bound has some slack, as (NB >= (64 - 56)) is all we
// need, but a bound of 16 (the longest JPEG Huffman code bit
// length) won't need to change even if, in the future, we
// enlarge the look-up table size.
ac_ht_fast = ac_huff_table_fast[bits >> 56] as base.u32
// Load at least 31 bits, by keeping 56 .. 64 loaded.
// Load at least 47 bits, by keeping 56 .. 64 loaded.
//
// TODO: eliminate this bounds check entirely.
if r.length() < 8 {
@@ -175,6 +206,9 @@ pri func decoder.decode_mcu!(workbuf: slice base.u8, mx: base.u32[..= 0x1FFF], m
n_bits |= 56
// Read the Huffman-encoded ac_symbol, up to 16 bits long.
//
// LOOK-UP: "ac_ht_fast = etc" conceptually happens here, just
// before deriving ac_bl from ac_ht_fast.
ac_bl = ac_ht_fast >> 8
if n_bits >= ac_bl {
ac_symbol = 0xFF & ac_ht_fast
@@ -65,8 +65,16 @@ pri func decoder.decode_mcu_progressive_ac_high_bits!(workbuf: slice base.u8, mx
break.goto_done
}
// Ensure the informal "the lower bound on the number of loaded
// bits is at least 16" loop pre-condition below.
if n_bits < 16 {
bits |= r.peek_u64be() >> (n_bits & 63)
// Skip these lines that are normally part of "load more bits".
// It's unnecessary, just for the informal (NB > 16) below, and
// skipping it avoids a small but negative performance impact.
//
// r.skip_u32_fast!( etc )
// n_bits |= 56
}
z = this.mcu_zig_index
@@ -78,9 +86,32 @@ pri func decoder.decode_mcu_progressive_ac_high_bits!(workbuf: slice base.u8, mx
{
assert z < 64 via "a < b: a <= c; c < b"(c: (this.scan_se as base.u32))
// Use the high bits of the bits variable to look up the
// Huffman table. Conceptually, we should do this *after*
// "Load at least 47 bits" below (at "LOOK-UP" further below),
// but it is noticably faster to do it beforehand:
// https://github.com/google/wuffs/commit/d9c7740ea6c4a450401c393787838436895b87bb
//
// Earlier look-up is OK because there is a informal loop
// pre-condition (informal means not enforced by the Wuffs
// compiler) that (NB >= 16) here, where NB is "the number of
// loaded bits in the bits variable". It is literally n_bits
// for almost all loop iterations, but it can be higher on the
// first iteration, set up by "Ensure the informal" above.
//
// For subsequent iterations, the "Load at least 47 bits" below
// does what it says. The Huffman code consumes up to 16 bits
// and processing the Huffman symbol's ssss nibble consumes up
// to 15 bits. (47 - 16 - 15) = 16 so at the end of the loop
// body, (n_bits >= 16).
//
// This 16 bound has some slack, as (NB >= (64 - 56)) is all we
// need, but a bound of 16 (the longest JPEG Huffman code bit
// length) won't need to change even if, in the future, we
// enlarge the look-up table size.
ac_ht_fast = ac_huff_table_fast[bits >> 56] as base.u32
// Load at least 31 bits, by keeping 56 .. 64 loaded.
// Load at least 47 bits, by keeping 56 .. 64 loaded.
//
// TODO: eliminate this bounds check entirely.
if r.length() < 8 {
@@ -92,6 +123,9 @@ pri func decoder.decode_mcu_progressive_ac_high_bits!(workbuf: slice base.u8, mx
n_bits |= 56
// Read the Huffman-encoded ac_symbol, up to 16 bits long.
//
// LOOK-UP: "ac_ht_fast = etc" conceptually happens here, just
// before deriving ac_bl from ac_ht_fast.
ac_bl = ac_ht_fast >> 8
if n_bits >= ac_bl {
ac_symbol = 0xFF & ac_ht_fast
@@ -62,7 +62,7 @@ pri func decoder.decode_mcu_progressive_ac_low_bit!(workbuf: slice base.u8, mx:
while.ac_components true,
inv ac_huff_table_fast <> nullptr,
{
// Load at least 31 bits, by keeping 56 .. 64 loaded (call it 8
// Load at least 47 bits, by keeping 56 .. 64 loaded (call it 8
// bytes). Just like the other decode_mcu_etc functions, this
// is enough for the Huffman-encoded ac_symbol (up to 16 bits)
// and processing the ac_value (up to 15 bits).
@@ -47,7 +47,7 @@ pri func decoder.decode_mcu_progressive_dc_high_bits!(workbuf: slice base.u8, mx
while.dc_component true,
inv this.mcu_current_block < 10,
{
// Load at least 31 bits, by keeping 56 .. 64 loaded.
// Load at least 47 bits, by keeping 56 .. 64 loaded.
if r.length() < 8 {
ret = 1 // Request another fill_bitstream call.
break.goto_done
@@ -39,7 +39,7 @@ pri func decoder.decode_mcu_progressive_dc_low_bit!(workbuf: slice base.u8, mx:
while.dc_component true,
inv this.mcu_current_block < 10,
{
// Load at least 31 bits, by keeping 56 .. 64 loaded.
// Load at least 47 bits, by keeping 56 .. 64 loaded.
if r.length() < 8 {
ret = 1 // Request another fill_bitstream call.
break.goto_done