API Docs

Class: MatrixArray

PD. MatrixArray

new MatrixArray()

A helper class for performing vector math using array-based matrices.

These are 16-item column-major transformation matrix arrays. This means that, when represented as a table with 4 columns and 4 rows, the X, Y and Z direction each of the local axis are read downwards in the first three columns and the 4th row gives the offset in each of those axis.

Any Float32Array with at least 16 items in the same format can also be used entirely interchangeably as both output or input in all matrix array methods.

Author:
  • drajmarsh

Methods

compose(out, translation, rotation, scale) <static>

Composes a flat 4x4 column-major matrix from the given translation, rotation and scaling factors.

Once created, you can use the PD.VectorArray.applyMatrix4 method to modify points and vertices.

NOTE: This method changes values within the out parameter.

Parameters:
Name Type Description
out Array.<number>

The 16-item column-major matrix array to receive the result.
translation Array.<number>

The [x,y,z] vector array defining the spatial translation in each axis.
rotation Array.<number>

The normalised [x,y,z,w] quaternion array defining the spatial rotation.
scale Array.<number>

The [x,y,z] vector array defining the spatial scaling in each axis.
Returns:

Returns the modified out matrix.

Type
Array.<number>

create() <static>

Creates a new 16-item column-major matrix array.

Returns:

Returns a new 16-item column-major matrix array.

Type
Array.<number>

decompose(matrix, translation, rotation, scale) <static>

Composes a flat 4x4 column-major matrix from the given translation, rotation and scaling factors.

Once created, you can use the PD.VectorArray.applyMatrix4 method to modify points and vertices.

NOTE: This method changes values within the translate, rotate and scale parameters.

Parameters:
Name Type Description
matrix Array.<number>

The 16-item column-major matrix array to receive the result.
translation Array.<number>

The [x,y,z] vector array defining the spatial translation in each axis.
rotation Array.<number>

The normalised [x,y,z,w] quaternion array defining the spatial rotation.
scale Array.<number>

The [x,y,z] vector array defining the spatial scaling in each axis.
Returns:

Returns the matrix argument.

Type
Array.<number>

determinant(mtx) <static>

Computes the determinant of the given 4x4 column-major matrix.

The determinant of a 4×4 matrix is a unique number calculated from a square matrix using a special formula. There are several formulas that can be used, and this method uses one, but the upshot is that it returns a single numerical value which is used when calculating the inverse or when solving systems of linear equations.

Parameters:
Name Type Description
mtx Array.<number>

The 16-item column-major matrix array.
Returns:

Returns the computed determinant.

Type
number

getRotation(quat, mtx) <static>

Retrieves the rotational component of a matrix as a quaternion.

Parameters:
Name Type Description
quat Array.<number>

The [x,y,z,w] quaternion array to receive the rotation.
mtx Array.<number>

The 16-item column-major matrix array to get it from.
Returns:

Returns the modified out [x,y,z,w] quaternion array.

Type
Array.<number>

getScale(vec, mtx) <static>

Retrieves the scaling factor component of a matrix.

Parameters:
Name Type Description
vec Array.<number>

The [x,y,z] vector array to receive the scale.
mtx Array.<number>

The 16-item column-major matrix array to get it from.
Returns:

Returns the modified vec [x,y,z] vector array.

Type
Array.<number>

getTranslation(vec, mtx) <static>

Retrieves the translation vector component of the matrix.

Parameters:
Name Type Description
vec Array.<number>

The [x,y,z] vector array to receive the translation.
mtx Array.<number>

The 16-item column-major matrix array to get it from.
Returns:

Returns the modified vec [x,y,z] vector array.

Type
Array.<number>

identity(out) <static>

Resets a 16-item column-major matrix to identity values.

NOTE: This method changes values within the out parameter.

Parameters:
Name Type Description
out Array.<number>

The 16-item column-major matrix array to set.
Returns:

Returns the updated out matrix.

Type
Array.<number>

invert(out [, mtx]) <static>

Inverts a 4x4 column-major matrix and stores the result in out.

NOTE: This method changes values within the out parameter, however it is safe to use the same array in both arguments, or simply give only one argument to change it in-place.

Parameters:
Name Type Argument Description
out Array.<number>

The 16-item column-major matrix array to receive the result.
mtx Array.<number> <optional>

