Web Engine Dev

Appearance

@web-engine-dev/math

@web-engine-dev/math / Mat4

Class: Mat4 ​

A 4x4 matrix stored in column-major order.

Memory layout (column-major, matching WebGPU/OpenGL): | m0 m4 m8 m12 | | m1 m5 m9 m13 | | m2 m6 m10 m14 | | m3 m7 m11 m15 |

Column vectors: [m0,m1,m2,m3], [m4,m5,m6,m7], [m8,m9,m10,m11], [m12,m13,m14,m15]

Default operations are immutable and return new instances. For performance-critical code paths (game loops, hot paths), use the mutable variants (suffix Mut) or static out-parameter methods (suffix Out) to avoid allocations.

Constructors ​

Constructor ​

new Mat4(data?): Mat4

Parameters ​

data? ​

ArrayLike<number>

Returns ​

Mat4

Methods ​

add() ​

add(m): Mat4

Parameters ​

m ​

Mat4

Returns ​

Mat4

copyMut() ​

copyMut(other): this

Copies another matrix into this matrix.

Parameters ​

other ​

Mat4

Source matrix

Returns ​

this

this for chaining

copyToArray() ​

copyToArray(arr, offset?): void

Parameters ​

arr ​

number[] | Float32Array<ArrayBufferLike>

offset? ​

number = 0

Returns ​

void

decompose() ​

decompose(outTranslation, outRotation, outScale): boolean

Decomposes this matrix into translation, rotation, and scale. Assumes the matrix has no skew.

Parameters ​

outTranslation ​

Vec3

Output translation vector

outRotation ​

Output rotation quaternion

w ​

number

x ​

number

y ​

number

z ​

number

outScale ​

Vec3

Output scale vector

Returns ​

boolean

true if decomposition succeeded

Example ​

ts
const worldMatrix = entity.getWorldMatrix();
const position = new Vec3();
const rotation = { x: 0, y: 0, z: 0, w: 1 };
const scale = new Vec3();
worldMatrix.decompose(position, rotation, scale);

determinant() ​

determinant(): number

Returns ​

number

equals() ​

equals(m, epsilon?): boolean

Parameters ​

m ​

Mat4

epsilon? ​

number = 0

Returns ​

boolean

get() ​

get(row, col): number

Parameters ​

row ​

number

col ​

number

Returns ​

number

getColumn() ​

getColumn(col): Vec4

Parameters ​

col ​

number

Returns ​

Vec4

getRotationScale() ​

getRotationScale(): Mat3

Extract the upper-left 3x3 rotation/scale matrix.

Returns ​

Mat3

getRow() ​

getRow(row): Vec4

Parameters ​

row ​

number

Returns ​

Vec4

getScale() ​

getScale(): Vec3

Returns ​

Vec3

getTranslation() ​

getTranslation(): Vec3

Returns ​

Vec3

invert() ​

invert(): Mat4 | null

Returns ​

Mat4 | null

invertMut() ​

invertMut(): Mat4 | null

Inverts this matrix in place.

Returns ​

Mat4 | null

this for chaining, or null if matrix is singular

mul() ​

mul(s): Mat4

Parameters ​

s ​

number

Returns ​

Mat4

mulMat() ​

mulMat(m): Mat4

Matrix-matrix multiplication (this * m).

Parameters ​

m ​

Mat4

Returns ​

Mat4

multiplyMut() ​

multiplyMut(m): this

Multiplies this matrix by another matrix in place (this = this * m).

Parameters ​

m ​

Mat4

Matrix to multiply with

Returns ​

this

this for chaining

mulVec3Direction() ​

mulVec3Direction(v): Vec3

Transform a Vec3 as a direction (w=0).

Parameters ​

v ​

Vec3

Returns ​

Vec3

mulVec3Point() ​

mulVec3Point(v): Vec3

Transform a Vec3 as a point (w=1) and divide by w.

Parameters ​

v ​

Vec3

Returns ​

Vec3

mulVec4() ​

mulVec4(v): Vec4

Transform a Vec4 by this matrix.

Parameters ​

v ​

Vec4

Returns ​

Vec4

normalMatrix() ​

normalMatrix(): Mat3 | null

Compute the normal matrix (inverse transpose of upper-left 3x3).

Returns ​

Mat3 | null

normalMatrixOut() ​

normalMatrixOut(target): boolean

Compute the normal matrix and write to target Mat3 (no allocations). Normal matrix = transpose(inverse(upper-left 3x3))

This is the allocation-free version for performance-critical code paths. Use this in render loops to avoid GC pressure from per-frame allocations.

