API Reference

Class List

pc.Mat4

A 4x4 matrix.

Summary

Static Properties

IDENTITYA constant matrix set to the identity.[read only]
ZEROA constant matrix with all elements set to 0.[read only]

Methods

addAdds the specified 4x4 matrix to the current instance.
add2Adds the specified 4x4 matrices together and stores the result in the current instance.
cloneCreates a duplicate of the specified matrix.
copyCopies the contents of a source 4x4 matrix to a destination 4x4 matrix.
equalsReports whether two matrices are equal.
getEulerAnglesExtracts the Euler angles equivalent to the rotational portion of the specified matrix.
getScaleExtracts the scale component from the specified 4x4 matrix.
getTranslationExtracts the transational component from the specified 4x4 matrix.
getXExtracts the x-axis from the specified 4x4 matrix.
getYExtracts the y-axis from the specified 4x4 matrix.
getZExtracts the z-axis from the specified 4x4 matrix.
invertSets the specified matrix to its inverse.
isIdentityReports whether the specified matrix is the identity matrix.
mulMultiplies the current instance by the specified 4x4 matrix.
mul2Multiplies the specified 4x4 matrices together and stores the result in the current instance.
setSets matrix data from an array.
setFromAxisAngleSets the specified matrix to a rotation matrix equivalent to a rotation around an axis.
setFromEulerAnglesSets the specified matrix to a rotation matrix defined by Euler angles.
setIdentitySets the specified matrix to the identity matrix.
setLookAtSets the specified matrix to a viewing matrix derived from an eye point, a target point and an up vector.
setOrthoSets the specified matrix to an orthographic projection matrix.
setPerspectiveSets the specified matrix to a persective projection matrix.
setTRSSets the specified matrix to the concatenation of a translation, a quaternion rotation and a scale.
toStringConverts the specified matrix to string form.
transformPointTransforms a 3-dimensional point by a 4x4 matrix.
transformVec4Transforms a 4-dimensional vector by a 4x4 matrix.
transformVectorTransforms a 3-dimensional vector by a 4x4 matrix.
transposeSets the specified matrix to its transpose.

Details

Static Properties

IDENTITYA constant matrix set to the identity.[read only]
ZEROA constant matrix with all elements set to 0.[read only]

Constructor

Mat4([v0], [v1], [v2], [v3], [v4], [v5], [v6], [v7], [v8], [v9], [v10], [v11], [v12], [v13], [v14], [v15])

Creates a new Mat4 object

Parameters

v0NumberThe value in row 0, column 0. If v0 is an array of length 16, the array will be used to populate all components.
v1NumberThe value in row 1, column 0.
v2NumberThe value in row 2, column 0.
v3NumberThe value in row 3, column 0.
v4NumberThe value in row 0, column 1.
v5NumberThe value in row 1, column 1.
v6NumberThe value in row 2, column 1.
v7NumberThe value in row 3, column 1.
v8NumberThe value in row 0, column 2.
v9NumberThe value in row 1, column 2.
v10NumberThe value in row 2, column 2.
v11NumberThe value in row 3, column 2.
v12NumberThe value in row 0, column 3.
v13NumberThe value in row 1, column 3.
v14NumberThe value in row 2, column 3.
v15NumberThe value in row 3, column 3.

Methods

add(rhs)

Adds the specified 4x4 matrix to the current instance.

var m = new pc.Mat4();

m.add(pc.Mat4.ONE);

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

Parameters

rhspc.Mat4The 4x4 matrix used as the second operand of the addition.

Returns

pc.Mat4 Self for chaining.

add2(lhs, rhs)

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

var m = new pc.Mat4();

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

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

Parameters

lhspc.Mat4The 4x4 matrix used as the first operand of the addition.
rhspc.Mat4The 4x4 matrix used as the second operand of the addition.

Returns

pc.Mat4 Self for chaining.

clone()

Creates a duplicate of the specified matrix.

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

Returns

pc.Mat4 A duplicate matrix.

copy(rhs)

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

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

Parameters

rhspc.Mat4A 4x4 matrix to be copied.

Returns

pc.Mat4 Self for chaining.

equals(rhs)

Reports whether two matrices are equal.

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"));

Parameters

rhspc.Mat4The other matrix.

Returns

Boolean true 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
var m = new pc.Mat4().setFromAxisAngle(pc.Vec3.UP, 45);

var eulers = m.getEulerAngles();

Parameters

eulerspc.Vec3A 3-d vector to receive the Euler angles.

Returns

pc.Vec3 A 3-d vector containing the Euler angles.

getScale([scale])

Extracts the scale component from the specified 4x4 matrix.

// Create a 4x4 scale matrix
var m = new pc.Mat4().scale(2, 3, 4);

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

Parameters

scalepc.Vec3Vector to receive the scale.

Returns

pc.Vec3 The scale in X, Y and Z of the specified 4x4 matrix.

getTranslation([t])

Extracts the transational component from the specified 4x4 matrix.

// Create a 4x4 matrix
var m = new pc.Mat4();

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

Parameters

tpc.Vec3The vector to receive the translation of the matrix.

Returns

