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.
Syntax
let matrix = xrRigidTransform.matrix;
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:
<math display="block">\begin{bmatrix} {a\lbrack 0\rbrack} & {a\lbrack 4\rbrack} & {a\lbrack 8\rbrack} & {a\lbrack 12\rbrack} \\ {a\lbrack 1\rbrack} & {a\lbrack 5\rbrack} & {a\lbrack 9\rbrack} & {a\lbrack 13\rbrack} \\ {a\lbrack 2\rbrack} & {a\lbrack 6\rbrack} & {a\lbrack 10\rbrack} & {a\lbrack 14\rbrack} \\ {a\lbrack 3\rbrack} & {a\lbrack 7\rbrack} & {a\lbrack 11\rbrack} & {a\lbrack 15\rbrack} \\
& & & \\
\end{bmatrix}</math>
The first time matrix is requested, it gets computed; after that, it's should be cached to avoid slowing down to compute it every time you need it.
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:
<math display="block">\begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \\ \end{bmatrix}</math>
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.
<math display="block">\begin{bmatrix} 1 & 0 & 0 & p \\ 0 & 1 & 0 & p \\ 0 & 0 & 1 & p \\ 0 & 0 & 0 & 1 \\ \end{bmatrix}</math>
Then a rotation matrix is created by computing a column-vector rotation matrix from the unit quaternion specified by orientation:
<math display="block">\begin{bmatrix} {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 \\ \end{bmatrix}</math>
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:
<math display="block">\begin{bmatrix} {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 \\ {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 \\ {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 \\ 0 & 0 & 0 & 1 \\ \end{bmatrix}</math>
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.
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 | Status | Comment |
|---|---|---|
| WebXR Device APIThe definition of 'XRRigidTransform.matrix' in that specification. | Working Draft | Initial definition. |
Browser compatibility
Update compatibility data on GitHub
| Desktop | Mobile | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
matrix
|
Chrome
Full support 79 |
Edge
Full support 79 |
Firefox
No support No |
IE
No support No |
Opera
No support No |
Safari
No support No |
WebView Android
No support No |
Chrome Android
Full support 79 |
Firefox Android
No support No |
Opera Android
No support No |
Safari iOS
No support No |
Samsung Internet Android
Full support 11.2 |
Legend
- Full support
- Full support
- No support
- No support
XRRigidTransform.matrix by Mozilla Contributors is licensed under CC-BY-SA 2.5.
