Class: Matrix4

Matrix4()

Utility class for 4x4 transformation matrices. Matrices are stored as flat 'Float32Array' values in column-major order. A matrix can be flattened into an array in two common ways: 1). row-major stores it row by row 2). column-major stores it column by column Example: [ m00 m01 m02 m03 ] [ m10 m11 m12 m13 ] [ m20 m21 m22 m23 ] [ m30 m31 m32 m33 ] Row-major : [ m00, m01, m02, m03, m10, m11, m12, m13, ... ] Column-major : [ m00, m10, m20, m30, m01, m11, m21, m31, ... ] To read or write a matrix cell in this flat array, convert its column and row position into an array index. 'row count' - is always '4', because each column of a 4x4 matrix contains 4 row values 'column index * row count' - gives the start index of the target column 'row index' - selects the value inside the target column The resulting formula is: 'cell index = column index * row count + row index' So: m20 -> cell index = 0 * 4 + 2 = 2 m01 -> cell index = 1 * 4 + 0 = 4 It is also important to highlight that, when a 4x4 matrix represents an 'affine transform', its translation part is stored in the last column. Conceptually, this translation column is multiplied by the input 'homogeneous' coordinate called 'w': [ ... ... ... tx ] [ ... ... ... ty ] [ ... ... ... tz ] [ ... ... ... w ] Here, 'tx, ty and tz' are 'x, y, z' translation components. When a transform is applied as 'transformed value = matrix * input value', the translation part contributes to the result through input 'w': 'new x = ... + tx * w' 'new y = ... + ty * w' 'new z = ... + tz * w' So, if 'w = 1', translation is added to the result. If 'w = 0', translation becomes zero and is ignored. Since 'tx', 'ty' and 'tz' are stored in the last column, their flat array indices are calculated by the same formula: tx -> m03 -> cell index = 3 * 4 + 0 = 12 ty -> m13 -> cell index = 3 * 4 + 1 = 13 tz -> m23 -> cell index = 3 * 4 + 2 = 14 For a usual affine transform, the last row is: [ 0, 0, 0, 1 ] It keeps the input 'w' unchanged during multiplication. Matrix multiplication is ordered: 'left * right' is not the same as 'right * left'. When the result is applied to a column vector, the right matrix is applied first.

Constructor

new Matrix4()

Source:

Methods

(static) createIdentity() → {Float32Array}

Creates a new 4x4 identity matrix: column 0: [ 1, 0, 0, 0 ] column 1: [ 0, 1, 0, 0 ] column 2: [ 0, 0, 1, 0 ] column 3: [ 0, 0, 0, 1 ]
Source:
Returns:
- A new identity matrix.
Type
Float32Array

(static) createPerspective(fieldOfViewRadians, aspectRatio, near, far) → {Float32Array}

Creates a perspective projection matrix: column 0: [ projectionScale / aspectRatio, 0, 0, 0 ] column 1: [ 0, projectionScale, 0, 0 ] column 2: [ 0, 0, depthScale, -1 ] column 3: [ 0, 0, depthOffset, 0 ] Perspective projection: - makes farther objects appear smaller and closer objects appear larger - unlike the orthographic projection, object size depends on distance from the camera How the matrix is applied to a 3D point? - the matrix stores projection coefficients, not a projected point - a view-space 3D point [x, y, z] is used as a homogeneous input [x, y, z, 1] - homogeneous input means a 3D point, stored with a helper 'w-component', not a point in 4D space - 'w = 1' means a position, 'w = 0' means a direction, so the translation/depth offset wouldn't apply Multiplying this homogeneous form of the 3D point by the matrix produces the clip-space coordinates: clip x: [ x * projectionScale / aspectRatio ] clip y: [ y * projectionScale ] clip z: [ z * depthScale + 1 * depthOffset ] clip w: [ z * (-1) + 1 * 0 = -z ] About spaces: - world-space describes where an object is in the scene - view-space describes the same object relative to the camera, before the projection - the perspective projection matrix converts the 'view-space' coordinates into the 'clip-space' coordinates - clip-space stores 4 components: [clip x, clip y, clip z, clip w] - clip-space is where projected coordinates are checked against the visible camera volume - after clipping, the perspective divide ('/ clip w') converts clip-space coordinates into NDC coordinates Notes about the projection scale: - the scale uses the half-angle between the camera center line and the vertical view boundary (that's why tangent is used) - tangent describes how wide the vertical view opens from this half-angle - the inverse is used, because tangent gives the view opening, while the matrix needs a scale, that brings this opening back to the unit boundary - the final scale value is the inverse of that opening value (tangent of half of the vertical FOV) Depth mapping: - depth scale controls how the view-space z value is scaled for clip-space z - depth offset shifts the scaled z value so 'near' and 'far' can be mapped to the clip-space depth limits Formulas: - aspect ratio = viewport width / viewport height - vertical projection scale = inverse of tangent(half vertical field of view) - horizontal projection scale = vertical projection scale / aspect ratio - depth scale = (far + near) / (near - far) - depth offset = 2 * far * near / (near - far)
Parameters:
Name Type Description
fieldOfViewRadians number Vertical field of view in radians.
aspectRatio number Viewport aspect ratio (width / height).
near number Near clipping plane, must be '> 0'.
far number Far clipping plane, must be '> near'.
Source:
Throws:
  • - If any argument is not a finite number.
    Type
    TypeError
  • - If the projection parameters are invalid or produce non-finite matrix values.
    Type
    RangeError
