Mat4 - Vircadia API Docs

Description

Supported Script Types: Interface Scripts • Client Entity Scripts • Avatar Scripts • Server Entity Scripts • Assignment Client Scripts

The Mat4 API provides facilities for generating and using 4 x 4 matrices. These matrices are typically used to represent transforms (scale, rotate, and translate) that convert one coordinate system into another, or perspective transforms that convert 3D points into screen coordinates.

Methods

Name	Return Value	Summary
`createFromArray`	Mat4	Creates a matrix from an array of values.
`createFromColumns`	Mat4	Creates a matrix from columns of values.
`createFromRotAndTrans`	Mat4	Creates a matrix that represents a rotation and translation.
`createFromScaleRotAndTrans`	Mat4	Creates a matrix that represents a scale, rotation, and translation.
`extractRotation`	Quat	Extracts the rotation from a matrix.
`extractScale`	Vec3	Extracts the scale from a matrix.
`extractTranslation`	Vec3	Extracts the translation from a matrix.
`getForward`	Vec3	Gets the "forward" direction that the camera would face if its orientation was set to the rotation contained in a matrix. The High Fidelity camera has axes x = right, y = up, -z = forward.
`getFront`	Vec3	Gets the "forward" direction that the camera would face if its orientation was set to the rotation contained in a matrix. The High Fidelity camera has axes x = right, y = up, -z = forward. Synonym for getForward.
`getRight`	Vec3	Gets the "right" direction that the camera would have if its orientation was set to the rotation contained in a matrix. The High Fidelity camera has axes x = right, y = up, -z = forward.
`getUp`	Vec3	Gets the "up" direction that the camera would have if its orientation was set to the rotation contained in a matrix. The High Fidelity camera has axes x = right, y = up, -z = forward.
`inverse`	Mat4	Calculates the inverse of a matrix.
`multiply`	Mat4	Multiplies two matrices.
`print`	None	Prints a matrix to the program log as a label followed by the matrix's values.
`transformPoint`	Vec3	Transforms a point into a new coordinate system: the point value is scaled, rotated, and translated.
`transformVector`	Vec3	Transforms a vector into a new coordinate system: the vector is scaled and rotated.

Method Details

(static) createFromArray( arr ) → {Mat4}
Returns: The matrix with the specified values.

Creates a matrix from an array of values.

Parameters

Name	Type	Description
`arr`	Array.<number>	The array of values, starting with column 0.

Example

Create a matrix from an array.

var arr = [
    0.707107, 1.224745, -1.414214, 0.0,
    -1.146447, 1.478398, 0.707107, 0.0,
    1.478398, 0.560660, 1.224745, 0.0,
    10.0, 11.0, 12.0, 1.00
];
var matrix = Mat4.createFromArray(arr);
Mat4.print("Matrix:", matrix);
//Matrix: dmat4x4((0.707107, 1.224745, -1.414214, 0.000000),
//                (-1.146447, 1.478398, 0.707107, 0.000000),
//                (1.478398, 0.560660, 1.224745, 0.000000),
//                (10.000000, 11.000000, 12.000000, 1.000000))

(static) createFromColumns( col0, col1, col2, col3 ) → {Mat4}
Returns: The matrix with the specified columns values.

Creates a matrix from columns of values.

Parameters

Name	Type	Description
`col0`	Vec4	Column 0 values.
`col1`	Vec4	Column 1 values.
`col2`	Vec4	Column 2 values.
`col3`	Vec4	Column 3 valuse.

Example

Create a matrix from columns.

var col0 = { x: 0.707107, y: 1.224745, z: -1.414214, w: 0.0 };
var col1 = { x: -1.146447, y: 1.478398, z: 0.707107, w: 0.0 };
var col2 = { x: 1.478398, y: 0.560660, z: 1.224745, w: 0.0 };
var col3 = { x: 10.0, y: 11.0, z: 12.0, w: 1.0 };
var matrix = Mat4.createFromColumns(col0, col1, col2, col3);
Mat4.print("Matrix:", matrix);
//Matrix: dmat4x4((0.707107, 1.224745, -1.414214, 0.000000),
//                (-1.146447, 1.478398, 0.707107, 0.000000),
//                (1.478398, 0.560660, 1.224745, 0.000000),
//                (10.000000, 11.000000, 12.000000, 1.000000))

(static) createFromRotAndTrans( rot, trans ) → {Mat4}
Returns: The matrix that represents the rotation and translation.

Creates a matrix that represents a rotation and translation.

Parameters

Name	Type	Description
`rot`	Quat	The rotation.
`trans`	Vec3	The translation.

Example

Create a matrix with rotation and translation.

var rot = Quat.fromPitchYawRollDegrees(30, 45, 60);
var trans = { x: 10, y: 11, z: 12 };
var matrix = Mat4.createFromRotAndTrans(rot, trans);
Mat4.print("Matrix:", matrix);
// Matrix: dmat4x4((0.353553, 0.612372, -0.707107, 0.000000),
//                 (-0.573223, 0.739199, 0.353553, 0.000000),
//                 (0.739199, 0.280330, 0.612372, 0.000000),
//                 (10.000000, 11.000000, 12.000000, 1.000000))

