Skip to main content

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;