Returns:
- A new perspective projection matrix.
Type
Float32Array

(static) createRotationX(angleRadians) → {Float32Array}

Creates a rotation matrix around the X axis: [ 1 0 0 0 ] [ 0 cosAngle -sinAngle 0 ] [ 0 sinAngle cosAngle 0 ] [ 0 0 0 1 ]
Parameters:
Name Type Description
angleRadians number Angle in radians.
Source:
Returns:
- A new rotation matrix.
Type
Float32Array

(static) createRotationY(angleRadians) → {Float32Array}

Creates a rotation matrix around the Y axis: [ cosAngle 0 sinAngle 0 ] [ 0 1 0 0 ] [ -sinAngle 0 cosAngle 0 ] [ 0 0 0 1 ]
Parameters:
Name Type Description
angleRadians number Angle in radians.
Source:
Returns:
- A new rotation matrix.
Type
Float32Array

(static) createRotationZ(angleRadians) → {Float32Array}

Creates a rotation matrix around the Z axis: [ cosAngle -sinAngle 0 0 ] [ sinAngle cosAngle 0 0 ] [ 0 0 1 0 ] [ 0 0 0 1 ]
Parameters:
Name Type Description
angleRadians number Angle in radians.
Source:
Returns:
- A new rotation matrix.
Type
Float32Array

(static) createScale(scaleX, scaleY, scaleZ) → {Float32Array}

Creates a scale matrix: column 0: [ scaleX, 0, 0, 0 ] column 1: [ 0, scaleY, 0, 0 ] column 2: [ 0, 0, scaleZ, 0 ] column 3: [ 0, 0, 0, 1 ]
Parameters:
Name Type Description
scaleX number Scale along X.
scaleY number Scale along Y.
scaleZ number Scale along Z.
Source:
Returns:
- A new scale matrix.
Type
Float32Array

(static) createTranslation(translateX, translateY, translateZ) → {Float32Array}

Creates a translation matrix: [ 1 0 0 translateX ] [ 0 1 0 translateY ] [ 0 0 1 translateZ ] [ 0 0 0 1 ]
Parameters:
Name Type Description
translateX number Translation along X axis.
translateY number Translation along Y axis.
translateZ number Translation along Z axis.
Source:
Returns:
- A new translation matrix.
Type
Float32Array

(static) invert(matrix) → {Float32Array}

Inverts a 4x4 matrix using its adjugate and determinant. A near-zero determinant means the matrix is singular or unsafe to invert.
Parameters:
Name Type Description
matrix Float32Array Input 4x4 matrix.
Source:
Returns:
- A new inverted matrix.
Type
Float32Array

(static) invertTo(out, matrix) → {Float32Array}

Inverts a 4x4 matrix into an existing output matrix using its adjugate and determinant. A near-zero determinant means the matrix is singular or unsafe to invert.
Parameters:
Name Type Description
out Float32Array Output 4x4 matrix.
matrix Float32Array Input 4x4 matrix.
Source:
Returns:
- The output matrix (out).
Type
Float32Array

(static) multiply(leftMatrix, rightMatrix) → {Float32Array}

Multiplies two 4x4 matrices: 'result = leftMatrix * rightMatrix'. Order matters. With column-vector style, right matrix is applied first.
Parameters:
Name Type Description
leftMatrix Float32Array Left-hand matrix (4x4).
rightMatrix Float32Array Right-hand matrix (4x4).
Source:
Returns:
- A new matrix containing the product.
Type
Float32Array

(static) multiplyMany(…matrices) → {Float32Array}

Multiplies several matrices in sequence: 'result = m0 * m1 * m2 * ... * mn' Notes: - order matters, with column-vector style, the last matrix is applied first - if no matrices are provided, returns a new identity matrix - if exactly one matrix is provided, returns the same matrix instance (no copy)
Parameters:
Name Type Attributes Description
matrices Float32Array <repeatable>
 Matrices to multiply, in order.
Source:
Returns:
- The resulting matrix.
Type
Float32Array

(static) multiplyTo(out, leftMatrix, rightMatrix) → {Float32Array}

