Class Matrix3

A 3x3 matrix, for 2D affine transforms such as UV transforms, and for the normal matrix of a 3D transform

Matrix3#elements holds the nine values column by column, the order shaders use, and a Matrix3 can be the value of a mat3x3<f32> uniform as it is. The 2D methods (Matrix3#translate, Matrix3#rotate, Matrix3#scale) each apply after the transform built so far, like pixi's Matrix.

Methods that change the matrix do so in place, or write into an out matrix when you pass one and leave this matrix as it is.

Example

const tile = new Matrix3().scale(4, 4).translate(0.5, 0);
const uv = new Vector2(0.25, 0.75).applyMatrix3(tile);

const normalMatrix = new Matrix3().getNormalMatrix(mesh.worldTransform);
const uniforms = new UniformGroup({ uNormalMatrix: { value: normalMatrix, type: 'mat3x3<f32>' } });

Index

Constructors

constructor

new Matrix3(elements?: TypedFixedArray<9>): Matrix3
Creates a new Matrix3, defaulting to the identity matrix
Parameters
- Optionalelements: TypedFixedArray<9>
  Optional column-major backing array of 9 floats, used as is rather than copied
Returns Matrix3

Properties

`Advanced`array

array: Float32Array<ArrayBufferLike> | null = null

The array Matrix3#toArray writes into when given no out; null until its first call

Example

uvTransform.toArray(true);
const rowMajor = uvTransform.array!;

Default

null
@advanced

elements

elements: TypedFixedArray<9>

The nine values, column by column: a 2D translation sits at indices 6 and 7

Example

const scrollU = uvTransform.elements[6];

Accessors

`Static`IDENTITY

get IDENTITY(): Readonly<Matrix3>
A read-only identity matrix

Important
This is a shared instance; do not mutate it. Use Matrix3.shared when you need a writable temporary.

Returns Readonly<Matrix3>
Example
```
const untransformed = uvTransform.equals(Matrix3.IDENTITY);
```

`Static`shared

get shared(): Matrix3
A shared Matrix3, reset to identity on every access, for a one-off calculation

Important
This matrix is shared and temporary. Do not store references to it.

Returns Matrix3
Example
```
const turned = new Vector2(1, 0).applyMatrix3(Matrix3.shared.rotate(angle));
```

Methods

append

append(m: Matrix3, out?: Matrix3): this
Pixi-style alias for Matrix3#multiply: this = this * m
Parameters
- m: Matrix3
  Matrix to append
- out: Matrix3 = ...
  Optional target; defaults to writing into this matrix
Returns this
The matrix the result was written to
Example
```
frameTransform.append(tileTransform, atlasUv);
```

appendFrom

appendFrom(a: Matrix3, b: Matrix3, out?: Matrix3): this
Alias for Matrix3#multiplyMatrices: this matrix becomes a * b
Parameters
- a: Matrix3
  Left operand
- b: Matrix3
  Right operand
- out: Matrix3 = ...
  Optional target; defaults to writing into this matrix
Returns this
The matrix the result was written to
Example
```
atlasUv.appendFrom(frameTransform, tileTransform);
```

clone

clone(): Matrix3
Creates a new Matrix3 with the same elements

Returns Matrix3
The new matrix
Example
```
const mirrored = uvTransform.clone().scale(-1, 1);
```

copyFrom

copyFrom(m: Matrix3): this
Copies the elements of m into this matrix
Parameters
- m: Matrix3
  Matrix to copy from
Returns this
This matrix
Example
```
previousUvTransform.copyFrom(uvTransform);
```

copyTo

copyTo<T extends Matrix3>(target: T): T
Copies this matrix's elements into target
Type Parameters
- T extends Matrix3
Parameters
- target: T
  Matrix to copy into
Returns T
The given target matrix
Example
```
uvTransform.copyTo(previousUvTransform);
```

determinant

determinant(): number
Computes the determinant of this matrix

Negative when the transform mirrors, and 0 when it flattens a dimension and can't be inverted.

Returns number
The determinant
Example
```
const mirrored = uvTransform.determinant() < 0;
```

equals

equals(m: Matrix3): boolean
Checks whether all 9 elements of this matrix match m exactly, with no tolerance
Parameters
- m: Matrix3
  Matrix to compare against
Returns boolean
True when every element matches
Example
```
if (!uvTransform.equals(previousUvTransform)) material.update();
```

fromArray

fromArray(array: ArrayLike<number>, offset?: number): this
Reads the 9 elements from array (column-major) starting at offset
Parameters
- array: ArrayLike<number>
  Source array of column-major elements
- offset: number = 0
  Index of the first element to read
Returns this
This matrix
Example
```
const frameTransform = new Matrix3().fromArray(packedTransforms, frame * 9);
```

