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

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

or

var 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

var mat = m4.identity();
var 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}

Modifies the given 4-by-4 matrix by rotation around the given axis by the
given angle.

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

The matrix.

axis Vec3

The axis
about which to rotate.

angleInRadians number

The angle by which to rotate (in radians).

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If none new one is created..

Returns:

m once modified.

Type
module:twgl/m4.Mat4

(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 Vec3

The axis
about which to rotate.

angleInRadians number

The angle by which to rotate (in radians).

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If none new one is created..

Returns:

A matrix which rotates angle radians
around the axis.

Type
module:twgl/m4.Mat4

(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.

Returns:

A copy of m.

Type
module:twgl/m4.Mat4

(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.

Returns:

The perspective projection matrix.

Type
module:twgl/m4.Mat4

(static) getAxis(m, axis) → {Vec3|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;

Returns:
  • [dst] vector.

    Type
    Vec3
  • The axis component of m.

    Type
    Vec3

(static) getTranslation(m, dstopt) → {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 Vec3 <optional>

vector..

Returns:

The translation component of m.

Type
Vec3

(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 none new one is created..

Returns:

An n-by-n identity matrix.

Type
module:twgl/m4.Mat4

(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 none new one is created..

Returns:

The inverse of m.

Type
module:twgl/m4.Mat4

(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 Vec3

The position of the eye.

target Vec3

The position meant to be viewed.

up Vec3

A vector pointing up.

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If none new one is created..

Returns:

The look-at matrix.

Type
module:twgl/m4.Mat4

(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 none new one is created..

Returns:

The matrix product of a and b.

Type
module:twgl/m4.Mat4

(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 none new one is created..

Returns:

-m.

Type
module:twgl/m4.Mat4

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

Computes a 4-by-4 othogonal 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.

top number

Top of the near clipping plane viewport.

bottom number

Bottom 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.

Returns:

The perspective matrix.

Type
module:twgl/m4.Mat4

(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
fieldOfViewYInRadians number

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 none new one is created..

Returns:

The perspective matrix.

Type
module:twgl/m4.Mat4

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

Modifies the given 4-by-4 matrix by a rotation around the x-axis by the given
angle.

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

The matrix.

angleInRadians number

The angle by which to rotate (in radians).

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If none new one is created..

Returns:

m once modified.

Type
module:twgl/m4.Mat4

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

Modifies the given 4-by-4 matrix by a rotation around the y-axis by the given
angle.

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

The matrix.

angleInRadians number

The angle by which to rotate (in radians).

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If none new one is created..

Returns:

m once modified.

Type
module:twgl/m4.Mat4

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

Modifies the given 4-by-4 matrix by a rotation around the z-axis by the given
angle.

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

The matrix.

angleInRadians number

The angle by which to rotate (in radians).

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If none new one is created..

Returns:

m once modified.

Type
module:twgl/m4.Mat4

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

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

Parameters:
Name Type Attributes Description
angleInRadians number

The angle by which to rotate (in radians).

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If none new one is created..

Returns:

The rotation matrix.

Type
module:twgl/m4.Mat4

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

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

Parameters:
Name Type Attributes Description
angleInRadians number

The angle by which to rotate (in radians).

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If none new one is created..

Returns:

The rotation matrix.

Type
module:twgl/m4.Mat4

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

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

Parameters:
Name Type Attributes Description
angleInRadians number

The angle by which to rotate (in radians).

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If none new one is created..

Returns:

The rotation matrix.

Type
module:twgl/m4.Mat4

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

Modifies the given 4-by-4 matrix, scaling 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 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 none new one is created..

Returns:

m once modified.

Type
module:twgl/m4.Mat4

(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 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 none new one is created..

Returns:

The scaling matrix.

Type
module:twgl/m4.Mat4

(static) setAxis(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
v 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 none a new one is created

Returns:

dst

Type
module:twgl/m4.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 Vec3

The vector.

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If none new one is created..

Returns:

a once modified.

Type
module:twgl/m4.Mat4

(static) transformDirection(m, v, dst) → {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 Description
m module:twgl/m4.Mat4

The matrix.

v Vec3

The direction.

dst Vec3

optional Vec3 to store result

Returns:

dst or new Vec3 if not provided

Type
Vec3

(static) transformNormal(m, v, dstopt) → {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 Vec3

The normal.

dst Vec3 <optional>

The direction.

Returns:

The transformed direction.

Type
Vec3

(static) transformPoint(m, v, dst) → {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 Description
m module:twgl/m4.Mat4

The matrix.

v Vec3

The point.

dst Vec3

optional vec3 to store result

Returns:

dst or new vec3 if not provided

Type
Vec3

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

Modifies the given 4-by-4 matrix by translation by the given vector v.

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

The matrix.

v Vec3

The vector by
which to translate.

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If none new one is created..

Returns:

m once modified.

Type
module:twgl/m4.Mat4

(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 Vec3

The vector by
which to translate.

dst module:twgl/m4.Mat4 <optional>

matrix to hold result. If none new one is created..

Returns:

The translation matrix.

Type
module:twgl/m4.Mat4

(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 none new one is created..

Returns:

The transpose of m.

Type
module:twgl/m4.Mat4

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