XRRigidTransform: matrix property
=================================

 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
 `Float32Array`s. 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 with JavaScript enabled. Enable JavaScript to view data.