Mat4

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 }