Identity # function

function : Identity() ~ Float[]

Return

IdentityInto # function

Identity, written into a buffer the caller owns. ## Why every builder here has an Into twin A matrix is a Float[16], and the returning forms allocate one per call. At one or two matrices per object per frame that is hundreds of arrays a second, which is enough to trigger a collection mid-frame -- the classic stutter. Objeck's 2D SDL renderer had to be rewritten once for exactly this. Four of these builders were worse than one allocation: Translation, RotationX, RotationY and RotationZ each called Identity() and then overwrote it, so they allocated twice. Now the returning form is the thin one, wrapping the Into form. Reuse one buffer per thing you draw, filled fresh each frame.

function : IdentityInto(out:Float[]) ~ Nil

Parameters

Inverse # function

Inverse of a 4x4 matrix, by cofactor expansion. Needed for lighting -- the normal matrix is the transposed inverse of the model matrix, and anything but a uniform scale makes the difference visible -- and for turning a view matrix back into a camera position. Returns the identity when the matrix is singular, which is the same choice LookAt makes for a degenerate basis: a wrong-but-usable matrix rather than a crash or a buffer full of infinities.

function : Inverse(m:Float[]) ~ Float[]

Parameters

Return

InverseInto # function

Inverse into a caller's buffer.

function : InverseInto(out:Float[], m:Float[]) ~ Bool

Parameters

Return

LookAt # function

A right-handed view matrix for a camera anywhere, looking anywhere. This is what lets a camera orbit or track a subject rather than sit on the +Z axis. Degenerate input -- eye equal to target, or an up vector parallel to the view direction -- yields identity rather than NaNs.

function : LookAt(eye:Vector3, target:Vector3, up:Vector3) ~ Float[]

Parameters

Return

LookAtInto # function

LookAt into a caller's buffer, for a camera that is not a Camera -- a light looking at a scene, say. Camera->GetViewMatrixInto is the cheaper route when there is a Camera.

function : LookAtInto(out:Float[], eye:Vector3, target:Vector3, up:Vector3) ~ Nil

Parameters

LookAtOrigin # function

A view matrix that steps back along +Z and looks at the origin. The smallest useful camera; use LookAt for one that can move.

function : LookAtOrigin(distance:Float) ~ Float[]

Parameters

Return

Multiply # function

Matrix product.

function : Multiply(lhs:Float[], rhs:Float[]) ~ Float[]

Parameters

Return

MultiplyInto # function

Matrix product written into a buffer the caller owns. Exists so a draw loop can avoid allocating. Multiply returns a fresh Float[16] every call, which at one or two matrices per object per frame is hundreds of arrays a second -- enough to trigger a collection mid-frame, the classic stutter. Scene uses this with a scratch buffer it keeps.

function : MultiplyInto(out:Float[], lhs:Float[], rhs:Float[]) ~ Nil

Parameters

Orthographic # function

Orthographic projection: no perspective, so distance does not shrink anything. Two uses. A 2D overlay -- a HUD, a minimap -- drawn in pixel coordinates. And, less obviously, a directional light's view of a scene: a light infinitely far away casts parallel rays, so the projection that matches it is parallel too. A shadow map rendered through a perspective projection is wrong in a way that looks like the shadows are being cast by a nearby lamp.

function : Orthographic(left:Float, right:Float, bottom:Float, top:Float, near:Float, far:Float) ~ Float[]

Parameters

Return

OrthographicBox # function

A square orthographic box centred on the origin -- the usual shape for a directional light's view of a scene.

function : OrthographicBox(extent:Float, near:Float, far:Float) ~ Float[]

Parameters

Return

OrthographicInto # function

Orthographic projection into a caller's buffer.

function : OrthographicInto(out:Float[], left:Float, right:Float, bottom:Float, top:Float, near:Float, far:Float) ~ Nil

Parameters

Perspective # function

Right-handed perspective projection, mapping to GL's -1..1 depth range.

function : Perspective(fov_radians:Float, aspect:Float, near:Float, far:Float) ~ Float[]

Parameters

Return

PerspectiveDegrees # function

Perspective with the field of view in DEGREES, and sensible clip planes. Both call sites spelled the fov as a bare expression -- Float->Pi() / 4.0 and Float->Pi() / 3.0 -- and repeated the same 0.1 and 100.0 clip distances verbatim. Degrees are how field of view is actually discussed; 60 is a normal first-person view, 45 a slightly telephoto one.

