Define better how to transform a point with a matrix

Fixes #183.

Author: zcorpan

geometry/Overview.bs

@@ -183,20 +183,13 @@ steps:
 method, when invoked, must run the following steps:
 
 <ol>
- <li><p>Create a new {{DOMPoint}} <var>point</var> initialized to {{DOMPoint/x}}, {{DOMPoint/y}},
- {{DOMPoint/z}} and {{DOMPoint/w}} of the current point.
-
  <li><p>Let <var>matrixObject</var> be the result of invoking <a>create a <code>DOMMatrix</code>
  from the dictionary</a> <var>matrix</var>.
 
- <li><a for=matrix>Post-multiply</a> <var>point</var> with <var>matrixObject</var>.
-
- <li><p>Return <var>point</var>.
+ <li><p>Return the result of invoking <a>transform a point with a matrix</a>, given the current
+ point and <var>matrixObject</var>. The current point does not get modified.
 </ol>
 
-<p>{{DOMPointReadOnly/matrixTransform()}} does not modify the current {{DOMPointReadOnly}} object
-and returns a new {{DOMPoint}} object.
-
 <div class=example>
  <p>In this example the method {{DOMPointReadOnly/matrixTransform()}} on a {{DOMPoint}} instance is
  called with a {{DOMMatrix}} instance as argument.
@@ -215,6 +208,51 @@ and returns a new {{DOMPoint}} object.
 </div>
 
 
+<h3 id=transforming-a-point-with-a-matrix>Transforming a point with a matrix</h3>
+
+<p>To <dfn export>transform a <a>point</a> with a <a>matrix</a></dfn>, given <var>point</var> and
+<var>matrix</var>:
+
+<ol>
+ <li><p>Let <var>x</var> be <var>point</var>'s <a for=point>x coordinate</a>.
+
+ <li><p>Let <var>y</var> be <var>point</var>'s <a for=point>y coordinate</a>.
+
+ <li><p>Let <var>z</var> be <var>point</var>'s <a for=point>z coordinate</a>.
+
+ <li><p>Let <var>w</var> be <var>point</var>'s <a for=point>w perspective</a>.
+
+ <li>
+  <p>Let <var>pointVector</var> be a new column vector with the elements being <var>x</var>,
+  <var>y</var>, <var>z</var>, and <var>w</var>, respectively.
+
+  <p><math display=inline><mrow><mfenced open=[ close=]><mrow><mtable><mtr><mtd><mi>x</mi></mtd></mtr><mtr><mtd><mi>y</mi></mtd></mtr><mtr><mtd><mi>z</mi></mtd></mtr><mtr><mtd><mi>w</mi></mtd></mtr></mtable></mrow></mfenced></mrow></math>
+
+ <li><p>Set <var>pointVector</var> to <var>pointVector</var> <a for=matrix>post-multiplied</a> by
+ <var>matrix</var>.
+
+ <li><p>Let <var>transformedPoint</var> be a new {{DOMPoint}} object.
+
+ <li><p>Set <var>transformedPoint</var>'s <a for=point>x coordinate</a> to <var>pointVector</var>'s
+ first element.
+
+ <li><p>Set <var>transformedPoint</var>'s <a for=point>y coordinate</a> to <var>pointVector</var>'s
+ second element.
+
+ <li><p>Set <var>transformedPoint</var>'s <a for=point>z coordinate</a> to <var>pointVector</var>'s
+ third element.
+
+ <li><p>Set <var>transformedPoint</var>'s <a for=point>w perspective</a> to <var>pointVector</var>'s
+ fourth element.
+
+ <li><p>Return <var>transformedPoint</var>.
+</ol>
+
+<p class=note>If <var>matrix</var>'s <a for=matrix>is 2D</a> is true, <var>point</var>'s <a
+for=point>z coordinate</a> is ''0'' or ''-0'', and <var>point</var>'s <a for=point>w perspective</a>
+is ''1'', then this is a 2D transformation. Otherwise this is a 3D transformation.
+
+
 <h2 id=DOMRect>The DOMRect interfaces</h2>
 
 <p>Objects implementing the {{DOMRectReadOnly}} interface represent a <dfn>rectangle</dfn>. The type
@@ -1395,13 +1433,9 @@ export>is 2D</dfn>. This flag indicates that:
  <dt><dfn>transformPoint(<var>point</var>)</dfn>
  <dd>
   <p>Let <var>pointObject</var> be the result of invoking <a>create a <code>DOMPoint</code> from the
-  dictionary</a> <var>point</var>. <var>pointObject</var> is <a for=matrix>post-multiplied</a> to
-  the current matrix and returns the resulting point. The passed argument does not get modified.
-
-  <p class=note>Even if {{DOMMatrixReadOnly/is2D}} of the current matrix returns <code>true</code>,
-  a 4x4 matrix multiplication will be performed if the {{DOMPointReadOnly/z}} attribute of
-  <var>point</var> is not ''0'' or ''-0'' or the {{DOMPointReadOnly/w}} attribute of
-  <var>point</var> is not ''1''.
+  dictionary</a> <var>point</var>. Return the result of invoking <a>transform a point with a
+  matrix</a>, given <var>pointObject</var> and the current matrix. The passed argument does not get
+  modified.
 
  <dt><dfn>toFloat32Array()</dfn>
  <dd><p>Returns the serialized 16 elements {{DOMMatrixReadOnly/m11}} to {{DOMMatrixReadOnly/m44}} of
@@ -2190,6 +2224,7 @@ Max Vujovic,
 Mike Taylor,
 Peter Hall,
 Philip Jägenstedt,
+Simon Fraser,
 and
 Timothy Loh
 for their careful reviews, comments, and corrections.