Skip to main content

Crate unityrs_texture

Crate unityrs_texture 

Source
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 to Selection::Export with its Format, or Selection::Skip with the Skip reason the manifest records (docs/BATCH_SPEC.md section 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 an Image, 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 under contain() 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 SpriteHelper renders them (docs/plans/extract.md E17; PARITY.md section 15.2), pixel for pixel, over a sheet crate::decode() gave.
write
Raw texture writes, format promotion and mip chains. The converter is export/Texture2DConverter.py:118-234; field edits and mip termination are classes/legacy_patch/Texture2D.py:14-60. The encode feature supplies etcpak and astcenc; without it compressed writes return a typed refusal.

Structs§

Formats
A set of formats, by TextureFormat value. 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 Charge for 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 &str or a String (what panic! 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()).
TextureFields
What select() reads of a Texture2D.

Enums§

CrunchError
Why legacy crunch could not be unpacked. No error owns input-sized heap.
DecodeError
Why a texture did not decode, in the order of the module docs’ checks. Every variant but Self::TooLarge, Self::Charge and Self::Panicked is 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, never Charge or Panicked, which decode() alone gives, after a plan that passed.
Format
The formats this crate decodes: the five of docs/plans/extract.md E15 and the rest of the formats UnityPy decodes with Pillow’s raw and bcn decoders (raw’s and bcn’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 (pvrtc and atc), and twenty-two raw formats using independent closed forms (tierb). ArgbFloat is a refusal-only sentinel, excluded from ALL.
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.md section 3). Its Display form is the manifest’s reason (docs/BATCH_SPEC.md 9.3).
SkippedPlatform
The platform an Skip::UnsupportedPlatform names.

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.md section 19.3).
MESSAGE_BYTES
The most bytes Payload::message gives: a decoder_panic’s detail is the payload cut to its first 1,024 bytes at a code point boundary (docs/BATCH_SPEC.md section 7.3).
NON_STRING_PAYLOAD
The text Payload::message gives when a panic’s payload is neither a &str nor a String (docs/BATCH_SPEC.md section 7.3).
SWITCH
BuildTarget.Switch (enums/BuildTarget.py:39).
TEXTURE_FORMATS
UnityPy 1.25.2’s TextureFormat members, 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 data as an error block at the footprint width x height: one verdict a block, in order. None for 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.md section 19.3), so a block’s legality reads the same on every host.
bcn_length
The length Pillow 9.5.0’s BCn decoder sees for len bytes of data: ImagingBcnDecode passes its Py_ssize_t length to decode_bcn’s int parameter, 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 becoming DecodeError::Panicked with its payload. f charges nothing (module docs), and must be UnwindSafe: a caller whose closure writes into a buffer it then drops on the error asserts so itself (std::panic::AssertUnwindSafe), as crate::decode() does.
decode
Decodes a texture’s mip 0, data being its image data from the start (image_data, or what its m_StreamData names: Texture2D.get_image_data), mips and all, as UnityPy 1.25.2 with Pillow 9.5.0 does (module docs), charging the output to meter before it is allocated. Its pixel loop runs under crate::contain(), so a panic there is DecodeError::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. signed selects the signed encoding, including negative zero.
decode_bc6h_signed
Decode signed BC6H with the same bounds, metering, crop and flip as decode. Unity’s TextureFormat::BC6H selects 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, and 1 << n is more than one GOB per block, n being the little-endian u32 at bytes 8 to 12 of the blob (get_switch_gobs_per_block, helpers/TextureSwizzler.py:117-118), so whenever n is 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 format at width x height from data_len bytes of data needs and gives, or the error decode() 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 return DecodeError::Crunch. HDR block content can likewise return DecodeError::Hdr after 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’s export/Texture2DConverter.py:297-306. Empty images precede it, and the existing Switch/Xbox gates still apply. Other formats use version 1’s five formats, as select() does.
select_in
select() under the formats a spec names (docs/BATCH_SPEC.md 1.5): a format outside formats is unsupported_format, as one this crate does not decode is. Unity’s names in formats allow 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 TextureFormat value, or None for a value its enum lacks (where TextureFormat(value) raises ValueError).