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

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