Class Mat4

A 4x4 matrix.

Constructors

constructor

new Mat4(): Mat4
Create a new Mat4 instance. It is initialized to the identity matrix.

Returns Mat4
- Defined in engine/src/core/math/mat4.js:28

Properties

data

data: Float32Array = ...

Matrix elements in the form of a flat array.

`Static` `Readonly` IDENTITY

IDENTITY: Mat4 = ...

A constant matrix set to the identity.

`Static` `Readonly` ZERO

ZERO: Mat4 = ...

A constant matrix with all elements set to 0.

Methods

add

add(rhs): Mat4
Adds the specified 4x4 matrix to the current instance.
Parameters
- rhs: Mat4
  The 4x4 matrix used as the second operand of the addition.
Returns Mat4
Self for chaining.
Example
```
const m = new pc.Mat4();

m.add(pc.Mat4.ONE);

console.log("The result of the addition is: " + m.toString());
```
- Defined in engine/src/core/math/mat4.js:95

add2

add2(lhs, rhs): Mat4
Adds the specified 4x4 matrices together and stores the result in the current instance.
Parameters
- lhs: Mat4
  The 4x4 matrix used as the first operand of the addition.
- rhs: Mat4
  The 4x4 matrix used as the second operand of the addition.
Returns Mat4
Self for chaining.
Example
```
const m = new pc.Mat4();

m.add2(pc.Mat4.IDENTITY, pc.Mat4.ONE);

console.log("The result of the addition is: " + m.toString());
```
- Defined in engine/src/core/math/mat4.js:58

clone

clone(): Mat4

Creates a duplicate of the specified matrix.

Returns Mat4

A duplicate matrix.

Example

const src = new pc.Mat4().setFromEulerAngles(10, 20, 30);
const dst = src.clone();
console.log("The two matrices are " + (src.equals(dst) ? "equal" : "different"));

copy

copy(rhs): Mat4

Copies the contents of a source 4x4 matrix to a destination 4x4 matrix.

Parameters

rhs: Mat4
A 4x4 matrix to be copied.

Returns Mat4

Self for chaining.

Example

const src = new pc.Mat4().setFromEulerAngles(10, 20, 30);
const dst = new pc.Mat4();
dst.copy(src);
console.log("The two matrices are " + (src.equals(dst) ? "equal" : "different"));

equals

equals(rhs): boolean
Reports whether two matrices are equal.
Parameters
- rhs: Mat4
  The other matrix.
Returns boolean
True if the matrices are equal and false otherwise.
Example
```
const a = new pc.Mat4().setFromEulerAngles(10, 20, 30);
const b = new pc.Mat4();
console.log("The two matrices are " + (a.equals(b) ? "equal" : "different"));
```
- Defined in engine/src/core/math/mat4.js:159

getEulerAngles

getEulerAngles(eulers?): Vec3
Extracts the Euler angles equivalent to the rotational portion of the specified matrix. The returned Euler angles are in XYZ order an in degrees.
Parameters
- Optional eulers: Vec3 = ...
  A 3-d vector to receive the Euler angles.
Returns Vec3
A 3-d vector containing the Euler angles.
Example
```
// Create a 4x4 rotation matrix of 45 degrees around the y-axis
const m = new pc.Mat4().setFromAxisAngle(pc.Vec3.UP, 45);

const eulers = m.getEulerAngles();
```
- Defined in engine/src/core/math/mat4.js:1244

getScale

getScale(scale?): Vec3
Extracts the scale component from the specified 4x4 matrix.
Parameters
- Optional scale: Vec3 = ...
  Vector to receive the scale.
Returns Vec3
The scale in X, Y and Z of the specified 4x4 matrix.
Example
```
// Query the scale component
const scale = m.getScale();
```
- Defined in engine/src/core/math/mat4.js:1155

getTranslation

getTranslation(t?): Vec3
Extracts the translational component from the specified 4x4 matrix.
Parameters
- Optional t: Vec3 = ...
  The vector to receive the translation of the matrix.
Returns Vec3
The translation of the specified 4x4 matrix.
Example
```
// Create a 4x4 matrix
const m = new pc.Mat4();

// Query the translation component
const t = new pc.Vec3();
m.getTranslation(t);
```
- Defined in engine/src/core/math/mat4.js:1091

getX

getX(x?): Vec3
Extracts the x-axis from the specified 4x4 matrix.
Parameters
- Optional x: Vec3 = ...
  The vector to receive the x axis of the matrix.
