Merge pull request #1738 from storytold/extract/usd-crate-codec

Extract bounded USD Crate LZ4 decompression
This commit is contained in:
Dylan M. Taylor
2026-11-15 17:04:17 -05:00
committed by GitHub
5 changed files with 132 additions and 0 deletions
Generated
+14
View File
@@ -2844,6 +2844,14 @@ dependencies = [
"zip",
]
[[package]]
name = "craft-usd"
version = "0.1.0"
dependencies = [
"lz4_flex",
"thiserror 2.0.21",
]
[[package]]
name = "craft-vcard"
version = "0.1.0"
@@ -6043,6 +6051,12 @@ version = "0.1.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4050469837a6ff301cd14c1f8f24f88549e6d548f24f64e2148eb0f72cebc51f"
[[package]]
name = "lz4_flex"
version = "0.11.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "373f5eceeeab7925e0c1098212f2fbc4d416adec9d35051a6ab251e824c1854a"
[[package]]
name = "maybe-owned"
version = "0.3.4"
+1
View File
@@ -11,6 +11,7 @@ rust-version = "1.95"
repository = "https://github.com/storytold/craft-libs"
[workspace.dependencies]
craft-usd = { path = "crates/usd" }
craft-smime = { path = "crates/smime" }
craft-ber = { path = "crates/ber" }
craft-proto = { path = "crates/proto" }
+15
View File
@@ -0,0 +1,15 @@
[package]
name = "craft-usd"
description = "Bounded USD Crate wire primitives, independent of scene and material policy"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
[lints]
workspace = true
[dependencies]
lz4_flex = { version = "0.11", default-features = false, features = ["safe-decode", "safe-encode"] }
thiserror.workspace = true
+7
View File
@@ -0,0 +1,7 @@
# craft-usd
Bounded wire primitives for USD Crate, independent of application scene and material models.
Currently provides Crate-framed LZ4 decompression only: 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 first extraction.
Adapted from TextureCraft `crates/formats/src/mesh_import/usd/codec.rs`, introduced by bflatastic in `bdbb52c9b66b221a55b370105b42f485a76e6fc7`. The LZ4 backend is MIT-licensed `lz4_flex`.
+95
View File
@@ -0,0 +1,95 @@
//! Bounded USD Crate wire primitives. Not a complete USD scene reader or writer.
//!
//! The framing decoder is adapted from TextureCraft's `usd/codec.rs`, originally
//! bflatastic, commit bdbb52c9b66b221a55b370105b42f485a76e6fc7.
#![forbid(unsafe_code)]
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
/// Failure to read a bounded Crate LZ4 frame.
#[derive(Debug, thiserror::Error)]
pub enum Error {
/// Invalid or incomplete chunk framing.
#[error("invalid USD Crate LZ4 framing: {0}")]
Framing(&'static str),
/// Invalid compressed data or output exceeding the supplied capacity.
#[error("USD Crate LZ4 data: {0}")]
Lz4(#[from] lz4_flex::block::DecompressError),
/// The bounded output allocation could not be reserved.
#[error("cannot allocate USD Crate LZ4 output")]
Allocation,
}
/// Decode Crate's chunk-count byte and LZ4 blocks to at most `max_output` bytes.
///
/// A zero count means a single unprefixed block; 1..=127 means that many blocks,
/// each preceded by a signed little-endian 32-bit length. As in the original reader,
/// bytes following the declared chunks are ignored. The output allocation is fallible
/// and capped by both the caller's budget and the input's maximum LZ4 expansion.
/// This bounds the returned plane, not backend internal scratch memory.
pub fn decompress(input: &[u8], max_output: usize) -> Result<Vec<u8>, Error> {
let (&chunks, mut rest) = input.split_first().ok_or(Error::Framing("empty block"))?;
if chunks > 127 {
return Err(Error::Framing("chunk count exceeds 127"));
}
let capacity = max_output.min(input.len().saturating_mul(256).saturating_add(64));
let mut output = Vec::new();
output.try_reserve_exact(capacity).map_err(|_| Error::Allocation)?;
output.resize(capacity, 0);
let written = if chunks == 0 {
lz4_flex::block::decompress_into(rest, &mut output)?
} else {
let mut total = 0usize;
for _ in 0..chunks {
let length = rest.get(..4).and_then(|b| b.try_into().ok()).map(i32::from_le_bytes).ok_or(Error::Framing("missing chunk length"))?;
let length = usize::try_from(length).map_err(|_| Error::Framing("negative chunk length"))?;
let end = 4usize.checked_add(length).ok_or(Error::Framing("chunk length overflow"))?;
let chunk = rest.get(4..end).ok_or(Error::Framing("truncated chunk"))?;
rest = rest.get(end..).unwrap_or_default();
let tail = output.get_mut(total..).ok_or(Error::Framing("output offset overflow"))?;
let count = lz4_flex::block::decompress_into(chunk, tail)?;
total = total.checked_add(count).ok_or(Error::Framing("output length overflow"))?;
}
total
};
output.truncate(written);
Ok(output)
}
#[cfg(test)]
#[allow(clippy::unwrap_used)]
mod tests {
use super::*;
#[test]
fn single_block_matches_original_wire() {
for n in [0, 1, 15, 16, 255, 4096] {
let raw: Vec<u8> = (0..n).map(|i| (i % 251) as u8).collect();
let mut frame = vec![0];
frame.extend(lz4_flex::block::compress(&raw));
assert_eq!(decompress(&frame, raw.len()).unwrap(), raw);
if n > 0 {
assert!(decompress(&frame, n - 1).is_err());
}
}
}
#[test]
fn counted_blocks_and_trailing_bytes_keep_existing_policy() {
let mut frame = vec![2];
for raw in [b"first".as_slice(), b"second".as_slice()] {
let block = lz4_flex::block::compress(raw);
frame.extend((block.len() as i32).to_le_bytes());
frame.extend(block);
}
frame.extend(b"ignored");
assert_eq!(decompress(&frame, 11).unwrap(), b"firstsecond");
assert!(decompress(&frame, 10).is_err());
}
#[test]
fn malformed_frames_fail_within_budget() {
for data in [vec![], vec![128], vec![1], vec![1, 255, 255, 255, 255], vec![1, 5, 0, 0, 0, 1]] {
assert!(decompress(&data, 32).is_err());
}
}
}