Class: Mat4

pc.Mat4

A 4x4 matrix.

Constructor

new Mat4()

Creates a new identity Mat4 object.
Source:

Members

(static, readonly) IDENTITY :pc.Mat4

A constant matrix set to the identity.
Type:
Source:

(static, readonly) ZERO :pc.Mat4

A constant matrix with all elements set to 0.
Type:
Source:

Methods

add(rhs) → {pc.Mat4}

Adds the specified 4x4 matrix to the current instance.
Parameters:
Name Type Description
rhs pc.Mat4 The 4x4 matrix used as the second operand of the addition.
Source:
Returns:
Self for chaining.
Type
pc.Mat4
Example
var m = new pc.Mat4();

m.add(pc.Mat4.ONE);

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

add2(lhs, rhs) → {pc.Mat4}

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

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

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

clone() → {pc.Mat4}

Creates a duplicate of the specified matrix.
Source:
Returns:
A duplicate matrix.
Type
pc.Mat4
Example
var src = new pc.Mat4().setFromEulerAngles(10, 20, 30);
var dst = src.clone();
console.log("The two matrices are " + (src.equals(dst) ? "equal" : "different"));

copy(rhs) → {pc.Mat4}

Copies the contents of a source 4x4 matrix to a destination 4x4 matrix.
Parameters:
Name Type Description
rhs pc.Mat4 A 4x4 matrix to be copied.
Source:
Returns:
Self for chaining.
Type
pc.Mat4
Example
var src = new pc.Mat4().setFromEulerAngles(10, 20, 30);
var dst = new pc.Mat4();
dst.copy(src);
console.log("The two matrices are " + (src.equals(dst) ? "equal" : "different"));

equals(rhs) → {Boolean}

Reports whether two matrices are equal.
Parameters:
Name Type Description
rhs pc.Mat4 The other matrix.
Source:
Returns:
true if the matrices are equal and false otherwise.
Type
Boolean
Example
var a = new pc.Mat4().setFromEulerAngles(10, 20, 30);
var b = new pc.Mat4();
console.log("The two matrices are " + (a.equals(b) ? "equal" : "different"));

