# 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 }``````