Skip to main content

unityrs_texture/
lib.rs

1// Ported from UnityPy 1.25.2 (MIT): UnityPy/export/Texture2DConverter.py's texture export for the formats it decodes with Pillow's raw and bcn decoders (Alpha8, ARGB4444, RGB24, RGBA32, ARGB32, RGB565, BGR24, DXT1, DXT3, DXT5, RGBA4444, BGRA32, BC7, BC4, BC5 and R8), the ETC and EAC formats, the ASTC LDR formats, PVRTC and ATC, with Pillow 9.5.0's, texture2ddecoder 1.0.5's and astc-encoder-py 0.1.12's decoders as it calls them. See THIRD_PARTY_LICENSES.
2//! `Texture2D` decoding for the batch engine (`docs/plans/extract.md` E15,
3//! E18, E59, E66): the five formats P1b exports, BC7, DXT1, DXT5, RGBA32 and
4//! RGB24; of P3, the rest of the formats UnityPy decodes with Pillow's raw
5//! and `bcn` decoders (Alpha8, ARGB4444, ARGB32, RGB565, BGR24, DXT3,
6//! RGBA4444, BGRA32, BC4, BC5 and R8) and the eight ETC and EAC formats
7//! (`ETC_RGB4`, `ETC2_RGB`, `ETC2_RGBA1`, `ETC2_RGBA8`, `EAC_R`,
8//! `EAC_R_SIGNED`, `EAC_RG` and `EAC_RG_SIGNED`), and the twelve ASTC LDR
9//! formats (`ASTC_RGB_NxN` and `ASTC_RGBA_NxN`, N of 4, 5, 6, 8, 10 and
10//! 12), the four PVRTC formats and the two ATC formats, decoded to the
11//! pixels UnityPy 1.25.2 with Pillow 9.5.0,
12//! texture2ddecoder 1.0.5 and astc-encoder-py 0.1.12 gives
13//! (`Texture2D.image`, `export/Texture2DConverter.py:237-320`), bit for bit,
14//! but for `ETC2_RGBA1`'s transparent pixels and a signed EAC base of -128
15//! (Tier C, below), in its mode (`L` for BC4, `RGB` for RGB24, RGB565,
16//! BGR24, R8 and BC5, `RGBA` for the rest: [`Format::mode`]) and its
17//! orientation (flipped top to bottom), and which textures are exported or
18//! skipped.
19//!
20//! Legacy `DXT1Crunched` and `DXT5Crunched` are also supported through the
21//! `crunch` module and existing BC1/BC3 decoders. [`select_in`] and
22//! [`select_crunch`] take the Unity version and choose legacy or Unity fork
23//! DXT; crunched ETC always uses the Unity fork and existing ETC decoders.
24//! Version 2 may allow-list Unity's four crunched names; version 1 keeps
25//! its five formats. Native builder fixtures and the pinned UnityPy pixel
26//! fixture cover both forks (`tests/crunch_oracle.rs` and
27//! `tests/unitycrunch_oracle.rs`).
28//!
29//! - [`select()`]: a texture's fields to [`Selection::Export`] with its
30//!   [`Format`], or [`Selection::Skip`] with the [`Skip`] reason the manifest
31//!   records (`docs/BATCH_SPEC.md` section 3). Pure; it reads no data.
32//! - [`plan()`]: what decoding a format at a size from data of a given
33//!   length needs (mip 0's bytes, or crunch's minimum header) and gives (the image's mode, size and
34//!   bytes, and what it charges), or the error the decode would return,
35//!   before any data is read. Crunch can also return a content error after
36//!   planning succeeds. This lets the engine count the work and the
37//!   memory first.
38//! - [`decode()`]: a texture's data (mip 0 first; the rest is ignored, as
39//!   Pillow ignores it) to an [`Image`], its pixels charged to the caller's
40//!   meter before they are allocated (and ASTC tables or crunch scratch, while
41//!   it runs), its pixel loop run under [`contain()`] so a panic is an
42//!   error ([`DecodeError::Panicked`]).
43//!
44//! [`plan_in`] and [`decode_in`] add platform fields: Switch GOB deswizzling
45//! (including RGB24/BGR24 promotion), Xbox byte pairs before crunch, and the
46//! crop after decoding. [`array`] maps `GraphicsFormat` values, resolves streamed
47//! data and decodes slices, applying PARITY section 19.2's B/C corrections
48//! and platform refusals. [`pad_image`] repeats edge pixels for encoder callers.
49//!
50//! [`write`] converts Pillow image storage to raw texture bytes, generates
51//! exact BICUBIC mips, pads and swizzles Switch writes, and installs object
52//! edits through `SerializedFile` save. The `encode` feature enables the pinned
53//! etcpak and astcenc encoders; otherwise nonempty compressed writes return
54//! [`write::WriteError::EncoderUnavailable`].
55//!
56//! **Tier B/C raw formats.** The twenty-two raw formats of `PARITY.md`
57//! sections 17.1, 19.1 and 19.2 use independent closed forms in `tierb`,
58//! with no Pillow conversion. `tests/tierb_oracle.rs` pins UnityPy's actual
59//! images/exceptions beside those references. Nonempty `ARGBFloat` and
60//! odd-width YUY2 layouts are refused by selection and planning; zero
61//! sides retain the empty image behavior. These decoders charge only
62//! their output and need no scratch allocation.
63//!
64//! **BC6H and ASTC HDR.** BC6H implements Khronos Data Format Specification
65//! 1.3 section 20.2; ASTC HDR ports the full HDR profile of the same
66//! astcenc revision as LDR. Both produce binary16 values before applying
67//! PARITY section 17.1's f64 clamp and rounding rule. `tests/bc6h_oracle.rs`
68//! and `tests/astc_hdr_oracle.rs` replay the references beside UnityPy's
69//! failures or incorrect LDR-profile results (Tier B and Tier C).
70//! [`decode_bc6h_signed`] exposes the signed form; Unity's format selects
71//! unsigned. Reserved or illegal HDR encodings return [`HdrError`].
72//!
73//! **How each format matches UnityPy.** UnityPy decodes the five, and the
74//! eleven of P3's Pillow formats, with Pillow (`CONV_TABLE`,
75//! `export/Texture2DConverter.py:488-566`), so each of their decoders here is
76//! Pillow 9.5.0's, ported: the raw formats are its raw decoder
77//! (`Image.frombytes(mode, size, data, "raw", rawmode)`, row by row through
78//! the raw mode's unpacker, `src/libImaging/Unpack.c`, then UnityPy's band
79//! order where it gives one, in the `raw` module), DXT1, DXT3, DXT5, BC4,
80//! BC5 and BC7 its `bcn` decoder with 1, 2, 3, 4, 5 and 7
81//! (`src/libImaging/BcnDecode.c`, in the `bcn` module), on the image padded
82//! to whole 4x4 blocks, then cropped and flipped as UnityPy does
83//! (`decode`'s module docs). texture2ddecoder, UnityPy's other decoder
84//! library, decodes none of them; it decodes the ETC and EAC formats,
85//! and its decoders for them are ported in the `etc` module, which writes
86//! an `ETC2_RGBA1` pixel its punch-through rule makes transparent as
87//! (0, 0, 0, 0), as the Khronos Data Format Specification 1.3, section
88//! 22.9, does, where texture2ddecoder keeps its colour (`PARITY.md`
89//! section 19.1). `tests/etc_oracle.rs` replays what UnityPy recorded for
90//! them (`tools/fixtures/texture.py`, with `tools/fixtures/texture_etc.py`'s
91//! blocks): every block mode, every size
92//! class, long data, zero and negative sides, and Pillow's limits on
93//! texture2ddecoder's output. `tests/oracle.rs` replays what the
94//! oracle recorded (`tools/fixtures/texture.py`): each of the five at sizes
95//! from 1x1 to 257x3, every BC7 mode, short, long and empty data, zero and
96//! negative sides, Pillow's raw width cap and its crop's decompression-bomb
97//! check, and the skips. `tests/raw_oracle.rs` replays the same for the
98//! eleven others (`tools/fixtures/texture.py`, with
99//! `tools/fixtures/texture_raw.py`'s data): every size class, every value of
100//! each packed field, every endpoint order of the block formats, long, short
101//! and empty data, zero and negative sides, each raw mode's width cap and
102//! the crop bound. UnityPy decodes the ASTC formats with astcenc
103//! (astc-encoder-py 0.1.12's, Arm astcenc at commit 631fb04), with the LDR
104//! profile into 8-bit output; the `astc` module ports its decoder, error
105//! colour and edge handling included. `tests/astc_oracle.rs` replays what
106//! UnityPy recorded for the twelve (`tools/fixtures/texture_astc.py`):
107//! blocks astcenc's encoder made, random blocks, cut edges, long, short and
108//! empty data, zero and negative sides, and Pillow's limits on astcenc's
109//! output; the crate's unit tests replay `Texture2DConverter.astc` alone at
110//! every footprint astcenc takes, on blocks crafted to reach every block
111//! mode class, partition count, dual-plane channel, endpoint mode, void
112//! extent and error block.
113//!
114//! PVRTC and ATC port texture2ddecoder 1.0.5 (`pvrtc` and `atc` modules).
115//! The four PVRTC names retain encoded alpha, use Morton order with wrapped
116//! endpoint/modulation neighbors, and pad only to the block footprint;
117//! ATC retains the original dimensions and uses interpolated alpha for
118//! `ATC_RGBA8`. See `PARITY.md` section 17 for the reference quirks and the
119//! coordinator-generated oracle replay (`tests/pvrtc_atc_oracle.rs`).
120//!
121//! **No panics, bounded work** (`docs/plans/core.md` section 3.15): indexing,
122//! `unwrap` and the like are denied outside tests; sizes are computed in
123//! `u64` from the `i32` sides; a texture past [`MAX_PIXELS`] (16384 x
124//! 16384, padded) is refused whatever its data's length once it is not
125//! empty, before any allocation, the
126//! one bound UnityPy does not have (`PARITY.md` section 19.3), while
127//! Pillow's own limits below it, its raw decoder's width cap and its crop's
128//! decompression-bomb check, are matched (`decode`'s module docs); a
129//! decode's pixel work is linear in its output. Crunch's header-derived
130//! palette and model setup also counts against the meter's work allowance.
131
132// Only write::ffi may opt in, at the synchronous encoder boundary.
133#![deny(unsafe_code)]
134// No panics on a texture's contents (plan section 3.15). Tests may opt out.
135#![cfg_attr(
136    not(test),
137    deny(
138        clippy::unwrap_used,
139        clippy::expect_used,
140        clippy::panic,
141        clippy::todo,
142        clippy::unimplemented,
143        clippy::unreachable,
144        clippy::indexing_slicing
145    )
146)]
147
148pub mod array;
149mod astc;
150mod atc;
151mod bc6h;
152mod bcn;
153mod contain;
154mod crunch;
155mod decode;
156mod etc;
157pub mod fetch;
158mod format;
159mod formats;
160mod hdr;
161mod image;
162mod place;
163pub mod platform;
164mod pvrtc;
165mod raw;
166mod select;
167pub mod sprite;
168mod tierb;
169pub mod write;
170
171pub use contain::{MESSAGE_BYTES, NON_STRING_PAYLOAD, Payload, contain};
172pub use crunch::CrunchError;
173pub use decode::{
174    DecodeError, Image, MAX_CROP_PIXELS, MAX_PIXELS, Plan, bcn_length, decode, decode_bc6h_signed,
175    plan,
176};
177pub use format::{Format, Mode, TEXTURE_FORMATS, texture_format_name};
178pub use formats::Formats;
179pub use hdr::HdrError;
180pub use image::{image_from_pixels, pad_image};
181pub use platform::{PlatformError, decode_in, decode_in_as, plan_in, plan_in_as};
182
183/// Decode one BC6H block to row-major binary16 RGB bit patterns, using
184/// Khronos Data Format Specification 1.3 section 20.2. Reserved modes are
185/// refused. `signed` selects the signed encoding, including negative zero.
186pub fn decode_bc6h_block(data: &[u8; 16], signed: bool) -> Result<[[u16; 3]; 16], HdrError> {
187    bc6h::block(data, signed).ok_or(HdrError::ReservedMode)
188}
189/// Whether astcenc's LDR decoder, as UnityPy calls it, reads each whole
190/// 16-byte block of `data` as an error block at the footprint `width` x
191/// `height`: one verdict a block, in order. `None` for a footprint astcenc
192/// does not take, or when the decode tables cannot be charged. This is the
193/// decoder's error status, not its colour, which differs by astcenc build
194/// (`PARITY.md` section 19.3), so a block's legality reads the same on
195/// every host.
196#[must_use]
197pub fn astc_ldr_error_blocks(width: u8, height: u8, data: &[u8]) -> Option<Vec<bool>> {
198    let fp = astc::Footprint::new(width, height)?;
199    let meter = unityrs_core::limits::Meter::unlimited();
200    let mut tables = astc::Tables::new(fp, &meter).ok()?;
201    Some(astc::error_blocks(&mut tables, data))
202}
203
204pub use select::{
205    SWITCH, Selection, Skip, SkippedPlatform, TextureFields, XBOX_SWAP_FORMATS, XBOX360,
206    is_switch_swizzled, select, select_crunch, select_in,
207};
208
209/// Asserts at compile time that `T` is `Send + Sync` (plan section 3.16).
210pub(crate) const fn send_sync<T: Send + Sync + ?Sized>() {}
211
212#[cfg(test)]
213mod golden_tests;
214#[cfg(test)]
215mod tests {
216    use std::path::Path;
217
218    /// Plan 3.16: every public type is `Send + Sync`, so the engine's pool
219    /// threads may move and share them.
220    #[test]
221    fn every_public_type_is_asserted() {
222        let src = Path::new(env!("CARGO_MANIFEST_DIR")).join("src");
223        let missing = unityrs_testkit::public_types::unasserted(&src);
224        assert!(missing.is_empty(), "not asserted Send + Sync: {missing:?}");
225    }
226
227    /// Plan 4.1: no thread, no wait; the decoders run on the engine's
228    /// threads.
229    #[test]
230    fn the_decoders_start_no_thread_and_never_wait() {
231        let src = Path::new(env!("CARGO_MANIFEST_DIR")).join("src");
232        let found = unityrs_testkit::waits::waits(&src);
233        assert!(found.is_empty(), "waits or starts a thread: {found:?}");
234    }
235}