Multiplies two 4x4 matrices into an existing output matrix: 'out = leftMatrix * rightMatrix'. Notes: - order matters, with column-vector style the right matrix is applied first - out must not be the same object as 'leftMatrix' or 'rightMatrix'
Parameters:
Name Type Description
out Float32Array Output 4x4 matrix.
leftMatrix Float32Array Left-hand matrix (4x4).
rightMatrix Float32Array Right-hand matrix (4x4).
Source:
Returns:
- The output matrix (out).
Type
Float32Array

(static) transpose(matrix) → {Float32Array}

Transposes a 4x4 matrix by swapping its rows and columns.
Parameters:
Name Type Description
matrix Float32Array Input 4x4 matrix.
Source:
Returns:
- A new transposed matrix.
Type
Float32Array

(static) transposeTo(out, matrix) → {Float32Array}

Transposes a 4x4 matrix into an existing output matrix by swapping rows and columns. Note: out must not be the same object as matrix.
Parameters:
Name Type Description
out Float32Array Output 4x4 matrix.
matrix Float32Array Input 4x4 matrix.
Source:
Returns:
- The output matrix (out).
Type
Float32Array

(static) writeOrthographicTo(out, left, right, bottom, top, near, far) → {Float32Array}

Writes an orthographic projection matrix to the provided output buffer. The output buffer is updated in place and returned without allocating a new matrix.
Parameters:
Name Type Description
out Float32Array Output 4x4 matrix buffer.
left number Left clipping plane.
right number Right clipping plane.
bottom number Bottom clipping plane.
top number Top clipping plane.
near number Near clipping distance.
far number Far clipping distance.
Source:
Throws:
  • - If the output buffer or arguments are invalid.
    Type
    TypeError
  • - If the projection bounds or clipping distances are invalid.
    Type
    RangeError
Returns:
- The provided output buffer.
Type
Float32Array

(static) writePerspectiveTo(out, fieldOfViewRadians, aspectRatio, near, far) → {Float32Array}

Writes a perspective projection matrix to the provided output buffer. The output buffer is updated in place and returned without allocating a new matrix.
Parameters:
Name Type Description
out Float32Array Output 4x4 matrix buffer.
fieldOfViewRadians number Vertical field of view in radians.
aspectRatio number Viewport width-to-height ratio.
near number Near clipping distance.
far number Far clipping distance.
Source:
Throws:
  • - If the output buffer is invalid or any argument is not a finite number.
    Type
    TypeError
  • - If the projection parameters are invalid or produce non-finite matrix values.
    Type
    RangeError
Returns:
- The provided output buffer.
Type
Float32Array

(static) writeTransformationTo(out, translateX, translateY, translateZ, rotationX, rotationY, rotationZ, scaleX, scaleY, scaleZ) → {Float32Array}

Writes a transformation matrix combining translation, Euler rotation and scale. The transformation is calculated as: 'M = T * Rz * Ry * Rx * S' Where: M - final transformation matrix T - translation matrix Rx - rotation matrix around the X axis Ry - rotation matrix around the Y axis Rz - rotation matrix around the Z axis S - scale matrix For a point, the transformations are applied in reverse order: 'S -> Rx -> Ry -> Rz -> T' This happens because 'Matrix4' uses column vectors and applies the rightmost transformation first. This means that a point is transformed in the following sequence: 1). scaled along its local X, Y and Z axes 2). rotated around X 3). rotated around Y 4). rotated around Z 5). translated to its final position The combined Euler rotation is 'R = Rz * Ry * Rx' using the following abbreviations: 'cx, sx' - cosine and sine of rotation X 'cy, sy' - cosine and sine of rotation Y 'cz, sz' - cosine and sine of rotation Z The resulting 3x3 rotation part is: [ cz*cy cz*sy*sx - sz*cx cz*sy*cx + sz*sx ] [ sz*cy sz*sy*sx + cz*cx sz*sy*cx - cz*sx ] [ -sy cy*sx cy*cx ] Each rotation column is multiplied by the corresponding scale value and translation is stored in the last column, producing this affine 4x4 matrix: column 0: [ (rotation00 * scaleX), (rotation10 * scaleX), (rotation20 * scaleX) , 0 ] column 1: [ (rotation01 * scaleY), (rotation11 * scaleY), (rotation21 * scaleY) , 0 ] column 2: [ (rotation02 * scaleZ), (rotation12 * scaleZ), (rotation22 * scaleZ) , 0 ] column 3: [ translateX, translateY, translateZ, 1 ] Writes directly to the output buffer without intermediate matrix allocations.
Parameters:
Name Type Description
out Float32Array Output 4x4 matrix buffer.
translateX number Translation along X axis.
translateY number Translation along Y axis.
translateZ number Translation along Z axis.
rotationX number Rotation around X axis in radians.
rotationY number Rotation around Y axis in radians.
rotationZ number Rotation around Z axis in radians.
scaleX number Scale along X axis.
scaleY number Scale along Y axis.
scaleZ number Scale along Z axis.
Source:
Throws:
- If the output buffer or arguments are invalid.
Type
TypeError
Returns:
- The provided output buffer.
Type
Float32Array