The 16-item column-major source matrix array, defaults to out if not supplied.
Returns:

Returns the modified out matrix array.

Type
Array.<number>

multiply(out, mtx2, mtx1) <static>

Multiply two 16-item column-major matrices together.

Parameters:
Name Type Description
out Array.<number>

The 16-item column-major matrix array to set.
mtx2 Array.<number>

The first 16-item column-major matrix array to multiply.
mtx1 Array.<number>

The second 16-item column-major matrix array to multiply.
Returns:

Returns the updated out matrix.

Type
Array.<number>

rotate(out, mtx, axis, angle) <static>

Rotate a flat 4x4 column-major matrix array by the given angle around the given axis.

Parameters:
Name Type Description
out Array.<number>

The 16-item column-major matrix array to receive the result.
mtx Array.<number>

The 16-item column-major matrix array to scale.
axis Array.<number>

The normalised [x,y,z] vector array defining the axis of rotation.
angle number

The angle or rotation in radians.
Returns:

Returns the modified out matrix.

Type
Array.<number>

scale(out, mtx, scale) <static>

Scale a flat 4x4 column-major matrix array by the given factors.

Parameters:
Name Type Description
out Array.<number>

The 16-item column-major matrix array to receive the result.
mtx Array.<number>

The 16-item column-major matrix array to scale.
scale Array.<number>

The [sx,sy,sz] vector array defining the spatial scaling in each axis.
Returns:

Returns the modified out matrix.

Type
Array.<number>

setFromThreeAxis(out, xAxis, yAxis, zAxis [, origin]) <static>

Sets a 16-item column-major matrix to use the given three axis and origin.

NOTE: This method changes values within the out parameter.

Parameters:
Name Type Argument Description
out Array.<number>

The 16-item column-major matrix array to set.
xAxis Array.<number>

The normalised [x,y,z] vector array defining the X-axis.
yAxis Array.<number>

The normalised [x,y,z] vector array defining the Y-axis.
zAxis Array.<number>

The normalised [x,y,z] vector array defining the Z-axis.
origin Array.<number> <optional>

The [x,y,z] vector array position of the origin, defaults to [0,0,0].
Returns:

Returns the updated out matrix.

Type
Array.<number>

setRotation(out, axis, angle) <static>

Sets a 16-item column-major matrix to the given rotation.

Using this method is the same as, but notably faster than, having to separately call the PD.MatrixArray#identity and then PD.MatrixArray#rotate methods.

NOTE: This method changes values within the out parameter.

Parameters:
Name Type Description
out Array.<number>

The 16-item column-major matrix array to set.
axis Array.<number>

The normalised [x,y,z] vector array defining the axis of rotation.
angle number

The angle or rotation in radians.
Returns:

Returns the modified out matrix.

Type
Array.<number>

setScale(out, scale) <static>

Sets a 16-item column-major matrix to the given scaling.

Using this method is the same as, but notably faster than, having to separately call the PD.MatrixArray#identity and then PD.MatrixArray#scale methods.

NOTE: This method changes values within the out parameter.

Parameters:
Name Type Description
out Array.<number>

The 16-item column-major matrix array to set.
scale Array.<number>

The [sx,sy,sz] vector array defining the spatial scaling in each axis.
Returns:

Returns the modified out matrix.

Type
Array.<number>

setTranslation(out, translation) <static>

Sets a 16-item column-major matrix to the given translation.

Using this method is the same as, but notably faster than, having to separately call the PD.MatrixArray#identity and then PD.MatrixArray#translate methods.

NOTE: This method changes values within the out parameter.

Parameters:
Name Type Description
out Array.<number>

The 16-item column-major matrix array to set.
translation Array.<number>

The [x,y,z] vector array defining the spatial translation in each axis.
Returns:

Returns the modified out matrix.

Type
Array.<number>

translate(out, mtx, translation) <static>

Translate a flat 4x4 column-major matrix array by the given vector.

Parameters:
Name Type Description
out Array.<number>

The 16-item column-major matrix array to receive the result.
mtx Array.<number>

The 16-item column-major matrix array to translate.
translation Array.<number>

The [x,y,z] vector array defining the spatial translation in each axis.
Returns:

Returns the modified out matrix.

Type
Array.<number>