Parameters ​

target ​

Mat3

Pre-allocated Mat3 to write result into

Returns ​

boolean

true if successful, false if matrix is singular

Example ​

ts
// In a render loop - reuse the same Mat3 each frame
const normalMatrix = Mat3.identity();
worldMatrix.normalMatrixOut(normalMatrix);
// normalMatrix now contains the result

preMultiplyMut() ​

preMultiplyMut(m): this

Pre-multiplies this matrix by another (result = m * this). Useful for applying parent transforms.

Parameters ​

m ​

Mat4

Matrix to pre-multiply with

Returns ​

this

this for chaining

scaleMut() ​

scaleMut(s): this

Applies a uniform scale to this matrix (post-multiply). Equivalent to this = this * scale(s) but faster.

Parameters ​

s ​

number

Scale factor

Returns ​

this

this for chaining

scaleVecMut() ​

scaleVecMut(v): this

Applies a scale from a vector to this matrix.

Parameters ​

v ​

Vec3

Scale vector

Returns ​

this

this for chaining

scaleXYZMut() ​

scaleXYZMut(sx, sy, sz): this

Applies a non-uniform scale to this matrix (post-multiply).

Parameters ​

sx ​

number

Scale X

sy ​

number

Scale Y

sz ​

number

Scale Z

Returns ​

this

this for chaining

setFromElementsMut() ​

setFromElementsMut(m00, m01, m02, m03, m10, m11, m12, m13, m20, m21, m22, m23, m30, m31, m32, m33): this

Sets this matrix from individual elements (no allocations). Order matches Mat4.fromArray and internal column-major layout.

Parameters ​

m00 ​

number

m01 ​

number

m02 ​

number

m03 ​

number

m10 ​

number

m11 ​

number

m12 ​

number

m13 ​

number

m20 ​

number

m21 ​

number

m22 ​

number

m23 ​

number

m30 ​

number

m31 ​

number

m32 ​

number

m33 ​

number

Returns ​

this

setFromRotationMut() ​

setFromRotationMut(q): this

Sets this matrix to a rotation matrix from a quaternion.

Parameters ​

q ​

Quaternion representing rotation

w ​

number

x ​

number

y ​

number

z ​

number

Returns ​

this

this for chaining

setFromScaleMut() ​

setFromScaleMut(v): this

Sets this matrix to a scale matrix.

Parameters ​

v ​

Vec3

Scale vector

Returns ​

this

this for chaining

setFromTranslationMut() ​

setFromTranslationMut(v): this

Sets this matrix to a translation matrix.

Parameters ​

v ​

Vec3

Translation vector

Returns ​

this

this for chaining

setFromTRSMut() ​

setFromTRSMut(translation, rotation, scale): this

Sets this matrix to a TRS matrix.

Parameters ​

translation ​

Vec3

Translation vector

rotation ​

Rotation quaternion

w ​

number

x ​

number

y ​

number

z ​

number

scale ​

Vec3

Scale vector

Returns ​

this

this for chaining

setIdentityMut() ​

setIdentityMut(): this

Sets this matrix to the identity matrix.

Returns ​

this

this for chaining

setTranslationMut() ​

setTranslationMut(x, y, z): this

Sets the translation component of this matrix without affecting rotation/scale.

Parameters ​

x ​

number

Translation X

y ​

number

Translation Y

z ​

number

Translation Z

Returns ​

this

this for chaining

setTranslationVecMut() ​

setTranslationVecMut(v): this

Sets the translation component from a vector.

Parameters ​

v ​

Vec3

Translation vector

Returns ​

this

this for chaining

sub() ​

sub(m): Mat4

Parameters ​

m ​

Mat4

Returns ​

Mat4

toArray() ​

toArray(): number[]

Returns ​

number[]

toFloat32Array() ​

toFloat32Array(): Float32Array

Returns ​

Float32Array

toString() ​

toString(): string

Returns ​

string

transformDirectionMut() ​

transformDirectionMut(v): Vec3

Transforms a Vec3 as a direction in place.

Parameters ​

v ​

Vec3

Direction vector (modified in place)

Returns ​

Vec3

v for chaining

transformVec3Mut() ​

transformVec3Mut(v): Vec3

Transforms a Vec3 as a point (w=1) in place. Returns a large vector if w is near zero to avoid Infinity/NaN.

Parameters ​

v ​

Vec3

Vector to transform (modified in place)

Returns ​

Vec3

v for chaining

translateMut() ​

translateMut(x, y, z): this

