Expand description
Texture2D decoding for the batch engine (docs/plans/extract.md E15,
E18, E59, E66): the five formats P1b exports, BC7, DXT1, DXT5, RGBA32 and
RGB24; of P3, the rest of the formats UnityPy decodes with Pillow’s raw
and bcn decoders (Alpha8, ARGB4444, ARGB32, RGB565, BGR24, DXT3,
RGBA4444, BGRA32, BC4, BC5 and R8) and the eight ETC and EAC formats
(ETC_RGB4, ETC2_RGB, ETC2_RGBA1, ETC2_RGBA8, EAC_R,
EAC_R_SIGNED, EAC_RG and EAC_RG_SIGNED), and the twelve ASTC LDR
formats (ASTC_RGB_NxN and ASTC_RGBA_NxN, N of 4, 5, 6, 8, 10 and
12), the four PVRTC formats and the two ATC formats, decoded to the
pixels UnityPy 1.25.2 with Pillow 9.5.0,
texture2ddecoder 1.0.5 and astc-encoder-py 0.1.12 gives
(Texture2D.image, export/Texture2DConverter.py:237-320), bit for bit,
but for ETC2_RGBA1’s transparent pixels and a signed EAC base of -128
(Tier C, below), in its mode (L for BC4, RGB for RGB24, RGB565,
BGR24, R8 and BC5, RGBA for the rest: Format::mode) and its
orientation (flipped top to bottom), and which textures are exported or
skipped.
Legacy DXT1Crunched and DXT5Crunched are also supported through the
crunch module and existing BC1/BC3 decoders. select_in and
select_crunch take the Unity version and choose legacy or Unity fork
DXT; crunched ETC always uses the Unity fork and existing ETC decoders.
Version 2 may allow-list Unity’s four crunched names; version 1 keeps
its five formats. Native builder fixtures and the pinned UnityPy pixel
fixture cover both forks (tests/crunch_oracle.rs and
tests/unitycrunch_oracle.rs).
select(): a texture’s fields toSelection::Exportwith itsFormat, orSelection::Skipwith theSkipreason the manifest records (docs/BATCH_SPEC.mdsection 3). Pure; it reads no data.plan(): what decoding a format at a size from data of a given length needs (mip 0’s bytes, or crunch’s minimum header) and gives (the image’s mode, size and bytes, and what it charges), or the error the decode would return, before any data is read. Crunch can also return a content error after planning succeeds. This lets the engine count the work and the memory first.decode(): a texture’s data (mip 0 first; the rest is ignored, as Pillow ignores it) to anImage, its pixels charged to the caller’s meter before they are allocated (and ASTC tables or crunch scratch, while it runs), its pixel loop run undercontain()so a panic is an error (DecodeError::Panicked).
plan_in and decode_in add platform fields: Switch GOB deswizzling
(including RGB24/BGR24 promotion), Xbox byte pairs before crunch, and the
crop after decoding. [array] maps GraphicsFormat values, resolves streamed
data and decodes slices, applying PARITY section 19.2’s B/C corrections
and platform refusals. pad_image repeats edge pixels for encoder callers.
[write] converts Pillow image storage to raw texture bytes, generates
exact BICUBIC mips, pads and swizzles Switch writes, and installs object
edits through SerializedFile save. The encode feature enables the pinned
etcpak and astcenc encoders; otherwise nonempty compressed writes return
write::WriteError::EncoderUnavailable.
Tier B/C raw formats. The twenty-two raw formats of PARITY.md
sections 17.1, 19.1 and 19.2 use independent closed forms in tierb,
with no Pillow conversion. tests/tierb_oracle.rs pins UnityPy’s actual
images/exceptions beside those references. Nonempty ARGBFloat and
odd-width YUY2 layouts are refused by selection and planning; zero
sides retain the empty image behavior. These decoders charge only
their output and need no scratch allocation.
BC6H and ASTC HDR. BC6H implements Khronos Data Format Specification
1.3 section 20.2; ASTC HDR ports the full HDR profile of the same
astcenc revision as LDR. Both produce binary16 values before applying
PARITY section 17.1’s f64 clamp and rounding rule. tests/bc6h_oracle.rs
and tests/astc_hdr_oracle.rs replay the references beside UnityPy’s
failures or incorrect LDR-profile results (Tier B and Tier C).
decode_bc6h_signed exposes the signed form; Unity’s format selects
unsigned. Reserved or illegal HDR encodings return HdrError.
How each format matches UnityPy. UnityPy decodes the five, and the
eleven of P3’s Pillow formats, with Pillow (CONV_TABLE,
export/Texture2DConverter.py:488-566), so each of their decoders here is
Pillow 9.5.0’s, ported: the raw formats are its raw decoder
(Image.frombytes(mode, size, data, "raw", rawmode), row by row through
the raw mode’s unpacker, src/libImaging/Unpack.c, then UnityPy’s band
order where it gives one, in the raw module), DXT1, DXT3, DXT5, BC4,
BC5 and BC7 its bcn decoder with 1, 2, 3, 4, 5 and 7
(src/libImaging/BcnDecode.c, in the bcn module), on the image padded
to whole 4x4 blocks, then cropped and flipped as UnityPy does
(decode’s module docs). texture2ddecoder, UnityPy’s other decoder
library, decodes none of them; it decodes the ETC and EAC formats,
and its decoders for them are ported in the etc module, which writes
an ETC2_RGBA1 pixel its punch-through rule makes transparent as
(0, 0, 0, 0), as the Khronos Data Format Specification 1.3, section
22.9, does, where texture2ddecoder keeps its colour (PARITY.md
section 19.1). tests/etc_oracle.rs replays what UnityPy recorded for
them (tools/fixtures/texture.py, with tools/fixtures/texture_etc.py’s
blocks): every block mode, every size
class, long data, zero and negative sides, and Pillow’s limits on
texture2ddecoder’s output. tests/oracle.rs replays what the
oracle recorded (tools/fixtures/texture.py): each of the five at sizes
from 1x1 to 257x3, every BC7 mode, short, long and empty data, zero and
negative sides, Pillow’s raw width cap and its crop’s decompression-bomb
check, and the skips. tests/raw_oracle.rs replays the same for the
eleven others (tools/fixtures/texture.py, with
tools/fixtures/texture_raw.py’s data): every size class, every value of
each packed field, every endpoint order of the block formats, long, short
and empty data, zero and negative sides, each raw mode’s width cap and
the crop bound. UnityPy decodes the ASTC formats with astcenc
(astc-encoder-py 0.1.12’s, Arm astcenc at commit 631fb04), with the LDR
profile into 8-bit output; the astc module ports its decoder, error
colour and edge handling included. tests/astc_oracle.rs replays what
UnityPy recorded for the twelve (tools/fixtures/texture_astc.py):
blocks astcenc’s encoder made, random blocks, cut edges, long, short and
empty data, zero and negative sides, and Pillow’s limits on astcenc’s
output; the crate’s unit tests replay Texture2DConverter.astc alone at
every footprint astcenc takes, on blocks crafted to reach every block
mode class, partition count, dual-plane channel, endpoint mode, void
extent and error block.
PVRTC and ATC port texture2ddecoder 1.0.5 (pvrtc and atc modules).
The four PVRTC names retain encoded alpha, use Morton order with wrapped
endpoint/modulation neighbors, and pad only to the block footprint;
ATC retains the original dimensions and uses interpolated alpha for
ATC_RGBA8. See PARITY.md section 17 for the reference quirks and the
coordinator-generated oracle replay (tests/pvrtc_atc_oracle.rs).
No panics, bounded work (docs/plans/core.md section 3.15): indexing,
unwrap and the like are denied outside tests; sizes are computed in
u64 from the i32 sides; a texture past MAX_PIXELS (16384 x
16384, padded) is refused whatever its data’s length once it is not
empty, before any allocation, the
one bound UnityPy does not have (PARITY.md section 19.3), while
Pillow’s own limits below it, its raw decoder’s width cap and its crop’s
decompression-bomb check, are matched (decode’s module docs); a
decode’s pixel work is linear in its output. Crunch’s header-derived
palette and model setup also counts against the meter’s work allowance.
Re-exports§
pub use platform::PlatformError;pub use platform::decode_in;pub use platform::decode_in_as;pub use platform::plan_in;pub use platform::plan_in_as;
Modules§
- array
- Array slices (
classes/legacy_patch/Texture2DArray.py:12-43) use integer division and range stepping, retaining per-slice mip tails. Platform 0 is UnityPy’s convention; Switch/Xbox arrays are explicitly Tier U. Empty inline data uses the supplied resource (Tier B). The eight 8-bit integer entries use the corresponding UNorm/SNorm channel counts (B/C), as PARITY section 19.2 specifies. Signed byte conversion is the closed form in section 17.1; no 16-bit decoder is used for those stored bytes. The six ASTC HDR graphics formats use the corresponding HDR decoders despite the pinned UnityPy map omitting them (Tier B). - fetch
- A texture’s inline bytes, or its streamed resource. Own bundle rows are
searched before the Environment, candidates in order, containers from
inner to outer, and directory rows from last to first. Each core call
remains separately observable through
Hooks. - platform
- Switch GOB layout and Xbox byte pairs, before crunch/decode/crop.
The table and GOB order are
helpers/TextureSwizzler.py:6-10,:73-103; padding is:106-114, deswizzle:17-41. Converter ordering and RGB promotion:export/Texture2DConverter.py:254-320. - sprite
- Sprites, rendered as UnityPy 1.25.2’s
SpriteHelperrenders them (docs/plans/extract.mdE17;PARITY.mdsection 15.2), pixel for pixel, over a sheetcrate::decode()gave. - write
- Raw texture writes, format promotion and mip chains. The converter is
export/Texture2DConverter.py:118-234; field edits and mip termination areclasses/legacy_patch/Texture2D.py:14-60. Theencodefeature supplies etcpak and astcenc; without it compressed writes return a typed refusal.
Structs§
- Formats
- A set of formats, by
TextureFormatvalue. Every value UnityPy 1.25.2 names is below 128 (TEXTURE_FORMATS). - Image
- A decoded image: rows top to bottom, each pixel its mode’s bytes, red
first. It holds the
Chargefor its pixels, returned when it drops, after the pixels’ buffer is freed. - Payload
- A panic’s payload, kept whole, with no copy: the box the unwinding
carried, downcast where it holds a
&stror aString(whatpanic!and the standard library’s panics carry), which moves nothing. - Plan
- What decoding a texture of a format and a size, from data of a given
length, will need and give, worked out before the data is read
(
plan()). - Texture
Fields - What
select()reads of aTexture2D.
Enums§
- Crunch
Error - Why legacy crunch could not be unpacked. No error owns input-sized heap.
- Decode
Error - Why a texture did not decode, in the order of the module docs’ checks.
Every variant but
Self::TooLarge,Self::ChargeandSelf::Panickedis a case where UnityPy 1.25.2 raises too, but for an ETC or EAC format with short data or a side padded below 0, where texture2ddecoder reads past the data (module docs, steps 3 and 6).plan()returns the checks’ variants only, neverChargeorPanicked, whichdecode()alone gives, after a plan that passed. - Format
- The formats this crate decodes: the five of
docs/plans/extract.mdE15 and the rest of the formats UnityPy decodes with Pillow’s raw andbcndecoders (raw’s andbcn’s module docs), the eight ETC and EAC formats texture2ddecoder decodes for it (etc’s module docs), and the twelve ASTC LDR formats astcenc decodes for it (astc’s module docs), the four PVRTC and two ATC formats (pvrtcandatc), and twenty-two raw formats using independent closed forms (tierb).ArgbFloatis a refusal-only sentinel, excluded fromALL. - HdrError
- A reserved or structurally illegal HDR encoding. These are content errors after a length-only plan succeeds; no partial image escapes.
- Mode
- An image mode, as Pillow names it.
- Selection
- What
select()decides. - Skip
- Why a texture is skipped (
docs/BATCH_SPEC.mdsection 3). ItsDisplayform is the manifest’s reason (docs/BATCH_SPEC.md9.3). - Skipped
Platform - The platform an
Skip::UnsupportedPlatformnames.
Constants§
- MAX_
CROP_ PIXELS - The most pixels UnityPy’s crop of a padded block-format image takes: twice
Pillow 9.5.0’s
Image.MAX_IMAGE_PIXELS,1024 * 1024 * 1024 // 4 // 3(module docs, step 8). - MAX_
PIXELS - The most pixels a texture may have, at its padded size: 16384 x 16384.
UnityPy has no such bound (module docs;
PARITY.mdsection 19.3). - MESSAGE_
BYTES - The most bytes
Payload::messagegives: adecoder_panic’s detail is the payload cut to its first 1,024 bytes at a code point boundary (docs/BATCH_SPEC.mdsection 7.3). - NON_
STRING_ PAYLOAD - The text
Payload::messagegives when a panic’s payload is neither a&strnor aString(docs/BATCH_SPEC.mdsection 7.3). - SWITCH
BuildTarget.Switch(enums/BuildTarget.py:39).- TEXTURE_
FORMATS - UnityPy 1.25.2’s
TextureFormatmembers, value and name, in its order (enums/TextureFormat.py:4-82). Values 37 to 40 are unassigned. - XBOX360
BuildTarget.XBOX360(enums/BuildTarget.py:16).- XBOX_
SWAP_ FORMATS - The formats UnityPy byte-swaps on Xbox 360:
RGB565,DXT1,DXT1Crunched,DXT5,DXT5Crunched(export/Texture2DConverter.py:569). Of the five exported, DXT1 and DXT5.
Functions§
- astc_
ldr_ error_ blocks - Whether astcenc’s LDR decoder, as UnityPy calls it, reads each whole
16-byte block of
dataas an error block at the footprintwidthxheight: one verdict a block, in order.Nonefor a footprint astcenc does not take, or when the decode tables cannot be charged. This is the decoder’s error status, not its colour, which differs by astcenc build (PARITY.mdsection 19.3), so a block’s legality reads the same on every host. - bcn_
length - The length Pillow 9.5.0’s
BCndecoder sees forlenbytes of data:ImagingBcnDecodepasses itsPy_ssize_tlength todecode_bcn’sintparameter, a conversion GCC and Clang both make modulo 2^32, then as a signed value (C leaves an out-of-range conversion to the implementation), so the decode loop (while (bytes >= SZ)) runs on the length’s low 32 bits, none when bit 31 is set. Below 2 GiB it is the length itself. - contain
- Runs
f, a panic in it becomingDecodeError::Panickedwith its payload.fcharges nothing (module docs), and must beUnwindSafe: a caller whose closure writes into a buffer it then drops on the error asserts so itself (std::panic::AssertUnwindSafe), ascrate::decode()does. - decode
- Decodes a texture’s mip 0,
databeing its image data from the start (image_data, or what itsm_StreamDatanames:Texture2D.get_image_data), mips and all, as UnityPy 1.25.2 with Pillow 9.5.0 does (module docs), charging the output tometerbefore it is allocated. Its pixel loop runs undercrate::contain(), so a panic there isDecodeError::Panicked, with the output’s charge returned. - decode_
bc6h_ block - Decode one BC6H block to row-major binary16 RGB bit patterns, using
Khronos Data Format Specification 1.3 section 20.2. Reserved modes are
refused.
signedselects the signed encoding, including negative zero. - decode_
bc6h_ signed - Decode signed BC6H with the same bounds, metering, crop and flip as
decode. Unity’sTextureFormat::BC6Hselects unsigned decoding; this entry point supports the specification’s signed encoding. - image_
from_ pixels - Copy already ordered pixels into a charged image, validating its length.
- is_
switch_ swizzled - Whether UnityPy deswizzles a texture as a Switch texture
(
TextureSwizzler.is_switch_swizzled,helpers/TextureSwizzler.py:121-127): the platform is Switch, the platform blob holds at least 12 bytes, and1 << nis more than one GOB per block,nbeing the little-endianu32at bytes 8 to 12 of the blob (get_switch_gobs_per_block,helpers/TextureSwizzler.py:117-118), so whenevernis not 0. - pad_
image - Extend the final column, row and corner with NEAREST sampling. Equal dimensions return the original allocation and charge, without work.
- plan
- What decoding
formatatwidthxheightfromdata_lenbytes of data needs and gives, or the errordecode()returns for it: the module docs’ size/length checks in their order. For crunch, success only establishes a memory bound: header or bitstream validation may subsequently returnDecodeError::Crunch. HDR block content can likewise returnDecodeError::Hdrafter planning succeeds. - select
- Whether a texture is exported, and as what, or skipped, and why
(module docs), under version 1’s five formats (
Formats::V1). - select_
crunch - Select crunched DXT/ETC with an explicit Unity
(major, minor). The version split and ETC exception are UnityPy’sexport/Texture2DConverter.py:297-306. Empty images precede it, and the existing Switch/Xbox gates still apply. Other formats use version 1’s five formats, asselect()does. - select_
in select()under the formats a spec names (docs/BATCH_SPEC.md1.5): a format outsideformatsisunsupported_format, as one this crate does not decode is. Unity’s names informatsallow both DXT crunch variants: before Unity 2017.3 the decoder is legacy, from 2017.3 it is Unity’s fork. An unknown version(u16::MAX, u16::MAX)uses the fork. Crunched ETC always uses the fork (export/Texture2DConverter.py:297-306).- texture_
format_ name - UnityPy 1.25.2’s name for a
TextureFormatvalue, orNonefor a value its enum lacks (whereTextureFormat(value)raisesValueError).