getEulerAngles(eulersopt) → {pc.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:
Name Type Attributes Description
eulers pc.Vec3 <optional>
A 3-d vector to receive the Euler angles.
Source:
Returns:
A 3-d vector containing the Euler angles.
Type
pc.Vec3
Example
// Create a 4x4 rotation matrix of 45 degrees around the y-axis
var m = new pc.Mat4().setFromAxisAngle(pc.Vec3.UP, 45);

var eulers = m.getEulerAngles();

getScale(scaleopt) → {pc.Vec3}

Extracts the scale component from the specified 4x4 matrix.
Parameters:
Name Type Attributes Description
scale pc.Vec3 <optional>
Vector to receive the scale.
Source:
Returns:
The scale in X, Y and Z of the specified 4x4 matrix.
Type
pc.Vec3
Example
// Create a 4x4 scale matrix
var m = new pc.Mat4().scale(2, 3, 4);

// Query the scale component
var scale = m.getScale();

getTranslation(topt) → {pc.Vec3}

Extracts the translational component from the specified 4x4 matrix.
Parameters:
Name Type Attributes Description
t pc.Vec3 <optional>
The vector to receive the translation of the matrix.
Source:
Returns:
The translation of the specified 4x4 matrix.
Type
pc.Vec3
Example
// Create a 4x4 matrix
var m = new pc.Mat4();

// Query the z-axis component
var t = new pc.Vec3();
m.getTranslation(t);

getX(xopt) → {pc.Vec3}

Extracts the x-axis from the specified 4x4 matrix.
Parameters:
Name Type Attributes Description
x pc.Vec3 <optional>
The vector to receive the x axis of the matrix.
Source:
Returns:
The x-axis of the specified 4x4 matrix.
Type
pc.Vec3
Example
// Create a 4x4 matrix
var m = new pc.Mat4();

// Query the z-axis component
var x = new pc.Vec3();
m.getX(x);

getY(yopt) → {pc.Vec3}

Extracts the y-axis from the specified 4x4 matrix.
Parameters:
Name Type Attributes Description
y pc.Vec3 <optional>
The vector to receive the y axis of the matrix.
Source:
Returns:
The y-axis of the specified 4x4 matrix.
Type
pc.Vec3
Example
// Create a 4x4 matrix
var m = new pc.Mat4();

// Query the z-axis component
var y = new pc.Vec3();
m.getY(y);

getZ(zopt) → {pc.Vec3}

Extracts the z-axis from the specified 4x4 matrix.
Parameters:
Name Type Attributes Description
z pc.Vec3 <optional>
The vector to receive the z axis of the matrix.
Source:
Returns:
The z-axis of the specified 4x4 matrix.
Type
pc.Vec3
Example
// Create a 4x4 matrix
var m = new pc.Mat4();

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

invert() → {pc.Mat4}

Sets the specified matrix to its inverse.
Source:
Returns:
Self for chaining.
Type
pc.Mat4
Example
// Create a 4x4 rotation matrix of 180 degrees around the y-axis
var rot = new pc.Mat4().setFromAxisAngle(pc.Vec3.UP, 180);

// Invert in place
rot.invert();

isIdentity() → {Boolean}

Reports whether the specified matrix is the identity matrix.
Source:
Returns:
true if the matrix is identity and false otherwise.
Type
Boolean
Example
var m = new pc.Mat4();
console.log("The matrix is " + (m.isIdentity() ? "identity" : "not identity"));

mul(rhs) → {pc.Mat4}

Multiplies the current instance by the specified 4x4 matrix.
Parameters:
Name Type Description
rhs pc.Mat4 The 4x4 matrix used as the second multiplicand of the operation.
Source:
Returns:
Self for chaining.
Type
pc.Mat4
Example
var a = new pc.Mat4().setFromEulerAngles(10, 20, 30);
var 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(lhs, rhs) → {pc.Mat4}

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

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

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

set(src) → {pc.Mat4}

Sets matrix data from an array.
Parameters:
Name Type Description
src Array Source array. Must have 16 values.
Source:
Returns:
Self for chaining.
Type
pc.Mat4

setFromAxisAngle(axis, angle) → {pc.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:
Name Type Description
axis pc.Vec3 The normalized axis vector around which to rotate.
angle Number The angle of rotation in degrees.
Source:
Returns:
Self for chaining.
Type
pc.Mat4
Example
// Create a 4x4 rotation matrix
var rm = new pc.Mat4().setFromAxisAngle(pc.Vec3.UP, 90);

setFromEulerAngles(ex, ey, ez) → {pc.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:
Name Type Description
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.
Source:
Returns:
Self for chaining.
Type
pc.Mat4
Example
var m = new pc.Mat4();
m.setFromEulerAngles(45, 90, 180);

(private) setFrustum(left, right, bottom, top, znear, zfar) → {pc.Mat4}

Sets the specified matrix to a perspective projection matrix. The function's parameters define the shape of a frustum.
Parameters:
Name Type Description
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.
znear Number The near clip plane in eye coordinates.
zfar Number The far clip plane in eye coordinates.
Source:
Returns:
Self for chaining.
Type
pc.Mat4
Example
// Create a 4x4 perspective projection matrix
var f = pc.Mat4().setFrustum(-2, 2, -1, 1, 1, 1000);

setIdentity() → {pc.Mat4}

Sets the specified matrix to the identity matrix.
Source:
Returns:
Self for chaining.
Type
pc.Mat4
Example
m.setIdentity();
console.log("The matrix is " + (m.isIdentity() ? "identity" : "not identity"));

setLookAt(position, target, up) → {pc.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:
Name Type Description
position pc.Vec3 3-d vector holding view position.
target pc.Vec3 3-d vector holding reference point.
up pc.Vec3 3-d vector holding the up direction.
Source:
Returns:
Self for chaining.
Type
pc.Mat4
Example
var position = new pc.Vec3(10, 10, 10);
var target = new pc.Vec3(0, 0, 0);
var up = new pc.Vec3(0, 1, 0);
var m = new pc.Mat4().setLookAt(position, target, up);

setOrtho(left, right, bottom, top, near, far) → {pc.Mat4}

Sets the specified matrix to an orthographic projection matrix. The function's parameters define the shape of a cuboid-shaped frustum.
Parameters:
Name Type Description
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.
Source:
Returns:
Self for chaining.
Type
pc.Mat4
Example
// Create a 4x4 orthographic projection matrix
var ortho = pc.Mat4().ortho(-2, 2, -2, 2, 1, 1000);

setPerspective(fov, aspect, znear, zfar, fovIsHorizontalopt) → {pc.Mat4}

Sets the specified matrix to a perspective projection matrix. The function's parameters define the shape of a frustum.
Parameters:
Name Type Attributes Default Description
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>
false Set to true to treat the fov as horizontal (x-axis) and false for vertical (y-axis). Defaults to false.
Source:
Returns:
Self for chaining.
Type
pc.Mat4
Example
// Create a 4x4 perspective projection matrix
var persp = pc.Mat4().setPerspective(45, 16 / 9, 1, 1000);

(private) setScale(x, y, z) → {pc.Mat4}

Sets the specified matrix to a scale matrix.
Parameters:
Name Type Description
x Number The x-component of the scale.
y Number The y-component of the scale.
z Number The z-component of the scale.
Source:
Returns:
Self for chaining.
Type
pc.Mat4
Example
// Create a 4x4 scale matrix
var sm = new pc.Mat4().setScale(10, 10, 10);

(private) setTranslate(x, y, z) → {pc.Mat4}

Sets the specified matrix to a translation matrix.
Parameters:
Name Type Description
x Number The x-component of the translation.
y Number The y-component of the translation.
z Number The z-component of the translation.
Source:
Returns:
Self for chaining.
Type
pc.Mat4
Example
// Create a 4x4 translation matrix
var tm = new pc.Mat4().setTranslate(10, 10, 10);

setTRS(t, r, s) → {pc.Mat4}

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

var m = new pc.Mat4();
m.setTRS(t, r, s);

toString() → {String}

Converts the specified matrix to string form.
Source:
Returns:
The matrix in string form.
Type
String
Example
var m = new pc.Mat4();
// Should output '[1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]'
console.log(m.toString());

transformPoint(vec, resopt) → {pc.Vec3}

Transforms a 3-dimensional point by a 4x4 matrix.
Parameters:
Name Type Attributes Description
vec pc.Vec3 The 3-dimensional point to be transformed.
res pc.Vec3 <optional>
An optional 3-dimensional point to receive the result of the transformation.
Source:
Returns:
The input point v transformed by the current instance.
Type
pc.Vec3
Example
// Create a 3-dimensional point
var v = new pc.Vec3(1, 2, 3);

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

var tv = m.transformPoint(v);

transformVec4(vec, resopt) → {pc.Vec4}

Transforms a 4-dimensional vector by a 4x4 matrix.
Parameters:
Name Type Attributes Description
vec pc.Vec4 The 4-dimensional vector to be transformed.
res pc.Vec4 <optional>
An optional 4-dimensional vector to receive the result of the transformation.
Source:
Returns:
The input vector v transformed by the current instance.
Type
pc.Vec4
Example
// Create an input 4-dimensional vector
var v = new pc.Vec4(1, 2, 3, 4);

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

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

m.transformVec4(v, result);

transformVector(vec, resopt) → {pc.Vec3}

Transforms a 3-dimensional vector by a 4x4 matrix.
Parameters:
Name Type Attributes Description
vec pc.Vec3 The 3-dimensional vector to be transformed.
res pc.Vec3 <optional>
An optional 3-dimensional vector to receive the result of the transformation.
Source:
Returns:
The input vector v transformed by the current instance.
Type
pc.Vec3
Example
// Create a 3-dimensional vector
var v = new pc.Vec3(1, 2, 3);

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

var tv = m.transformVector(v);

transpose() → {pc.Mat4}

Sets the specified matrix to its transpose.
Source:
Returns:
Self for chaining.
Type
pc.Mat4
Example
var m = new pc.Mat4();

// Transpose in place
m.transpose();