mat4
The Mat4 interface represents a 4x4 matrix, stored as a 16-element array in column-major order. This type of matrix is commonly used in 3D geometry to represent transformations, including position, rotation, and scale (also known as a TRS matrix). These matrices are essential for defining the position, orientation, and size of objects in a 3D scene.
Certain matrices, such as TRS matrices, have efficiently computable inverses. In these cases, Mat4 allows for the inverse to be calculated in constant time, making it a very fast O(1) operation. Mat4 objects are created using the ecs.math.mat4 factory (Mat4Factory) or through operations on existing Mat4 instances.
Factory
i
Identity matrix
ecs.math.mat4.i() // -> mat4
of
Creates a matrix with directly specified data, using column-major order. An optional inverse can be provided. If not provided, the inverse will be calculated automatically if the matrix is invertible. Attempting to calculate the inverse for a non-invertible matrix will throw an error.
ecs.math.mat4.of(data: number[], inverseData?: number[]) // -> mat4
r
Creates a rotation matrix from a quaternion.
ecs.math.mat4.r(q: QuatSource) // -> mat4
rows
Creates a matrix using specified row data. You can also optionally provide inverse row data. Both dataRows and inverseDataRows should be arrays, each containing four numbers. If the inverse is not provided, it will be computed automatically if the matrix is invertible.
Attempting to calculate the inverse for a non-invertible matrix will throw an error.
ecs.math.mat4.rows(dataRows: number[][], inverseDataRows?: number[][]) // -> mat4
s
Creates a scale matrix. Specify the scale factors along the x, y, and z axes.
ecs.math.mat4.s(x: number, y: number, z: number) // -> mat4
t
Creates a translation matrix. Specify the translation offsets along the x, y, and z axes.
ecs.math.mat4.t(x: number, y: number, z: number) // -> mat4
tr
Creates a combined translation and rotation matrix using a translation vector and a quaternion for the rotation.
ecs.math.mat4.tr(t: Vec3Source, r: QuatSource) // -> mat4
trs
Creates a combined translation, rotation, and scale matrix. Use a translation vector, a quaternion for rotation, and scale factors for x, y, and z axes.
ecs.math.mat4.trs(t: Vec3Source, r: QuatSource, s: Vec3Source) // -> mat4
Immutable
The following methods perform computations using the current value of a Mat4 without altering its contents. Methods that return Mat4 types generate new instances. While immutable APIs are generally safer, more readable, and reduce errors compared to mutable APIs, they may be less efficient in scenarios where thousands of objects are created each frame.
If garbage collection becomes a performance issue, consider using the Mutable API.
clone
Create a new matrix with the same components as this matrix.
ecs.math.mat4.clone() // -> mat4
data
Get the raw data of the matrix, in column-major order.
ecs.math.mat4.data() // -> number[]
decomposeTrs
Decompose the matrix into its translation, rotation, and scale components, assuming it was formed by a translation, rotation, and scale in that order. If ‘target’ is supplied, the result will be stored in ‘target’ and ‘target’ will be returned. Otherwise, a new {t, r, s} object will be created and returned.
ecs.math.mat4.decomposeTrs(target?: {t: Vec3, r: Quat, s: Vec3}) // -> {t: Vec3, r: Quat, s: Vec3}
determinant
Compute the determinant of the matrix.
ecs.math.mat4.determinant() // -> number
equals
Check whether two matrices are equal, with a specified floating point tolerance.
ecs.math.mat4.equals(m: Mat4, tolerance: number) // -> boolean
inv
Invert the matrix, or throw if the matrix is not invertible. Because Mat4 stores a precomputed inverse, this operation is very fast.
ecs.math.mat4.inv() // -> mat4
inverseData
Get the raw data of the inverse matrix, in column-major order, or null if the matrix is not invertible.
ecs.math.mat4.inverseData() // -> number[] | null
lookAt
Get a matrix with the same position and scale as this matrix, but with the rotation set to look at the target.
ecs.math.mat4.lookAt(target: Vec3Source, up: Vec3Source) // -> mat4
scale
Multiply the matrix by a scalar.
Scaling by 0 throws an error.
ecs.math.mat4.scale(s: number) // -> mat4
transpose
Get the transpose of the matrix.
ecs.math.mat4.transpose() // -> mat4
times
Multiply the matrix by another matrix.
ecs.math.mat4.times(m: Mat4) // -> mat4
timesVec
Multiply the matrix by a vector using homogeneous coordinates.
ecs.math.mat4.timesVec(v: Vec3Source, target?: Vec3) // -> vec3
Mutable
The following methods compute results based on the current value of a Mat4 and modify its contents directly. They mirror the methods in the Immutable API described earlier. Methods returning Mat4 types provide a reference to the same object, allowing for method chaining. While mutable APIs can offer better performance than immutable ones, they tend to be less safe, less readable, and more prone to errors.
If code is unlikely to be executed frequently within a single frame, consider using the Immutable API for better code safety and clarity.
setInv
Invert the matrix, or throw if the matrix is not invertible. Because Mat4 stores a precomputed inverse, this operation is very fast. Store the result in this Mat4 and return this Mat4 for chaining.
existingMat4.setInv() // -> mat4
setLookAt
Set the matrix rotation to look at the target, keeping translation and scale unchanged. Store the result in this Mat4 and return this Mat4 for chaining.
existingMat4.setLookAt(target: Vec3Source, up: Vec3Source) // -> mat4
setPremultiply
Sets this matrix the result of m times this matrix. Store the result in this Mat4 and return this Mat4 for chaining.
existingMat4.setPremultiply(m: Mat4) // -> mat4
setScale
Multiply each element of the matrix by a scaler. Scaling by 0 throws an error. Store the result in this Mat4 and return this Mat4 for chaining.
existingMat4.setScale(s: number) // -> mat4
setTimes
Set the matrix to its transpose. Store the result in this Mat4 and return this Mat4 for chaining.
existingMat4.setTranspose() // -> mat4
Set
The following methods set the value of the current Mat4 object without regard to its current content, replacing whatever was there before.
makeI
Set the matrix to the identity matrix. Store the result in this Mat4 and return this Mat4 for chaining.
existingMat4.makeI() // -> mat4
makeR
Set this matrix to a rotation matrix from the specified quaternion. Store the result in this Mat4 and return this Mat4 for chaining.
existingMat4.makeR(r: QuatSource) // -> mat4
makeRows
Create a matrix with specified row data, and optionally specified inverse row data. dataRows and inverseDataRows should be four arrays, each with four numbers. If the inverse is not specified, it will be computed if the matrix is invertible.
If the matrix is not invertible, calling inv() will throw an error.
existingMat4.makeRows(rowData: number[][], inverseRowData?: number[][]) // -> mat4
makeS
Set this matrix to a scale matrix from the specified vector. No element of the vector should be zero. Store the result in this Mat4 and return this Mat4 for chaining.
existingMat4.makeS(s: Vec3Source) // -> mat4
makeT
Set this matrix to a translation matrix from the specified vector. Store the result in this Mat4 and return this Mat4 for chaining.
existingMat4.makeT(s: Vec3Source) // -> mat4
makeTr
Set this matrix to a translation and rotation matrix from the specified vector and quaternion. Store the result in this Mat4 and return this Mat4 for chaining.
existingMat4.makeTr(t: Vec3Source, r: QuatSource) // -> mat4
makeTrs
Set this matrix to a translation, rotation, and scale matrix from the specified vectors and quaternion. Store the result in this Mat4 and return this Mat4 for chaining.
existingMat4.makeTrs(t: Vec3Source, r: QuatSource, s: Vec3Source) // -> mat4
set
Sets the value of the matrix and inverse to the provided values. If no inverse is provided, one will be computed if possible. If the matrix is not invertible, calling inv() will throw an error. Store the result in this Mat4 and return this Mat4 for chaining.
existingMat4.set(data: number[], inverseData?: number[]) // -> mat4