Module int32 

Saturating 32-bit integer scalar helpers.

The PS1 has no FPU and the engine keeps all gameplay math in i32/i16 fixed-point, so the same small scalar helpers (absolute value that cannot overflow at MIN, a clamp into the GTE’s i16 vertex range, an integer square root for vector lengths) get re-implemented next to every consumer. This module owns them once. Every function is branch-light, allocation-free, and safe on the full input domain:

• abs_* saturate MIN to MAX instead of overflowing.
• square_i32_saturating returns i32::MAX once the true square would exceed i32.
• isqrt_i32 is the classic digit-by-digit (binary restoring) integer square root: exact floor(sqrt(n)), no multiplies.
• mul_q12_i32 multiplies an i32 by a Q1.12 factor without a 64-bit intermediate, splitting whole and fractional parts so the products stay inside i32.
• mul_div_i32, mul_shr_i32 and mul_shr_trunc_i32 are the signed a * b / c forms games otherwise spell as i64 expressions (which link __divdi3): bit-identical results, native mult/divu.
• isqrt_u64 and div_u64_by_u32 give full-width roots and 64-by-32 quotients in 32-bit operations.

Structs

InvariantDivisor31

Exact n / d for 0 <= n < 2^31 by one multu and a shift, for a divisor that is fixed across many dividends.

Functions

abs_i16

Absolute value of an i16, saturating i16::MIN to i16::MAX.

abs_i32

Absolute value of an i32, saturating i32::MIN to i32::MAX.

clamp_i16

Clamp an i32 into the i16 range (the GTE’s vertex domain).

div_u64_by_u32

floor((hi * 2^32 + lo) / divisor) for a quotient that fits u32, in 32-bit operations only.

isqrt_i32

Integer square root: exact floor(sqrt(value)) for positive inputs, 0 for zero and negative inputs.

isqrt_u32

Exact floor square root across the complete unsigned 32-bit domain.

isqrt_u64

Exact floor(sqrt(value)) across the complete unsigned 64-bit domain, with 32-bit operations and native multu only (no divide).

mul_div_i32

a * b / c through the full 64-bit product, truncated toward zero: identical to (i64::from(a) * i64::from(b) / i64::from(c)) as i32 for every input, with no 64-bit helper call.

mul_div_u32

Exact floor(a * b / divisor) when the quotient fits u32.

mul_q12_i32

Multiply an i32 by a Q1.12 factor (4096 = 1.0) without a 64-bit intermediate.

mul_q12_i32_wide

floor(value * q12 / 4096) through the full 64-bit product.

mul_shr_i32

(a * b) >> shift through the full 64-bit product: rounds toward negative infinity like an arithmetic shift, and wraps to the low 32 bits where the shifted value does not fit i32.

mul_shr_trunc_i32

a * b / 2^shift, truncated toward zero, through the full 64-bit product.

scroll_q8_wrapped

Signed Q8 texels/second, truncated toward zero and wrapped to a texture. period must be in 1..=256; a zero tick rate leaves only the phase.

square_i32_saturating

value * value, saturating to i32::MAX when the square would overflow (|value| > 46340, the largest i32 whose square fits).