fixed32.h File Reference

SNES 16.16 Fixed-Point Math. More...

#include <snes/types.h>
#include <snes/math.h>

Go to the source code of this file.

Macros
#define	FIX32(x)
	Convert integer to fixed32 (shift left 16).
#define	FIX32_FRAC(x)
	Get fractional part of a fixed32 as a u16 (0..65535).
#define	FIX32_MAKE(i, f)
	Build a fixed32 from integer + fractional parts.
#define	UNFIX32(x)
	Convert fixed32 to integer (floor).

Typedefs
typedef s32	fixed32
	16.16 signed fixed-point type

Functions
fixed32	fix32Abs (fixed32 x)
	Absolute value of a fixed32.
fixed32	fix32Clamp (fixed32 x, fixed32 min, fixed32 max)
	Clamp x to [min, max].
fixed32	fix32Cos (u8 angle)
fixed32	fix32Div (fixed32 a, fixed32 b)
	16.16 fixed-point divide
fixed32	fix32Lerp (fixed32 a, fixed32 b, fixed32 t)
	16.16 fixed-point linear interpolation
fixed32	fix32Max (fixed32 a, fixed32 b)
	Maximum of two fixed32.
fixed32	fix32Min (fixed32 a, fixed32 b)
	Minimum of two fixed32.
fixed32	fix32Mul (fixed32 a, fixed32 b)
	16.16 fixed-point multiply
fixed32	fix32Sin (u8 angle)
	16.16 fixed-point sine of an 8-bit angle (0..255 = 0..360°)

Detailed Description

SNES 16.16 Fixed-Point Math.

32-bit signed fixed-point arithmetic for world-space coordinates, physics velocity accumulators, and any quantity that needs more range or precision than the lib's 8.8 fixed type from <snes/math.h>.

Overview

• 16-bit integer part: -32768 to +32767 (enough for a 32k-tile world)
• 16-bit fractional part: 1/65536 ≈ 0.0000153 precision

The lib's existing 8.8 fixed type (range ±128, precision 1/256) is fine for screen-space coords and velocities. Use fixed32 when:

• The world is larger than 128 tiles in any dimension.
• Accumulator drift over many frames matters (e.g. sub-pixel motion that must integrate without bias over thousands of frames).
• Two values multiplied risk overflowing 8.8 (e.g. velocity × time).

u8 angle = 0;                           // 0-255 = one full turn
angle += 1;                             // ~1.4 degrees per frame
fixed32 vx = fix32Mul(FIX32(2), fix32Sin(angle));   // fix32Sin takes a u8

Operations available

Operation	Helper	Cost (cycles, approx)
Add/sub	+ / - on s32	inline, 8-10
Negate	unary -	inline
Abs	fix32Abs	inline
Clamp	fix32Clamp	inline
Multiply	fix32Mul	~280 (16 × 8x8 hw)

Division (fix32Div, 0 on a zero divisor), sine / cosine (fix32Sin, fix32Cos) and fix32Lerp are declared below. (This line called them "deferred" long after they shipped.)

Sign convention

fixed32 is signed two's complement s32. Negative values are stored with the sign bit at position 31. Use FIX32(-5) for negative integers; the bit pattern handles itself. fix32Mul handles signs internally (XOR-then-negate-result).

Author

OpenSNES Team

Copyright

MIT License

Macro Definition Documentation

FIX32

#define FIX32

(

x

)

Value:

((fixed32)((u32)(s32)(x) << 16))

Convert integer to fixed32 (shift left 16).

Parameters

x	Integer value (-32768 to +32767)

Returns

fixed32 representation

fixed32 pos = FIX32(1000);   // 1000.0
fixed32 half = FIX32(1) >> 1; // 0.5 (32768 in raw)

FIX32_FRAC

#define FIX32_FRAC

(

x

)

Value:

((u16)((fixed32)(x) & 0xFFFF))

Get fractional part of a fixed32 as a u16 (0..65535).

Parameters

x	fixed32 value

Returns

Low 16 bits (the fractional part)

fixed32 q = FIX32(1) >> 2;       // 0.25
u16 frac = FIX32_FRAC(q);        // 16384

FIX32_MAKE

#define FIX32_MAKE	(		i,
			f )

Value:

(((fixed32)(s16)(i) << 16) | (fixed32)(u16)(f))

Build a fixed32 from integer + fractional parts.

Parameters

i	Integer part (s16)
f	Fractional part (u16)

Returns

Combined fixed32

fixed32 v = FIX32_MAKE(100, 32768);  // 100.5

UNFIX32

#define UNFIX32

(

x

)

Value:

((s16)((fixed32)(x) >> 16))

Convert fixed32 to integer (floor).

Parameters

x	fixed32 value

Returns

Integer part as s16

Rounds toward MINUS infinity, not toward zero: the cc65816 backend implements the signed right shift as arithmetic, so UNFIX32 of -0.5 is -1. (This block claimed "toward zero for both signs" until 2026-09-20.)

fixed32 pos = FIX32(1000) + 32768;  // 1000.5
s16 screen = UNFIX32(pos);          // 1000

Typedef Documentation

fixed32

typedef s32 fixed32

16.16 signed fixed-point type

Range: -32768.0 to +32767.99998 Precision: 1/65536 ≈ 0.0000153

Function Documentation

fix32Abs()

fixed32 fix32Abs ( fixed32 x )

inline

Absolute value of a fixed32.

Parameters

x

fixed32

Returns

|x| (or INT32_MIN for INT32_MIN — the one-value undefined edge)

