# Mat4

Class · category: Math

Source: https://github.com/playcanvas/engine/blob/f059dc005842f76e052cdf44d8370c8c7ec475ac/src/core/math/mat4.js#L48

A 4x4 matrix. Mat4 is commonly used to represent world, view and projection transformations in 3D
graphics, combining rotation, translation and scale into a single matrix.

A new Mat4 is the identity. Elements live in [data](https://api.playcanvas.com/engine/classes/Mat4.md#data), a 16-element `Float32Array` in
column-major order: the translation occupies elements 12, 13 and 14. Build a transform with
[setTRS](https://api.playcanvas.com/engine/classes/Mat4.md#settrs), [setFromEulerAngles](https://api.playcanvas.com/engine/classes/Mat4.md#setfromeulerangles) or [setFromAxisAngle](https://api.playcanvas.com/engine/classes/Mat4.md#setfromaxisangle), a camera matrix with
[setLookAt](https://api.playcanvas.com/engine/classes/Mat4.md#setlookat), [setPerspective](https://api.playcanvas.com/engine/classes/Mat4.md#setperspective) or [setOrtho](https://api.playcanvas.com/engine/classes/Mat4.md#setortho), and read parts back with
[getTranslation](https://api.playcanvas.com/engine/classes/Mat4.md#gettranslation), [getScale](https://api.playcanvas.com/engine/classes/Mat4.md#getscale) and [getEulerAngles](https://api.playcanvas.com/engine/classes/Mat4.md#geteulerangles). Angles are in degrees.

Matrices combine by multiplication: `r.mul2(a, b)` computes `a * b`, so `b` is applied first when
the result transforms a point. [transformPoint](https://api.playcanvas.com/engine/classes/Mat4.md#transformpoint) applies the full transform including
translation, while [transformVector](https://api.playcanvas.com/engine/classes/Mat4.md#transformvector) applies only rotation and scale, which is what
directions need.

Methods modify the matrix they are called on and return it for chaining. Use [clone](https://api.playcanvas.com/engine/classes/Mat4.md#clone) for an
independent copy and [copy](https://api.playcanvas.com/engine/classes/Mat4.md#copy) to overwrite. [IDENTITY](https://api.playcanvas.com/engine/classes/Mat4.md#identity) and [ZERO](https://api.playcanvas.com/engine/classes/Mat4.md#zero) are frozen
shared instances, and the matrix returned by [GraphNode#getWorldTransform](https://api.playcanvas.com/engine/classes/GraphNode.md#getworldtransform) is internal
storage to be treated as read-only.

**Example**

```ts
// Compose a transform from position, rotation and scale
const world = new Mat4().setTRS(
    new Vec3(0, 1, 0),
    new Quat().setFromEulerAngles(0, 45, 0),
    Vec3.ONE
);
```

**Example**

```ts
// Transform a local point into world space
const worldPoint = entity.getWorldTransform().transformPoint(localPoint);
```

## Constructors

### constructor

```ts
new Mat4()
```

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

## Properties

### data

```ts
data: Float32Array<ArrayBufferLike>
```

Matrix elements in the form of a flat array.

### IDENTITY

```ts
static readonly IDENTITY: Mat4
```

A constant matrix set to the identity.

### ZERO

```ts
static readonly ZERO: Mat4
```

A constant matrix with all elements set to 0.

## Methods

### add

```ts
add(rhs: Mat4): Mat4
```

Adds the specified 4x4 matrix to the current instance.

**Parameters**

- `rhs` ([`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md)): The 4x4 matrix used as the second operand of the addition.

**Returns** [`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md): Self for chaining.

**Example**

```ts
const m = new Mat4();

m.add(Mat4.ONE);

console.log("The result of the addition is: " + m.toString());
```

### add2

```ts
add2(lhs: Mat4, rhs: Mat4): Mat4
```

Adds the specified 4x4 matrices together and stores the result in the current instance.

**Parameters**

- `lhs` ([`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md)): The 4x4 matrix used as the first operand of the addition.
- `rhs` ([`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md)): The 4x4 matrix used as the second operand of the addition.

**Returns** [`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md): Self for chaining.

**Example**

```ts
const m = new Mat4();

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

console.log("The result of the addition is: " + m.toString());
```

### clone

```ts
clone(): Mat4
```

Creates a duplicate of the specified matrix.

**Returns** [`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md): A duplicate matrix.

**Example**

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

### copy

```ts
copy(rhs: Mat4): Mat4
```

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

**Parameters**

- `rhs` ([`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md)): A 4x4 matrix to be copied.

**Returns** [`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md): Self for chaining.

**Example**

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

### equals

```ts
equals(rhs: Mat4): boolean
```

Reports whether two matrices are equal.

**Parameters**

- `rhs` ([`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md)): The other matrix.

**Returns** `boolean`: True if the matrices are equal and false otherwise.

**Example**

```ts
const a = new Mat4().setFromEulerAngles(10, 20, 30);
const b = new Mat4();
console.log("The two matrices are " + (a.equals(b) ? "equal" : "different"));
```

### getEulerAngles

```ts
getEulerAngles(eulers?: Vec3): Vec3
```

Extracts the Euler angles equivalent to the rotational portion of the specified matrix. The
returned Euler angles are in **intrinsic XYZ** order and in degrees.

**Parameters**

- `eulers` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md), optional): A 3-d vector to receive the Euler angles.

**Returns** [`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md): A 3-d vector containing the Euler angles.

**Example**

```ts
// Create a 4x4 rotation matrix of 45 degrees around the y-axis
const m = new Mat4().setFromAxisAngle(Vec3.UP, 45);

const eulers = m.getEulerAngles();
```

### getScale

```ts
getScale(scale?: Vec3): Vec3
```

Extracts the scale component from the specified 4x4 matrix.

**Parameters**

- `scale` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md), optional): Vector to receive the scale.

**Returns** [`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md): The scale in X, Y and Z of the specified 4x4 matrix.

**Example**

```ts
// Query the scale component
const scale = m.getScale();
```

### getTranslation

```ts
getTranslation(t?: Vec3): Vec3
```

Extracts the translational component from the specified 4x4 matrix.

**Parameters**

- `t` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md), optional): The vector to receive the translation of the matrix.

**Returns** [`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md): The translation of the specified 4x4 matrix.

**Example**

```ts
// Create a 4x4 matrix
const m = new Mat4();

// Query the translation component
const t = new Vec3();
m.getTranslation(t);
```

### getX

```ts
getX(x?: Vec3): Vec3
```

Extracts the x-axis from the specified 4x4 matrix.

**Parameters**

- `x` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md), optional): The vector to receive the x axis of the matrix.

**Returns** [`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md): The x-axis of the specified 4x4 matrix.

**Example**

```ts
// Create a 4x4 matrix
const m = new Mat4();

// Query the x-axis component
const x = new Vec3();
m.getX(x);
```

### getY

```ts
getY(y?: Vec3): Vec3
```

Extracts the y-axis from the specified 4x4 matrix.

**Parameters**

- `y` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md), optional): The vector to receive the y axis of the matrix.

**Returns** [`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md): The y-axis of the specified 4x4 matrix.

**Example**

```ts
// Create a 4x4 matrix
const m = new Mat4();

// Query the y-axis component
const y = new Vec3();
m.getY(y);
```

### getZ

```ts
getZ(z?: Vec3): Vec3
```

Extracts the z-axis from the specified 4x4 matrix.

**Parameters**

- `z` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md), optional): The vector to receive the z axis of the matrix.

**Returns** [`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md): The z-axis of the specified 4x4 matrix.

**Example**

```ts
// Create a 4x4 matrix
const m = new Mat4();

// Query the z-axis component
const z = new Vec3();
m.getZ(z);
```

### invert

```ts
invert(src?: Mat4): Mat4
```

Sets the matrix to the inverse of a source matrix.

**Parameters**

- `src` ([`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md), optional): The matrix to invert. If not set, the matrix is inverted in-place.

**Returns** [`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md): Self for chaining.

**Example**

```ts
// Create a 4x4 rotation matrix of 180 degrees around the y-axis
const rot = new Mat4().setFromAxisAngle(Vec3.UP, 180);

// Invert in place
rot.invert();
```

### isIdentity

```ts
isIdentity(): boolean
```

Reports whether the specified matrix is the identity matrix.

**Returns** `boolean`: True if the matrix is identity and false otherwise.

**Example**

```ts
const m = new Mat4();
console.log("The matrix is " + (m.isIdentity() ? "identity" : "not identity"));
```

### mul

```ts
mul(rhs: Mat4): Mat4
```

Multiplies the current instance by the specified 4x4 matrix.

**Parameters**

- `rhs` ([`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md)): The 4x4 matrix used as the second multiplicand of the operation.

**Returns** [`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md): Self for chaining.

**Example**

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

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

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

### mul2

```ts
mul2(lhs: Mat4, rhs: Mat4): Mat4
```

Multiplies the specified 4x4 matrices together and stores the result in the current
instance.

**Parameters**

- `lhs` ([`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md)): The 4x4 matrix used as the first multiplicand of the operation.
- `rhs` ([`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md)): The 4x4 matrix used as the second multiplicand of the operation.

**Returns** [`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md): Self for chaining.

**Example**

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

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

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

### mulAffine2

```ts
mulAffine2(lhs: Mat4, rhs: Mat4): 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 [mul2](https://api.playcanvas.com/engine/classes/Mat4.md#mul2).

**Parameters**

- `lhs` ([`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md)): The affine transformation 4x4 matrix used as the first multiplicand of
  the operation.
- `rhs` ([`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md)): The affine transformation 4x4 matrix used as the second multiplicand of
  the operation.

**Returns** [`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md): Self for chaining.

**Example**

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

// r = a * b (optimized for affine transforms)
r.mulAffine2(a, b);
```

### set

```ts
set(src: number[]): Mat4
```

Sets matrix data from an array.

**Parameters**

- `src` (`number[]`): Source array. Must have 16 values.

**Returns** [`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md): Self for chaining.

**Example**

```ts
const m = new Mat4();
m.set([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 10, 20, 30, 1]);
```

### setFromAxisAngle

```ts
setFromAxisAngle(axis: Vec3, angle: number): 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`](https://api.playcanvas.com/engine/classes/Vec3.md)): The normalized axis vector around which to rotate.
- `angle` (`number`): The angle of rotation in degrees.

**Returns** [`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md): Self for chaining.

**Example**

```ts
// Create a 4x4 rotation matrix
const rm = new Mat4().setFromAxisAngle(Vec3.UP, 90);
```

### setFromEulerAngles

```ts
setFromEulerAngles(ex: number, ey: number, ez: number): Mat4
```

Sets the specified matrix to a rotation matrix defined by Euler angles. The rotation is
applied using an **intrinsic XYZ** order: first around the X-axis, then around the newly
transformed Y-axis, and finally around the resulting Z-axis. Angles are specified 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`](https://api.playcanvas.com/engine/classes/Mat4.md): Self for chaining.

**Example**

```ts
const m = new Mat4();
m.setFromEulerAngles(45, 90, 180);
```

### setIdentity

```ts
setIdentity(): Mat4
```

Sets the specified matrix to the identity matrix.

**Returns** [`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md): Self for chaining.

**Example**

```ts
m.setIdentity();
console.log("The matrix is " + (m.isIdentity() ? "identity" : "not identity"));
```

### setLookAt

```ts
setLookAt(position: Vec3, target: Vec3, up: Vec3): 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`](https://api.playcanvas.com/engine/classes/Vec3.md)): 3-d vector holding view position.
- `target` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): 3-d vector holding reference point.
- `up` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): 3-d vector holding the up direction.

**Returns** [`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md): Self for chaining.

**Example**

```ts
const position = new Vec3(10, 10, 10);
const target = new Vec3(0, 0, 0);
const up = new Vec3(0, 1, 0);
const m = new Mat4().setLookAt(position, target, up);
```

### setOrtho

```ts
setOrtho(left: number, right: number, bottom: number, top: number, near: number, far: number): 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`](https://api.playcanvas.com/engine/classes/Mat4.md): Self for chaining.

**Example**

```ts
// Create a 4x4 orthographic projection matrix
const ortho = new Mat4().setOrtho(-2, 2, -2, 2, 1, 1000);
```

### setPerspective

```ts
setPerspective(fov: number, aspect: number, znear: number, zfar: number, fovIsHorizontal?: boolean): 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.
- `fovIsHorizontal` (`boolean`, optional): Set to true to treat the fov as horizontal (x-axis) and
  false for vertical (y-axis). Defaults to false.

**Returns** [`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md): Self for chaining.

**Example**

```ts
// Create a 4x4 perspective projection matrix
const persp = new Mat4().setPerspective(45, 16 / 9, 1, 1000);
```

### setReflection

```ts
setReflection(normal: Vec3, distance: number): Mat4
```

Sets the matrix to a reflection matrix, which can be used as a mirror transformation by the
plane.

**Parameters**

- `normal` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The normal of the plane to reflect by.
- `distance` (`number`): The distance of plane to reflect by.

**Returns** [`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md): Self for chaining.

**Example**

```ts
// Create a reflection matrix for a horizontal plane at y=0
const reflection = new Mat4().setReflection(Vec3.UP, 0);
```

### setTRS

```ts
setTRS(t: Vec3, r: Quat, s: Vec3): Mat4
```

Sets the specified matrix to the concatenation of a translation, a quaternion rotation and a
scale.

**Parameters**

- `t` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): A 3-d vector translation.
- `r` ([`Quat`](https://api.playcanvas.com/engine/classes/Quat.md)): A quaternion rotation.
- `s` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): A 3-d vector scale.

**Returns** [`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md): Self for chaining.

**Example**

```ts
const t = new Vec3(10, 20, 30);
const r = new Quat();
const s = new Vec3(2, 2, 2);

const m = new Mat4();
m.setTRS(t, r, s);
```

### toString

```ts
toString(): string
```

Converts the specified matrix to string form.

**Returns** `string`: The matrix in string form.

**Example**

```ts
const m = new Mat4();
// Outputs [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
console.log(m.toString());
```

### transformPoint

```ts
transformPoint(vec: Vec3, res?: Vec3): Vec3
```

Transforms a 3-dimensional point by a 4x4 matrix.

**Parameters**

- `vec` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The 3-dimensional point to be transformed.
- `res` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md), optional): An optional 3-dimensional point to receive the result of the
  transformation.

