twgl/m4

4x4 Matrix math math functions.

Almost all functions take an optional dst argument. If it is not passed in the
functions will create a new matrix. In other words you can do this

const mat = m4.translation([1, 2, 3]);  // Creates a new translation matrix

or

const mat = m4.create();
m4.translation([1, 2, 3], mat);  // Puts translation matrix in mat.

The first style is often easier but depending on where it's used it generates garbage where
as there is almost never allocation with the second style.

It is always save to pass any matrix as the destination. So for example

const mat = m4.identity();
const trans = m4.translation([1, 2, 3]);
m4.multiply(mat, trans, mat);  // Multiplies mat * trans and puts result in mat.

Methods

(static) axisRotate(m, axis, angleInRadians, dstopt) → {module:twgl/m4.Mat4}

Rotates the given 4-by-4 matrix around the given axis by the
given angle.

Parameters:
Name Type Attributes Description
m module:twgl/m4.Mat4

The matrix.

axis module:twgl/v3.Vec3

The axis

The angle by which to rotate (in radians).

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

The rotated matrix.

(static) axisRotation(axis, angleInRadians, dstopt) → {module:twgl/m4.Mat4}

Creates a 4-by-4 matrix which rotates around the given axis by the given
angle.

Parameters:
Name Type Attributes Description
axis module:twgl/v3.Vec3

The axis

The angle by which to rotate (in radians).

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

A matrix which rotates angle radians
around the axis.

(static) copy(m, dstopt) → {module:twgl/m4.Mat4}

Copies a matrix.

Parameters:
Name Type Attributes Description
m module:twgl/m4.Mat4

The matrix.

dst module:twgl/m4.Mat4 <optional>

The matrix. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

A copy of m.

(static) frustum(left, right, bottom, top, near, far, dstopt) → {module:twgl/m4.Mat4}

Computes a 4-by-4 perspective transformation matrix given the left, right,
top, bottom, near and far clipping planes. The arguments define a frustum
extending in the negative z direction. The arguments near and far are the
distances to the near and far clipping planes. Note that near and far are not
z coordinates, but rather they are distances along the negative z-axis. The
matrix generated sends the viewing frustum to the unit box. We assume a unit
box extending from -1 to 1 in the x and y dimensions and from 0 to 1 in the z
dimension.

Parameters:
Name Type Attributes Description
left number

The x coordinate of the left plane of the box.

right number

The x coordinate of the right plane of the box.

bottom number

The y coordinate of the bottom plane of the box.

top number

The y coordinate of the right plane of the box.

near number

The negative z coordinate of the near plane of the box.

far number

The negative z coordinate of the far plane of the box.

dst module:twgl/m4.Mat4 <optional>

Output matrix. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

The perspective projection matrix.

(static) getAxis(m, axis) → {module:twgl/v3.Vec3|module:twgl/v3.Vec3}

Returns an axis of a 4x4 matrix as a vector with 3 entries

Parameters:
Name Type Description
m module:twgl/m4.Mat4

The matrix.

axis number

The axis 0 = x, 1 = y, 2 = z;

(static) getTranslation(m, dstopt) → {module:twgl/v3.Vec3}

Returns the translation component of a 4-by-4 matrix as a vector with 3
entries.

Parameters:
Name Type Attributes Description
m module:twgl/m4.Mat4

The matrix.

dst module:twgl/v3.Vec3 <optional>

vector to hold result. If not passed a new one is created.

Returns:
Type:
module:twgl/v3.Vec3

The translation component of m.

(static) identity(dstopt) → {module:twgl/m4.Mat4}

Creates an n-by-n identity matrix.

Parameters:
Name Type Attributes Description
dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

An n-by-n identity matrix.

(static) inverse(m, dstopt) → {module:twgl/m4.Mat4}

Computes the inverse of a 4-by-4 matrix.

Parameters:
Name Type Attributes Description
m module:twgl/m4.Mat4

The matrix.

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

The inverse of m.

(static) lookAt(eye, target, up, dstopt) → {module:twgl/m4.Mat4}

Computes a 4-by-4 look-at transformation.

This is a matrix which positions the camera itself. If you want
a view matrix (a matrix which moves things in front of the camera)
take the inverse of this.

Parameters:
Name Type Attributes Description
eye module:twgl/v3.Vec3

The position of the eye.

target module:twgl/v3.Vec3

The position meant to be viewed.

up module:twgl/v3.Vec3

A vector pointing up.

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

The look-at matrix.

(static) multiply(a, b, dstopt) → {module:twgl/m4.Mat4}

