unityrs_texture/crunch/mod.rs
1// Ported from Crunch legacy decoder in texture2ddecoder 1.0.5 (LicenseRef-Crunch): legacy CRN unpacking. See THIRD_PARTY_LICENSES.
2// src/Texture2DDecoder/crunch/crn_decomp.h. Altered source: safe Rust port.
3// Crunch Library Copyright (c) 2010-2016 Richard Geldreich, Jr.
4// See LICENSE-CRUNCH and THIRD_PARTY_LICENSES.
5//! Legacy CRN unpacking, followed by the existing Pillow BC1/BC3 decoder.
6//!
7//! The sdist's `src/pylink.cpp:134-155` always requests level zero;
8//! `src/Texture2DDecoder/crunch.cpp:6-40` supplies a single face pointer.
9//! Cubemaps would overrun that pointer array and are refused here.
10//! Checksums are deliberately ignored, as in that wrapper's calls to
11//! `crnd_get_texture_info` and `crnd_unpack_begin`, rather than
12//! `crnd_validate_file` (crn_decomp.h:2702-2771, crn_decomp.h:3667-3688).
13//! All offsets, counts, code lengths and reads are checked before use.
14//! Nonempty bit regions zero-extend on exhaustion, matching the reference.
15//! Header ranges still have to name bytes in the supplied buffer.
16//!
17//! This legacy decoder contains static Huffman models only
18//! (crn_decomp.h:1981-2042, crn_decomp.h:3085-3161). The changing state is
19//! the chunk encoding reservoir and previous palette indices, not an
20//! adaptive Huffman tree. Unity's fork is implemented in `unity`, sharing the bit reader and models.
21
22mod blocks;
23mod header;
24mod palettes;
25mod symbol;
26pub(crate) mod unity;
27
28/// Why legacy crunch could not be unpacked. No error owns input-sized heap.
29#[derive(Debug, PartialEq, Eq, thiserror::Error)]
30#[non_exhaustive]
31pub enum CrunchError {
32 /// A malformed header, range, dimension or palette descriptor.
33 #[error("invalid crunch header: {0}")]
34 Header(&'static str),
35 /// A bitstream region is empty (reference `start_decoding` refuses it).
36 #[error("truncated crunch bitstream")]
37 Truncated,
38 /// Invalid Huffman model, run or canonical code.
39 #[error("invalid crunch Huffman code")]
40 Huffman,
41 /// A decoded palette index or selector delta is out of range.
42 #[error("invalid crunch palette index")]
43 Palette,
44 /// A block reference reads row storage the reference never initialized.
45 #[error("uninitialized crunch block reference")]
46 Reference,
47 /// The reference `Texture2D` wrapper provides only one destination face.
48 #[error("crunch Texture2D requires one face, got {0}")]
49 Faces(u8),
50 /// Segmented CRN needs an external level source the wrapper cannot supply.
51 #[error("segmented crunch is unsupported")]
52 Segmented,
53 /// Allocation or meter refusal, with every live buffer released on return.
54 #[error(transparent)]
55 Charge(#[from] unityrs_core::limits::ChargeError),
56}
57const _: () = crate::send_sync::<CrunchError>();
58
59type Result<T> = std::result::Result<T, CrunchError>;
60
61use std::sync::Arc;
62use unityrs_core::limits::{Meter, MeteredVec, heap_cost};
63
64/// A length-only plan cannot read counts: bound every palette by the
65/// header's 16-bit count, every model by its 14-bit alphabet, and
66/// include the temporary code-length model/array while palettes decode.
67/// Actual allocations use the checked header counts, never this maximum.
68/// Eight sorted-symbol arrays cover five persistent models, two palette
69/// models, and the nested code-length model; one temporary length array.
70pub(crate) fn scratch(block_bytes: u64) -> u64 {
71 heap_cost(block_bytes)
72 + heap_cost(65535 * 4) * 2
73 + heap_cost(65535 * 2)
74 + heap_cost(65535 * 8)
75 + heap_cost(16383 * 2) * 8
76 + heap_cost(16383)
77}
78
79/// Precharge traversal of every block in the even-rounded block grid and
80/// an upper bound on its u32 symbols, including hidden edge blocks. Both
81/// traversals round block extents to even dimensions. One reference symbol
82/// per block is conservative;
83/// endpoint and selector counts are bounded independently of their codes.
84/// Output pixel work belongs to the caller and is not charged here.
85fn block_work(size: (usize, usize), symbols: u64, meter: &Arc<Meter>) -> Result<()> {
86 let width = (size.0 as u64).div_ceil(4).div_ceil(2) * 2;
87 let height = (size.1 as u64).div_ceil(4).div_ceil(2) * 2;
88 meter.count_decode(width * height * (1 + symbols * 4))?;
89 Ok(())
90}
91
92/// Palette symbols are u32 values. Both reference decoders skip both alpha
93/// palettes when the alpha-endpoint count is zero, regardless of selectors.
94fn palette_work(header: &header::Header, symbols: [u64; 4], meter: &Arc<Meter>) -> Result<()> {
95 meter.count_decode(
96 header
97 .palettes
98 .iter()
99 .zip(symbols)
100 .enumerate()
101 .filter(|(i, _)| *i < 2 || header.palettes[2].count != 0)
102 .map(|(_, (region, symbols))| region.count as u64 * symbols * 4)
103 .sum(),
104 )?;
105 Ok(())
106}
107
108/// Unpack the requested mip. Public `Texture2D` decoding always calls this
109/// with zero (texture2ddecoder 1.0.5 sdist src/pylink.cpp:134-155).
110pub(crate) fn unpack(
111 data: &[u8],
112 dxt5: bool,
113 size: (usize, usize),
114 level: usize,
115 meter: &Arc<Meter>,
116) -> Result<MeteredVec<u8>> {
117 const ZEROS: [u8; 4096] = [0; 4096];
118 let (header, source, width, height) = prepare(data, dxt5, size, level)?;
119 let len = width
120 .div_ceil(4)
121 .checked_mul(height.div_ceil(4))
122 .and_then(|n| n.checked_mul(if dxt5 { 16 } else { 8 }))
123 .ok_or(CrunchError::Header("block buffer overflow"))?;
124 // Palette symbol decodes are independent of image dimensions and may
125 // greatly exceed the output work (6/8/2/8 symbols per entry). Count
126 // their u32 bytes before setup; model alphabet work is charged by Model itself.
127 block_work((width, height), if dxt5 { 5 } else { 3 }, meter)?;
128 palette_work(&header, [6, 8, 2, 8], meter)?;
129 let models = blocks::Models::new(&header, data, meter)?;
130 let palettes = palettes::Palettes::new(&header, data, meter)?;
131 let mut out = MeteredVec::with_capacity(meter, len)?;
132 while out.len() < len {
133 let n = (len - out.len()).min(ZEROS.len());
134 out.extend_from_slice(
135 ZEROS
136 .get(..n)
137 .ok_or(CrunchError::Header("block fill size"))?,
138 )?;
139 }
140 blocks::unpack(
141 source,
142 dxt5,
143 width,
144 height,
145 &models,
146 &palettes,
147 out.as_mut_slice(),
148 )?;
149 Ok(out)
150}
151
152/// Validate the header and requested level before either image buffer is
153/// allocated. There is no dimension-dependent compressed-size minimum:
154/// for N chunks with ordinary 0..511 layout symbols the *consumed* bits
155/// are at least ceil(N/3) + 5N (DXT1)
156/// or ceil(N/3) + 10N (DXT5): one-bit chunk codes for groups of three,
157/// one endpoint and four selectors per channel, including edge blocks
158/// (crn_decomp.h:4196-4303, crn_decomp.h:4397-4470). But the reader can
159/// supply arbitrarily many of those bits as zeros. A single byte with
160/// singleton models decodes even a 16384-square image identically to the
161/// reference. Only an empty region is refused, by `start_decoding`
162/// (crn_decomp.h:3166-3180). Caller meters bound this inherent expansion.
163pub(crate) fn validate(data: &[u8], dxt5: bool, size: (usize, usize)) -> Result<()> {
164 prepare(data, dxt5, size, 0).map(|_| ())
165}
166
167fn prepare(
168 data: &[u8],
169 dxt5: bool,
170 size: (usize, usize),
171 level: usize,
172) -> Result<(header::Header, &[u8], usize, usize)> {
173 let header = header::Header::parse(data)?;
174 let (source, width, height) = header.level(data, level)?;
175 if header.dxt5 != dxt5 {
176 return Err(CrunchError::Header("Texture2D/CRN format mismatch"));
177 }
178 // The wrapper sizes its buffer from the CRN header while Pillow reads
179 // it using Texture2D dimensions. Require the same block extent so the
180 // length-only plan bounds this second buffer. Sub-block differences
181 // still decode/crop exactly as Pillow does. See PARITY.md section 19.3.
182 if (width.div_ceil(4), height.div_ceil(4)) != (size.0.div_ceil(4), size.1.div_ceil(4)) {
183 return Err(CrunchError::Header("Texture2D/CRN block extent mismatch"));
184 }
185 if source.is_empty() {
186 return Err(CrunchError::Truncated);
187 }
188 Ok((header, source, width, height))
189}
190
191#[cfg(test)]
192mod tests;