Returns Vec3
The x-axis of the specified 4x4 matrix.
Example
```
// Create a 4x4 matrix
const m = new pc.Mat4();

// Query the x-axis component
const x = new pc.Vec3();
m.getX(x);
```
- Defined in engine/src/core/math/mat4.js:1108

getY

getY(y?): Vec3
Extracts the y-axis from the specified 4x4 matrix.
Parameters
- Optional y: Vec3 = ...
  The vector to receive the y axis of the matrix.
Returns Vec3
The y-axis of the specified 4x4 matrix.
Example
```
// Create a 4x4 matrix
const m = new pc.Mat4();

// Query the y-axis component
const y = new pc.Vec3();
m.getY(y);
```
- Defined in engine/src/core/math/mat4.js:1125

getZ

getZ(z?): Vec3
Extracts the z-axis from the specified 4x4 matrix.
Parameters
- Optional z: Vec3 = ...
  The vector to receive the z axis of the matrix.
Returns Vec3
The z-axis of the specified 4x4 matrix.
Example
```
// Create a 4x4 matrix
const m = new pc.Mat4();

// Query the z-axis component
const z = new pc.Vec3();
m.getZ(z);
```
- Defined in engine/src/core/math/mat4.js:1142

invert

invert(src?): Mat4
Sets the matrix to the inverse of a source matrix.
Parameters
- Optional src: Mat4 = ...
  The matrix to invert. If not set, the matrix is inverted in-place.
Returns Mat4
Self for chaining.
Example
```
// Create a 4x4 rotation matrix of 180 degrees around the y-axis
const rot = new pc.Mat4().setFromAxisAngle(pc.Vec3.UP, 180);

// Invert in place
rot.invert();
```
- Defined in engine/src/core/math/mat4.js:830

isIdentity

isIdentity(): boolean
Reports whether the specified matrix is the identity matrix.

Returns boolean
True if the matrix is identity and false otherwise.
Example
```
const m = new pc.Mat4();
console.log("The matrix is " + (m.isIdentity() ? "identity" : "not identity"));
```
- Defined in engine/src/core/math/mat4.js:189

mul

mul(rhs): Mat4

Multiplies the current instance by the specified 4x4 matrix.

Parameters

rhs: Mat4
The 4x4 matrix used as the second multiplicand of the operation.

Returns Mat4

Self for chaining.

Example

const a = new pc.Mat4().setFromEulerAngles(10, 20, 30);
const b = new pc.Mat4().setFromAxisAngle(pc.Vec3.UP, 180);

// a = a * b
a.mul(b);

console.log("The result of the multiplication is: " + a.toString());

mul2

mul2(lhs, rhs): Mat4
Multiplies the specified 4x4 matrices together and stores the result in the current instance.
Parameters
- lhs: Mat4
  The 4x4 matrix used as the first multiplicand of the operation.
- rhs: Mat4
  The 4x4 matrix used as the second multiplicand of the operation.
Returns Mat4
Self for chaining.
Example
```
const a = new pc.Mat4().setFromEulerAngles(10, 20, 30);
const b = new pc.Mat4().setFromAxisAngle(pc.Vec3.UP, 180);
const r = new pc.Mat4();

// r = a * b
r.mul2(a, b);

console.log("The result of the multiplication is: " + r.toString());
```
- Defined in engine/src/core/math/mat4.js:227

mulAffine2

mulAffine2(lhs, rhs): Mat4
Multiplies the specified 4x4 matrices together and stores the result in the current instance. This function assumes the matrices are affine transformation matrices, where the upper left 3x3 elements are a rotation matrix, and the bottom left 3 elements are translation. The rightmost column is assumed to be [0, 0, 0, 1]. The parameters are not verified to be in the expected format. This function is faster than general Mat4#mul2.
Parameters
- lhs: Mat4
  The affine transformation 4x4 matrix used as the first multiplicand of the operation.
- rhs: Mat4
  The affine transformation 4x4 matrix used as the second multiplicand of the operation.
Returns Mat4
Self for chaining.
- Defined in engine/src/core/math/mat4.js:304

set

set(src): Mat4
Sets matrix data from an array.
Parameters
- src: number[]
  Source array. Must have 16 values.
Returns Mat4
Self for chaining.
- Defined in engine/src/core/math/mat4.js:897

setFromAxisAngle

setFromAxisAngle(axis, angle): Mat4
Sets the specified matrix to a rotation matrix equivalent to a rotation around an axis. The axis must be normalized (unit length) and the angle must be specified in degrees.
Parameters
- axis: Vec3
  The normalized axis vector around which to rotate.