Multiplies two 4-by-4 matrices with a on the left and b on the right

Parameters:
Name Type Attributes Description
a module:twgl/m4.Mat4

The matrix on the left.

b module:twgl/m4.Mat4

The matrix on the right.

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

The matrix product of a and b.

(static) negate(m, dstopt) → {module:twgl/m4.Mat4}

Negates a matrix.

Parameters:
Name Type Attributes Description
m module:twgl/m4.Mat4

The matrix.

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

-m.

(static) ortho(left, right, bottom, top, near, far, dstopt) → {module:twgl/m4.Mat4}

Computes a 4-by-4 orthogonal transformation matrix given the left, right,
bottom, and top dimensions of the near clipping plane as well as the
near and far clipping plane distances.

Parameters:
Name Type Attributes Description
left number

Left side of the near clipping plane viewport.

right number

Right side of the near clipping plane viewport.

bottom number

Bottom of the near clipping plane viewport.

top number

Top of the near clipping plane viewport.

near number

The depth (negative z coordinate)
of the near clipping plane.

far number

The depth (negative z coordinate)
of the far clipping plane.

dst module:twgl/m4.Mat4 <optional>

Output matrix. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

The perspective matrix.

(static) perspective(fieldOfViewYInRadians, aspect, zNear, zFar, dstopt) → {module:twgl/m4.Mat4}

Computes a 4-by-4 perspective transformation matrix given the angular height
of the frustum, the aspect ratio, and the near and far clipping planes. The
arguments define a frustum extending in the negative z direction. The given
angle is the vertical angle of the frustum, and the horizontal angle is
determined to produce the given aspect ratio. The arguments near and far are
the distances to the near and far clipping planes. Note that near and far
are not z coordinates, but rather they are distances along the negative
z-axis. The matrix generated sends the viewing frustum to the unit box.
We assume a unit box extending from -1 to 1 in the x and y dimensions and
from 0 to 1 in the z dimension.

Parameters:
Name Type Attributes Description

The camera angle from top to bottom (in radians).

aspect number

The aspect ratio width / height.

zNear number

The depth (negative z coordinate)
of the near clipping plane.

zFar number

The depth (negative z coordinate)
of the far clipping plane.

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

The perspective matrix.

(static) rotateX(m, angleInRadians, dstopt) → {module:twgl/m4.Mat4}

Rotates the given 4-by-4 matrix around the x-axis by the given
angle.

Parameters:
Name Type Attributes Description
m module:twgl/m4.Mat4

The matrix.

The angle by which to rotate (in radians).

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

The rotated matrix.

(static) rotateY(m, angleInRadians, dstopt) → {module:twgl/m4.Mat4}

Rotates the given 4-by-4 matrix around the y-axis by the given
angle.

Parameters:
Name Type Attributes Description
m module:twgl/m4.Mat4

The matrix.

The angle by which to rotate (in radians).

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

The rotated matrix.

(static) rotateZ(m, angleInRadians, dstopt) → {module:twgl/m4.Mat4}

Rotates the given 4-by-4 matrix around the z-axis by the given
angle.

Parameters:
Name Type Attributes Description
m module:twgl/m4.Mat4

The matrix.

The angle by which to rotate (in radians).

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

The rotated matrix.

Creates a 4-by-4 matrix which rotates around the x-axis by the given angle.

Parameters:
Name Type Attributes Description

The angle by which to rotate (in radians).

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

The rotation matrix.

Creates a 4-by-4 matrix which rotates around the y-axis by the given angle.

Parameters:
Name Type Attributes Description

The angle by which to rotate (in radians).

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

The rotation matrix.

Creates a 4-by-4 matrix which rotates around the z-axis by the given angle.

Parameters:
Name Type Attributes Description

The angle by which to rotate (in radians).

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

The rotation matrix.

(static) scale(m, v, dstopt) → {module:twgl/m4.Mat4}

Scales the given 4-by-4 matrix in each dimension by an amount
given by the corresponding entry in the given vector; assumes the vector has
three entries.

Parameters:
Name Type Attributes Description
m module:twgl/m4.Mat4

The matrix to be modified.

v module:twgl/v3.Vec3

A vector of three entries specifying the
factor by which to scale in each dimension.

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

The scaled matrix.

(static) scaling(v, dstopt) → {module:twgl/m4.Mat4}

Creates a 4-by-4 matrix which scales in each dimension by an amount given by
the corresponding entry in the given vector; assumes the vector has three
entries.

Parameters:
Name Type Attributes Description
v module:twgl/v3.Vec3

