Class Matrix4

The Matrix4 implements a 4x4 matrix that can be used for homogenous transformations of three dimensional vectors and points.

The class follows the 'copy-on-write' pattern, which means that every operation such as Matrix4.multiply returns a copy of the matrix with updated values. It also implies that the values of the matrix cannot be directly modified.

The concept of immutability improves sharing of objects as all types in TypeScript are assigned by identity, instead of by-value (e.g. a copy) as in other programming languages like C.

Note

The matrix storage is "row-major" meaning that elements [0...3] represents the first row. The first column is represented by the elements[0, 4, 8, 12]

Constructors

constructor

new Matrix4(
    m00?: number,
    m01?: number,
    m02?: number,
    m03?: number,
    m10?: number,
    m11?: number,
    m12?: number,
    m13?: number,
    m20?: number,
    m21?: number,
    m22?: number,
    m23?: number,
    m30?: number,
    m31?: number,
    m32?: number,
    m33?: number,
): Matrix4
Creates a new matrix with the specified elements. If no arguments are specified, an identity matrix is constructed.
Parameters
- Optionalm00: number
- Optionalm01: number
- Optionalm02: number
- Optionalm03: number
- Optionalm10: number
- Optionalm11: number
- Optionalm12: number
- Optionalm13: number
- Optionalm20: number
- Optionalm21: number
- Optionalm22: number
- Optionalm23: number
- Optionalm30: number
- Optionalm31: number
- Optionalm32: number
- Optionalm33: number
Returns Matrix4

Properties

`Static` `Readonly`identity

identity: Immutable<Matrix4>

Identity matrix.

`Static` `Readonly`zero

zero: Immutable<Matrix4>

A matrix with all zero values.

Accessors

m00

get m00(): number

Returns number
set m00(m00: number): void
Parameters
- m00: number
Returns void

m01

get m01(): number

Returns number
set m01(m01: number): void
Parameters
- m01: number
Returns void

m02

get m02(): number

Returns number
set m02(m02: number): void
Parameters
- m02: number
Returns void

m03

get m03(): number

Returns number
set m03(m03: number): void
Parameters
- m03: number
Returns void

m10

get m10(): number

Returns number
set m10(m10: number): void
Parameters
- m10: number
Returns void

m11

get m11(): number

Returns number
set m11(m11: number): void
Parameters
- m11: number
Returns void

m12

get m12(): number

Returns number
set m12(m12: number): void
Parameters
- m12: number
Returns void

m13

get m13(): number

Returns number
set m13(m13: number): void
Parameters
- m13: number
Returns void

m20

get m20(): number

Returns number
set m20(m20: number): void
Parameters
- m20: number
Returns void

m21

get m21(): number

Returns number
set m21(m21: number): void
Parameters
- m21: number
Returns void

m22

get m22(): number

Returns number
set m22(m22: number): void
Parameters
- m22: number
Returns void

m23

get m23(): number

Returns number
set m23(m23: number): void
Parameters
- m23: number
Returns void

m30

get m30(): number

Returns number
set m30(m30: number): void
Parameters
- m30: number
Returns void

m31

get m31(): number

Returns number
set m31(m31: number): void
Parameters
- m31: number
Returns void

m32

get m32(): number

Returns number
set m32(m32: number): void
Parameters
- m32: number
Returns void

m33

get m33(): number

Returns number
set m33(m33: number): void
Parameters
- m33: number
Returns void

Methods

assign

assign(other: Immutable<Matrix4>): Matrix4
Copies all properties defined by the prototype of Matrix4 from other to this instance.
Parameters
- other: Immutable<Matrix4>
Returns Matrix4

calculateDeterminant

calculateDeterminant(): number

Calculates the determinant of the matrix.

Returns number
Determinant of the matrix.

clone

clone(): Matrix4

Clones this instance and returns a new Matrix4 with identical values.

Returns Matrix4

doInvert

doInvert(): void

Calculates the inverse of the matrix. If matrix is affine use invertAffine as it is faster.

