Skip to main content

unityrs_texture/
decode.rs

1// Ported from UnityPy 1.25.2 (MIT): UnityPy/export/Texture2DConverter.py's parse_image_data for the formats decoded here (the checks, the block padding, the crop and the flip) and its astc's data check, and how Pillow 9.5.0, texture2ddecoder 1.0.5 and astc-encoder-py 0.1.12, as it calls them, treat short and long data and the sizes they refuse. See THIRD_PARTY_LICENSES.
2// Ported from Pillow 9.5.0 (MIT-CMU): its raw decoder as UnityPy calls it (src/libImaging/RawDecode.c's row copy, and the width cap of src/decode.c's _setimage), and the decompression-bomb check of src/PIL/Image.py's crop, with its message. See THIRD_PARTY_LICENSES.
3//! [`decode()`]: a texture's mip 0 to pixels, as `parse_image_data` gives them
4//! for the formats of [`Format`] (`export/Texture2DConverter.py:254-320`), and
5//! [`plan()`]: what a decode of data of a given length will need and give,
6//! or why it fails, before the data is read.
7//!
8//! **What UnityPy does.** `parse_image_data` returns an empty image for a
9//! side of 0, raises for empty data, pads a block format's size to whole
10//! 4x4 blocks (`:291`, `get_compressed_image_size`; the raw formats are not
11//! padded; an ASTC format to whole blocks of its footprint, `:36-50`), has
12//! Pillow decode the padded image (`Image.frombytes` with
13//! `CONV_TABLE`'s arguments, `:331-344`, `:488-566`), or for an ETC or EAC
14//! format texture2ddecoder, whose `BGRA` output Pillow's raw decoder then
15//! reads (`:405-432`, `:523-532`), or for an ASTC format astcenc (the
16//! `astc` module), whose `RGBA` output it reads (`:356-366`, `:533-544`),
17//! crops it back to size
18//! (`:314-315`) and flips it top to bottom (`:317-318`). Pillow decodes the
19//! data from its start and stops when the image is full: bytes past it
20//! (later mips, anything else) are ignored, so a texture with mips decodes
21//! as its mip 0.
22//!
23//! **Closed-form raw formats.** `tierb` follows PARITY.md sections 17.1,
24//! 19.1 and 19.2, independently of UnityPy. After the zero-side check, a
25//! nonempty `ARGBFloat` or odd-width YUY2 layout is `DecodeError::Unsupported`,
26//! before the data check. These formats validate the full stored length,
27//! use no Pillow width cap and allocate only the metered RGB(A) output.
28//!
29//! **The order.** [`plan()`] and [`decode()`] make one series of checks,
30//! the first that fails naming the error. For ordinary formats a plan's
31//! answer is the decode's; crunch also validates content during unpacking:
32//! 1. A side of 0 gives an empty `RGBA` image, 0x0, before the data, the
33//!    format or the other side is looked at (`:265-266`).
34//! 2. Empty data is [`DecodeError::NoImageData`], UnityPy's
35//!    `ValueError("Texture2D has no image data")` (`:268-269`).
36//! 3. A negative side is [`DecodeError::NegativeSize`]: Pillow's
37//!    `ValueError`, whichever of its checks meets it first ("Width and
38//!    height must be >= 0", or, where padding made a side 0, a crop or tile
39//!    error). For an ETC or EAC format, where padding made a side 0
40//!    texture2ddecoder decodes nothing and the crop raises, but a side
41//!    padded below 0 (-4 and below) reaches it as a width or height near
42//!    2^32, which it multiplies in 32 bits and then reads and writes past
43//!    its buffers with: the error is unityrs's own refusal there
44//!    (`PARITY.md` section 19.3). So for an ASTC format: where padding made a
45//!    side 0 the crop raises, and a side padded below 0 reaches
46//!    astc-encoder-py as a negative size, which it refuses with `ASTCError`
47//!    when one side is, and with both reads and writes past astcenc's
48//!    buffers once the data holds the blocks the two negative counts'
49//!    product names.
50//! 4. A texture of more than [`MAX_PIXELS`] pixels at its padded size is
51//!    [`DecodeError::TooLarge`], whatever the data's length once it is not
52//!    empty: the bound UnityPy does not have (below).
53//! 5. A raw texture wider than `INT_MAX / bits - 7` pixels is
54//!    [`DecodeError::PillowMemoryError`]: Pillow's raw decoder refuses such
55//!    a row with `MemoryError` when it is set up, before it reads any data
56//!    (`_setimage`, `src/decode.c:197-198`), `bits` being its raw mode's
57//!    unpacker's (`Format::raw_bits`): 268,435,448 pixels for Alpha8 and R8
58//!    (8 bits), 134,217,720 for ARGB4444, RGBA4444 and RGB565 (16),
59//!    89,478,478 for RGB24 and BGR24 (24), 67,108,856 for RGBA32, BGRA32
60//!    and ARGB32 (32).
61//!    So is an ETC, EAC or ASTC texture whose padded width passes
62//!    67,108,856 (67,108,857 and up, padded to 67,108,860 at 4x4): Pillow's
63//!    raw decoder reads texture2ddecoder's output as `BGRA`, or astcenc's
64//!    as `RGBA`, at that width, and refuses it after the decode, which
65//!    changes no pixel. The `bcn` decoder has no such cap. For an ASTC
66//!    format step 6 comes first: `astc` checks the data's length before
67//!    astcenc decodes and Pillow reads (`:356-366`).
68//! 6. Data that runs out before mip 0 does is [`DecodeError::NotEnoughData`],
69//!    Pillow's `ValueError` "not enough image data" (`Image.frombytes`;
70//!    `RawDecode.c` reads whole rows, of `bits / 8` bytes a pixel,
71//!    `BcnDecode.c` whole blocks). The `BCn`
72//!    decoder takes the data's length as a C `int` (`decode_bcn`'s
73//!    `bytes`), so data of 2 GiB or more is read as that length's low 32
74//!    bits, signed: data whose low 32 bits are below what the image needs,
75//!    or negative, is short too ([`bcn_length`]). texture2ddecoder checks
76//!    no length, and reads on past the data's end where it is short (its
77//!    `decode` template, `src/pylink.cpp`, ignores the length it parses):
78//!    for an ETC or EAC format the error is unityrs's own refusal, which
79//!    reads nothing that is not there (`PARITY.md` section 19.3). For an
80//!    ASTC format it is `astc`'s
81//!    `ValueError("Invalid ASTC data size: {len} < {size}")`, mip 0's blocks
82//!    at 16 bytes each (`calculate_astc_compressed_size`, `:390-397`).
83//! 7. The decode.
84//! 8. A block-format texture (DXT1, DXT3, DXT5, BC4, BC5, BC7, ETC, EAC or
85//!    ASTC) with a side that
86//!    is no multiple of its block's and
87//!    more than [`MAX_CROP_PIXELS`] (178,956,970) pixels is
88//!    [`DecodeError::DecompressionBomb`]: UnityPy's crop of the padded image
89//!    runs Pillow's decompression-bomb check on the size it crops to, which
90//!    raises `DecompressionBombError` past twice `Image.MAX_IMAGE_PIXELS`
91//!    (`Image._crop`, `src/PIL/Image.py:1232-1250`; `:3162-3180`), after the
92//!    decode. No pixel depends on it, so it is decided before the decode,
93//!    after the data check, as in Pillow. An aligned texture is not cropped,
94//!    nor is a raw one, and neither is checked. Past `MAX_IMAGE_PIXELS`
95//!    alone the crop only warns, which changes no pixel.
96//!
97//! The decoders write straight into the output, cropped and flipped as they
98//! go, with no padded image between: each block is decoded into a 16-pixel
99//! array on the stack (an ASTC block into one of up to 144 pixels), and only
100//! the pixels inside the texture are copied,
101//! each to its flipped row. That is the padded decode, then the crop and
102//! the flip, pixel for pixel.
103//!
104//! **The bound, where UnityPy has none.** [`MAX_PIXELS`] is 16384 x 16384
105//! at the padded size, the largest size Unity's texture importer offers,
106//! checked before the data's length (step 4), so the output is at most
107//! 1 GiB, pixel work is linear in it, and [`plan()`] needs only the data's
108//! length. It is
109//! the stated divergence (`PARITY.md` section 19.3), and every limit Pillow
110//! has that a texture could meet beyond steps 5 and 8 lies past it:
111//! `Image.new`'s `MemoryError` for a row wider than 536,870,910 pixels, the
112//! `OverflowError` of a `BCn` side padded to 2^31, and the raw decoder's
113//! count of the bytes it read, which wraps through an `int` at 2 GiB
114//! (Pillow then returns the image with its unread rows zero). A texture
115//! with a negative side and data is [`DecodeError::NegativeSize`] whatever
116//! its other side, where Pillow, given a padded side past those limits,
117//! raises theirs. With step 5 in, no width that passes overflows the `int`
118//! Pillow's raw decoder computes a row's bytes in
119//! (`src/libImaging/RawDecode.c:31`, `state->xsize * state->bits + 7`): a
120//! width of at most `INT_MAX / bits - 7` makes it at most
121//! `INT_MAX - 7 * bits + 7`. Sizes are computed here in `u64`, from the
122//! `i32` sides, so none wraps.
123//!
124//! **Crunch.** [`Format::Dxt1Crunched`] and [`Format::Dxt5Crunched`] select
125//! legacy input. Call [`crate::select_in`] or [`crate::select_crunch`] with
126//! the Unity version: Unity 2017.3+ selects `UnityDxt1Crunched` or
127//! `UnityDxt5Crunched`; crunched ETC always selects the Unity fork.
128//! Unpacking chooses mip zero, then the existing BC1/BC3 or ETC path crops
129//! and flips its blocks. The
130//! `crunch` module checks header ranges and models; failures are typed
131//! [`DecodeError::Crunch`], even after a length-only plan succeeds. The
132//! native builder fixture checks blocks at every mip; the optional pinned
133//! UnityPy fixture must be recorded before claiming pixel parity.
134//!
135//! **Memory** (`docs/plans/extract.md` E59). Except for crunch, the output is the only buffer a
136//! decode allocates in proportion to the texture. PVRTC uses a fixed
137//! nine-block neighborhood on the stack (about 1.5 KiB); ATC uses one
138//! 16-pixel block and allocates no scratch. An ASTC format's decode also
139//! builds its footprint's
140//! tables (the `astc` module, at most about 0.55 MB, at 12x12, whatever the
141//! texture's size), charged to the same meter after the output and dropped
142//! before the decode returns: [`Plan::scratch`]. The output is charged to the caller's [`Meter`] at
143//! [`heap_cost`] of its length before it is allocated (through
144//! [`MeteredVec`], whose refusal allocates nothing and whose allocation
145//! failure is a refusal too), once every check above has passed, and the
146//! [`Charge`] lives in the [`Image`], declared after its pixels, so it is
147//! returned after their buffer is freed, on every path, a panic's unwinding
148//! included. Only the pixel loop runs under [`crate::contain()`]. The
149//! engine calls [`plan()`] first: an `Ok` is a decode that will charge
150//! [`Plan::charge`], at most [`Plan::peak_charge`] while it runs, and write
151//! [`Plan::output_bytes`] (export work,
152//! `docs/plans/batch.md` 2.6 step 10); an `Err` is the decode's error, which
153//! charges nothing. For crunch an `Ok` plan only validates sizes and the
154//! minimum header length: content errors can follow. `Plan::scratch` also
155//! bounds a second buffer (8/16 bytes per block), palettes and Huffman tables.
156//! Actual scratch allocations are fallible `MeteredVec`s sized from checked
157//! header counts, released before returning the image. Palette and model setup
158//! also charges the meter's decode-work allowance before its loops. A plan's maximum uses
159//! the header's 16-bit palette counts and the codec's 8192-symbol limit.
160
161use std::fmt;
162use std::panic::AssertUnwindSafe;
163use std::sync::Arc;
164
165use unityrs_core::limits::{Charge, ChargeError, Meter, MeteredVec, heap_cost};
166
167use crate::contain::Payload;
168use crate::format::{Format, Library, Mode};
169use crate::{astc, atc, bcn, crunch, etc, pvrtc, raw};
170
171/// The most pixels a texture may have, at its padded size: 16384 x 16384.
172/// UnityPy has no such bound (module docs; `PARITY.md` section 19.3).
173pub const MAX_PIXELS: u64 = 1 << 28;
174
175/// The most pixels UnityPy's crop of a padded block-format image takes: twice
176/// Pillow 9.5.0's `Image.MAX_IMAGE_PIXELS`, `1024 * 1024 * 1024 // 4 // 3`
177/// (module docs, step 8).
178pub const MAX_CROP_PIXELS: u64 = 2 * 89_478_485;
179
180/// C's `INT_MAX`, the bound of Pillow's `int` sizes.
181const INT_MAX: u32 = 0x7FFF_FFFF;
182
183/// Why a texture did not decode, in the order of the module docs' checks.
184/// Every variant but [`Self::TooLarge`], [`Self::Charge`] and
185/// [`Self::Panicked`] is a case where UnityPy 1.25.2 raises too, but
186/// for an ETC or EAC format with short data or a side padded below 0,
187/// where texture2ddecoder reads past the data (module docs, steps 3 and
188/// 6). [`plan()`]
189/// returns the checks' variants only, never `Charge` or `Panicked`, which
190/// [`decode()`] alone gives, after a plan that passed.
191///
192/// Not `Clone`, by design, unlike the core's errors: `Panicked` owns the
193/// panic's payload, the box the unwinding carried ([`Payload`]), which
194/// cannot be cloned, and a copy of its text would allocate on the panic
195/// path.
196#[derive(Debug, PartialEq, Eq, thiserror::Error)]
197#[non_exhaustive]
198pub enum DecodeError {
199    /// Reserved or illegal content in a specification-defined HDR block.
200    #[error(transparent)]
201    Hdr(#[from] crate::HdrError),
202    /// An unsupported platform layout or a size that cannot be represented.
203    #[error(transparent)]
204    Platform(#[from] crate::PlatformError),
205    /// A Tier U layout: `ARGBFloat`, or YUY2 with an odd width.
206    #[error("unsupported texture layout: {format:?} at width {width}")]
207    Unsupported {
208        /// The refused format.
209        format: Format,
210        /// The stored width.
211        width: i32,
212    },
213    /// A malformed legacy or Unity CRN stream or unsupported CRN feature.
214    #[error(transparent)]
215    Crunch(crunch::CrunchError),
216    /// The data is empty: UnityPy's `ValueError("Texture2D has no
217    /// image data")`.
218    #[error("the texture has no image data")]
219    NoImageData,
220    /// A side is negative (and neither is 0): Pillow's `ValueError`.
221    #[error("the texture's size {width}x{height} has a negative side")]
222    NegativeSize {
223        /// `m_Width`.
224        width: i32,
225        /// `m_Height`.
226        height: i32,
227    },
228    /// The texture passes [`MAX_PIXELS`] at its padded size, a bound
229    /// UnityPy does not have.
230    #[error("the texture's {pixels} pixels pass the decoders' bound of {max}")]
231    TooLarge {
232        /// Its pixels, padded to whole blocks.
233        pixels: u64,
234        /// [`MAX_PIXELS`].
235        max: u64,
236    },
237    /// A raw texture's row, or an ETC, EAC or ASTC texture's padded row,
238    /// wider than Pillow's raw decoder takes: Pillow's `MemoryError`
239    /// (module docs, step 5).
240    #[error("Pillow's raw decoder refuses a row of {width} pixels, past {max} (MemoryError)")]
241    PillowMemoryError {
242        /// The row's width as Pillow's raw decoder gets it: `m_Width`,
243        /// padded to whole blocks for an ETC, EAC or ASTC format.
244        width: u32,
245        /// The widest row it takes: `INT_MAX / bits - 7`.
246        max: u32,
247    },
248    /// The data ends before mip 0 does: Pillow's `ValueError` "not enough
249    /// image data", for an ASTC format UnityPy's `ValueError` "Invalid ASTC
250    /// data size", or for an ETC or EAC format, where texture2ddecoder
251    /// reads on past the data's end, unityrs's own refusal (module docs,
252    /// step 6).
253    #[error("not enough image data: {needed} bytes needed, {got} given")]
254    NotEnoughData {
255        /// What mip 0 holds, at its padded size.
256        needed: u64,
257        /// The data's length.
258        got: u64,
259    },
260    /// UnityPy's crop of a padded `BCn` image meets Pillow's
261    /// decompression-bomb check: its `DecompressionBombError`, whose message
262    /// this one is (module docs, step 8).
263    #[error(
264        "Image size ({pixels} pixels) exceeds limit of {max} pixels, could be decompression bomb DOS attack."
265    )]
266    DecompressionBomb {
267        /// `m_Width` x `m_Height`.
268        pixels: u64,
269        /// [`MAX_CROP_PIXELS`].
270        max: u64,
271    },
272    /// texture2ddecoder refuses a PVRTC grid with non-power-of-two block counts.
273    #[error("PVRTC block counts must be powers of two")]
274    PvrtcBlockCount,
275    /// The meter or its budget refused the output buffer, or the allocator
276    /// did; nothing was allocated.
277    #[error(transparent)]
278    Charge(#[from] ChargeError),
279    /// The decoder panicked ([`crate::contain()`]): its payload, kept whole.
280    #[error("the decoder panicked: {payload}")]
281    Panicked {
282        /// The payload; [`Payload::message`] is the manifest's detail.
283        payload: Payload,
284    },
285}
286
287const _: () = crate::send_sync::<DecodeError>();
288
289impl From<crunch::CrunchError> for DecodeError {
290    fn from(error: crunch::CrunchError) -> Self {
291        match error {
292            crunch::CrunchError::Charge(charge) => Self::Charge(charge),
293            other => Self::Crunch(other),
294        }
295    }
296}
297
298/// What decoding a texture of a format and a size, from data of a given
299/// length, will need and give, worked out before the data is read
300/// ([`plan()`]).
301#[derive(Clone, Copy, Debug, PartialEq, Eq)]
302pub struct Plan {
303    /// The image's mode: the format's, or `RGBA` for a side of 0.
304    pub mode: Mode,
305    /// The image's width: the texture's, or 0 for a side of 0.
306    pub width: u32,
307    /// The image's height: the texture's, or 0 for a side of 0.
308    pub height: u32,
309    /// The bytes of data mip 0 takes, at its padded size; 0 for a side of
310    /// 0. For crunch, the minimum CRN header size (74), not its variable
311    /// compressed length.
312    pub input_bytes: u64,
313    /// The image's bytes: width x height x the mode's bytes per pixel.
314    pub output_bytes: u64,
315    /// What the decode charges beside the output while it runs, and returns
316    /// before it ends: an ASTC format's tables, or a conservative bound for
317    /// crunch blocks, palettes and Huffman tables; 0 for the rest.
318    pub scratch: u64,
319}
320
321const _: () = crate::send_sync::<Plan>();
322
323impl Plan {
324    /// What [`decode()`] charges the meter for the output: [`heap_cost`] of
325    /// [`Self::output_bytes`] (0 for the empty image). The allocator may
326    /// round the allocation up past it, in which case [`MeteredVec`]
327    /// charges the difference too.
328    #[must_use]
329    pub const fn charge(&self) -> u64 {
330        heap_cost(self.output_bytes)
331    }
332
333    /// The most [`decode()`] has charged at once: [`Self::charge`] and
334    /// [`Self::scratch`].
335    #[must_use]
336    pub const fn peak_charge(&self) -> u64 {
337        self.charge().saturating_add(self.scratch)
338    }
339}
340
341/// What decoding `format` at `width` x `height` from `data_len` bytes of
342/// data needs and gives, or the error [`decode()`] returns for it: the
343/// module docs' size/length checks in their order. For crunch, success
344/// only establishes a memory bound: header or bitstream validation may
345/// subsequently return [`DecodeError::Crunch`]. HDR block content can
346/// likewise return [`DecodeError::Hdr`] after planning succeeds.
347pub fn plan(format: Format, data_len: usize, width: i32, height: i32) -> Result<Plan, DecodeError> {
348    if width == 0 || height == 0 {
349        return Ok(Plan {
350            mode: Mode::Rgba,
351            width: 0,
352            height: 0,
353            input_bytes: 0,
354            output_bytes: 0,
355            scratch: 0,
356        });
357    }
358    if format == Format::ArgbFloat || (format == Format::Yuy2 && width % 2 != 0) {
359        return Err(DecodeError::Unsupported { format, width });
360    }
361    if data_len == 0 {
362        return Err(DecodeError::NoImageData);
363    }
364    let (Ok(w), Ok(h)) = (u32::try_from(width), u32::try_from(height)) else {
365        return Err(DecodeError::NegativeSize { width, height });
366    };
367    let (w64, h64) = (u64::from(w), u64::from(h));
368    let block = format.block_bytes();
369    let (padded_w, padded_h) = match format.block_size() {
370        Some((bw, bh)) => {
371            let (bw, bh) = (u64::from(bw), u64::from(bh));
372            (w64.div_ceil(bw) * bw, h64.div_ceil(bh) * bh)
373        }
374        None => (w64, h64),
375    };
376    // Each side is at most 2^31 + 11, so the product fits a u64.
377    let pixels = padded_w * padded_h;
378    if pixels > MAX_PIXELS {
379        return Err(DecodeError::TooLarge {
380            pixels,
381            max: MAX_PIXELS,
382        });
383    }
384    if let Some(is2) = format.pvrtc_2bpp() {
385        let bx = padded_w / if is2 { 8 } else { 4 };
386        let by = padded_h / 4;
387        if !bx.is_power_of_two() || !by.is_power_of_two() {
388            return Err(DecodeError::PvrtcBlockCount);
389        }
390    }
391    let mode = format.mode();
392    let library = format.library();
393    // Output is at most 4 x MAX_PIXELS; raw stored input at most 16 x MAX_PIXELS.
394    let len = u64::try_from(data_len).unwrap_or(u64::MAX);
395    let unpacked_bytes = block.map_or(0, |b| padded_w / 4 * (padded_h / 4) * b);
396    let (input_bytes, seen) = if format.is_crunched() {
397        // Fixed header/first offset plus a nonempty level region. The
398        // reference zero-extends it indefinitely, so consumed chunk bits
399        // cannot impose a larger length bound (crunch::validate).
400        (75, len)
401    } else {
402        match (block, format.block_size(), library) {
403            (Some(b), Some((bw, bh)), _) => {
404                let blocks = padded_w / u64::from(bw) * (padded_h / u64::from(bh));
405                let seen = if library == Library::PillowBcn {
406                    bcn_length(data_len)
407                } else {
408                    len
409                };
410                (blocks * b, seen)
411            }
412            // ATC is block storage without UnityPy padding or a crop.
413            (Some(b), None, _) => (w64.div_ceil(4) * h64.div_ceil(4) * b, len),
414            // Pillow's raw decoder reads whole rows of `bits` a pixel, each a
415            // whole number of bytes here.
416            _ => (pixels * raw_pixel_bytes(format), len),
417        }
418    };
419    let short = seen < input_bytes;
420    let not_enough = || DecodeError::NotEnoughData {
421        needed: input_bytes,
422        got: len,
423    };
424    // UnityPy checks an ASTC texture's data before astcenc decodes it and
425    // Pillow reads its output (`export/Texture2DConverter.py:356-366`); for
426    // the rest Pillow's width cap comes first (module docs, step 5).
427    if library == Library::Astcenc && short {
428        return Err(not_enough());
429    }
430    if let Some(bits) = format.raw_bits() {
431        // The width Pillow's raw decoder is set up with: the texture's, or
432        // for texture2ddecoder's and astcenc's output the padded one, at
433        // most 2^28 here.
434        let row = u32::try_from(padded_w).unwrap_or(u32::MAX);
435        let max = INT_MAX / bits - 7;
436        if row > max {
437            return Err(DecodeError::PillowMemoryError { width: row, max });
438        }
439    }
440    if short {
441        return Err(not_enough());
442    }
443    let shown = w64 * h64;
444    if (padded_w, padded_h) != (w64, h64) && shown > MAX_CROP_PIXELS {
445        return Err(DecodeError::DecompressionBomb {
446            pixels: shown,
447            max: MAX_CROP_PIXELS,
448        });
449    }
450    Ok(Plan {
451        mode,
452        width: w,
453        height: h,
454        input_bytes,
455        output_bytes: shown * mode.bytes_per_pixel(),
456        scratch: scratch_charge(format, unpacked_bytes, w64),
457    })
458}
459
460/// A decoded image: rows top to bottom, each pixel its mode's bytes, red
461/// first. It holds the [`Charge`] for its pixels, returned when it drops,
462/// after the pixels' buffer is freed.
463pub struct Image {
464    mode: Mode,
465    width: u32,
466    height: u32,
467    pixels: Vec<u8>,
468    // After `pixels`: fields drop in order, so the charge outlives the
469    // buffer it pays for.
470    charge: Charge,
471}
472
473const _: () = crate::send_sync::<Image>();
474
475impl fmt::Debug for Image {
476    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
477        f.debug_struct("Image")
478            .field("mode", &self.mode)
479            .field("width", &self.width)
480            .field("height", &self.height)
481            .field("bytes", &self.pixels.len())
482            .field("charge", &self.charge)
483            .finish()
484    }
485}
486
487impl Image {
488    /// An image of pixels already charged by `charge` (the sprite renderer's
489    /// canvases).
490    pub(crate) fn from_parts(
491        mode: Mode,
492        width: u32,
493        height: u32,
494        pixels: Vec<u8>,
495        charge: Charge,
496    ) -> Self {
497        Self {
498            mode,
499            width,
500            height,
501            pixels,
502            charge,
503        }
504    }
505
506    /// The mode.
507    #[must_use]
508    pub fn mode(&self) -> Mode {
509        self.mode
510    }
511
512    /// The width in pixels.
513    #[must_use]
514    pub fn width(&self) -> u32 {
515        self.width
516    }
517
518    /// The height in pixels.
519    #[must_use]
520    pub fn height(&self) -> u32 {
521        self.height
522    }
523
524    /// The pixels: what Pillow's `tobytes()` gives for the image UnityPy
525    /// returns. One exception: `tobytes()`, and so a PNG save, raises
526    /// `MemoryError` for an image wider than `INT_MAX / bits - 7` pixels,
527    /// `bits` its mode's (its raw encoder's cap, `src/encode.c:260-262`):
528    /// 67,108,856 for `RGBA`, 89,478,478 for `RGB`. The images that wide
529    /// that decode, in UnityPy as here, are a `BCn` texture's in `RGBA`:
530    /// 67,108,857 to 67,108,864 wide at a height of 1 or 2, and 67,108,860
531    /// or 67,108,864 wide at a height of 4 (a height of 3, or another width
532    /// at 4, is a [`DecodeError::DecompressionBomb`]); and a raw texture's
533    /// whose raw mode takes fewer bits a pixel than its image's mode, up to
534    /// that raw mode's cap (step 5): Alpha8's, ARGB4444's and RGBA4444's in
535    /// `RGBA`, R8's and RGB565's in `RGB`. A PNG writer mirrors that cap.
536    #[must_use]
537    pub fn pixels(&self) -> &[u8] {
538        &self.pixels
539    }
540
541    /// The charge the pixels hold.
542    #[must_use]
543    pub fn charge(&self) -> &Charge {
544        &self.charge
545    }
546
547    /// The pixels and their charge, which must live as long as the pixels'
548    /// allocation does: drop the charge last. Beware `let (pixels, charge) =
549    /// image.into_parts();`: a pattern's bindings drop in reverse order, so
550    /// that drops `charge` first, returning its bytes while the buffer still
551    /// holds them. Drop the pixels first (`drop(pixels)`), or keep the
552    /// charge in an owner that outlives them.
553    pub fn into_parts(self) -> (Vec<u8>, Charge) {
554        (self.pixels, self.charge)
555    }
556}
557
558/// Decodes a texture's mip 0, `data` being its image data from the start
559/// (`image_data`, or what its `m_StreamData` names: `Texture2D.get_image_data`),
560/// mips and all, as UnityPy 1.25.2 with Pillow 9.5.0 does (module docs),
561/// charging the output to `meter` before it is allocated. Its pixel loop
562/// runs under [`crate::contain()`], so a panic there is
563/// [`DecodeError::Panicked`], with the output's charge returned.
564pub fn decode(
565    format: Format,
566    data: &[u8],
567    width: i32,
568    height: i32,
569    meter: &Arc<Meter>,
570) -> Result<Image, DecodeError> {
571    decode_with(format, data, width, height, meter, fill, false)
572}
573
574/// Decode signed BC6H with the same bounds, metering, crop and flip as
575/// [`decode`]. Unity's `TextureFormat::BC6H` selects unsigned decoding;
576/// this entry point supports the specification's signed encoding.
577pub fn decode_bc6h_signed(
578    data: &[u8],
579    width: i32,
580    height: i32,
581    meter: &Arc<Meter>,
582) -> Result<Image, DecodeError> {
583    decode_with(Format::Bc6h, data, width, height, meter, fill, true)
584}
585
586/// The pixels the loop writes: `out` is `w` x `h` pixels of the format's
587/// mode, `data` holds at least mip 0 ([`plan()`]), and an ASTC format has
588/// its tables.
589type Fill = fn(Format, &[u8], usize, usize, &mut [u8], Option<&mut astc::Tables>);
590
591/// [`decode()`] with its pixel loop, which a test may replace.
592fn decode_with(
593    format: Format,
594    data: &[u8],
595    width: i32,
596    height: i32,
597    meter: &Arc<Meter>,
598    fill: Fill,
599    signed_bc6h: bool,
600) -> Result<Image, DecodeError> {
601    let plan = plan(format, data.len(), width, height)?;
602    meter.count_decode(plan.output_bytes)?;
603    let (Ok(out_len), Ok(w), Ok(h)) = (
604        usize::try_from(plan.output_bytes),
605        usize::try_from(plan.width),
606        usize::try_from(plan.height),
607    ) else {
608        // Only on a target whose `usize` cannot hold 1 GiB and more.
609        return Err(DecodeError::TooLarge {
610            pixels: u64::from(plan.width) * u64::from(plan.height),
611            max: MAX_PIXELS,
612        });
613    };
614    if out_len > 0 && format.is_crunched() {
615        if format.is_unity_crunched() {
616            crunch::unity::validate(data, format, (w, h))?;
617        } else {
618            crunch::validate(data, format == Format::Dxt5Crunched, (w, h))?;
619        }
620    }
621    // The empty image of a side of 0 charges and allocates nothing.
622    let (pixels, charge) = MeteredVec::<u8>::with_capacity(meter, out_len)?.into_parts();
623    let mut image = Image {
624        mode: plan.mode,
625        width: plan.width,
626        height: plan.height,
627        pixels,
628        charge,
629    };
630    // Within the capacity just reserved: no allocation.
631    image.pixels.resize(out_len, 0);
632    if out_len > 0 {
633        if format.is_crunched() {
634            // CRN ranges/counts are checked before their allocations. The
635            // second buffer and all temporary tables remain metered until
636            // freed. Pillow BC1/BC3 supplies precisely the existing pixels.
637            crate::contain(AssertUnwindSafe(|| {
638                let blocks = if format.is_unity_crunched() {
639                    crunch::unity::unpack(data, format, (w, h), 0, meter)?
640                } else {
641                    crunch::unpack(data, format == Format::Dxt5Crunched, (w, h), 0, meter)?
642                };
643                fill(format, blocks.as_slice(), w, h, &mut image.pixels, None);
644                Ok(())
645            }))?;
646            return Ok(image);
647        }
648        // An ASTC format's tables, charged after the output (`Plan::scratch`)
649        // and dropped before the decode returns.
650        let mut tables = match astc_footprint(format) {
651            Some(fp) => Some(astc::Tables::new(fp, meter)?),
652            None => None,
653        };
654        let out = &mut image.pixels;
655        // Unwind-safe: on a panic `image` and the tables are dropped, never
656        // read, so their half-written bytes are seen by no one; `data` is
657        // only read.
658        crate::contain(AssertUnwindSafe(|| {
659            if format.is_astc_hdr() {
660                let tables = tables.as_mut().ok_or(crate::HdrError::InvalidBlock)?;
661                astc::hdr::decode_image(tables, data, w, h, out)?;
662                return Ok(());
663            }
664            if format == Format::Bc6h {
665                if signed_bc6h {
666                    crate::bc6h::decode_signed(data, w, h, out)?;
667                } else {
668                    crate::bc6h::decode(data, w, h, out)?;
669                }
670                return Ok(());
671            }
672            fill(format, data, w, h, out, tables.as_mut());
673            Ok(())
674        }))?;
675    }
676    Ok(image)
677}
678
679/// The format's decoder.
680fn fill(
681    format: Format,
682    data: &[u8],
683    w: usize,
684    h: usize,
685    out: &mut [u8],
686    tables: Option<&mut astc::Tables>,
687) {
688    if let Some(tables) = tables {
689        // Every ASTC format, and only they, has tables. UnityPy flips the
690        // padded image after astcenc's decode and its crop.
691        astc::decode_image(tables, data, (w, h), true, astc::ERROR, out);
692        return;
693    }
694    if crate::tierb::layout(format).is_some() {
695        crate::tierb::decode(format, data, w, h, out);
696        return;
697    }
698    match format {
699        Format::Alpha8 => raw::decode(raw::Kind::A, data, w, h, out),
700        Format::Argb4444 => raw::decode(raw::Kind::Rgba4BArgb, data, w, h, out),
701        Format::Rgb24 => raw::decode(raw::Kind::Rgb, data, w, h, out),
702        Format::Rgba32 => raw::decode(raw::Kind::Rgba, data, w, h, out),
703        Format::Argb32 => raw::decode(raw::Kind::Argb, data, w, h, out),
704        Format::Rgb565 => raw::decode(raw::Kind::Bgr16, data, w, h, out),
705        Format::Bgr24 => raw::decode(raw::Kind::Bgr, data, w, h, out),
706        Format::Rgba4444 => raw::decode(raw::Kind::Rgba4BRgba, data, w, h, out),
707        Format::Bgra32 => raw::decode(raw::Kind::Bgra, data, w, h, out),
708        Format::R8 => raw::decode(raw::Kind::R, data, w, h, out),
709        Format::Dxt1 | Format::Dxt1Crunched | Format::UnityDxt1Crunched => {
710            bcn::decode(bcn::Kind::Bc1, data, w, h, out);
711        }
712        Format::Dxt3 => bcn::decode(bcn::Kind::Bc2, data, w, h, out),
713        Format::Dxt5 | Format::Dxt5Crunched | Format::UnityDxt5Crunched => {
714            bcn::decode(bcn::Kind::Bc3, data, w, h, out);
715        }
716        Format::Bc4 => bcn::decode(bcn::Kind::Bc4, data, w, h, out),
717        Format::Bc5 => bcn::decode(bcn::Kind::Bc5, data, w, h, out),
718        Format::Bc7 => bcn::decode(bcn::Kind::Bc7, data, w, h, out),
719        Format::PvrtcRgb2 | Format::PvrtcRgba2 => pvrtc::decode(data, w, h, true, out),
720        Format::PvrtcRgb4 | Format::PvrtcRgba4 => pvrtc::decode(data, w, h, false, out),
721        Format::AtcRgb4 => atc::decode(data, w, h, false, out),
722        Format::AtcRgba8 => atc::decode(data, w, h, true, out),
723        Format::EtcRgb4 | Format::EtcRgb4Crunched => etc::decode(etc::Kind::Etc1, data, w, h, out),
724        Format::EacR => etc::decode(etc::Kind::EacR, data, w, h, out),
725        Format::EacRSigned => etc::decode(etc::Kind::EacRSigned, data, w, h, out),
726        Format::EacRg => etc::decode(etc::Kind::EacRg, data, w, h, out),
727        Format::EacRgSigned => etc::decode(etc::Kind::EacRgSigned, data, w, h, out),
728        Format::Etc2Rgb => etc::decode(etc::Kind::Etc2, data, w, h, out),
729        Format::Etc2Rgba1 => etc::decode(etc::Kind::Etc2A1, data, w, h, out),
730        Format::Etc2Rgba8 | Format::Etc2Rgba8Crunched => {
731            etc::decode(etc::Kind::Etc2A8, data, w, h, out);
732        }
733        // Closed forms and refusals handled before this match.
734        Format::Bc6h
735        | Format::AstcHdr4x4
736        | Format::AstcHdr5x5
737        | Format::AstcHdr6x6
738        | Format::AstcHdr8x8
739        | Format::AstcHdr10x10
740        | Format::AstcHdr12x12
741        | Format::R16
742        | Format::RHalf
743        | Format::RgHalf
744        | Format::RgbaHalf
745        | Format::RFloat
746        | Format::RgFloat
747        | Format::RgbaFloat
748        | Format::Yuy2
749        | Format::Rgb9e5Float
750        | Format::RgbFloat
751        | Format::Rg16
752        | Format::Rg32
753        | Format::Rgb48
754        | Format::Rgba64
755        | Format::R8Signed
756        | Format::Rg16Signed
757        | Format::Rgb24Signed
758        | Format::Rgba32Signed
759        | Format::R16Signed
760        | Format::Rg32Signed
761        | Format::Rgb48Signed
762        | Format::Rgba64Signed
763        | Format::ArgbFloat
764        // Decoded above, with their tables.
765        | Format::AstcRgb4x4
766        | Format::AstcRgb5x5
767        | Format::AstcRgb6x6
768        | Format::AstcRgb8x8
769        | Format::AstcRgb10x10
770        | Format::AstcRgb12x12
771        | Format::AstcRgba4x4
772        | Format::AstcRgba5x5
773        | Format::AstcRgba6x6
774        | Format::AstcRgba8x8
775        | Format::AstcRgba10x10
776        | Format::AstcRgba12x12 => {}
777    }
778}
779
780mod length;
781pub use length::bcn_length;
782use length::{astc_footprint, raw_pixel_bytes, scratch_charge};
783
784#[cfg(test)]
785mod tests;