Skip to main content

unityrs_texture/
sprite.rs

1// Ported from UnityPy 1.25.2 (MIT): UnityPy/export/SpriteHelper.py's SpriteSettings, get_image, get_image_from_sprite, mask_sprite, render_sprite_mesh and copy_triangle. See THIRD_PARTY_LICENSES.
2//! Sprites, rendered as UnityPy 1.25.2's `SpriteHelper` renders them
3//! (`docs/plans/extract.md` E17; `PARITY.md` section 15.2), pixel for pixel,
4//! over a sheet [`crate::decode()`] gave.
5//!
6//! - [`Sheet::new`]: the sprite's texture, and its alpha texture merged in
7//!   where it has one (`get_image`, `export/SpriteHelper.py:44-59`).
8//! - [`select_render_data`]: the render data `get_image_from_sprite`
9//!   renders from (`:63-86`), the Sprite's own or its atlas's.
10//! - [`render()`]: one sprite's image from its sheet, its render data
11//!   ([`SpriteData`]) and, for a tight sprite, its mesh
12//!   (`get_image_from_sprite`, `:62-127`).
13//!
14//! **What `get_image_from_sprite` does, and the order here.** It crops the
15//! sheet by `textureRect` (Pillow's crop: the box's edges compared, then
16//! each rounded half to even, then the decompression-bomb check, then C
17//! `int`s; [`canvas::crop_box`]); reads the settings (a rotation from 5 to
18//! 15 raises, [`Settings::parse`]); when packed, flips or turns the crop
19//! (`:100-113`); for tight packing, processes the sprite's own `m_RD` mesh
20//! (`:116-118`) and, when its `m_UV0` holds a non-zero value, renders the
21//! first submesh's triangles from the whole sheet (`render_sprite_mesh`,
22//! `:173-224`), and otherwise masks the crop by every submesh's triangles
23//! (`mask_sprite`, `:130-170`); and flips the result top to bottom
24//! (`:127`). Every check UnityPy makes raises here, as [`SpriteError`],
25//! in UnityPy's order, within the bounds below. One step is not taken: the
26//! crop is made only where a later step reads it (rectangle packing, and
27//! the mask), since the mesh path replaces it unread; its checks are made
28//! wherever UnityPy makes them, Pillow's width cap on it and on its turned
29//! size included ([`SpriteError::ImageTooWide`]).
30//!
31//! **Orientation.** UnityPy decodes the sheet unflipped
32//! (`get_image_from_texture2d(texture, False)`, `:47-58`), and
33//! [`crate::decode()`] returns a texture flipped, as `Texture2D.image`
34//! gives it, so a [`Sheet`] reads its rows from the last.
35//!
36//! **Divergences** (`PARITY.md` sections 19.2 and 19.3). A triangle whose
37//! system meets an exactly zero pivot in `numpy`'s LU on the pinned kernel
38//! copies nothing, where `numpy` raises `LinAlgError` (Tier C, [`affine`]);
39//! three collinear destination corners need not make one, and where they
40//! do not, the triangle is copied as UnityPy copies it. A canvas of more
41//! than [`crate::MAX_PIXELS`] pixels is [`SpriteError::TooLarge`], where
42//! Pillow's behaviour is its memory's. A field the render reads that is
43//! missing or of another type is [`SpriteError::Malformed`] (Tier U). Every
44//! buffer is charged to the caller's meter before it is allocated, and
45//! every loop's work counted on it before it runs (`docs/plans/extract.md`
46//! E59): an image's bytes and its rows, an empty image's rows included,
47//! and of the fields [`SpriteFields::read`] and [`select_render_data`]
48//! read, each atlas, map entry, field walked and tag, a name's comparison
49//! by its bytes ([`fields`]); a refusal is [`SpriteError::Charge`].
50
51pub mod affine;
52mod canvas;
53mod exact;
54pub mod fields;
55pub mod helpers;
56mod raster;
57mod render;
58
59use std::sync::Arc;
60
61use unityrs_core::limits::{ChargeError, Meter};
62use unityrs_meshdecode::{MeshError, Processed};
63
64use crate::contain::Payload;
65use crate::decode::{DecodeError, Image};
66
67pub use canvas::Sheet;
68pub use fields::{
69    AtlasKey, Guid, Pptr, RenderData, SpriteFields, atlas_render_data, select_render_data,
70};
71
72/// What [`render()`] reads of a sprite: its render data's rectangle and
73/// settings (the Sprite's `m_RD`, or the atlas's `SpriteAtlasData` for
74/// it), and the Sprite's `m_PixelsToUnits`, as Python `float`s and `int`s.
75#[derive(Clone, Copy, Debug, PartialEq)]
76pub struct SpriteData {
77    /// `textureRect`: `x`, `y`, `width`, `height`.
78    pub texture_rect: [f64; 4],
79    /// `settingsRaw`.
80    pub settings_raw: u64,
81    /// `m_PixelsToUnits`.
82    pub pixels_to_units: f64,
83}
84
85const _: () = crate::send_sync::<SpriteData>();
86
87/// `SpritePackingMode` (`enums/SpritePackingMode.py`).
88#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
89pub enum PackingMode {
90    /// `kSPMTight`, 0.
91    Tight,
92    /// `kSPMRectangle`, 1.
93    Rectangle,
94}
95
96/// `SpritePackingRotation` (`enums/SpritePackingRotation.py`).
97#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
98pub enum Rotation {
99    /// `kSPRNone`, 0.
100    None,
101    /// `kSPRFlipHorizontal`, 1: Pillow's `FLIP_LEFT_RIGHT`.
102    FlipHorizontal,
103    /// `kSPRFlipVertical`, 2: `FLIP_TOP_BOTTOM`.
104    FlipVertical,
105    /// `kSPRRotate180`, 3: `ROTATE_180`.
106    Rotate180,
107    /// `kSPRRotate90`, 4: `ROTATE_270`, a quarter turn clockwise.
108    Rotate90,
109}
110
111/// `SpriteSettings` (`export/SpriteHelper.py:29-40`): `settingsRaw`'s bits.
112#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
113pub struct Settings {
114    /// Bit 0.
115    pub packed: bool,
116    /// Bit 1.
117    pub packing_mode: PackingMode,
118    /// Bits 2 to 5.
119    pub packing_rotation: Rotation,
120    /// Bit 6, `SpriteMeshType`: 0 `kSMTFullRect`, 1 `kSMTTight`, which
121    /// rendering does not read.
122    pub mesh_type: u8,
123}
124
125const _: () = crate::send_sync::<Settings>();
126const _: () = crate::send_sync::<PackingMode>();
127const _: () = crate::send_sync::<Rotation>();
128
129impl Settings {
130    /// `SpriteSettings(settings_raw)`: a rotation from 5 to 15 is no
131    /// `SpritePackingRotation`, [`SpriteError::Rotation`]; the bits past 6
132    /// are ignored (`:35-40`).
133    pub fn parse(raw: u64) -> Result<Self, SpriteError> {
134        let packing_mode = if (raw >> 1) & 1 == 0 {
135            PackingMode::Tight
136        } else {
137            PackingMode::Rectangle
138        };
139        let rotation = (raw >> 2) & 0xF;
140        let packing_rotation = match rotation {
141            0 => Rotation::None,
142            1 => Rotation::FlipHorizontal,
143            2 => Rotation::FlipVertical,
144            3 => Rotation::Rotate180,
145            4 => Rotation::Rotate90,
146            // Masked to four bits: 5 to 15.
147            other => return Err(SpriteError::Rotation(other)),
148        };
149        Ok(Self {
150            packed: raw & 1 == 1,
151            packing_mode,
152            packing_rotation,
153            mesh_type: u8::from((raw >> 6) & 1 == 1),
154        })
155    }
156}
157
158/// Why a sprite did not render. Each variant but [`Self::Malformed`],
159/// [`Self::UnverifiedMode`], [`Self::AtlasUnresolved`], [`Self::TooLarge`], [`Self::Charge`] and
160/// [`Self::Panicked`] is a case where UnityPy 1.25.2 raises;
161/// [`Self::python`] gives its exception's class and message.
162#[derive(Debug, thiserror::Error)]
163#[non_exhaustive]
164pub enum SpriteError {
165    /// Pillow's crop of `textureRect`: its right edge before its left
166    /// (`ValueError`), checked before the lower edge.
167    #[error("Coordinate 'right' is less than 'left'")]
168    CropRightLeft,
169    /// Its lower edge above its upper (`ValueError`).
170    #[error("Coordinate 'lower' is less than 'upper'")]
171    CropLowerUpper,
172    /// `round()` of a NaN (`ValueError`).
173    #[error("cannot convert float NaN to integer")]
174    RoundNan,
175    /// `round()` of an infinity (`OverflowError`).
176    #[error("cannot convert float infinity to integer")]
177    RoundInfinity,
178    /// Pillow's crop of more than [`crate::MAX_CROP_PIXELS`] pixels
179    /// (`DecompressionBombError`).
180    #[error(
181        "Image size ({pixels} pixels) exceeds limit of 178956970 pixels, could be decompression bomb DOS attack."
182    )]
183    DecompressionBomb {
184        /// The crop's pixels, exactly, in decimal, as Python counts them.
185        pixels: String,
186    },
187    /// A box edge that `PyArg_ParseTuple`'s `i` refuses within a C `long`
188    /// (`OverflowError`): past `INT_MAX` when `above`, else below
189    /// `INT_MIN`.
190    #[error("signed integer is {}", if *above { "greater than maximum" } else { "less than minimum" })]
191    CIntOverflow {
192        /// Above `INT_MAX`, else below `INT_MIN`.
193        above: bool,
194    },
195    /// A box edge past a C `long`, which `PyLong_AsLong` refuses before
196    /// `i` sees it (`OverflowError`).
197    #[error("Python int too large to convert to C long")]
198    CLongOverflow,
199    /// An image Pillow refuses to make: wider than `INT_MAX / 4 - 1`
200    /// pixels, whatever its height (`ImagingNewPrologueSubtype`'s
201    /// `MemoryError`, which has no message): a crop, its turned size, a
202    /// mesh's canvas, a translated triangle's crop.
203    #[error("Pillow refuses an image wider than 536870910 pixels")]
204    ImageTooWide,
205    /// `numpy.linalg.solve` of a source corner outside `[-2^63, 2^64)`,
206    /// which `numpy` holds in an `object` array that its `solve` cannot
207    /// cast (`UFuncTypeError`).
208    #[error(
209        "Cannot cast ufunc 'solve1' input 1 from dtype('O') to dtype('float64') with casting rule 'same_kind'"
210    )]
211    SolveCast,
212    /// `SpritePackingRotation(n)` of 5 to 15 (`ValueError`).
213    #[error("{0} is not a valid SpritePackingRotation")]
214    Rotation(u64),
215    /// The alpha texture's decoded size is not the texture's: `Image.merge`'s
216    /// `ValueError`.
217    #[error("size mismatch")]
218    AlphaSizeMismatch,
219    /// A texture of one band (BC4's `L`) beside an alpha texture:
220    /// `Image.merge`'s `ValueError`, raised before it compares sizes.
221    #[error("wrong number of bands")]
222    AlphaBandCount,
223    /// A texture, or an alpha texture, whose decoded mode the renderer is
224    /// not verified on (`L`), where UnityPy renders it: unityrs's own
225    /// refusal (Tier U, `PARITY.md` section 19.2).
226    #[error("the sprite renderer is not verified on a sheet of mode {mode}")]
227    UnverifiedMode {
228        /// Pillow's name for the mode.
229        mode: &'static str,
230    },
231    /// `mask_sprite`'s `assert positions` (`AssertionError`).
232    #[error("No vertices found in sprite mesh!")]
233    NoVertices,
234    /// A tuple unpacked into `expected` names (`ValueError`): `got` fewer,
235    /// or `None` for more.
236    #[error("{}", unpack_message(*expected, *got))]
237    Unpack {
238        /// The names.
239        expected: usize,
240        /// The tuple's length, when shorter.
241        got: Option<usize>,
242    },
243    /// An index past a list (`IndexError` "list index out of range"), or
244    /// past a tuple when `tuple` ("tuple index out of range").
245    #[error("{} index out of range", if *tuple { "tuple" } else { "list" })]
246    Index {
247        /// A tuple's, else a list's.
248        tuple: bool,
249    },
250    /// `render_sprite_mesh`: every axis of the vertices varies
251    /// (`ValueError`).
252    #[error("Can't process 3d sprites!")]
253    Sprite3d,
254    /// `render_sprite_mesh`: no submesh with vertices (`ValueError`).
255    #[error("No triangles found in mesh!")]
256    NoTriangles,
257    /// The standalone mesh renderer was given no UV coordinates.
258    #[error("No UV coordinates found in sprite mesh!")]
259    NoUv,
260    /// `Image.new` of a negative side (`ValueError`).
261    #[error("Width and height must be >= 0")]
262    NegativeSize,
263    /// The atlas holds no render data for the sprite's key: the
264    /// `StopIteration` of `next()` (`:78`).
265    #[error("the atlas has no render data for the sprite's m_RenderDataKey")]
266    NoAtlasData,
267    /// The Sprite's `m_SpriteAtlas` does not resolve: the caller found no
268    /// object for it, where UnityPy's `deref_parse_as_object` raises its
269    /// own error (Tier U).
270    #[error("the sprite's m_SpriteAtlas does not resolve")]
271    AtlasUnresolved,
272    /// A field the render reads is missing, or not of the type its
273    /// typetree gives it, where UnityPy's behaviour is not characterised
274    /// (Tier U): named by its path.
275    #[error("the sprite's {0} is missing or of another type")]
276    Malformed(&'static str),
277    /// The mesh's own error (`unityrs_meshdecode`).
278    #[error(transparent)]
279    Mesh(#[from] MeshError),
280    /// A canvas of more than [`crate::MAX_PIXELS`] pixels: the bound
281    /// UnityPy does not have (`PARITY.md` section 19.3).
282    #[error("the sprite's {what} is past the renderer's bound")]
283    TooLarge {
284        /// What: `"canvas"`, every image the render makes.
285        what: &'static str,
286    },
287    /// A buffer's charge or a loop's work, refused by the caller's meter.
288    #[error(transparent)]
289    Charge(#[from] ChargeError),
290    /// A panic in the render, caught ([`crate::contain()`]).
291    #[error("the sprite's render panicked: {}", .0.message())]
292    Panicked(Payload),
293}
294
295const _: () = crate::send_sync::<SpriteError>();
296
297fn unpack_message(expected: usize, got: Option<usize>) -> String {
298    match got {
299        Some(n) => format!("not enough values to unpack (expected {expected}, got {n})"),
300        None => format!("too many values to unpack (expected {expected})"),
301    }
302}
303
304impl SpriteError {
305    /// The class and message of the exception UnityPy raises where this
306    /// error is returned, or `None` where it raises none (a bound, a
307    /// charge, a panic, a Tier U refusal) or the mesh's error has none.
308    #[must_use]
309    pub fn python(&self) -> Option<(&'static str, String)> {
310        let class = match self {
311            Self::CropRightLeft
312            | Self::CropLowerUpper
313            | Self::RoundNan
314            | Self::Rotation(_)
315            | Self::Unpack { .. }
316            | Self::Sprite3d
317            | Self::NoTriangles
318            | Self::NoUv
319            | Self::NegativeSize
320            | Self::AlphaSizeMismatch
321            | Self::AlphaBandCount => "ValueError",
322            Self::RoundInfinity | Self::CIntOverflow { .. } | Self::CLongOverflow => {
323                "OverflowError"
324            }
325            Self::DecompressionBomb { .. } => "DecompressionBombError",
326            Self::NoVertices => "AssertionError",
327            Self::Index { .. } => "IndexError",
328            Self::SolveCast => "UFuncTypeError",
329            // `PyErr_NoMemory()`'s, which has no message.
330            Self::ImageTooWide => return Some(("MemoryError", String::new())),
331            // `next()`'s `StopIteration`, which has no message.
332            Self::NoAtlasData => return Some(("StopIteration", String::new())),
333            Self::Mesh(e) => return e.python(),
334            Self::Malformed(_)
335            | Self::UnverifiedMode { .. }
336            | Self::AtlasUnresolved
337            | Self::TooLarge { .. }
338            | Self::Charge(_)
339            | Self::Panicked(_) => {
340                return None;
341            }
342        };
343        Some((class, self.to_string()))
344    }
345}
346
347impl From<DecodeError> for SpriteError {
348    /// [`crate::contain()`]'s errors: a panic, or a charge.
349    fn from(e: DecodeError) -> Self {
350        match e {
351            DecodeError::Panicked { payload } => Self::Panicked(payload),
352            DecodeError::Charge(c) => Self::Charge(c),
353            // `contain` returns no other; a check of the decode's is no
354            // render's.
355            _ => Self::Malformed("decode"),
356        }
357    }
358}
359
360/// One sprite's image (module docs): `sheet` is the render data's texture
361/// (and alpha texture), `data` its rectangle and settings with the
362/// Sprite's `m_PixelsToUnits`, and `mesh` processes the Sprite's own
363/// `m_RD` (`MeshHandler(m_Sprite.m_RD, version).process()`), called only
364/// for a tight sprite, where UnityPy calls it. The image is charged to
365/// `meter`, and every buffer and loop on the way; the pixel work runs
366/// under [`crate::contain()`].
367pub fn render<'p>(
368    sheet: &Sheet<'_>,
369    data: &SpriteData,
370    mesh: impl FnOnce() -> Result<Processed<'p>, MeshError>,
371    meter: &Arc<Meter>,
372) -> Result<Image, SpriteError> {
373    render::render(sheet, data, mesh, meter)
374}
375
376/// Runs a pixel loop over buffers already charged under
377/// [`crate::contain()`]: a panic in it is [`SpriteError::Panicked`].
378pub(crate) fn contained<T>(f: impl FnOnce() -> T) -> Result<T, SpriteError> {
379    crate::contain(std::panic::AssertUnwindSafe(|| Ok(f()))).map_err(SpriteError::from)
380}