A vector of
three entries specifying the factor by which to scale in each dimension.

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

The scaling matrix.

(static) setAxis(m, v, axis, dstopt) → {module:twgl/m4.Mat4}

Sets an axis of a 4x4 matrix as a vector with 3 entries

Parameters:
Name Type Attributes Description
m module:twgl/m4.Mat4

The matrix.

v module:twgl/v3.Vec3

the axis vector

axis number

The axis 0 = x, 1 = y, 2 = z;

dst module:twgl/m4.Mat4 <optional>

The matrix to set. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

The matrix with axis set.

(static) setDefaultType(ctor) → {constructor}

Sets the type this library creates for a Mat4

Parameters:
Name Type Description
ctor constructor

the constructor for the type. Either Float32Array or Array

Returns:
Type:
constructor

previous constructor for Mat4

(static) setTranslation(a, v, dstopt) → {module:twgl/m4.Mat4}

Sets the translation component of a 4-by-4 matrix to the given
vector.

Parameters:
Name Type Attributes Description
a module:twgl/m4.Mat4

The matrix.

v module:twgl/v3.Vec3

The vector.

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

The matrix with translation set.

(static) transformDirection(m, v, dstopt) → {module:twgl/v3.Vec3}

Takes a 4-by-4 matrix and a vector with 3 entries, interprets the vector as a
direction, transforms that direction by the matrix, and returns the result;
assumes the transformation of 3-dimensional space represented by the matrix
is parallel-preserving, i.e. any combination of rotation, scaling and
translation, but not a perspective distortion. Returns a vector with 3
entries.

Parameters:
Name Type Attributes Description
m module:twgl/m4.Mat4

The matrix.

v module:twgl/v3.Vec3

The direction.

dst module:twgl/v3.Vec3 <optional>

optional Vec3 to store result. If not passed a new one is created.

Returns:
Type:
module:twgl/v3.Vec3

The transformed direction.

(static) transformNormal(m, v, dstopt) → {module:twgl/v3.Vec3}

Takes a 4-by-4 matrix m and a vector v with 3 entries, interprets the vector
as a normal to a surface, and computes a vector which is normal upon
transforming that surface by the matrix. The effect of this function is the
same as transforming v (as a direction) by the inverse-transpose of m. This
function assumes the transformation of 3-dimensional space represented by the
matrix is parallel-preserving, i.e. any combination of rotation, scaling and
translation, but not a perspective distortion. Returns a vector with 3
entries.

Parameters:
Name Type Attributes Description
m module:twgl/m4.Mat4

The matrix.

v module:twgl/v3.Vec3

The normal.

dst module:twgl/v3.Vec3 <optional>

The direction. If not passed a new one is created.

Returns:
Type:
module:twgl/v3.Vec3

The transformed normal.

(static) transformPoint(m, v, dstopt) → {module:twgl/v3.Vec3}

Takes a 4-by-4 matrix and a vector with 3 entries,
interprets the vector as a point, transforms that point by the matrix, and
returns the result as a vector with 3 entries.

Parameters:
Name Type Attributes Description
m module:twgl/m4.Mat4

The matrix.

v module:twgl/v3.Vec3

The point.

dst module:twgl/v3.Vec3 <optional>

optional vec3 to store result. If not passed a new one is created.

Returns:
Type:
module:twgl/v3.Vec3

The transformed point.

(static) translate(m, v, dstopt) → {module:twgl/m4.Mat4}

Translates the given 4-by-4 matrix by the given vector v.

Parameters:
Name Type Attributes Description
m module:twgl/m4.Mat4

The matrix.

v module:twgl/v3.Vec3

The vector by
which to translate.

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

The translated matrix.

(static) translation(v, dstopt) → {module:twgl/m4.Mat4}

Creates a 4-by-4 matrix which translates by the given vector v.

Parameters:
Name Type Attributes Description
v module:twgl/v3.Vec3

The vector by
which to translate.

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

The translation matrix.

(static) transpose(m, dstopt) → {module:twgl/m4.Mat4}

Takes the transpose of a matrix.

Parameters:
Name Type Attributes Description
m module:twgl/m4.Mat4

The matrix.

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If not passed a new one is created.

Returns:
Type:
module:twgl/m4.Mat4

The transpose of m.

Type Definitions

Mat4

A JavaScript array with 16 values or a Float32Array with 16 values.
When created by the library will create the default type which is Float32Array
but can be set by calling module:twgl/m4.setDefaultType.

Type:
• Array.<number> | Float32Array