**Returns** [`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md): The input point v transformed by the current instance.

**Example**

```ts
// Create a 3-dimensional point
const v = new Vec3(1, 2, 3);

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

const tv = m.transformPoint(v);
```

### transformVec4

```ts
transformVec4(vec: Vec4, res?: Vec4): Vec4
```

Transforms a 4-dimensional vector by a 4x4 matrix.

**Parameters**

- `vec` ([`Vec4`](https://api.playcanvas.com/engine/classes/Vec4.md)): The 4-dimensional vector to be transformed.
- `res` ([`Vec4`](https://api.playcanvas.com/engine/classes/Vec4.md), optional): An optional 4-dimensional vector to receive the result of the
  transformation.

**Returns** [`Vec4`](https://api.playcanvas.com/engine/classes/Vec4.md): The input vector v transformed by the current instance.

**Example**

```ts
// Create an input 4-dimensional vector
const v = new Vec4(1, 2, 3, 4);

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

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

m.transformVec4(v, result);
```

### transformVector

```ts
transformVector(vec: Vec3, res?: Vec3): Vec3
```

Transforms a 3-dimensional vector by a 4x4 matrix.

**Parameters**

- `vec` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The 3-dimensional vector to be transformed.
- `res` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md), optional): An optional 3-dimensional vector to receive the result of the
  transformation.

**Returns** [`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md): The input vector v transformed by the current instance.

**Example**

```ts
// Create a 3-dimensional vector
const v = new Vec3(1, 2, 3);

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

const tv = m.transformVector(v);
```

### transpose

```ts
transpose(src?: Mat4): Mat4
```

Sets the matrix to the transpose of a source matrix.

**Parameters**

- `src` ([`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md), optional): The matrix to transpose. If not set, the matrix is transposed in-place.

**Returns** [`Mat4`](https://api.playcanvas.com/engine/classes/Mat4.md): Self for chaining.

**Example**

```ts
const m = new Mat4();

// Transpose in place
m.transpose();
```