Returns void

doInvertAffine

doInvertAffine(): void

Calculates the inverse of the matrix. Matrix must be affine.

Returns void

doMultiply

doMultiply(rhs: Immutable<Matrix4>): Matrix4
Multiplies this matrix with the provided one and returns this.
Parameters
- rhs: Immutable<Matrix4>
Returns Matrix4

doReplaceColumn

doReplaceColumn(columnIndex: number, column: Immutable<Vector4>): Matrix4
Sets values of a specific column in the matrix.
Parameters
- columnIndex: number
  Index of the column in range [0, 3].
- column: Immutable<Vector4>
  Values to set in the column.
Returns Matrix4

doTranspose

doTranspose(): void

Transposes the matrix (switched columns and rows).

Returns void

getColumn

getColumn(columnIndex: number): Vector4
Gets a specific column in the matrix.
Parameters
- columnIndex: number
  Index of the column in range [0, 3].
Returns Vector4
The column as Vector4.

getColumn3

getColumn3(columnIndex: number): Vector3
Gets a specific column in the matrix as a Vector3, discarding the fourth component.
Parameters
- columnIndex: number
  Index of the column in range [0, 3].
Returns Vector3
The upper three rows of the column as Vector3.

getElement

getElement(row: number, column: number): number
Gets the value of the specified element in the matrix.
Parameters
- row: number
  Row index of the element to retrieve.
- column: number
  Column index of the element to retrieve.
Returns number
Value of the element.

getElementAtIndex

getElementAtIndex(index: number): number
Returns value of the specified element in the matrix using a linear index. Linear index can be calculated using the following formula: idx = row * 4 + column.
Parameters
- index: number
  Linear index to get the value of.
Returns number
Value of the element.

getTranslation

getTranslation(): Vector3

Gets the translation part from the matrix.

Returns Vector3
The translation as Vector3.

getTranslationRotationScale

getTranslationRotationScale(): {
    rotation: Quaternion;
    scale: Vector3;
    translation: Vector3;
}
Decompose a matrix to translation, rotation and scale components. Matrix must consist only of translation, rotation and uniform scale transformations, otherwise accurate results are not guaranteed. Applying non-uniform scale guarantees results will not be accurate.

Returns { rotation: Quaternion; scale: Vector3; translation: Vector3 }
An object containing:
- translation the translation
- rotation the rotation
- scale the scale.

inverse

inverse(): Matrix4

Calculates the inverse of the matrix.

Returns Matrix4

invertAffine

invertAffine(): Matrix4

Calculates the inverse of the matrix. Matrix must be affine.

Returns Matrix4

isEqual

isEqual(rhs: Immutable<Matrix4>): boolean
Determines if this matrix is are element-wise equal to the provided one.
Parameters
- rhs: Immutable<Matrix4>
Returns boolean

multiply

multiply(rhs: Immutable<Matrix4>): Matrix4
Multiplies this matrix with the provided and returns a copy matrix with the result.
Parameters
- rhs: Immutable<Matrix4>
Returns Matrix4

multiplyAffineVector3

multiplyAffineVector3(point: Immutable<Vector3>): Vector3
Transform a 3D point by this matrix. Matrix must be affine. Affine multiplication offers better performance than the general case.
Parameters
- point: Immutable<Vector3>
  Point to transform.
Returns Vector3
Point transformed by this matrix.

multiplyAffineVector4

multiplyAffineVector4(vector: Immutable<Vector4>): Vector4
Transform a 4D vector by this matrix. Matrix must be affine. Affine multiplication offers better performance than the general case.
Parameters
- vector: Immutable<Vector4>
  Vector to transform.
Returns Vector4
Vector transformed by this matrix.

multiplyDirection

multiplyDirection(direction: Immutable<Vector3>): Vector3
Transform a 3D direction vector by this matrix. w component is assumed to be 0.
Parameters
- direction: Immutable<Vector3>
  Direction vector to transform.