(static) createFromScaleRotAndTrans( scale, rot, trans ) → {Mat4}
Returns: The matrix that represents the scale, rotation, and translation.

Creates a matrix that represents a scale, rotation, and translation.

Parameters

Name	Type	Description
`scale`	Vec3	The scale.
`rot`	Quat	The rotation.
`trans`	Vec3	The translation.

Example

Create a matrix with scale, rotation, and translation.

var scale = Vec3.multiply(2, Vec3.ONE);
var rot = Quat.fromPitchYawRollDegrees(30, 45, 60);
var trans = { x: 10, y: 11, z: 12 };
var matrix = Mat4.createFromScaleRotAndTrans(scale, rot, trans);
Mat4.print("Matrix:", matrix);
// Matrix: dmat4x4((0.707107, 1.224745, -1.414214, 0.000000),
//                 (-1.146447, 1.478398, 0.707107, 0.000000),
//                 (1.478398, 0.560660, 1.224745, 0.000000),
//                 (10.000000, 11.000000, 12.000000, 1.000000))

(static) extractRotation( m ) → {Quat}
Returns: The rotation contained in the matrix.

Extracts the rotation from a matrix.

Parameters

Name	Type	Description
`m`	Mat4	The matrix.

Example

Extract the rotation from a matrix.

var scale = Vec3.multiply(2, Vec3.ONE);
var rot = Quat.fromPitchYawRollDegrees(30, 45, 60);
var trans = { x: 10, y: 11, z: 12 };
var matrix = Mat4.createFromScaleRotAndTrans(scale, rot, trans);

rot = Mat4.extractRotation(matrix);
print("Rotation: " + JSON.stringify(Quat.safeEulerAngles(rot)));
// Rotation: {"x":29.999998092651367,"y":45.00000762939453,"z":60.000003814697266}

(static) extractScale( m ) → {Vec3}
Returns: The scale contained in the matrix.

Extracts the scale from a matrix.

Parameters

Name	Type	Description
`m`	Mat4	The matrix.

Example

Extract the scale from a matrix.

var scale = Vec3.multiply(2, Vec3.ONE);
var rot = Quat.fromPitchYawRollDegrees(30, 45, 60);
var trans = { x: 10, y: 11, z: 12 };
var matrix = Mat4.createFromScaleRotAndTrans(scale, rot, trans);

scale = Mat4.extractScale(matrix);
print("Scale: " + JSON.stringify(scale));
// Scale: {"x":1.9999998807907104,"y":1.9999998807907104,"z":1.9999998807907104}

(static) extractTranslation( m ) → {Vec3}
Returns: The translation contained in the matrix.

Extracts the translation from a matrix.

Parameters

Name	Type	Description
`m`	Mat4	The matrix.

Example

Extract the translation from a matrix.

var scale = Vec3.multiply(2, Vec3.ONE);
var rot = Quat.fromPitchYawRollDegrees(30, 45, 60);
var trans = { x: 10, y: 11, z: 12 };
var matrix = Mat4.createFromScaleRotAndTrans(scale, rot, trans);

trans = Mat4.extractTranslation(matrix);
print("Translation: " + JSON.stringify(trans));
// Translation: {"x":10,"y":11,"z":12}

(static) getForward( m ) → {Vec3}
Returns: The negative z-axis rotated by the rotation in the matrix.

Gets the "forward" direction that the camera would face if its orientation was set to the rotation contained in a matrix. The High Fidelity camera has axes x = right, y = up, -z = forward.

Parameters

Name	Type	Description
`m`	Mat4	The matrix.

Example

Demonstrate that the "forward" direction is the negative z-axis.

var rot = Quat.IDENTITY;
var trans = Vec3.ZERO;
var matrix = Mat4.createFromRotAndTrans(rot, trans);
var forward = Mat4.getForward(matrix);
print("Forward: " + JSON.stringify(forward));
// Forward: {"x":0,"y":0,"z":-1}

(static) getFront( m ) → {Vec3}
Returns: The negative z-axis rotated by orientation.

Gets the "forward" direction that the camera would face if its orientation was set to the rotation contained in a matrix. The High Fidelity camera has axes x = right, y = up, -z = forward.

Synonym for getForward.

Parameters

Name	Type	Description
`m`	Mat4	The matrix.

(static) getRight( m ) → {Vec3}
Returns: The x-axis rotated by the rotation in the matrix.

Gets the "right" direction that the camera would have if its orientation was set to the rotation contained in a matrix. The High Fidelity camera has axes x = right, y = up, -z = forward.

Parameters

Name	Type	Description
`m`	Mat4	The matrix.

(static) getUp( m ) → {Vec3}
Returns: The y-axis rotated by the rotation in the matrix.

