# XRRigidTransform: matrix property

Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The read-only XRRigidTransform property matrix returns the transform matrix represented by the object. The returned matrix can then be premultiplied with a column vector to rotate the vector by the 3D rotation specified by the orientation, then translate it by the position.

## Value

A Float32Array containing 16 entries which represents the 4x4 transform matrix which is described by the position and orientation properties.

## Usage notes

### Matrix format

All 4x4 transform matrices used in WebGL are stored in 16-element Float32Arrays. The values are stored into the array in column-major order; that is, each column is written into the array top-down before moving to the right one column and writing the next column into the array. Thus, for an array [a0, a1, a2, …, a13, a14, a15], the matrix looks like this:

$[ a0 a4 a8 a12 a1 a5 a9 a13 a2 a6 a10 a14 a3 a7 a11 a15 ] \begin{bmatrix} a[0] & a[4] & a[8] & a[12]\ a[1] & a[5] & a[9] & a[13]\ a[2] & a[6] & a[10] & a[14]\ a[3] & a[7] & a[11] & a[15]\ \end{bmatrix}$

On the first request, the matrix gets computed. After that, it should be cached for performance reasons.

### Creating the matrix

In this section, intended for more advanced readers, we cover how the API calculates the matrix for the specified transform. It begins by allocating a new matrix and writing a 4x4 identity matrix into it:

$[ 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1 ] \begin{bmatrix} 1 & 0 & 0 & 0\ 0 & 1 & 0 & 0\ 0 & 0 & 1 & 0\ 0 & 0 & 0 & 1 \end{bmatrix}$

This is a transform that will not change either the orientation or position of any point, vector, or object to which it's applied.

Next, the position is placed into the right-hand column, like this, resulting in a translation matrix that will transform a coordinate system by the specified distance in each dimension, with no rotational change. Here px, py, and pz are the values of the x, y, and z members of the DOMPointReadOnly position.

$[ 1 0 0 p x 0 1 0 p y 0 0 1 p z 0 0 0 1 ] \begin{bmatrix} 1 & 0 & 0 & x\ 0 & 1 & 0 & y\ 0 & 0 & 1 & z\ 0 & 0 & 0 & 1 \end{bmatrix}$

Then a rotation matrix is created by computing a column-vector rotation matrix from the unit quaternion specified by orientation:

$[ 1 - 2 ( q y 2 + q z 2 ) 2 ( q x q y - q z q w ) 2 ( q x q z + q y q w ) 0 2 ( q x q y + q z q w ) 1 - 2 ( q x 2 + q z 2 ) 2 ( q y q z - q x q w ) 0 2 ( q x q z - q y q w ) 2 ( q y q z + q x q w ) 1 - 2 ( q x 2 + q y 2 ) 0 0 0 0 1 ] \begin{bmatrix} 1 - 2(q_y^2 + q_z^2) & 2(q_xq_y - q_zq_w) & 2(q_xq_z + q_yq_w) & p_x\ 2(q_xq_y + q_zq_w) & 1 - 2(q_x^2 + q_z^2) & 2(q_yq_z - q_xq_w) & p_y\ 2(q_xq_z - q_yq_w) & 2(q_yq_z + q_xq_w) & 1 - 2(q_x^2 + q_y^2) & p_z\ 0 & 0 & 0 & 1 \end{bmatrix}$

The final transform matrix is calculated by multiplying the translation matrix by the rotation matrix, in the order (translation * rotation). This yields the final transform matrix as returned by matrix:

$[ 1 - 2 ( q y 2 + q z 2 ) 2 ( q x q y - q z q w ) 2 ( q x q z + q y q w ) p x 2 ( q x q y + q z q w ) 1 - 2 ( q x 2 + q z 2 ) 2 ( q y q z - q x q w ) p y 2 ( q x q z - q y q w ) 2 ( q y q z + q x q w ) 1 - 2 ( q x 2 + q y 2 ) p z 0 0 0 1 ] \begin{bmatrix} 1 - 2(q_y^2 + q_z^2) & 2(q_xq_y - q_zq_w) & 2(q_xq_z + q_yq_w) & p_x\ 2(q_xq_y + q_zq_w) & 1 - 2(q_x^2 + q_z^2) & 2(q_yq_z - q_xq_w) & p_y\ 2(q_xq_z - q_yq_w) & 2(q_yq_z + q_xq_w) & 1 - 2(q_x^2 + q_y^2) & p_z\ 0 & 0 & 0 & 1 \end{bmatrix}$

## Examples

In this example, a transform is created to create a matrix which can be used as a transform during rendering of WebGL objects, in order to place objects to match a given offset and orientation. The matrix is then passed into a library function that uses WebGL to render an object matching a given name using the transform matrix specified to position and orient it.

js
let transform = new XRRigidTransform(
{ x: 0, y: 0.5, z: 0.5 },
{ x: 0, y: -0.5, z: -0.5, w: 1 },
);
drawGLObject("magic-lamp", transform.matrix);


## Specifications

Specification
WebXR Device API
# dom-xrrigidtransform-matrix

## Browser compatibility

BCD tables only load in the browser