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;