# 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

`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

`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) 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`