Applies a translation to this matrix (post-multiply). Equivalent to this = this * translation(x, y, z) but faster.

Parameters ​

x ​

number

Translation X

y ​

number

Translation Y

z ​

number

Translation Z

Returns ​

this

this for chaining

translateVecMut() ​

translateVecMut(v): this

Applies a translation from a vector to this matrix.

Parameters ​

v ​

Vec3

Translation vector

Returns ​

this

this for chaining

transpose() ​

transpose(): Mat4

Returns ​

Mat4

transposeMut() ​

transposeMut(): this

Transposes this matrix in place.

Returns ​

this

this for chaining

fromArray() ​

static fromArray(arr, offset?): Mat4

Parameters ​

arr ​

ArrayLike<number>

offset? ​

number = 0

Returns ​

Mat4

fromColumns() ​

static fromColumns(c0, c1, c2, c3): Mat4

Parameters ​

c0 ​

Vec4

c1 ​

Vec4

c2 ​

Vec4

c3 ​

Vec4

Returns ​

Mat4

fromTRS() ​

static fromTRS(translation, rotation, scale): Mat4

Creates a TRS (Translation-Rotation-Scale) matrix in a single operation. More efficient than multiplying separate matrices.

Parameters ​

translation ​

Vec3

Translation vector

rotation ​

Rotation quaternion

w ​

number

x ​

number

y ​

number

z ​

number

scale ​

Vec3

Scale vector

Returns ​

Mat4

New TRS matrix

Example ​

ts
const position = new Vec3(10, 0, 5);
const rotation = Quat.fromEuler(0, Math.PI / 4, 0);  // 45° Y rotation
const scale = Vec3.one();
const worldMatrix = Mat4.fromTRS(position, rotation, scale);

identity() ​

static identity(): Mat4

Returns ​

Mat4

invertOut() ​

static invertOut(m, out): Mat4 | null

Inverts a matrix and writes the result to out.

Parameters ​

m ​

Mat4

Matrix to invert

out ​

Mat4

Output matrix

Returns ​

Mat4 | null

out for chaining, or null if matrix is singular

lookAt() ​

static lookAt(eye, target, up): Mat4

Creates a look-at view matrix.

Parameters ​

eye ​

Vec3

Camera position.

target ​

Vec3

Point to look at.

up ​

Vec3

Up vector.

Returns ​

Mat4

Example ​

ts
const eye = new Vec3(0, 5, 10);
const target = Vec3.zero();
const up = Vec3.up();
const viewMatrix = Mat4.lookAt(eye, target, up);

lookAtOut() ​

static lookAtOut(eye, target, up, out): Mat4

Writes a look-at view matrix into an existing Mat4 (no allocations).

Parameters ​

eye ​

Vec3

Camera position.

target ​

Vec3

Point to look at.

up ​

Vec3

Up vector.

out ​

Mat4

Output matrix to write into.

Returns ​

Mat4

multiplyChainOut() ​

static multiplyChainOut(matrices, out): Mat4

Computes the product of multiple matrices efficiently. More efficient than chaining multiply calls.

Parameters ​

matrices ​

readonly Mat4[]

Array of matrices to multiply (left to right)

out ​

Mat4

Output matrix

Returns ​

Mat4

out for chaining

multiplyOut() ​

static multiplyOut(a, b, out): Mat4

Multiplies two matrices and writes the result to out.

Parameters ​

a ​

Mat4

First matrix

b ​

Mat4

Second matrix

out ​

Mat4

Output matrix

Returns ​

Mat4

out for chaining

multiplyOutSafe() ​

static multiplyOutSafe(a, b, out): Mat4

Multiplies this matrix by another, storing result in out. Allows a === out or b === out safely.

Parameters ​

a ​

Mat4

First matrix

b ​

Mat4

Second matrix

out ​

Mat4

Output matrix

Returns ​

Mat4

out for chaining

orthographic() ​

static orthographic(left, right, bottom, top, near, far): Mat4

Creates an orthographic projection matrix.

Parameters ​

left ​

number

number

bottom ​

number

top ​

number

near ​

number

far ​

number

Returns ​

Mat4

orthographicOut() ​

static orthographicOut(left, right, bottom, top, near, far, out): void

Writes an orthographic projection matrix into an existing Mat4, avoiding allocation. Useful for hot paths such as shadow cascade rendering where one matrix must be computed per cascade per frame.

Parameters ​

left ​

number

Left clipping plane

right ​

number

Right clipping plane

bottom ​

number

Bottom clipping plane

top ​

number

Top clipping plane

near ​

number

Near clipping plane

far ​

number