The "undefined" edge is for x = -2^31 exactly, which has no positive representation in s32. The function returns INT32_MIN unchanged in that case, matching standard library abs behavior on overflow.

fix32Clamp()

fixed32 fix32Clamp ( fixed32 x, fixed32 min, fixed32 max )

inline

Clamp x to [min, max].

Returns

min if x < min, max if x > max, else x

Caller's responsibility to ensure min <= max.

fix32Cos()

fixed32 fix32Cos

(

u8

angle

)

fix32Div()

fixed32 fix32Div	(	fixed32	a,
		fixed32	b )

16.16 fixed-point divide

Parameters

a	Numerator
b	Denominator (must be non-zero; division by zero is undefined)

Returns

(a / b) at 16.16 precision (low 32 bits of (a << 16) / b)

Algorithm: 48-iteration bit-by-bit long divide of (|a| << 16) by |b|, with sign-magnitude handling. The 48-bit dividend doesn't fit in a single 32-bit register, so we can't reuse tcc_udivmod32 directly — the custom loop processes one quotient bit per iteration with an 80-bit working register.

Cycles: ~1500 (much slower than fix32Mul; use sparingly in hot loops).

A zero divisor returns 0, like fixDiv() / div16() / mod16().

Warning

Not callable from an nmiSet() callback — see fix32Mul().

fixed32 velocity = fix32Div(distance, time);
fixed32 ratio = fix32Div(width, FIX32(2));  // halve width

fix32Lerp()

fixed32 fix32Lerp ( fixed32 a, fixed32 b, fixed32 t )

inline

16.16 fixed-point linear interpolation

Parameters

a	Start value (returned when t = 0)
b	End value (returned when t = FIX32(1))
t	Interpolation parameter in 16.16, typically [0, FIX32(1)]

Returns

a + (b - a) * t at 16.16 precision

Inline: just a + fix32Mul(b - a, t). No new asm — the multiply carries the cost (~280 cycles), the add is one Kl op.

Extrapolation is supported: t > FIX32(1) extends past b, t < 0 extends before a. The caller is responsible for clamping if a strict interpolation is needed.

Range caveat: b - a is a 32-bit difference. When a and b have opposite signs and |b - a| reaches 32768.0 (say a = FIX32(-20000), b = FIX32(20000)) it wraps and the result is wrong, not imprecise — nothing in the multiply can recover it. For such spans use fix32Mul(a, FIX32(1) - t) + fix32Mul(b, t) (one extra mul, no difference). (Until 2026-10-04 this note spoke of lost precision.)

fixed32 midpoint = fix32Lerp(p0, p1, FIX32(1) >> 1);  // (p0 + p1) / 2
fixed32 eased = fix32Lerp(start, end, easing_curve_t);

fix32Max()

fixed32 fix32Max ( fixed32 a, fixed32 b )

inline

Maximum of two fixed32.

fix32Min()

fixed32 fix32Min ( fixed32 a, fixed32 b )

inline

Minimum of two fixed32.

fix32Mul()

fixed32 fix32Mul	(	fixed32	a,
		fixed32	b )

16.16 fixed-point multiply

Parameters

a	First operand
b	Second operand

Returns

(a * b) at 16.16 precision (bits 16-47 of the full 64-bit product)

Algorithm: three 16×16→32 unsigned partial products (a_l*b_l, a_l*b_h, a_h*b_l) + one 16×16→16 (low 16 of a_h*b_h) combined as result = ml1 + ml2 + (ll >> 16) + (hh_lo << 16) Each 16×16→32 uses 4 hardware 8×8 multiplies — ~280 cycles total.

Sign-magnitude internally: result = sign(a) XOR sign(b) applied to the unsigned 32-bit magnitude. Overflow wraps modulo 2^32.

fixed32 area = fix32Mul(FIX32(width), FIX32(height));
fixed32 dy = fix32Mul(velocity, FIX32(dt));

Warning

NOT safe inside an nmiSet() callback, like fixMul(): it drives the hardware multiplier ($4202/$4203) and uses static scratch, so an NMI-context call corrupts a main-thread call in flight. fix32Div(), fix32Lerp(), fix32Sin() and fix32Cos() share the scratch and the restriction (the sine and cosine write the same result words).

fix32Sin()

fixed32 fix32Sin

(

u8

angle

)

16.16 fixed-point sine of an 8-bit angle (0..255 = 0..360°)

Parameters

angle

0=0°, 64=90°, 128=180°, 192=270°

Returns

sin(angle) in 16.16, range [FIX32(-1), FIX32(1)]

Lifted from the existing 8.8 fixSin LUT by shifting left 8 bits to fill the upper half of the 16-bit fractional field. The lower 8 bits are always zero (no precision gained beyond what the 8.8 LUT provides). Cost: one LUT lookup, a sign-extend and a shift (the measured figure is in docs/PERF.md; "about 30 cycles" stood here until 2026-10-04).

Precision: each LUT step is 1/256 ≈ 0.0039, so for fine animation (sub-pixel motion over many frames) this is adequate. For high- precision physics that compound thousands of operations, the 8-bit-fractional limit may show as drift; a future chantier could add a 16-bit LUT for a 256× precision improvement at 512 bytes ROM.

fixed32 dx = fix32Mul(speed, fix32Sin(angle));

Warning

NOT safe inside an nmiSet() callback: both write the result scratch of fix32Mul() (f32_res_lo/hi), so a call from the NMI corrupts a main-thread fix32Mul() / fix32Div() in flight — the warning on fix32Mul() applies to them (library audit, 2026-10-04).