Returns Vector3
Direction vector transformed by this matrix.

multiplyVector3

multiplyVector3(point: Immutable<Vector3>): Vector3
Transform a 3D point by this matrix. w component of the vector is assumed to be 1. After transformation all components are projected back so that w remains 1. If your matrix doesn't contain projection components use multiplyAffineVector4 as it is faster.
Parameters
- point: Immutable<Vector3>
  Point to transform.
Returns Vector3
Point transformed by this matrix.

multiplyVector4

multiplyVector4(vector: Immutable<Vector4>): Vector4
Transform a 4D vector by this matrix. If your matrix doesn't contain projection components use multiplyAffineVector4 as it is faster.
Parameters
- vector: Immutable<Vector4>
  Vector to transform.
Returns Vector4
Vector transformed by this matrix.

replaceColumn

replaceColumn(columnIndex: number, column: Immutable<Vector4>): Matrix4
Sets values of a specific column in the matrix.
Parameters
- columnIndex: number
  Index of the column in range [0, 3].
- column: Immutable<Vector4>
  Values to set in the column.
Returns Matrix4

setElement

setElement(row: number, column: number, value: number): void
Sets the value of the specified element in the matrix.
Parameters
- row: number
  Row index of the element to retrieve.
- column: number
  Column index of the element to retrieve.
- value: number
Returns void
Value of the element.

setElementAtIndex

setElementAtIndex(index: number, value: number): void
Sets value of the specified element in the matrix using a linear index. Linear index can be calculated using the following formula: idx = row * 4 + column.
Parameters
- index: number
  Linear index to gsetet the value of.
- value: number
  New value of the element.
Returns void

setTranslation

setTranslation(translation: Immutable<Vector3>): void
Sets the translation part from the matrix.
Parameters
- translation: Immutable<Vector3>
  The translation as Vector3.
Returns void

setTranslationRotationScale

setTranslationRotationScale(
    translation: Immutable<Vector3>,
    rotation: Immutable<Quaternion>,
    scale: Immutable<Vector3>,
): void
Creates a matrix from translation, rotation and scale.
Parameters
- translation: Immutable<Vector3>
  Translation offset.
- rotation: Immutable<Quaternion>
  rotation quaternion.
- scale: Immutable<Vector3>
  scale factors.
Returns void

Note
The transformation are applied in scale->rotation->translation order.

toString

toString(): string

Returns string

transpose

transpose(): Matrix4

Returns a transpose of the matrix (switched columns and rows).

Returns Matrix4

`Static`fromMatrix3

fromMatrix3(matrix: Immutable<Matrix3>): Matrix4
Returns a 4x4 matrix with the upper-left 3x3 portion set from the provided matrix. The translation column is set to identity values.
Parameters
- matrix: Immutable<Matrix3>
  Matrix to embed into the 4x4 matrix.
Returns Matrix4
4x4 matrix with the rotation/scaling parts set from the provided 3x3 matrix.

`Static`isEqual

isEqual(lhs: Immutable<Matrix4>, rhs: Immutable<Matrix4>): boolean
Determines if both matrices are element-wise equal.
Parameters
- lhs: Immutable<Matrix4>
- rhs: Immutable<Matrix4>
Returns boolean

`Static`multiply

multiply(lhs: Immutable<Matrix4>, rhs: Immutable<Matrix4>): Matrix4
Multiplies both matrices and returns the result.
Parameters
- lhs: Immutable<Matrix4>
- rhs: Immutable<Matrix4>
Returns Matrix4

`Static`toMatrix3

toMatrix3(matrix: Immutable<Matrix4>): Matrix3
Returns the rotation/scaling parts of the 4x4 matrix.
Parameters
- matrix: Immutable<Matrix4>
  Matrix to extract the rotation/scaling from.
Returns Matrix3
3x3 matrix representing an upper left portion of the provided matrix.

`Static`withIdentity

withIdentity(): Matrix4

Creates a new identity matrix.

Returns Matrix4

`Static`withInverseTRS

