mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-16 20:25:02 +00:00
Extract bounded USD Crate integer delta decoding
Retain TextureCraft signed wrapping and delta widths from bdbb52c9b66b221a55b370105b42f485a76e6fc7; use explicit widths, output byte budget, checked code-table admission and fallible reservation.
This commit is contained in:
committed by
Dylan M. Taylor
parent
556d02941a
commit
456abf7b7a
@@ -2,6 +2,6 @@
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Adapted from TextureCraft `crates/formats/src/mesh_import/usd/codec.rs`, introduced by bflatastic in `bdbb52c9b66b221a55b370105b42f485a76e6fc7`. The LZ4 backend is MIT-licensed `lz4_flex`.
|
||||
|
||||
@@ -0,0 +1,127 @@
|
||||
//! USD Crate integer delta decoding, adapted from TextureCraft's bflatastic implementation.
|
||||
|
||||
/// Wire width of each integer and its common delta.
|
||||
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
|
||||
pub enum Width {
|
||||
/// Signed 32-bit wrapping arithmetic, sign-extended to i64 on output.
|
||||
I32,
|
||||
/// Signed 64-bit wrapping arithmetic.
|
||||
I64,
|
||||
}
|
||||
impl Width {
|
||||
fn bytes(self) -> usize {
|
||||
match self {
|
||||
Self::I32 => 4,
|
||||
Self::I64 => 8,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Invalid packed data or a caller output-budget/allocation failure.
|
||||
#[derive(Debug, thiserror::Error)]
|
||||
pub enum Error {
|
||||
/// The declared count exceeds the caller's byte budget or addressable output.
|
||||
#[error("USD integer array exceeds output budget")]
|
||||
Limit,
|
||||
/// A common delta, code table or selected delta is incomplete.
|
||||
#[error("truncated USD integer array")]
|
||||
Truncated,
|
||||
/// The bounded output reservation failed.
|
||||
#[error("cannot allocate USD integer array")]
|
||||
Allocation,
|
||||
}
|
||||
|
||||
fn signed(bytes: &[u8], at: usize, width: usize) -> Option<i64> {
|
||||
let part = bytes.get(at..at.checked_add(width)?)?;
|
||||
Some(match width {
|
||||
1 => i64::from(i8::from_le_bytes(part.try_into().ok()?)),
|
||||
2 => i64::from(i16::from_le_bytes(part.try_into().ok()?)),
|
||||
4 => i64::from(i32::from_le_bytes(part.try_into().ok()?)),
|
||||
8 => i64::from_le_bytes(part.try_into().ok()?),
|
||||
_ => return None,
|
||||
})
|
||||
}
|
||||
|
||||
/// Decode `count` values, charging eight output bytes per value against `max_output_bytes`.
|
||||
///
|
||||
/// The common delta is followed by a packed two-bit code per value and variable-width
|
||||
/// exceptional deltas. Arithmetic wraps at the specified wire width. Extra bytes after the
|
||||
/// values are ignored, matching the original reader. Counts, the code table and the output
|
||||
/// byte budget are checked before a fallible reservation. A zero count returns an empty vector.
|
||||
pub fn decode(data: &[u8], count: usize, width: Width, max_output_bytes: usize) -> Result<Vec<i64>, Error> {
|
||||
let output_bytes = count.checked_mul(8).filter(|n| *n <= max_output_bytes && *n <= isize::MAX as usize).ok_or(Error::Limit)?;
|
||||
if output_bytes == 0 {
|
||||
return Ok(Vec::new());
|
||||
}
|
||||
let size = width.bytes();
|
||||
let common = signed(data, 0, size).ok_or(Error::Truncated)?;
|
||||
let code_bytes = count.div_ceil(4);
|
||||
let mut at = size.checked_add(code_bytes).ok_or(Error::Truncated)?;
|
||||
let codes = data.get(size..at).ok_or(Error::Truncated)?;
|
||||
let mut output = Vec::new();
|
||||
output.try_reserve_exact(count).map_err(|_| Error::Allocation)?;
|
||||
let mut previous = 0i64;
|
||||
for i in 0..count {
|
||||
let code = (codes.get(i / 4).copied().ok_or(Error::Truncated)? >> (2 * (i % 4))) & 3;
|
||||
let delta = if code == 0 {
|
||||
common
|
||||
} else {
|
||||
let bytes = (size >> (3 - usize::from(code))).max(1);
|
||||
let value = signed(data, at, bytes).ok_or(Error::Truncated)?;
|
||||
at = at.checked_add(bytes).ok_or(Error::Truncated)?;
|
||||
value
|
||||
};
|
||||
previous = match width {
|
||||
Width::I32 => i64::from((previous as i32).wrapping_add(delta as i32)),
|
||||
Width::I64 => previous.wrapping_add(delta),
|
||||
};
|
||||
output.push(previous);
|
||||
}
|
||||
Ok(output)
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
#[allow(clippy::unwrap_used)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn common_deltas_and_output_budget() {
|
||||
let mut data = 1i32.to_le_bytes().to_vec();
|
||||
data.push(0);
|
||||
assert_eq!(decode(&data, 4, Width::I32, 32).unwrap(), [1, 2, 3, 4]);
|
||||
assert!(matches!(decode(&data, 4, Width::I32, 31), Err(Error::Limit)));
|
||||
assert!(matches!(decode(&data[..4], 4, Width::I32, 32), Err(Error::Truncated)));
|
||||
assert!(matches!(decode(&[], usize::MAX, Width::I64, usize::MAX), Err(Error::Limit)));
|
||||
assert!(decode(&[], 0, Width::I64, 0).unwrap().is_empty());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn narrow_exception_codes_sign_extend() {
|
||||
for (width, size) in [(Width::I32, 4), (Width::I64, 8)] {
|
||||
let mut data = vec![0; size];
|
||||
data.push(1 | (2 << 2));
|
||||
let first_size = (size >> 2).max(1);
|
||||
let second_size = size >> 1;
|
||||
data.extend_from_slice(&(-3i64).to_le_bytes()[..first_size]);
|
||||
data.extend_from_slice(&7i64.to_le_bytes()[..second_size]);
|
||||
assert_eq!(decode(&data, 2, width, 16).unwrap(), [-3, 4]);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn exceptional_deltas_and_wrapping() {
|
||||
for (width, size) in [(Width::I32, 4), (Width::I64, 8)] {
|
||||
// Full-width positive maximum, followed by common +1, wraps to signed minimum.
|
||||
let mut data = 1i64.to_le_bytes()[..size].to_vec();
|
||||
data.push(3);
|
||||
let maximum = if width == Width::I32 { i64::from(i32::MAX) } else { i64::MAX };
|
||||
data.extend_from_slice(&maximum.to_le_bytes()[..size]);
|
||||
let minimum = if width == Width::I32 { i64::from(i32::MIN) } else { i64::MIN };
|
||||
assert_eq!(decode(&data, 2, width, 16).unwrap(), [maximum, minimum]);
|
||||
assert!(decode(&data[..data.len() - 1], 2, width, 16).is_err());
|
||||
data.extend(b"ignored tail");
|
||||
assert_eq!(decode(&data, 2, width, 16).unwrap(), [maximum, minimum]);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -5,6 +5,9 @@
|
||||
#![forbid(unsafe_code)]
|
||||
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
|
||||
|
||||
/// Bounded Crate integer delta arrays.
|
||||
pub mod integers;
|
||||
|
||||
/// Failure to read a bounded Crate LZ4 frame.
|
||||
#[derive(Debug, thiserror::Error)]
|
||||
pub enum Error {
|
||||
|
||||
Reference in New Issue
Block a user