getInverse

getInverse(m: Matrix3, throwOnDegenerate?: boolean, out?: Matrix3): this
Sets this matrix to the inverse of m

When m can't be inverted (its determinant is 0), the result is the identity and a warning is logged.
Parameters
- m: Matrix3
  Matrix to invert
- OptionalthrowOnDegenerate: boolean
  true throws instead of warning when m can't be inverted
- out: Matrix3 = ...
  Optional target; defaults to writing into this matrix
Returns this
The matrix the result was written to
Example
```
const screenToUv = new Matrix3().getInverse(uvToScreen);
```

getNormalMatrix

getNormalMatrix(matrix4: Matrix4, out?: Matrix3): this
Sets this matrix to the normal matrix of matrix4: the inverse transpose of its upper-left 3x3 block

Normals transformed by it stay at right angles to the surface when the model has non-uniform scale; renormalize them after. A matrix with zero scale on an axis gives the identity and logs a warning.
Parameters
- matrix4: Matrix4
  World matrix to derive the normal matrix from
- out: Matrix3 = ...
  Optional target; defaults to writing into this matrix
Returns this
The matrix the result was written to
Example
```
const normalMatrix = new Matrix3().getNormalMatrix(mesh.worldTransform);
const worldNormal = hitNormal.clone().applyMatrix3(normalMatrix).normalize();
```

identity

identity(): this
Resets this matrix to the identity matrix

Returns this
This matrix
Example
```
uvTransform.identity().translate(scroll, 0);
```

isIdentity

isIdentity(): boolean
Checks whether this matrix equals the identity matrix exactly

Returns boolean
True when every element matches the identity matrix
Example
```
if (!uvTransform.isIdentity()) uniforms.uniforms.uUvTransform = uvTransform;
```

multiply

multiply(m: Matrix3, out?: Matrix3): this
Multiplies this matrix by m: this = this * m, so m applies to a point first
Parameters
- m: Matrix3
  Matrix to multiply by
- out: Matrix3 = ...
  Optional target; defaults to writing into this matrix
Returns this
The matrix the result was written to
Example
```
const atlasUv = new Matrix3();

frameTransform.multiply(tileTransform, atlasUv);
```

multiplyMatrices

multiplyMatrices(a: Matrix3, b: Matrix3, out?: Matrix3): this
Sets this matrix to a * b, so b applies to a point first
Parameters
- a: Matrix3
  Left operand
- b: Matrix3
  Right operand
- out: Matrix3 = ...
  Optional target; defaults to writing into this matrix
Returns this
The matrix the result was written to
Example
```
atlasUv.multiplyMatrices(frameTransform, tileTransform);
```

multiplyScalar

multiplyScalar(s: number, out?: Matrix3): this
Advanced
Multiplies every element of this matrix by the scalar s
Parameters
- s: number
  Scalar to multiply by
- out: Matrix3 = ...
  Optional target; defaults to writing into this matrix
Returns this
The matrix the result was written to

premultiply

premultiply(m: Matrix3, out?: Matrix3): this
Pre-multiplies this matrix by m: this = m * this, so m applies to a point last
Parameters
- m: Matrix3
  Matrix to pre-multiply by
- out: Matrix3 = ...
  Optional target; defaults to writing into this matrix
Returns this
The matrix the result was written to
Example
```
uvTransform.premultiply(frameTransform);
```

prepend

prepend(m: Matrix3, out?: Matrix3): this
Pixi-style alias for Matrix3#premultiply: this = m * this
Parameters
- m: Matrix3
  Matrix to prepend
- out: Matrix3 = ...
  Optional target; defaults to writing into this matrix
Returns this
The matrix the result was written to
Example
```
uvTransform.prepend(frameTransform);
```

rotate

rotate(theta: number, out?: Matrix3): this
Rotates this matrix by theta radians around the origin (2D affine)

The rotation applies after the existing transform, and a positive angle turns +x toward +y, the same as pixi's Matrix.rotate.
Parameters
- theta: number
  Rotation angle in radians
- out: Matrix3 = ...
  Optional target; defaults to writing into this matrix
Returns this
The matrix the result was written to
Example
```
const spin = new Matrix3().translate(-0.5, -0.5).rotate(angle).translate(0.5, 0.5);
```

scale

scale(sx: number, sy: number, out?: Matrix3): this
Scales this 2D transform by (sx, sy) about the origin, applied after the transform built so far, like pixi's Matrix.scale
Parameters
- sx: number
  Scale along x
- sy: number
  Scale along y
- out: Matrix3 = ...
  Optional target; defaults to writing into this matrix
Returns this
The matrix the result was written to
Example
```
const tiled = new Matrix3().scale(4, 4);
```

