twgl/m4 - Documentation

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

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 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 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 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 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) create() → {module:twgl/m4.Mat4}

Creates a matrix.

Returns:

Type:: module:twgl/m4.Mat4

A new matrix.

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

Returns:

Type:

module:twgl/v3.Vec3

[dst] vector.
Type:

module:twgl/v3.Vec3

The axis component of m.

(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
`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 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.
`angleInRadians`	`number`		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.
`angleInRadians`	`number`		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.
`angleInRadians`	`number`		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) 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 not passed a new one is created.

Returns:

Type:: module:twgl/m4.Mat4

The rotation matrix.

(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 not passed a new one is created.

Returns:

Type:: module:twgl/m4.Mat4

The rotation matrix.

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