jpeg: add tokenless two-pass baseline encoding

This commit is contained in:
Dylan M. Taylor committed 2026-11-17 16:00:45 -05:00
1 parent 93dac78c93
commit 971e8ad8f8
3 files changed
+261 -23

No files matched your search

+105 -22
View File
@@ -419,6 +419,34 @@ pub fn encode_baseline(
sub: ChromaSubsampling,
app_segments: &[(u8, Vec<u8>)],
) -> Result<Vec<u8>, 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<u8>)],
) -> Result<Vec<u8>, 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<u8>)]) -> 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<u8>)],
optimize: bool,
) -> Vec<u8> {
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<u8>)],
optimize: bool,
low_memory: bool,
) -> Vec<u8> {
// 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<usize> = (0..my.div_ceil(rows_per_band)).collect();
let num_bands = my.div_ceil(rows_per_band);
let bands: Vec<usize> = 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<Token>, [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<Token>, [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<Token>, [Freq; 4])> = bands.par_iter().map(tokenize_band).collect();
let tokenized: Vec<(Vec<Token>, [Freq; 4])> = if low_memory { Vec::new() } else { bands.par_iter().map(tokenize_band).collect() };
#[cfg(not(feature = "parallel"))]
let tokenized: Vec<(Vec<Token>, [Freq; 4])> = bands.iter().map(tokenize_band).collect();
let tokenized: Vec<(Vec<Token>, [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<u8>); 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<Vec<u8>> = tokenized.into_par_iter().map(|(t, _)| write_tokens(&t, &huff)).collect();
let coded: Vec<Vec<u8>> = if low_memory { Vec::new() } else { tokenized.into_par_iter().map(|(t, _)| write_tokens(&t, &huff)).collect() };
#[cfg(not(feature = "parallel"))]
let coded: Vec<Vec<u8>> = tokenized.into_iter().map(|(t, _)| write_tokens(&t, &huff)).collect();
let coded: Vec<Vec<u8>> = 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::<usize>() + 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;
+155
View File
@@ -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<u8> {
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<u8>)]) {
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}");
}
}
}
+1 -1
View File
@@ -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;