function : PerspectiveDegrees(fov_degrees:Float, aspect:Float) ~ Float[]

Parameters

Return

PerspectiveDegrees # function

Perspective in degrees with explicit clip planes.

function : PerspectiveDegrees(fov_degrees:Float, aspect:Float, near:Float, far:Float) ~ Float[]

Parameters

Return

PerspectiveInto # function

Perspective into a caller's buffer. See IdentityInto. Note this zeroes the destination first, so unlike the other Into forms it must NOT be handed a buffer that already holds something wanted -- a projection matrix is mostly zeroes, and leaving a previous matrix's values in the untouched slots would produce nonsense rather than a projection.

function : PerspectiveInto(out:Float[], fov_radians:Float, aspect:Float, near:Float, far:Float) ~ Nil

Parameters

RotationX # function

Rotation about the X axis.

function : RotationX(radians:Float) ~ Float[]

Parameters

Return

RotationXInto # function

Rotation about X, into a caller's buffer. See IdentityInto.

function : RotationXInto(out:Float[], radians:Float) ~ Nil

Parameters

RotationY # function

Rotation about the Y axis.

function : RotationY(radians:Float) ~ Float[]

Parameters

Return

RotationYInto # function

Rotation about Y, into a caller's buffer. See IdentityInto.

function : RotationYInto(out:Float[], radians:Float) ~ Nil

Parameters

RotationYXZ # function

Yaw, pitch and roll, allocating.

function : RotationYXZ(yaw:Float, pitch:Float, roll:Float) ~ Float[]

Parameters

Return

RotationYXZInto # function

Yaw, then pitch, then roll -- the same result as RotationY * RotationX * RotationZ, computed directly. Spelling that composition out costs six allocations (three builders, each of which allocated twice) plus two matrix products, per object per frame. This is nine multiplies and no allocation. The derivation is verified against the composition in the regression suite, because a transposed or sign-flipped term here produces a rotation that looks plausible until something is mirrored.

function : RotationYXZInto(out:Float[], yaw:Float, pitch:Float, roll:Float) ~ Nil

Parameters

RotationZ # function

Rotation about the Z axis.

function : RotationZ(radians:Float) ~ Float[]

Parameters

Return

RotationZInto # function

Rotation about Z, into a caller's buffer. See IdentityInto.

function : RotationZInto(out:Float[], radians:Float) ~ Nil

Parameters

Scale # function

Uniform scale matrix.

function : Scale(s:Float) ~ Float[]

Parameters

Return

ScaleXYZ # function

Non-uniform scale. This is what lets one unit-cube mesh become every box in a scene -- walls, floors and obstacles -- instead of uploading a separate mesh per shape.

function : ScaleXYZ(x:Float, y:Float, z:Float) ~ Float[]

Parameters

Return

ScaleXYZInto # function

Non-uniform scale, into a caller's buffer. See IdentityInto.

function : ScaleXYZInto(out:Float[], x:Float, y:Float, z:Float) ~ Nil

Parameters

Translation # function

Translation matrix.

function : Translation(x:Float, y:Float, z:Float) ~ Float[]

Parameters

Return

TranslationInto # function

Translation, into a caller's buffer. See IdentityInto.

function : TranslationInto(out:Float[], x:Float, y:Float, z:Float) ~ Nil

Parameters

TranslationScale # function

Translate and scale, allocating.

function : TranslationScale(x:Float, y:Float, z:Float, sx:Float, sy:Float, sz:Float) ~ Float[]

Parameters

Return

TranslationScaleInto # function

Translate and scale in one step, with no multiply at all. This is the whole of a Box's transform -- position plus half-extents -- and it is the single most common model matrix there is. Composing it as Multiply(Translation(...), ScaleXYZ(...)) costs two allocations and sixty-four multiply-adds to produce a matrix whose scale is its diagonal and whose translation is its last column. So write those directly.

function : TranslationScaleInto(out:Float[], x:Float, y:Float, z:Float, sx:Float, sy:Float, sz:Float) ~ Nil

Parameters

Transpose # function

Transpose: rows become columns.

function : Transpose(m:Float[]) ~ Float[]

Parameters

Return

TransposeInto # function

Transpose into a caller's buffer.

function : TransposeInto(out:Float[], m:Float[]) ~ Nil

Parameters