From 255516bc210aa1cb67c9bc5ec460b3c79c033981 Mon Sep 17 00:00:00 2001 From: Nigel Tao Date: Wed, 21 Jun 2023 22:50:49 +1000 Subject: [PATCH] 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. --- std/jpeg/decode_mcu_default.wuffs | 38 ++++++++++++++++++- .../decode_mcu_progressive_ac_high_bits.wuffs | 36 +++++++++++++++++- .../decode_mcu_progressive_ac_low_bit.wuffs | 2 +- .../decode_mcu_progressive_dc_high_bits.wuffs | 2 +- .../decode_mcu_progressive_dc_low_bit.wuffs | 2 +- 5 files changed, 74 insertions(+), 6 deletions(-) diff --git a/std/jpeg/decode_mcu_default.wuffs b/std/jpeg/decode_mcu_default.wuffs index 1dac5211..2b7cd2fe 100644 --- a/std/jpeg/decode_mcu_default.wuffs +++ b/std/jpeg/decode_mcu_default.wuffs @@ -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 diff --git a/std/jpeg/decode_mcu_progressive_ac_high_bits.wuffs b/std/jpeg/decode_mcu_progressive_ac_high_bits.wuffs index 2d41c436..cb969983 100644 --- a/std/jpeg/decode_mcu_progressive_ac_high_bits.wuffs +++ b/std/jpeg/decode_mcu_progressive_ac_high_bits.wuffs @@ -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 diff --git a/std/jpeg/decode_mcu_progressive_ac_low_bit.wuffs b/std/jpeg/decode_mcu_progressive_ac_low_bit.wuffs index e7c62a5d..429180b0 100644 --- a/std/jpeg/decode_mcu_progressive_ac_low_bit.wuffs +++ b/std/jpeg/decode_mcu_progressive_ac_low_bit.wuffs @@ -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). diff --git a/std/jpeg/decode_mcu_progressive_dc_high_bits.wuffs b/std/jpeg/decode_mcu_progressive_dc_high_bits.wuffs index c309154a..73a324cf 100644 --- a/std/jpeg/decode_mcu_progressive_dc_high_bits.wuffs +++ b/std/jpeg/decode_mcu_progressive_dc_high_bits.wuffs @@ -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 diff --git a/std/jpeg/decode_mcu_progressive_dc_low_bit.wuffs b/std/jpeg/decode_mcu_progressive_dc_low_bit.wuffs index f9cb5412..29a16784 100644 --- a/std/jpeg/decode_mcu_progressive_dc_low_bit.wuffs +++ b/std/jpeg/decode_mcu_progressive_dc_low_bit.wuffs @@ -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