Mirror Engine API / Mat4
Class: Mat4
A 4x4 matrix.
Constructors
new Mat4()
new Mat4(): Mat4
Create a new Mat4 instance. It is initialized to the identity matrix.
Returns
Properties
data
data: Float32Array<ArrayBufferLike>
Matrix elements in the form of a flat array.
IDENTITY
readonly static IDENTITY: Mat4;
A constant matrix set to the identity.
ZERO
readonly static ZERO: Mat4;
A constant matrix with all elements set to 0.
Methods
add()
add(rhs: Mat4): Mat4
Adds the specified 4x4 matrix to the current instance.
Parameters
rhs
The 4x4 matrix used as the second operand of the addition.
Returns
Self for chaining.
Example
const m = new Mat4()
m.add(Mat4.ONE)
console.log('The result of the addition is: ' + m.toString())
add2()
add2(lhs: Mat4, rhs: Mat4): Mat4
Adds the specified 4x4 matrices together and stores the result in the current instance.
Parameters
lhs
The 4x4 matrix used as the first operand of the addition.
rhs
The 4x4 matrix used as the second operand of the addition.
Returns
Self for chaining.
Example
const m = new Mat4()
m.add2(Mat4.IDENTITY, Mat4.ONE)
console.log('The result of the addition is: ' + m.toString())
clone()
clone(): Mat4
Creates a duplicate of the specified matrix.
Returns
A duplicate matrix.
Example
const src = new Mat4().setFromEulerAngles(10, 20, 30)
const dst = src.clone()
console.log('The two matrices are ' + (src.equals(dst) ? 'equal' : 'different'))
copy()
copy(rhs: Mat4): Mat4
Copies the contents of a source 4x4 matrix to a destination 4x4 matrix.
Parameters
rhs
A 4x4 matrix to be copied.
Returns
Self for chaining.
Example
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()
equals(rhs: Mat4): boolean
Reports whether two matrices are equal.
Parameters
rhs
The other matrix.
Returns
boolean
True if the matrices are equal and false otherwise.
Example
const a = new Mat4().setFromEulerAngles(10, 20, 30)
const b = new Mat4()
console.log('The two matrices are ' + (a.equals(b) ? 'equal' : 'different'))
getEulerAngles()
getEulerAngles(eulers?: Vec3): 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
eulers?
Vec3 = ...
A 3-d vector to receive the Euler angles.
Returns
A 3-d vector containing the Euler angles.
Example
// 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()
getScale(scale?: Vec3): Vec3
Extracts the scale component from the specified 4x4 matrix.
Parameters
scale?
Vec3 = ...
Vector to receive the scale.
Returns
The scale in X, Y and Z of the specified 4x4 matrix.
Example
// Query the scale component
const scale = m.getScale()
getTranslation()
getTranslation(t?: Vec3): Vec3
Extracts the translational component from the specified 4x4 matrix.
Parameters
t?
Vec3 = ...
The vector to receive the translation of the matrix.
Returns
The translation of the specified 4x4 matrix.
Example
// Create a 4x4 matrix
const m = new Mat4()
// Query the translation component
const t = new Vec3()
m.getTranslation(t)
getX()
getX(x?: Vec3): Vec3
Extracts the x-axis from the specified 4x4 matrix.
Parameters
x?
Vec3 = ...
The vector to receive the x axis of the matrix.
Returns
The x-axis of the specified 4x4 matrix.
Example
// Create a 4x4 matrix
const m = new Mat4()
// Query the x-axis component
const x = new Vec3()
m.getX(x)
getY()
getY(y?: Vec3): Vec3
Extracts the y-axis from the specified 4x4 matrix.
Parameters
y?
Vec3 = ...
The vector to receive the y axis of the matrix.
Returns
The y-axis of the specified 4x4 matrix.
Example
// Create a 4x4 matrix
const m = new Mat4()
// Query the y-axis component
const y = new Vec3()
m.getY(y)
getZ()
getZ(z?: Vec3): Vec3
Extracts the z-axis from the specified 4x4 matrix.
Parameters
z?
Vec3 = ...
The vector to receive the z axis of the matrix.
Returns
The z-axis of the specified 4x4 matrix.
Example
// Create a 4x4 matrix
const m = new Mat4()
// Query the z-axis component
const z = new Vec3()
m.getZ(z)
invert()
invert(src?: Mat4): Mat4
Sets the matrix to the inverse of a source matrix.
Parameters
src?
Mat4 = ...
The matrix to invert. If not set, the matrix is inverted in-place.
Returns
Self for chaining.
Example
// 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()
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 Mat4()
console.log('The matrix is ' + (m.isIdentity() ? 'identity' : 'not identity'))
mul()
mul(rhs: Mat4): Mat4
Multiplies the current instance by the specified 4x4 matrix.
Parameters
rhs
The 4x4 matrix used as the second multiplicand of the operation.
Returns
Self for chaining.
Example
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()
mul2(lhs: Mat4, rhs: Mat4): Mat4
Multiplies the specified 4x4 matrices together and stores the result in the current instance.
Parameters
lhs
The 4x4 matrix used as the first multiplicand of the operation.
rhs
The 4x4 matrix used as the second multiplicand of the operation.
Returns
Self for chaining.
Example
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()
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 Mat4#mul2.
Parameters
lhs
The affine transformation 4x4 matrix used as the first multiplicand of the operation.
rhs
The affine transformation 4x4 matrix used as the second multiplicand of the operation.
Returns
Self for chaining.
set()
set(src: number[]): Mat4
Sets matrix data from an array.
Parameters
src
number[]
Source array. Must have 16 values.
Returns
Self for chaining.
setFromAxisAngle()
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
The normalized axis vector around which to rotate.
angle
number
The angle of rotation in degrees.
Returns
Self for chaining.
Example
// Create a 4x4 rotation matrix
const rm = new Mat4().setFromAxisAngle(Vec3.UP, 90)
setFromEulerAngles()
setFromEulerAngles(
ex: number,
ey: number,
ez: number): 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
Self for chaining.
Example
const m = new Mat4()
m.setFromEulerAngles(45, 90, 180)
setIdentity()
setIdentity(): Mat4
Sets the specified matrix to the identity matrix.
Returns
Self for chaining.
Example
m.setIdentity()
console.log('The matrix is ' + (m.isIdentity() ? 'identity' : 'not identity'))
setLookAt()
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
3-d vector holding view position.
target
3-d vector holding reference point.
up
3-d vector holding the up direction.
Returns
Self for chaining.
Example
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()
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
Self for chaining.
Example
// Create a 4x4 orthographic projection matrix
const ortho = Mat4().ortho(-2, 2, -2, 2, 1, 1000)
setPerspective()
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
Set to true to treat the fov as horizontal (x-axis) and false for vertical (y-axis). Defaults to false.
Returns
Self for chaining.
Example
// Create a 4x4 perspective projection matrix
const persp = Mat4().setPerspective(45, 16 / 9, 1, 1000)
setReflection()
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
The normal of the plane to reflect by.
distance
number
The distance of plane to reflect by.
Returns
Self for chaining.
setTRS()
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
A 3-d vector translation.
r
A quaternion rotation.
s
A 3-d vector scale.
Returns
Self for chaining.
Example
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()
toString(): string
Converts the specified matrix to string form.
Returns
string
The matrix in string form.
Example
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()
transformPoint(vec: Vec3, res?: Vec3): Vec3
Transforms a 3-dimensional point by a 4x4 matrix.
Parameters
vec
The 3-dimensional point to be transformed.
res?
Vec3 = ...
An optional 3-dimensional point to receive the result of the transformation.
Returns
The input point v transformed by the current instance.
Example
// 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()
transformVec4(vec: Vec4, res?: Vec4): Vec4
Transforms a 4-dimensional vector by a 4x4 matrix.
Parameters
vec
The 4-dimensional vector to be transformed.
res?
Vec4 = ...
An optional 4-dimensional vector to receive the result of the transformation.
Returns
The input vector v transformed by the current instance.
Example
// 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()
transformVector(vec: Vec3, res?: Vec3): Vec3
Transforms a 3-dimensional vector by a 4x4 matrix.
Parameters
vec
The 3-dimensional vector to be transformed.
res?
Vec3 = ...
An optional 3-dimensional vector to receive the result of the transformation.
Returns
The input vector v transformed by the current instance.
Example
// 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()
transpose(src?: Mat4): Mat4
Sets the matrix to the transpose of a source matrix.
Parameters
src?
Mat4 = ...
The matrix to transpose. If not set, the matrix is transposed in-place.
Returns
Self for chaining.
Example
const m = new Mat4()
// Transpose in place
m.transpose()