set

set(
    n11: number,
    n12: number,
    n13: number,
    n21: number,
    n22: number,
    n23: number,
    n31: number,
    n32: number,
    n33: number,
): this
Sets the 9 elements from arguments given row by row, as the matrix is written on paper
Parameters
- n11: number
  Row 1, column 1
- n12: number
  Row 1, column 2
- n13: number
  Row 1, column 3
- n21: number
  Row 2, column 1
- n22: number
  Row 2, column 2
- n23: number
  Row 2, column 3
- n31: number
  Row 3, column 1
- n32: number
  Row 3, column 2
- n33: number
  Row 3, column 3
Returns this
This matrix
Example
```
const skew = new Matrix3().set(
  1, 0.3, 0,
  0, 1, 0,
  0, 0, 1,
);
```

setFromMatrix4

setFromMatrix4(m: Matrix4, out?: Matrix3): this
Sets this matrix to the upper-left 3x3 block of the given Matrix4: its rotation and scale, without the translation
Parameters
- m: Matrix4
  Matrix to read from
- out: Matrix3 = ...
  Optional target; defaults to writing into this matrix
Returns this
The matrix the result was written to
Example
```
const linear = new Matrix3().setFromMatrix4(mesh.worldTransform);
const worldOffset = localOffset.clone().applyMatrix3(linear);
```

setUvTransform

setUvTransform(
    tx: number,
    ty: number,
    sx: number,
    sy: number,
    rotation: number,
    cx: number,
    cy: number,
): this
Sets this matrix to a UV transform: rotate by rotation and scale by (sx, sy), both about (cx, cy), then offset by (tx, ty)

A positive rotation turns +u toward -v. The rotation applies before the scale, which is the opposite of glTF's KHR_texture_transform, so the two disagree when the scale is non-uniform and the rotation isn't zero. A material's UVs take a pixi Matrix in BaseMaterial3D#uvTransform instead.
Parameters
- tx: number
  Translation along u
- ty: number
  Translation along v
- sx: number
  Scale along u
- sy: number
  Scale along v
- rotation: number
  Rotation angle in radians
- cx: number
  Rotation center u
- cy: number
  Rotation center v
Returns this
This matrix
Example
```
const uvTransform = new Matrix3().setUvTransform(0, 0, 2, 2, Math.PI / 4, 0.5, 0.5);
```

toArray

toArray(transpose?: boolean, out?: Float32Array<ArrayBufferLike>): Float32Array
Writes this matrix's elements into a Float32Array

Without out, writes into and returns Matrix3#array.
Parameters
- Optionaltranspose: boolean
  true writes row-major instead of column-major
- Optionalout: Float32Array<ArrayBufferLike>
  Optional destination array
Returns Float32Array
The populated array
Example
```
const rowMajor = new Float32Array(9);

uvTransform.toArray(true, rowMajor);
```

toString

toString(): string

Advanced
Formats this matrix as a readable row-by-row string

Returns string
The string representation

translate

translate(tx: number, ty: number, out?: Matrix3): this
Moves this 2D transform by (tx, ty), applied after the transform built so far, like pixi's Matrix.translate
Parameters
- tx: number
  Translation along x
- ty: number
  Translation along y
- out: Matrix3 = ...
  Optional target; defaults to writing into this matrix
Returns this
The matrix the result was written to
Example
```
app.ticker.add((ticker) => {
  uvTransform.identity().translate((ticker.lastTime * 0.0001) % 1, 0);
});
```

transpose

transpose(out?: Matrix3): this
Transposes this matrix
Parameters
- out: Matrix3 = ...
  Optional target; defaults to writing into this matrix
Returns this
The matrix the result was written to
Example
```
const rowMajor = new Matrix3();

normalMatrix.transpose(rowMajor);
```

Class Matrix3

Example

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns Matrix3

Properties

Advancedarray

Example

Default

elements

Example

Accessors

StaticIDENTITY

Returns Readonly<Matrix3>

Example

Staticshared

Returns Matrix3

Example

Methods

append

Parameters

Returns this

Example

appendFrom

Parameters

Returns this

Example

clone

Returns Matrix3

Example

copyFrom

Parameters

Returns this

Example

copyTo

Type Parameters

Parameters

Returns T

Example

determinant

Returns number

Example

equals

Parameters

Returns boolean

Example

fromArray

Parameters

Returns this

Example

getInverse

Parameters

Returns this

Example

getNormalMatrix

Parameters

Returns this

Example

identity

Returns this

Example

isIdentity

Returns boolean

Example

multiply

Parameters

Returns this

Example

multiplyMatrices

Parameters

Returns this

Example

multiplyScalar

Parameters

`Advanced`array

`Static`IDENTITY

`Static`shared