From 02ab4e01ef584345c4c5fc43d3bad2e9fdfc28bf Mon Sep 17 00:00:00 2001 From: bflatastic Date: Sun, 15 Nov 2026 15:15:31 -0500 Subject: [PATCH] Share bounded USD Crate LZ4 compression Adapt TextureCraft bdbb52c9 single-block framing with checked worst-case output sizing and fallible allocation. Preserve original compressed wire bytes. --- crates/usd/README.md | 2 +- crates/usd/src/compress.rs | 76 ++++++++++++++++++++++++++++++++++++++ crates/usd/src/lib.rs | 3 ++ 3 files changed, 80 insertions(+), 1 deletion(-) create mode 100644 crates/usd/src/compress.rs diff --git a/crates/usd/README.md b/crates/usd/README.md index 9e9635185..fcf585760 100644 --- a/crates/usd/README.md +++ b/crates/usd/README.md @@ -2,6 +2,6 @@ Bounded wire primitives for USD Crate, independent of application scene and material models. -Provides bounded integer-delta array decoding and Crate-framed LZ4 decompression: a single unprefixed block or up to 127 length-prefixed blocks, under a caller-provided output-byte cap with fallible output allocation. Trailing bytes after counted chunks retain the original reader's ignored-tail policy. This is not a complete USD reader/writer; scene interpretation, integer packing and export remain outside this extraction. Integer decoding uses explicit 32/64-bit widths, signed wrapping arithmetic, a caller output-byte cap and fallible allocation. +Provides bounded integer-delta array decoding and Crate-framed LZ4 compression/decompression: a single unprefixed block or up to 127 length-prefixed blocks, under a caller-provided output-byte cap with fallible output allocation. Trailing bytes after counted chunks retain the original reader's ignored-tail policy. This is not a complete USD reader/writer; scene interpretation, integer packing and full scene export remain outside this extraction. Compression uses a caller cap on worst-case reserved output and fallible allocation. Integer decoding uses explicit 32/64-bit widths, signed wrapping arithmetic, a caller output-byte cap and fallible allocation. Adapted from TextureCraft `crates/formats/src/mesh_import/usd/codec.rs`, introduced by bflatastic in `bdbb52c9b66b221a55b370105b42f485a76e6fc7`. The LZ4 backend is MIT-licensed `lz4_flex`. diff --git a/crates/usd/src/compress.rs b/crates/usd/src/compress.rs new file mode 100644 index 000000000..b92fa3be8 --- /dev/null +++ b/crates/usd/src/compress.rs @@ -0,0 +1,76 @@ +//! Bounded single-block USD Crate LZ4 writing. + +/// Compression admission, allocation or backend failure. +#[derive(Debug, thiserror::Error)] +pub enum Error { + /// Input or worst-case output exceeds the supported/caller budget. + #[error("USD Crate LZ4 compression exceeds budget")] + Limit, + /// The bounded output reservation failed. + #[error("cannot allocate USD Crate LZ4 output")] + Allocation, + /// The backend could not encode into the preflighted output buffer. + #[error("USD Crate LZ4 compression: {0}")] + Encode(#[from] lz4_flex::block::CompressError), +} + +fn capacity(input: usize, max_output_bytes: usize) -> Result { + // Keep inputs below the LZ4 single-block limit and preflight the backend's + // 20 + input*110/100 sizing arithmetic before calling it, including the count byte. + if input > 0x7e00_0000 { + return Err(Error::Limit); + } + input + .checked_mul(110) + .map(|n| n / 100) + .and_then(|n| n.checked_add(21)) + .filter(|n| *n <= max_output_bytes && *n <= isize::MAX as usize) + .ok_or(Error::Limit) +} + +/// Write one Crate-framed LZ4 block, beginning with a zero chunk-count byte. +/// +/// `max_output_bytes` bounds the reserved output including framing. Admission uses +/// the backend's worst-case size, so even highly compressible input must fit that bound. +/// Allocation is fallible; backend scratch memory is not included in the output cap. +/// Uses TextureCraft's original LZ4 backend/configuration and produces the same block bytes. +pub fn compress(input: &[u8], max_output_bytes: usize) -> Result, Error> { + let capacity = capacity(input.len(), max_output_bytes)?; + let mut output = Vec::new(); + output.try_reserve_exact(capacity).map_err(|_| Error::Allocation)?; + output.resize(capacity, 0); + let target = output.get_mut(1..).ok_or(Error::Limit)?; + let written = lz4_flex::block::compress_into(input, target)?; + output.truncate(written.checked_add(1).ok_or(Error::Limit)?); + Ok(output) +} + +#[cfg(test)] +#[allow(clippy::unwrap_used)] +mod tests { + use super::*; + + #[test] + fn original_wire_bytes_and_roundtrip() { + for size in [0, 1, 15, 16, 255, 4096, 65536] { + for repeated in [false, true] { + let input: Vec = (0..size).map(|i| if repeated { 17 } else { (i % 251) as u8 }).collect(); + let mut old = vec![0]; + old.extend(lz4_flex::block::compress(&input)); + let encoded = compress(&input, 1 << 20).unwrap(); + assert_eq!(encoded, old); + assert_eq!(crate::decompress(&encoded, size).unwrap(), input); + } + } + } + + #[test] + fn checks_worst_case_before_allocation() { + let input = [0; 100]; + assert!(matches!(compress(&input, 130), Err(Error::Limit))); + assert!(compress(&input, 131).is_ok()); + assert!(capacity(usize::MAX, usize::MAX).is_err()); + assert!(capacity(0x7e00_0001, usize::MAX).is_err()); + assert_eq!(capacity(0, 21).unwrap(), 21); + } +} diff --git a/crates/usd/src/lib.rs b/crates/usd/src/lib.rs index edaeb89a2..33c7f3484 100644 --- a/crates/usd/src/lib.rs +++ b/crates/usd/src/lib.rs @@ -5,6 +5,9 @@ #![forbid(unsafe_code)] #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] +/// Bounded single-block Crate LZ4 compression. +pub mod compress; + /// Bounded Crate integer delta arrays. pub mod integers;