pc.Vec3 The translation of the specified 4x4 matrix.

getX([x])

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

// Create a 4x4 matrix
var m = new pc.Mat4();

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

Parameters

xpc.Vec3The vector to receive the x axis of the matrix.

Returns

pc.Vec3 The x-axis of the specified 4x4 matrix.

getY([y])

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

// Create a 4x4 matrix
var m = new pc.Mat4();

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

Parameters

ypc.Vec3The vector to receive the y axis of the matrix.

Returns

pc.Vec3 The y-axis of the specified 4x4 matrix.

getZ([z])

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

// Create a 4x4 matrix
var m = new pc.Mat4();

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

Parameters

zpc.Vec3The vector to receive the z axis of the matrix.

Returns

pc.Vec3 The z-axis of the specified 4x4 matrix.

invert()

Sets the specified matrix to its inverse.

// 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();

Returns

pc.Mat4 Self for chaining.

isIdentity()

Reports whether the specified matrix is the identity matrix.

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

Returns

Boolean true if the matrix is identity and false otherwise.

mul(rhs)

Multiplies the current instance by the specified 4x4 matrix.

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());

Parameters

rhspc.Mat4The 4x4 matrix used as the second multiplicand of the operation.

Returns

pc.Mat4 Self for chaining.

mul2(lhs, rhs)

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

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());

Parameters

lhspc.Mat4The 4x4 matrix used as the first multiplicand of the operation.
rhspc.Mat4The 4x4 matrix used as the second multiplicand of the operation.

Returns

pc.Mat4 Self for chaining.

set(Source)

Sets matrix data from an array.

Parameters

SourceArrayarray. Must have 16 values.

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
var rm = new pc.Mat4().setFromAxisAngle(pc.Vec3.UP, 90);

Parameters

axispc.Vec3The normalized axis vector around which to rotate.
angleNumberThe angle of rotation in degrees.

Returns

pc.Mat4 Self 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.

var m = new pc.Mat4();
m.setFromEulerAngles(45, 90, 180);

Parameters

exNumberAngle to rotate around X axis in degrees.
eyNumberAngle to rotate around Y axis in degrees.
ezNumberAngle to rotate around Z axis in degrees.

Returns

pc.Mat4 Self for chaining.

setIdentity()

Sets the specified matrix to the identity matrix.

m.setIdentity();
console.log("The two matrices are " + (src.equal(dst) ? "equal" : "different"));

Returns

pc.Mat4 Self 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.

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);

Parameters

positionpc.Vec33-d vector holding view position.
targetpc.Vec33-d vector holding reference point.
uppc.Vec33-d vector holding the up direction.

Returns

pc.Mat4 Self for chaining.

setOrtho(left, right, bottom, top, znear, zfar)

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
var ortho = pc.Mat4().ortho(-2, 2, -2, 2, 1, 1000);

Parameters

leftNumberThe x-coordinate for the left edge of the camera's projection plane in eye space.
rightNumberThe x-coordinate for the right edge of the camera's projection plane in eye space.
bottomNumberThe y-coordinate for the bottom edge of the camera's projection plane in eye space.
topNumberThe y-coordinate for the top edge of the camera's projection plane in eye space.
znearNumberThe near clip plane in eye coordinates.
zfarNumberThe far clip plane in eye coordinates.

Returns

pc.Mat4 Self for chaining.

setPerspective(fovy, aspect, znear, zfar)

Sets the specified matrix to a persective projection matrix. The function's parameters define the shape of a frustum.

// Create a 4x4 persepctive projection matrix
var persp = pc.Mat4().setPerspective(45, 16 / 9, 1, 1000);

Parameters

fovyNumberThe field of view in the frustum in the Y-axis of eye space (or X axis if fovIsHorizontal is true).
aspectNumberThe aspect ratio of the frustum's projection plane (width / height).
znearNumberThe near clip plane in eye coordinates.
zfarNumberThe far clip plane in eye coordinates.

Returns

pc.Mat4 Self for chaining.

setTRS(t, r, s)

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

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.compose(t, r, s);

Parameters

tpc.Vec3A 3-d vector translation.
rpc.QuatA quaternion rotation.
spc.Vec3A 3-d vector scale.

Returns

pc.Mat4 Self for chaining.

toString()

Converts the specified matrix to string form.

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());

Returns

String The matrix in string form.

transformPoint(vec, [res])

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

// 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);

Parameters

vecpc.Vec3The 3-dimensional point to be transformed.
respc.Vec3An optional 3-dimensional point to receive the result of the transformation.

Returns

pc.Vec3 The 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
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);

Parameters

vecpc.Vec4The 4-dimensional vector to be transformed.
respc.Vec4An optional 4-dimensional vector to receive the result of the transformation.

Returns

pc.Vec4 The 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
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);

Parameters

vecpc.Vec3The 3-dimensional vector to be transformed.
respc.Vec3An optional 3-dimensional vector to receive the result of the transformation.

Returns

pc.Vec3 The input vector v transformed by the current instance.

transpose()

Sets the specified matrix to its transpose.

var m = new pc.Mat4();

// Transpose in place
m.transpose();

Returns

pc.Mat4 Self for chaining.