From 971e8ad8f8f3dee5d171516c28ffbccef665cf03 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Tue, 17 Nov 2026 16:00:45 -0500 Subject: [PATCH] jpeg: add tokenless two-pass baseline encoding --- crates/jpeg/src/encode.rs | 127 ++++++++++++++--- crates/jpeg/src/encode_low_memory_tests.rs | 155 +++++++++++++++++++++ crates/jpeg/src/lib.rs | 2 +- 3 files changed, 261 insertions(+), 23 deletions(-) create mode 100644 crates/jpeg/src/encode_low_memory_tests.rs diff --git a/crates/jpeg/src/encode.rs b/crates/jpeg/src/encode.rs index 548f4c9f9..fb5fe183c 100644 --- a/crates/jpeg/src/encode.rs +++ b/crates/jpeg/src/encode.rs @@ -419,6 +419,34 @@ pub fn encode_baseline( sub: ChromaSubsampling, app_segments: &[(u8, Vec)], ) -> Result, EncodeError> { + validate_encode(data, width, height, channels, app_segments)?; + Ok(encode(data, width, height, channels, quality, sub, app_segments)) +} + +/// Encode the same optimized baseline JPEG as [`encode_baseline`], trading a second DCT pass +/// for working memory independent of image height. This path is sequential even when the +/// `parallel` feature is enabled. It retains only one MCU row of conversion planes and writes +/// directly into the returned encoded buffer: no image-wide tokens or duplicate coded buffer. +/// +/// Scratch consists of at most `24 * width + 8` floats (odd-width 4:2:0), plus fixed-size coding tables. +/// The caller still owns the input pixels and the returned JPEG; this is not a cap on output +/// size or a replacement for the caller's image/admission budget. Geometry, quality, metadata, +/// Huffman tables and restart boundaries match [`encode_baseline`] byte for byte. +#[allow(clippy::too_many_arguments)] +pub fn encode_baseline_low_memory( + data: &[u8], + width: usize, + height: usize, + channels: usize, + quality: u8, + sub: ChromaSubsampling, + app_segments: &[(u8, Vec)], +) -> Result, EncodeError> { + validate_encode(data, width, height, channels, app_segments)?; + Ok(encode_impl(data, width, height, channels, quality, sub, app_segments, true, true)) +} + +fn validate_encode(data: &[u8], width: usize, height: usize, channels: usize, app_segments: &[(u8, Vec)]) -> Result<(), EncodeError> { let fits = width.checked_mul(height).and_then(|n| n.checked_mul(channels)).is_some_and(|n| n <= data.len()); if !fits || width == 0 || height == 0 || width > 65_535 || height > 65_535 || !matches!(channels, 1 | 3 | 4) { return Err(EncodeError::InvalidInput(format!("{width}x{height}, {channels} channels, {} bytes", data.len()))); @@ -426,7 +454,7 @@ pub fn encode_baseline( if app_segments.iter().any(|(marker, payload)| !(0xE0..=0xEF).contains(marker) || payload.len() > 65_533) { return Err(EncodeError::InvalidInput("APP markers must be 0xE0..=0xEF with payloads no larger than 65533 bytes".into())); } - Ok(encode(data, width, height, channels, quality, sub, app_segments)) + Ok(()) } /// [`encode`], with optimized Huffman tables or (`optimize` false) the Annex K example tables. @@ -440,6 +468,21 @@ fn encode_with( sub: ChromaSubsampling, app_segments: &[(u8, Vec)], optimize: bool, +) -> Vec { + encode_impl(data, width, height, channels, quality, sub, app_segments, optimize, false) +} + +#[allow(clippy::too_many_arguments)] +fn encode_impl( + data: &[u8], + width: usize, + height: usize, + channels: usize, + quality: u8, + sub: ChromaSubsampling, + app_segments: &[(u8, Vec)], + optimize: bool, + low_memory: bool, ) -> Vec { // The public entry takes caller-sized dimensions: refuse (an empty output) what would size an allocation from // them or index past `data`, rather than panic or allocate for them. @@ -509,6 +552,8 @@ fn encode_with( planes.push(Plane { w: cw, h: crows.len(), data: cb }); planes.push(Plane { w: cw, h: crows.len(), data: cr }); } + #[cfg(test)] + low_memory_tests::record_planes(planes.iter().map(|p| p.data.len()).sum()); planes }; @@ -519,45 +564,58 @@ fn encode_with( let (mx, my) = (width.div_ceil(mcu_w), height.div_ceil(mcu_h)); // restart interval: whole MCU rows per band, ≤ 65535 MCUs, enough bands to keep all cores busy let rows_per_band = (my / 64).clamp(1, (65_535 / mx.max(1)).max(1)); - let bands: Vec = (0..my.div_ceil(rows_per_band)).collect(); + let num_bands = my.div_ceil(rows_per_band); + let bands: Vec = if low_memory { Vec::new() } else { (0..num_bands).collect() }; // first pass: each band's quantized blocks as symbols, with their counts per table (DC // prediction restarts per band, as the restart markers say) - let tokenize_band = |band: &usize| -> (Vec, [Freq; 4]) { + let visit_band = |band: &usize, emit: &mut dyn FnMut(&[i16; 64], &mut i32, bool)| { let (mut blk, mut q) = ([0f32; 64], [0i16; 64]); - let (mut tokens, mut freq) = (Vec::new(), [[0u64; 256]; 4]); let mut pred = [0i32; 3]; let (m0, m1) = (band * rows_per_band, ((band + 1) * rows_per_band).min(my)); - // the band's planes, its MCU row `m0` at their top (blocks past the image's bottom repeat its last row, - // which is the band's last row then) - let planes = convert(m0 * mcu_h..(m1 * mcu_h).min(height), m0 * 8..(m1 * 8).min(ch)); for mcu_y in m0..m1 { - let mcu_y = mcu_y - m0; + // Convert only the current MCU row. DC predictors still span the original band, + // so its symbols/restart decisions are identical to whole-band conversion. + let planes = convert(mcu_y * mcu_h..((mcu_y + 1) * mcu_h).min(height), mcu_y * 8..((mcu_y + 1) * 8).min(ch)); for mcu_x in 0..mx { for vy in 0..vs { for hx in 0..hs { - planes[0].block(mcu_x * hs + hx, mcu_y * vs + vy, &mut blk); + planes[0].block(mcu_x * hs + hx, vy, &mut blk); fdct_quant(&blk, &rl, &mut q); - tokenize_block(&q, &mut pred[0], false, &mut tokens, &mut freq); + emit(&q, &mut pred[0], false); } } if !gray { for (plane, pred) in planes.iter().zip(pred.iter_mut()).take(3).skip(1) { - plane.block(mcu_x, mcu_y, &mut blk); + plane.block(mcu_x, 0, &mut blk); fdct_quant(&blk, &rc, &mut q); - tokenize_block(&q, pred, true, &mut tokens, &mut freq); + emit(&q, pred, true); } } } } + }; + let tokenize_band = |band: &usize| -> (Vec, [Freq; 4]) { + let (mut tokens, mut freq) = (Vec::new(), [[0u64; 256]; 4]); + visit_band(band, &mut |q, pred, chroma| tokenize_block(q, pred, chroma, &mut tokens, &mut freq)); + #[cfg(test)] + low_memory_tests::record_tokens(tokens.len()); (tokens, freq) }; #[cfg(feature = "parallel")] - let tokenized: Vec<(Vec, [Freq; 4])> = bands.par_iter().map(tokenize_band).collect(); + let tokenized: Vec<(Vec, [Freq; 4])> = if low_memory { Vec::new() } else { bands.par_iter().map(tokenize_band).collect() }; #[cfg(not(feature = "parallel"))] - let tokenized: Vec<(Vec, [Freq; 4])> = bands.iter().map(tokenize_band).collect(); + let tokenized: Vec<(Vec, [Freq; 4])> = if low_memory { Vec::new() } else { bands.iter().map(tokenize_band).collect() }; // the tables: DC luma, AC luma, DC chroma, AC chroma let tables: [([u8; 16], Vec); 4] = if optimize { let mut total = [[0u64; 256]; 4]; + if low_memory { + for band in 0..num_bands { + visit_band(&band, &mut |q, pred, chroma| { + let base = if chroma { 2 } else { 0 }; + block_symbols(q, pred, |ac, symbol, _, _| total[base + ac as usize][symbol & 0xFF] += 1); + }); + } + } for (_, f) in &tokenized { for (t, f) in total.iter_mut().zip(f) { for (t, f) in t.iter_mut().zip(f) { @@ -577,9 +635,9 @@ fn encode_with( let huff = tables.each_ref().map(|(bits, vals)| Huff::new(bits, vals)); // second pass: code the symbols #[cfg(feature = "parallel")] - let coded: Vec> = tokenized.into_par_iter().map(|(t, _)| write_tokens(&t, &huff)).collect(); + let coded: Vec> = if low_memory { Vec::new() } else { tokenized.into_par_iter().map(|(t, _)| write_tokens(&t, &huff)).collect() }; #[cfg(not(feature = "parallel"))] - let coded: Vec> = tokenized.into_iter().map(|(t, _)| write_tokens(&t, &huff)).collect(); + let coded: Vec> = if low_memory { Vec::new() } else { tokenized.into_iter().map(|(t, _)| write_tokens(&t, &huff)).collect() }; // headers let mut out = Vec::with_capacity(coded.iter().map(Vec::len).sum::() + 4096); @@ -617,7 +675,7 @@ fn encode_with( dht(&mut out, 0x11, acb, acv); } let interval = (rows_per_band * mx) as u16; - if coded.len() > 1 { + if num_bands > 1 { segment(&mut out, 0xDD, &interval.to_be_bytes()); } if gray { @@ -625,11 +683,32 @@ fn encode_with( } else { segment(&mut out, 0xDA, &[3, 1, 0x00, 2, 0x11, 3, 0x11, 0, 63, 0]); } - let last = coded.len().saturating_sub(1); - for (i, c) in coded.iter().enumerate() { - out.extend_from_slice(c); - if i < last { - out.extend_from_slice(&[0xFF, 0xD0 + (i % 8) as u8]); + if low_memory { + let last = num_bands.saturating_sub(1); + for i in 0..num_bands { + // Continue directly in the final buffer, resetting entropy bits at the same band + // boundaries as the retained-token path. Only the output grows with image height. + let mut bits = Bits { out, acc: 0, n: 0 }; + visit_band(&i, &mut |q, pred, chroma| { + let base = if chroma { 2 } else { 0 }; + block_symbols(q, pred, |ac, symbol, extra, n| { + let (code, len) = huff[base + ac as usize].code[symbol & 0xFF]; + bits.put(code as u32, len as u32); + bits.put(extra & 0xFFFF, n & 0xF); + }); + }); + out = bits.finish(); + if i < last { + out.extend_from_slice(&[0xFF, 0xD0 + (i % 8) as u8]); + } + } + } else { + let last = coded.len().saturating_sub(1); + for (i, c) in coded.iter().enumerate() { + out.extend_from_slice(c); + if i < last { + out.extend_from_slice(&[0xFF, 0xD0 + (i % 8) as u8]); + } } } out.extend_from_slice(&[0xFF, 0xD9]); @@ -877,3 +956,7 @@ mod tests { assert!(psnr(&src, &px) > 35.0); } } + +#[cfg(test)] +#[path = "encode_low_memory_tests.rs"] +mod low_memory_tests; diff --git a/crates/jpeg/src/encode_low_memory_tests.rs b/crates/jpeg/src/encode_low_memory_tests.rs new file mode 100644 index 000000000..de45f8dfe --- /dev/null +++ b/crates/jpeg/src/encode_low_memory_tests.rs @@ -0,0 +1,155 @@ +use super::*; +use std::cell::Cell; + +thread_local! { + static STATS: Cell<(usize, usize)> = const { Cell::new((0, 0)) }; +} + +pub(super) fn record_planes(samples: usize) { + STATS.with(|s| { + let (peak, tokens) = s.get(); + s.set((peak.max(samples), tokens)); + }); +} +pub(super) fn record_tokens(count: usize) { + STATS.with(|s| { + let (peak, tokens) = s.get(); + s.set((peak, tokens + count)); + }); +} + +fn noise(len: usize) -> Vec { + let mut seed = 0x89ab_cdefu32; + (0..len) + .map(|_| { + seed ^= seed << 13; + seed ^= seed >> 17; + seed ^= seed << 5; + seed as u8 + }) + .collect() +} + +fn compare(src: &[u8], w: usize, h: usize, ch: usize, q: u8, sub: ChromaSubsampling, app: &[(u8, Vec)]) { + let expected = encode_baseline(src, w, h, ch, q, sub, app).unwrap(); + STATS.with(|s| s.set((0, 0))); + let actual = encode_baseline_low_memory(src, w, h, ch, q, sub, app).unwrap(); + assert_eq!(actual, expected, "{w}x{h} channels={ch} quality={q} subsampling={sub:?}"); + let (peak, tokens) = STATS.with(Cell::get); + assert!(peak <= 24 * w + 8, "MCU-row scratch exceeded: {peak}"); + assert_eq!(tokens, 0, "low-memory mode retained entropy tokens"); +} + +#[test] +fn all_sampling_and_channels_match_retained_tokens_byte_for_byte() { + for (w, h) in [(1, 1), (7, 9), (17, 31), (33, 65), (17, 1025)] { + for ch in [1, 3, 4] { + let src = noise(w * h * ch); + for sub in [ChromaSubsampling::S444, ChromaSubsampling::S422, ChromaSubsampling::S420] { + for q in [0, 1, 25, 50, 90, 100, 255] { + compare(&src, w, h, ch, q, sub, &[]); + } + } + } + } +} + +#[test] +fn high_entropy_hd_and_wide_frames_keep_only_one_mcu_row() { + for (w, h) in [(1920, 1080), (65_535, 1)] { + let src = noise(w * h * 3); + compare(&src, w, h, 3, 100, ChromaSubsampling::S444, &[]); + } +} + +#[test] +fn metadata_empty_tables_and_extra_source_bytes_keep_exact_output() { + let app = [(0xe0, b"custom density".to_vec()), (0xe2, vec![73; 65_533])]; + for ch in [1, 3, 4] { + let src = vec![127; 19 * 23 * ch + 5]; + compare(&src, 19, 23, ch, 75, ChromaSubsampling::S420, &app); + } +} + +#[test] +fn checked_admission_matches_original_without_panics() { + for (w, h, ch) in [(0, 1, 3), (1, 0, 3), (1, 1, 0), (1, 1, 2), (usize::MAX, 2, 4), (65_536, 1, 1), (1, 65_536, 1), (4, 4, 3)] { + let src = vec![0; if w == 65_536 || h == 65_536 { 65_536 } else { 8 }]; + let old = encode_baseline(&src, w, h, ch, 90, ChromaSubsampling::S444, &[]); + let new = encode_baseline_low_memory(&src, w, h, ch, 90, ChromaSubsampling::S444, &[]); + assert!(new.is_err()); + assert_eq!(new, old); + } + for app in [vec![(0xdf, vec![])], vec![(0xf0, vec![])], vec![(0xe1, vec![0; 65_534])]] { + assert_eq!( + encode_baseline_low_memory(&[0; 3], 1, 1, 3, 90, ChromaSubsampling::S444, &app), + encode_baseline(&[0; 3], 1, 1, 3, 90, ChromaSubsampling::S444, &app) + ); + } +} + +// Generated with the immutable pre-change encoder at craft-libs +// 937ac93c5cf3cd4b6a81e195b078fe161eb081b9, not the refactored token-retaining path. +// Odd chroma edges and 1025/2049-row inputs exercise multi-row restart bands. +#[test] +fn prechange_encoded_bytes_remain_pinned_across_band_boundaries() { + let cases = [ + (1, 1, 1, 1, 444, 159, 0xe3bd59145381ba57), + (1, 1, 1, 75, 422, 159, 0xcb2b103914bbdbd3), + (1, 1, 1, 100, 420, 160, 0xd9f640613efb6abf), + (1, 1, 3, 1, 444, 284, 0x61d2772b8fd9df17), + (1, 1, 3, 75, 422, 286, 0xa0e03ab7efa23296), + (1, 1, 3, 100, 420, 288, 0x5660667f1abd0a63), + (1, 1, 4, 1, 444, 284, 0x61d2772b8fd9df17), + (1, 1, 4, 75, 422, 286, 0xa0e03ab7efa23296), + (1, 1, 4, 100, 420, 288, 0x5660667f1abd0a63), + (17, 31, 1, 1, 444, 240, 0xf8d277e9499253d4), + (17, 31, 1, 75, 422, 515, 0xa6946d4f144bf243), + (17, 31, 1, 100, 420, 793, 0xbb3db259708d8951), + (17, 31, 3, 1, 444, 363, 0xff2b5b41ffb3f81b), + (17, 31, 3, 75, 422, 877, 0x0374ffb527378dfe), + (17, 31, 3, 100, 420, 1220, 0x2feeedfa90885737), + (17, 31, 4, 1, 444, 366, 0xde7f8d1330e436eb), + (17, 31, 4, 75, 422, 879, 0xb1559fbfc3ee0cf6), + (17, 31, 4, 100, 420, 1214, 0xaf5dcf12d28c8e88), + (33, 65, 1, 1, 444, 388, 0xbee80491e42c8fd2), + (33, 65, 1, 75, 422, 1470, 0x284f4eb78b785ca5), + (33, 65, 1, 100, 420, 2576, 0xa81cc94015f326dc), + (33, 65, 3, 1, 444, 526, 0xf75b4036acc30874), + (33, 65, 3, 75, 422, 2322, 0x6fbc56bd9a1eec70), + (33, 65, 3, 100, 420, 3796, 0xcad25051562ac816), + (33, 65, 4, 1, 444, 527, 0x4bfedc11153de4c1), + (33, 65, 4, 75, 422, 2309, 0x47bf11bf32bac6a4), + (33, 65, 4, 100, 420, 3775, 0x64c2303fde273cd1), + (17, 1025, 1, 1, 444, 2017, 0x242f4a95d8579612), + (17, 1025, 1, 75, 422, 10728, 0xfe49408f379bdffb), + (17, 1025, 1, 100, 420, 19686, 0x1355b995e38d6467), + (17, 1025, 3, 1, 444, 2137, 0x4e319440cb6946c2), + (17, 1025, 3, 75, 422, 17682, 0xf456c63b731dde8f), + (17, 1025, 3, 100, 420, 29015, 0x0631001154b128cf), + (17, 1025, 4, 1, 444, 2155, 0xa2de9c1d77e62aa6), + (17, 1025, 4, 75, 422, 17648, 0x7d85fbdf56061f0c), + (17, 1025, 4, 100, 420, 29010, 0x4848eeb93daf1df2), + (19, 2049, 1, 1, 444, 3531, 0x9b93cf219ff85796), + (19, 2049, 1, 75, 422, 26283, 0xb160523444397608), + (19, 2049, 1, 100, 420, 51883, 0xc5c26836c0a976c6), + (19, 2049, 3, 1, 444, 3303, 0x26eaac2272e1fdb8), + (19, 2049, 3, 75, 422, 42745, 0x38b9843fb54db698), + (19, 2049, 3, 100, 420, 79868, 0xd6a7917af19682f7), + (19, 2049, 4, 1, 444, 3343, 0x6bf577903528692f), + (19, 2049, 4, 75, 422, 42706, 0x0e62366274593a93), + (19, 2049, 4, 100, 420, 79804, 0x867d05cf9d944599), + ]; + for (w, h, ch, q, sampling, len, hash) in cases { + let sub = match sampling { + 444 => ChromaSubsampling::S444, + 422 => ChromaSubsampling::S422, + _ => ChromaSubsampling::S420, + }; + let src = noise(w * h * ch); + for actual in [encode_baseline(&src, w, h, ch, q, sub, &[]).unwrap(), encode_baseline_low_memory(&src, w, h, ch, q, sub, &[]).unwrap()] { + let actual_hash = actual.iter().fold(0xcbf29ce484222325u64, |h, b| (h ^ u64::from(*b)).wrapping_mul(0x100000001b3)); + assert_eq!((actual.len(), actual_hash), (len, hash), "{w}x{h} channels={ch} quality={q} sampling={sampling}"); + } + } +} diff --git a/crates/jpeg/src/lib.rs b/crates/jpeg/src/lib.rs index 23434fdd0..ed2ee1988 100644 --- a/crates/jpeg/src/lib.rs +++ b/crates/jpeg/src/lib.rs @@ -1705,7 +1705,7 @@ mod tests; /// Baseline JPEG encoder (8-bit, Huffman-coded sequential DCT). mod encode; -pub use encode::{ChromaSubsampling, EncodeError, encode_baseline}; +pub use encode::{ChromaSubsampling, EncodeError, encode_baseline, encode_baseline_low_memory}; mod app14; pub use app14::adobe_transform;