- angle: number
  The angle of rotation in degrees.
Returns Mat4
Self for chaining.
Example
```
// Create a 4x4 rotation matrix
const rm = new pc.Mat4().setFromAxisAngle(pc.Vec3.UP, 90);
```
- Defined in engine/src/core/math/mat4.js:642

setFromEulerAngles

setFromEulerAngles(ex, ey, ez): Mat4
Sets the specified matrix to a rotation matrix defined by Euler angles. The Euler angles are specified in XYZ order and in degrees.
Parameters
- ex: number
  Angle to rotate around X axis in degrees.
- ey: number
  Angle to rotate around Y axis in degrees.
- ez: number
  Angle to rotate around Z axis in degrees.
Returns Mat4
Self for chaining.
Example
```
const m = new pc.Mat4();
m.setFromEulerAngles(45, 90, 180);
```
- Defined in engine/src/core/math/mat4.js:1190

setIdentity

setIdentity(): Mat4
Sets the specified matrix to the identity matrix.

Returns Mat4
Self for chaining.
Example
```
m.setIdentity();
console.log("The matrix is " + (m.isIdentity() ? "identity" : "not identity"));
```
- Defined in engine/src/core/math/mat4.js:928

setLookAt

setLookAt(position, target, up): Mat4
Sets the specified matrix to a viewing matrix derived from an eye point, a target point and an up vector. The matrix maps the target point to the negative z-axis and the eye point to the origin, so that when you use a typical projection matrix, the center of the scene maps to the center of the viewport. Similarly, the direction described by the up vector projected onto the viewing plane is mapped to the positive y-axis so that it points upward in the viewport. The up vector must not be parallel to the line of sight from the eye to the reference point.
Parameters
- position: Vec3
  3-d vector holding view position.
- target: Vec3
  3-d vector holding reference point.
- up: Vec3
  3-d vector holding the up direction.
Returns Mat4
Self for chaining.
Example
```
const position = new pc.Vec3(10, 10, 10);
const target = new pc.Vec3(0, 0, 0);
const up = new pc.Vec3(0, 1, 0);
const m = new pc.Mat4().setLookAt(position, target, up);
```
- Defined in engine/src/core/math/mat4.js:491

setOrtho

setOrtho(left, right, bottom, top, near, far): Mat4
Sets the specified matrix to an orthographic projection matrix. The function's parameters define the shape of a cuboid-shaped frustum.
Parameters
- left: number
  The x-coordinate for the left edge of the camera's projection plane in eye space.
- right: number
  The x-coordinate for the right edge of the camera's projection plane in eye space.
- bottom: number
  The y-coordinate for the bottom edge of the camera's projection plane in eye space.
- top: number
  The y-coordinate for the top edge of the camera's projection plane in eye space.
- near: number
  The near clip plane in eye coordinates.
- far: number
  The far clip plane in eye coordinates.
Returns Mat4
Self for chaining.
Example
```
// Create a 4x4 orthographic projection matrix
const ortho = pc.Mat4().ortho(-2, 2, -2, 2, 1, 1000);
```
- Defined in engine/src/core/math/mat4.js:608

setPerspective

setPerspective(fov, aspect, znear, zfar, fovIsHorizontal?): Mat4
Sets the specified matrix to a perspective projection matrix. The function's parameters define the shape of a frustum.
Parameters
- fov: number
  The frustum's field of view in degrees. The fovIsHorizontal parameter controls whether this is a vertical or horizontal field of view. By default, it's a vertical field of view.
- aspect: number
  The aspect ratio of the frustum's projection plane (width / height).
- znear: number
  The near clip plane in eye coordinates.
- zfar: number
  The far clip plane in eye coordinates.
- Optional fovIsHorizontal: boolean
  Set to true to treat the fov as horizontal (x-axis) and false for vertical (y-axis). Defaults to false.
Returns Mat4
Self for chaining.
Example
```
// Create a 4x4 perspective projection matrix
const persp = pc.Mat4().setPerspective(45, 16 / 9, 1, 1000);
```
- Defined in engine/src/core/math/mat4.js:584

setReflection

setReflection(normal, distance): Mat4
Sets the matrix to a reflection matrix, which can be used as a mirror transformation by the plane.
Parameters
- normal: Vec3
  The normal of the plane to reflect by.
- distance: number
  The distance of plane to reflect by.
Returns Mat4
Self for chaining.
- Defined in engine/src/core/math/mat4.js:791