Far clipping plane

out ​

Mat4

Target matrix to write into (mutated in-place)

Returns ​

void

perspective() ​

static perspective(fovY, aspect, near, far): Mat4

Creates a perspective projection matrix. Uses standard WebGPU depth range (near=0, far=1). For reverse-Z (better depth precision), use perspectiveReverseZ().

Parameters ​

fovY ​

number

Vertical field of view in radians.

aspect ​

number

Aspect ratio (width / height).

near ​

number

Near plane distance.

far ​

number

Far plane distance.

Returns ​

Mat4

Example ​

ts
const fov = Math.PI / 4;  // 45 degrees
const aspect = canvas.width / canvas.height;
const projMatrix = Mat4.perspective(fov, aspect, 0.1, 1000);

perspectiveOut() ​

static perspectiveOut(fovY, aspect, near, far, out): Mat4

Writes a perspective projection matrix into an existing Mat4 (no allocations).

Parameters ​

fovY ​

number

aspect ​

number

near ​

number

far ​

number

out ​

Mat4

Returns ​

Mat4

perspectiveReverseZ() ​

static perspectiveReverseZ(fovY, aspect, near, far): Mat4

Creates a perspective projection matrix with reverse-Z. Depth goes from 1 (near) to 0 (far) for better precision.

Parameters ​

fovY ​

number

aspect ​

number

near ​

number

far ​

number

Returns ​

Mat4

rotationAxis() ​

static rotationAxis(axis, angle): Mat4

Creates a rotation matrix around an arbitrary axis.

Parameters ​

axis ​

Vec3

Normalized rotation axis.

angle ​

number

Rotation angle in radians.

Returns ​

Mat4

rotationX() ​

static rotationX(angle): Mat4

Creates a rotation matrix around the X axis.

Parameters ​

angle ​

number

Rotation angle in radians.

Returns ​

Mat4

rotationY() ​

static rotationY(angle): Mat4

Creates a rotation matrix around the Y axis.

Parameters ​

angle ​

number

Rotation angle in radians.

Returns ​

Mat4

rotationZ() ​

static rotationZ(angle): Mat4

Creates a rotation matrix around the Z axis.

Parameters ​

angle ​

number

Rotation angle in radians.

Returns ​

Mat4

scale() ​

static scale(s): Mat4

Creates a uniform scale matrix.

Parameters ​

s ​

number

Returns ​

Mat4

scaling() ​

static scaling(sx, sy, sz): Mat4

Creates a non-uniform scale matrix.

Parameters ​

sx ​

number

sy ​

number

sz ​

number

Returns ​

Mat4

scalingVec() ​

static scalingVec(v): Mat4

Parameters ​

v ​

Vec3

Returns ​

Mat4

setTRSMut() ​

static setTRSMut(out, translation, rotation, scale): Mat4

Sets this matrix to a TRS (Translation-Rotation-Scale) matrix. More efficient than multiplying separate matrices.

Parameters ​

out ​

Mat4

Output matrix

translation ​

Vec3

Translation vector

rotation ​

Rotation quaternion

w ​

number

x ​

number

y ​

number

z ​

number

scale ​

Vec3

Scale vector

Returns ​

Mat4

out for chaining

transformDirectionOut() ​

static transformDirectionOut(m, v, out): Vec3

Transforms a Vec3 as a direction (w=0) and writes the result to out. Ignores translation component.

Parameters ​

m ​

Mat4

Transformation matrix

v ​

Vec3

Direction vector

out ​

Vec3

Output vector

Returns ​

Vec3

out for chaining

transformVec3Out() ​

static transformVec3Out(m, v, out): Vec3

Transforms a Vec3 as a point (w=1) and writes the result to out.

Parameters ​

m ​

Mat4

Transformation matrix

v ​

Vec3

Vector to transform

out ​

Vec3

Output vector

Returns ​

Vec3

out for chaining

translation() ​

static translation(x, y, z): Mat4

Creates a translation matrix.

Parameters ​

x ​

number

y ​

number

z ​

number

Returns ​

Mat4

translationVec() ​

static translationVec(v): Mat4

Parameters ​

v ​

Vec3

Returns ​

Mat4

transposeOut() ​

static transposeOut(m, out): Mat4

Transposes a matrix and writes the result to out.

Parameters ​

m ​

Mat4

Matrix to transpose

out ​

Mat4

Output matrix

Returns ​

Mat4

out for chaining

zero() ​

static zero(): Mat4

Returns ​

Mat4

Proprietary software. All rights reserved.

Copyright 2025-present Web Engine Dev