Mat4
A 4x4 matrix.
Summary
Static Properties
IDENTITY | A constant matrix set to the identity.[read only] |
ZERO | A constant matrix with all elements set to 0.[read only] |
Properties
data | Matrix elements in the form of a flat array. |
Methods
add | Adds the specified 4x4 matrix to the current instance. |
add2 | Adds the specified 4x4 matrices together and stores the result in the current instance. |
clone | Creates a duplicate of the specified matrix. |
copy | Copies the contents of a source 4x4 matrix to a destination 4x4 matrix. |
equals | Reports whether two matrices are equal. |
getEulerAngles | Extracts the Euler angles equivalent to the rotational portion of the specified matrix. |
getScale | Extracts the scale component from the specified 4x4 matrix. |
getTranslation | Extracts the translational component from the specified 4x4 matrix. |
getX | Extracts the x-axis from the specified 4x4 matrix. |
getY | Extracts the y-axis from the specified 4x4 matrix. |
getZ | Extracts the z-axis from the specified 4x4 matrix. |
invert | Sets the matrix to the inverse of a source matrix. |
isIdentity | Reports whether the specified matrix is the identity matrix. |
mul | Multiplies the current instance by the specified 4x4 matrix. |
mul2 | Multiplies the specified 4x4 matrices together and stores the result in the current instance. |
mulAffine2 | Multiplies the specified 4x4 matrices together and stores the result in the current instance. |
set | Sets matrix data from an array. |
setFromAxisAngle | Sets the specified matrix to a rotation matrix equivalent to a rotation around an axis. |
setFromEulerAngles | Sets the specified matrix to a rotation matrix defined by Euler angles. |
setIdentity | Sets the specified matrix to the identity matrix. |
setLookAt | Sets the specified matrix to a viewing matrix derived from an eye point, a target point and an up vector. |
setOrtho | Sets the specified matrix to an orthographic projection matrix. |
setPerspective | Sets the specified matrix to a perspective projection matrix. |
setReflection | Sets the matrix to a reflection matrix, which can be used as a mirror transformation by the plane. |
setTRS | Sets the specified matrix to the concatenation of a translation, a quaternion rotation and a scale. |
toString | Converts the specified matrix to string form. |
transformPoint | Transforms a 3-dimensional point by a 4x4 matrix. |
transformVec4 | Transforms a 4-dimensional vector by a 4x4 matrix. |
transformVector | Transforms a 3-dimensional vector by a 4x4 matrix. |
transpose | Sets the matrix to the transpose of a source matrix. |
Details
Static Properties
IDENTITY | A constant matrix set to the identity. [read only] |
ZERO | A constant matrix with all elements set to 0. [read only] |
Constructor
Mat4()
Create a new Mat4 instance. It is initialized to the identity matrix.
Properties
Methods
add(rhs)
Adds the specified 4x4 matrix to the current instance.
const m = new pc.Mat4();
m.add(pc.Mat4.ONE);
console.log("The result of the addition is: " + m.toString());
Parameters
rhs | Mat4 | The 4x4 matrix used as the second operand of the addition. |
Returns
Mat4Self for chaining.
add2(lhs, rhs)
Adds the specified 4x4 matrices together and stores the result in the current instance.
const m = new pc.Mat4();
m.add2(pc.Mat4.IDENTITY, pc.Mat4.ONE);
console.log("The result of the addition is: " + m.toString());
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
Mat4Self for chaining.
clone()
Creates a duplicate of the specified matrix.
const src = new pc.Mat4().setFromEulerAngles(10, 20, 30);
const dst = src.clone();
console.log("The two matrices are " + (src.equals(dst) ? "equal" : "different"));
Returns
thisA duplicate matrix.
copy(rhs)
Copies the contents of a source 4x4 matrix to a destination 4x4 matrix.
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"));
Parameters
rhs | Mat4 | A 4x4 matrix to be copied. |
Returns
Mat4Self for chaining.
equals(rhs)
Reports whether two matrices are equal.
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"));
Parameters
rhs | Mat4 | The other matrix. |
Returns
booleanTrue if the matrices are equal and false otherwise.
getEulerAngles([eulers])
Extracts the Euler angles equivalent to the rotational portion of the specified matrix. The returned Euler angles are in XYZ order an in degrees.
// 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();
Parameters
eulers | Vec3 | A 3-d vector to receive the Euler angles. |
Returns
Vec3A 3-d vector containing the Euler angles.
getScale([scale])
Extracts the scale component from the specified 4x4 matrix.
// Query the scale component
const scale = m.getScale();
Parameters
scale | Vec3 | Vector to receive the scale. |
Returns
Vec3The scale in X, Y and Z of the specified 4x4 matrix.
getTranslation([t])
Extracts the translational component from the specified 4x4 matrix.
// Create a 4x4 matrix
const m = new pc.Mat4();
// Query the translation component
const t = new pc.Vec3();
m.getTranslation(t);
Parameters
t | Vec3 | The vector to receive the translation of the matrix. |
Returns
Vec3The translation of the specified 4x4 matrix.
getX([x])
Extracts the x-axis from the specified 4x4 matrix.
// Create a 4x4 matrix
const m = new pc.Mat4();
// Query the x-axis component
const x = new pc.Vec3();
m.getX(x);
Parameters
x | Vec3 | The vector to receive the x axis of the matrix. |
Returns
Vec3The x-axis of the specified 4x4 matrix.
getY([y])
Extracts the y-axis from the specified 4x4 matrix.
// Create a 4x4 matrix
const m = new pc.Mat4();
// Query the y-axis component
const y = new pc.Vec3();
m.getY(y);
Parameters
y | Vec3 | The vector to receive the y axis of the matrix. |
Returns
Vec3The y-axis of the specified 4x4 matrix.
getZ([z])
Extracts the z-axis from the specified 4x4 matrix.
// Create a 4x4 matrix
const m = new pc.Mat4();
// Query the z-axis component
const z = new pc.Vec3();
m.getZ(z);
Parameters
z | Vec3 | The vector to receive the z axis of the matrix. |
Returns
Vec3The z-axis of the specified 4x4 matrix.
invert([src])
Sets the matrix to the inverse of a source matrix.
// 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();
Parameters
src | Mat4 | The matrix to invert. If not set, the matrix is inverted in-place. |
Returns
Mat4Self for chaining.
isIdentity()
Reports whether the specified matrix is the identity matrix.
const m = new pc.Mat4();
console.log("The matrix is " + (m.isIdentity() ? "identity" : "not identity"));
Returns
booleanTrue if the matrix is identity and false otherwise.
mul(rhs)
Multiplies the current instance by the specified 4x4 matrix.
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());
Parameters
rhs | Mat4 | The 4x4 matrix used as the second multiplicand of the operation. |
Returns
Mat4Self for chaining.
mul2(lhs, rhs)
Multiplies the specified 4x4 matrices together and stores the result in the current instance.
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());
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
Mat4Self for chaining.
mulAffine2(lhs, rhs)
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
Mat4Self for chaining.
set(src)
Sets matrix data from an array.
Parameters
src | number[] | Source array. Must have 16 values. |
Returns
Mat4Self for chaining.
setFromAxisAngle(axis, angle)
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.
// Create a 4x4 rotation matrix
const rm = new pc.Mat4().setFromAxisAngle(pc.Vec3.UP, 90);
Parameters
axis | Vec3 | The normalized axis vector around which to rotate. |
angle | number | The angle of rotation in degrees. |
Returns
Mat4Self for chaining.
setFromEulerAngles(ex, ey, ez)
Sets the specified matrix to a rotation matrix defined by Euler angles. The Euler angles are specified in XYZ order and in degrees.
const m = new pc.Mat4();
m.setFromEulerAngles(45, 90, 180);
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
Mat4Self for chaining.
setIdentity()
Sets the specified matrix to the identity matrix.
m.setIdentity();
console.log("The matrix is " + (m.isIdentity() ? "identity" : "not identity"));
Returns
Mat4Self for chaining.
setLookAt(position, target, up)
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.
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);
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
Mat4Self for chaining.
setOrtho(left, right, bottom, top, near, far)
Sets the specified matrix to an orthographic projection matrix. The function's parameters define the shape of a cuboid-shaped frustum.
// Create a 4x4 orthographic projection matrix
const ortho = pc.Mat4().ortho(-2, 2, -2, 2, 1, 1000);
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
Mat4Self for chaining.
setPerspective(fov, aspect, znear, zfar, [fovIsHorizontal])
Sets the specified matrix to a perspective projection matrix. The function's parameters define the shape of a frustum.
// Create a 4x4 perspective projection matrix
const persp = pc.Mat4().setPerspective(45, 16 / 9, 1, 1000);
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
Mat4Self for chaining.
setReflection(normal, distance)
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
Mat4Self for chaining.
setTRS(t, r, s)
Sets the specified matrix to the concatenation of a translation, a quaternion rotation and a scale.
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);
Parameters
t | Vec3 | A 3-d vector translation. |
r | Quat | A quaternion rotation. |
s | Vec3 | A 3-d vector scale. |
Returns
Mat4Self for chaining.
toString()
Converts the specified matrix to string form.
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());
Returns
stringThe matrix in string form.
transformPoint(vec, [res])
Transforms a 3-dimensional point by a 4x4 matrix.
// 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);
Parameters
vec | Vec3 | The 3-dimensional point to be transformed. |
res | Vec3 | An optional 3-dimensional point to receive the result of the transformation. |
Returns
Vec3The input point v transformed by the current instance.
transformVec4(vec, [res])
Transforms a 4-dimensional vector by a 4x4 matrix.
// 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);
Parameters
vec | Vec4 | The 4-dimensional vector to be transformed. |
res | Vec4 | An optional 4-dimensional vector to receive the result of the transformation. |
Returns
Vec4The input vector v transformed by the current instance.
transformVector(vec, [res])
Transforms a 3-dimensional vector by a 4x4 matrix.
// 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);
Parameters
vec | Vec3 | The 3-dimensional vector to be transformed. |
res | Vec3 | An optional 3-dimensional vector to receive the result of the transformation. |
Returns
Vec3The input vector v transformed by the current instance.