withInverseTRS(
    translation: Immutable<Vector3>,
    rotation: Immutable<Quaternion>,
    scale: Immutable<Vector3>,
): Matrix4
Creates a new matrix that performs inverse translation, rotation and scale.
Parameters
- translation: Immutable<Vector3>
  Offset to translate by.
- rotation: Immutable<Quaternion>
  rotation quaternion.
- scale: Immutable<Vector3>
  Non-uniform scale factors.
Returns Matrix4
Inverted matrix that performs scale, followed by rotation, followed by translation.

`Static`withInverseTRSS

withInverseTRSS(
    translation: Immutable<Vector3>,
    rotation: Immutable<Quaternion>,
    scale: Immutable<Vector3>,
    skew: Immutable<Vector3>,
): Matrix4
Creates a new matrix that performs inverse translation, rotation, scale and skew.
Parameters
- translation: Immutable<Vector3>
  Offset to translate by.
- rotation: Immutable<Quaternion>
  Rotation quaternion.
- scale: Immutable<Vector3>
  Non-uniform scale factors.
- skew: Immutable<Vector3>
  Skew factors (as produced by QDU decomposition).
Returns Matrix4
Inverted matrix. Cheaper than withTRSS followed by inverse().

`Static`withMatrix3AndPosition

withMatrix3AndPosition(
matrix: Immutable<Matrix3>,
position: Immutable<Vector3>,
): Matrix4
Returns a 4x4 matrix with the upper-left 3x3 portion set from matrix and the translation column set from position.
Parameters
- matrix: Immutable<Matrix3>
  3x3 matrix to embed into the upper-left of the 4x4 matrix.
- position: Immutable<Vector3>
  Translation to set in the last column.
Returns Matrix4
4x4 matrix combining the rotation/scaling from the 3x3 matrix and the provided translation.

`Static`withTRS

withTRS(
    translation: Immutable<Vector3>,
    rotation: Immutable<Quaternion>,
    scale: Immutable<Vector3>,
): Matrix4
Creates a new matrix that performs translation, rotation and scale.
Parameters
- translation: Immutable<Vector3>
  Offset to translate by.
- rotation: Immutable<Quaternion>
  rotation quaternion.
- scale: Immutable<Vector3>
  Non-uniform scale factors.
Returns Matrix4
Matrix that performs scale, followed by rotation, followed by translation.

`Static`withTRSS

withTRSS(
    translation: Immutable<Vector3>,
    rotation: Immutable<Quaternion>,
    scale: Immutable<Vector3>,
    skew: Immutable<Vector3>,
): Matrix4
Creates a new matrix that performs translation, rotation, scale and skew.
Parameters
- translation: Immutable<Vector3>
  Offset to translate by.
- rotation: Immutable<Quaternion>
  Rotation quaternion.
- scale: Immutable<Vector3>
  Non-uniform scale factors.
- skew: Immutable<Vector3>
  Skew factors (as produced by QDU decomposition).
Returns Matrix4
Matrix that performs skew+scale, followed by rotation, followed by translation.

Class Matrix4

Note

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns Matrix4

Properties

Static Readonlyidentity

Static Readonlyzero

Accessors

m00

Returns number

Parameters

Returns void

m01

Returns number

Parameters

Returns void

m02

Returns number

Parameters

Returns void

m03

Returns number

Parameters

Returns void

m10

Returns number

Parameters

Returns void

m11

Returns number

Parameters

Returns void

m12

Returns number

Parameters

Returns void

m13

Returns number

Parameters

Returns void

m20

Returns number

Parameters

Returns void

m21

Returns number

Parameters

Returns void

m22

Returns number

Parameters

Returns void

m23

Returns number

Parameters

Returns void

m30

Returns number

Parameters

Returns void

m31

Returns number

Parameters

Returns void

m32

Returns number

Parameters

Returns void

m33

Returns number

Parameters

Returns void

Methods

`Static` `Readonly`identity

`Static` `Readonly`zero