Gets the "up" direction that the camera would have if its orientation was set to the rotation contained in a matrix. The High Fidelity camera has axes x = right, y = up, -z = forward.

Parameters

Name	Type	Description
`m`	Mat4	The matrix.

(static) inverse( m ) → {Mat4}
Returns: The inverse of the matrix.

Calculates the inverse of a matrix.

Parameters

Name	Type	Description
`m`	Mat4	The matrix.

Example

A matrix multiplied with its inverse is the unit matrix.

var scale = Vec3.multiply(2, Vec3.ONE);
var rot = Quat.fromPitchYawRollDegrees(30, 45, 60);
var trans = { x: 10, y: 11, z: 12 };
var matrix = Mat4.createFromScaleRotAndTrans(scale, rot, trans);
var inverse = Mat4.inverse(matrix);
var multiplied = Mat4.multiply(matrix, inverse);
Mat4.print("Multiplied:", multiplied);
//Multiplied: dmat4x4((1.000000, 0.000000, 0.000000, 0.000000),
//                    (0.000000, 1.000000, -0.000000, 0.000000),
//                    (0.000000, 0.000000, 1.000000, 0.000000),
//                    (0.000000, 0.000000, 0.000001, 1.000000))

(static) multiply( m1, m2 ) → {Mat4}
Returns: m1 multiplied with m2.

Multiplies two matrices.

Parameters

Name	Type	Description
`m1`	Mat4	The first matrix.
`m2`	Mat4	The second matrix.

(static) print( label, m, transposeopt )

Prints a matrix to the program log as a label followed by the matrix's values.

Parameters

Name	Type	Attributes	Default Value	Description
`label`	string			The label to print.
`m`	Mat4			The matrix to print.
`transpose`	boolean	<optional>	false	`true` to transpose the matrix before printing (so that it prints the matrix's rows), `false` to not transpose the matrix (so that it prints the matrix's columns).

Example

Two ways of printing a label and matrix value.

var scale = Vec3.multiply(2, Vec3.ONE);
var rot = Quat.fromPitchYawRollDegrees(30, 45, 60);
var trans = { x: 10, y: 11, z: 12 };
var matrix = Mat4.createFromScaleRotAndTrans(scale, rot, trans);

Mat4.print("Matrix:", matrix);
// Matrix: dmat4x4((0.707107, 1.224745, -1.414214, 0.000000),
//                 (-1.146447, 1.478398, 0.707107, 0.000000),
//                 (1.478398, 0.560660, 1.224745, 0.000000),
//                 (10.000000, 11.000000, 12.000000, 1.000000))

print("Matrix: " + JSON.stringify(matrix));
// Matrix: {"r0c0":0.7071067094802856,"r1c0":1.2247446775436401,"r2c0":-1.4142136573791504,"r3c0":0,
//          "r0c1": -1.1464465856552124, "r1c1": 1.4783978462219238, "r2c1": 0.7071066498756409, "r3c1": 0,
//          "r0c2": 1.4783978462219238, "r1c2": 0.5606603026390076, "r2c2": 1.2247447967529297, "r3c2": 0,
//          "r0c3": 10, "r1c3": 11, "r2c3": 12, "r3c3": 1}

(static) transformPoint( m, point ) → {Vec3}
Returns: The point in the new coordinate system.

Transforms a point into a new coordinate system: the point value is scaled, rotated, and translated.

Parameters

Name	Type	Description
`m`	Mat4	The transform to the new coordinate system.
`point`	Vec3	The point to transform.

Example

Transform a point.

var scale = Vec3.multiply(2, Vec3.ONE);
var rot = Quat.fromPitchYawRollDegrees(0, 45, 0);
var trans = { x: 0, y: 10, z: 0 };
var matrix = Mat4.createFromScaleRotAndTrans(scale, rot, trans);

var point = { x: 1, y: 1, z: 1 };
var transformedPoint = Mat4.transformPoint(matrix, point);
print("Transformed point: " + JSON.stringify(transformedPoint));
// Transformed point: { "x": 2.8284270763397217, "y": 12, "z": -2.384185791015625e-7 }

(static) transformVector( m, vector ) → {Vec3}
Returns: The vector in the new coordinate system.

Transforms a vector into a new coordinate system: the vector is scaled and rotated.

Parameters

Name	Type	Description
`m`	Mat4	The transform to the new coordinate system.
`vector`	Vec3	The vector to transform.

Example

Transform a vector.

var scale = Vec3.multiply(2, Vec3.ONE);
var rot = Quat.fromPitchYawRollDegrees(0, 45, 0);
var trans = { x: 0, y: 10, z: 0 };
var matrix = Mat4.createFromScaleRotAndTrans(scale, rot, trans);

var vector = { x: 1, y: 1, z: 1 };
var transformedVector = Mat4.transformVector(matrix, vector);
print("Transformed vector: " + JSON.stringify(transformedVector));
// Transformed vector: { "x": 2.8284270763397217, "y": 2, "z": -2.384185791015625e-7 }