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}