Make XRRay.matrix unique, add steps for obtaining it (#655)

Manishearth · toji · commit 58b85323c3c8 · 2019-05-28T15:07:42.000-07:00
Adds an algorithm for how `XRRay.matrix` must be calculated to ensure compatibility between UAs.
diff --git a/index.bs b/index.bs
@@ -1188,9 +1188,25 @@ The <dfn attribute for="XRRay">origin</dfn> attribute defines the 3-dimensional
 The <dfn attribute for="XRRay">direction</dfn> attribute defines the ray's 3-dimensional directional vector. The {{XRRay/direction}}'s {{DOMPointReadOnly/w}} attribute MUST be <code>0.0</code> and the vector MUST be normalized to have a length of <code>1.0</code>.
 
 <section class="unstable">
-The <dfn attribute for="XRRay">matrix</dfn> attribute is a [=matrix=] which represents the transform from a ray originating at <code>[0, 0, 0]</code> and extending down the negative Z axis to the ray described by the {{XRRay}}'s {{XRRay/origin}} and {{XRRay/direction}}.
+The <dfn attribute for="XRRay">matrix</dfn> attribute is a [=matrix=] which represents a transform that can be used to position objects along the {{XRRay}. It is a transform from a ray originating at <code>[0, 0, 0]</code> and extending down the negative Z axis to the ray described by the {{XRRay}}'s {{XRRay/origin}} and {{XRRay/direction}}. Such a matrix MUST be one that has a rotation component which leaves any vector perpendicular to {{XRRay/direction}} and the <code>Z</code> axis unchanged. This attribute MUST be computed by [=XRRay/obtain the matrix|obtaining the matrix=] for the {{XRRay}}. This attribute SHOULD be lazily evaluated.
 
 NOTE: The {{XRRay}}'s {{XRRay/matrix}} can be used to easily position graphical representations of the ray when rendering.
+
+<div class=algorithm data-algorithm="obtain-ray-matrix">
+
+To <dfn for=XRRay>obtain the matrix</dfn> for a given {{XRRay}} |ray|
+
+  1. Let |z| be the vector <code>[0, 0, -1]</code>
+  1. Let |axis| be the vector cross product of |z| and |ray|'s {{XRRay/direction}}, <code>z × direction</code>
+  1. Let |angle| be the scalar dot product of |z| and |ray|'s {{XRRay/direction}}, <code>z · direction</code>
+  1. Let |rotation| be an identity matrix
+  1. If |axis| and |angle| are both nonzero:
+    1. Set |rotation| to the rotation matrix representing a right handed planar rotation around |axis| by |angle|
+  1. Let |translation| be the translation matrix with components corresponding to |ray|'s {{XRRay/origin}}
+  1. Let |matrix| be the result of premultiplying |rotation| from the left onto |translation| (i.e. <code>translation * rotation</code>) in column-vector notation.
+  1. Return |matrix|
+
+</div>
 </section>
 
 Pose {#pose}