setTRS

setTRS(t, r, s): Mat4
Sets the specified matrix to the concatenation of a translation, a quaternion rotation and a scale.
Parameters
- t: Vec3
  A 3-d vector translation.
- r: Quat
  A quaternion rotation.
- s: Vec3
  A 3-d vector scale.
Returns Mat4
Self for chaining.
Example
```
const t = new pc.Vec3(10, 20, 30);
const r = new pc.Quat();
const s = new pc.Vec3(2, 2, 2);

const m = new pc.Mat4();
m.setTRS(t, r, s);
```
- Defined in engine/src/core/math/mat4.js:967

toString

toString(): string
Converts the specified matrix to string form.

Returns string
The matrix in string form.
Example
```
const m = new pc.Mat4();
// Outputs [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
console.log(m.toString());
```
- Defined in engine/src/core/math/mat4.js:1287

transformPoint

transformPoint(vec, res?): Vec3
Transforms a 3-dimensional point by a 4x4 matrix.
Parameters
- vec: Vec3
  The 3-dimensional point to be transformed.
- Optional res: Vec3 = ...
  An optional 3-dimensional point to receive the result of the transformation.
Returns Vec3
The input point v transformed by the current instance.
Example
```
// Create a 3-dimensional point
const v = new pc.Vec3(1, 2, 3);

// Create a 4x4 rotation matrix
const m = new pc.Mat4().setFromEulerAngles(10, 20, 30);

const tv = m.transformPoint(v);
```
- Defined in engine/src/core/math/mat4.js:393

transformVec4

transformVec4(vec, res?): Vec4
Transforms a 4-dimensional vector by a 4x4 matrix.
Parameters
- vec: Vec4
  The 4-dimensional vector to be transformed.
- Optional res: Vec4 = ...
  An optional 4-dimensional vector to receive the result of the transformation.
Returns Vec4
The input vector v transformed by the current instance.
Example
```
// Create an input 4-dimensional vector
const v = new pc.Vec4(1, 2, 3, 4);

// Create an output 4-dimensional vector
const result = new pc.Vec4();

// Create a 4x4 rotation matrix
const m = new pc.Mat4().setFromEulerAngles(10, 20, 30);

m.transformVec4(v, result);
```
- Defined in engine/src/core/math/mat4.js:456

transformVector

transformVector(vec, res?): Vec3
Transforms a 3-dimensional vector by a 4x4 matrix.
Parameters
- vec: Vec3
  The 3-dimensional vector to be transformed.
- Optional res: Vec3 = ...
  An optional 3-dimensional vector to receive the result of the transformation.
Returns Vec3
The input vector v transformed by the current instance.
Example
```
// Create a 3-dimensional vector
const v = new pc.Vec3(1, 2, 3);

// Create a 4x4 rotation matrix
const m = new pc.Mat4().setFromEulerAngles(10, 20, 30);

const tv = m.transformVector(v);
```
- Defined in engine/src/core/math/mat4.js:423

transpose

transpose(src?): Mat4
Sets the matrix to the transpose of a source matrix.
Parameters
- Optional src: Mat4 = ...
  The matrix to transpose. If not set, the matrix is transposed in-place.
Returns Mat4
Self for chaining.
Example
```
const m = new pc.Mat4();

// Transpose in place
m.transpose();
```
- Defined in engine/src/core/math/mat4.js:1026

Class Mat4

Index

Constructors

Properties

Methods

Constructors

constructor

Returns Mat4

Properties

data

Static Readonly IDENTITY

Static Readonly ZERO

Methods

add

Parameters

Returns Mat4

Example

add2

Parameters

Returns Mat4

Example

clone

Returns Mat4

Example

copy

Parameters

Returns Mat4

Example

equals

Parameters

Returns boolean

Example

getEulerAngles

Parameters

Returns Vec3

Example

getScale

Parameters

Returns Vec3

Example

getTranslation

Parameters

Returns Vec3

Example

getX

Parameters

Returns Vec3

Example

getY

Parameters

Returns Vec3

Example

getZ

Parameters

Returns Vec3

Example

invert

Parameters

Returns Mat4

Example

isIdentity

Returns boolean

Example

mul

Parameters

Returns Mat4

Example

mul2

Parameters

Returns Mat4

Example

mulAffine2

Parameters

Returns Mat4

set

Parameters

Returns Mat4

setFromAxisAngle

Parameters

Returns Mat4

`Static` `Readonly` IDENTITY

`Static` `Readonly` ZERO