Fix multiplication order for transforms

klausw · toji · commit 6868682b896c · 2019-05-16T11:19:46.000-07:00
The multiplication order in the spec needs to match the matrix
semantics we've agreed on, and the usage appeared to be backwards.

Specific justifications following.

getViewerPose: if |offset| is the view offset of an eye view, the expected
semantics would be that it's a pose-like transform where the transform's
position is the eye view's coordinates in XRViewerPose space. The
corresponding matrix is viewerFromEye. XRViewerPose contains the viewer
pose in the base reference space, so its transform's position is the viewer
position in base space coordinates, and the transform is baseFromViewer.

Chaining these transforms works as follows:

```js
offset.matrix = viewerFromEye;
viewerPose.transform.matrix = baseFromViewer;

view.transform.matrix = baseFromEye
                      = baseFromViewer * viewerFromEye
                      = viewerPose.transform.matrix * offset.matrix
```

For originOffset, the logic is similar:

```js
let offsetASpace = baseSpace.getOffsetReferenceSpace(offsetAInBase);
// offsetAInBase.matrix = baseFromA
let offsetBSpace = offsetASpace.getOffsetReferenceSpace(offsetBInA);
// offsetBInA.matrix = AFromB

// equivalent to:
let offsetBSpace = baseSpace.getOffsetReferenceSpace(offsetBInBase);
// offsetBInBase.matrix = baseFromA * AFromB = offsetAInBase.matrix * offsetBInA.matrix
```

Lastly, for XRRay, the convention is to transform points or vectors by
premultiplying the transform matrix from the left, I've rephrased those usages
to make that explicit. The current text was basically saying "multiply
vector by matrix" which would be backwards.
diff --git a/index.bs b/index.bs
@@ -734,7 +734,7 @@ When the <dfn method for="XRFrame">getViewerPose(|referenceSpace|)</dfn> method
       1. Initialize |xrview|'s {{XRView/eye}} to |view|'s [=view/eye=]
       1. Initialize |xrview|'s {{XRView/projectionMatrix}} to |view|'s [=view/projection matrix=]
       1. Let |offset| be an {{XRRigidTransform}} equal to the [=view offset=] of |view|
-      1. Set |xrview|'s {{XRView/transform}} property to the result of [=multiply transforms|multiplying=] the |offset| transform by the {{XRViewerPose}}'s {{XRPose/transform}}
+      1. Set |xrview|'s {{XRView/transform}} property to the result of [=multiply transforms|multiplying=] the {{XRViewerPose}}'s {{XRPose/transform}} by the |offset| transform
       1. [=list/Append=] |xrview| to |xrviews|
   1. Set |pose|'s {{XRViewerPose/views}} to |xrviews|
   1. Return |pose|.
@@ -852,7 +852,7 @@ The <dfn method for="XRReferenceSpace">getOffsetReferenceSpace(|originOffset|)</
   1. If |base| is an instance of {{XRBoundedReferenceSpace}}, let |offsetSpace| be a new {{XRBoundedReferenceSpace}} and set |offsetSpace|'s {{boundsGeometry}} to |base|'s {{boundsGeometry}}, with each point multiplied by the {{XRRigidTransform/inverse}} of |originOffset|.
   1. Else let |offsetSpace| be a new {{XRReferenceSpace}}.
   1. Set |offsetSpace|'s [=native origin=] to |base|'s [=native origin=].
-  1. Set |offsetSpace|'s [=origin offset=] to the result of [=multiply transforms|multiplying=] |originOffset| by |base|'s [=origin offset=].
+  1. Set |offsetSpace|'s [=origin offset=] to the result of [=multiply transforms|multiplying=] |base|'s [=origin offset=] by |originOffset|.
   1. Return |offsetSpace|.
 
 </div>
@@ -1094,8 +1094,8 @@ The <dfn constructor for="XRRay">XRRay(|transform|)</dfn> constructor MUST perfo
   1. Let |ray| be a new {{XRRay}}.
   1. Initialize |ray|'s {{XRRay/origin}} to <code>{ x: 0.0, y: 0.0, z: 0.0, w: 1.0 }</code>.
   1. Initialize |ray|'s {{XRRay/direction}} to <code>{ x: 0.0, y: 0.0, z: -1.0, w: 0.0 }</code>.
-  1. Multiply |ray|'s {{XRRay/origin}} by the |transform|'s {{XRRigidTransform/matrix}} and set |ray| to the result.
-  1. Multiply |ray|'s {{XRRay/direction}} by the |transform|'s {{XRRigidTransform/matrix}} and set |ray| to the result.
+  1. Transform |ray|'s {{XRRay/origin}} by premultiplying the |transform|'s {{XRRigidTransform/matrix}} and set |ray| to the result.
+  1. Transform |ray|'s {{XRRay/direction}} by premultiplying the |transform|'s {{XRRigidTransform/matrix}} and set |ray| to the result.
   1. [=Normalize=] the {{DOMPointReadOnly/x}}, {{DOMPointReadOnly/y}}, and {{DOMPointReadOnly/z}} components of |ray|'s {{XRRay/direction}}
   1. Return |ray|.
 
