2012-01-27 simon.fraser@apple.com

    Add in 3D transform functions in their own section.
    Move the basic 2D rendering examples up into the rendering model section.
    Add ChangeLog file

Author: smfr

css3-transforms/ChangeLog

@@ -0,0 +1,7 @@
+2012-01-27 simon.fraser@apple.com
+    Add in 3D transform functions in their own section.
+    Move the basic 2D rendering examples up into the rendering model section.
+
+2012-01-27 simon.fraser@apple.com
+    Style and formatting changes, since the default style is more readable.
+    Removed the Changes section, since the autogenerated content instead links to a separate ChangeLog file (this file).

css3-transforms/Overview.html

@@ -250,6 +250,13 @@ <h2 class="no-num no-toc" id=contents>Table of contents</h2>
 
    <li><a href="#transform-functions"><span class=secno>12. </span> The
     Transformation Functions </a>
+    <ul class=toc>
+     <li><a href="#two-d-transform-functions"><span class=secno>12.1.
+      </span>2D Transformation Functions</a>
+
+     <li><a href="#three-d-transform-functions"><span class=secno>12.2.
+      </span>3D Transformation Functions</a>
+    </ul>
 
    <li><a href="#transform-values"><span class=secno>13. </span> Transform
     Values and Lists </a>
@@ -434,7 +441,49 @@ <h2 id=transform-rendering><span class=secno>5. </span>The Transform
    towards the viewer.
 
   <p> Transforms apply to <a href="#TermTransformableElement">transformable
-   elements</a>.</p>
+   elements</a>.
+
+  <div class=example>
+   <pre>
+div {
+    transform: translate(100px, 100px);
+}
+</pre>
+
+   <p>This transform moves the element by 100 pixels in both the X and Y
+    directions.</p>
+
+   <div class=figure> <img alt="The 100px translation in X and Y"
+    src=transform1.png></div>
+  </div>
+
+  <div class=example>
+   <pre>
+div {
+    height: 100px; width: 100px;
+    transform: translate(80px, 80px) scale(1.5, 1.5) rotate(45deg);
+}
+</pre>
+
+   <p>Move the element by 80 pixels in both the X and Y directions, then
+    scale the element by 150%, then rotate it 45 degrees clockwise about the
+    Z axis. Note that the scale and rotate operate about the center of the
+    element, since the element has the default transform-origin of 50% 50%.</p>
+
+   <div class=figure> <img alt="The transform specified above"
+    src="compound_transform.png"></div>
+
+   <p>Note that an identical rendering can be obtained by nesting elements
+    with the equivalent transforms:
+
+   <pre>
+&lt;div style="transform: translate(80px, 80px)"&gt;
+  &lt;div style="transform: scale(1.5, 1.5)"&gt;
+    &lt;div style="transform: rotate(45deg)"&gt;&lt;/div&gt;
+  &lt;/div&gt;
+&lt;/div&gt;
+</pre>
+  </div>
   <!-- This "in the HTML namespace" is awkward. Is there a better way? -->
 
   <p> In the HTML namespace, the transform property does not affect the flow
@@ -509,11 +558,11 @@ <h3 id=transform-3d-rendering><span class=secno>5.1. </span>3D Transform
 &lt;/div&gt;
 </pre>
 
-   <p>The transform is a 50&deg; rotation about the vertical Y axis. Note how
-    this makes the gray box appear narrower, but not three-dimensional.</p>
-
    <div class=figure> <img alt="Div with a rotateY transform." height=190
     src="examples/simple-3d-example.png" width=210></div>
+
+   <p>The transform is a 50&deg; rotation about the vertical, Y axis. Note
+    how this makes the blue box appear narrower, but not three-dimensional.</p>
   </div>
 
   <div class=example>
@@ -532,15 +581,16 @@ <h3 id=transform-3d-rendering><span class=secno>5.1. </span>3D Transform
 &lt;/div&gt;
 </pre>
 
-   <p>The inner element has the same transform as before, but its rendering
-    is now influenced by the perspective property on its parent element.
-    Perspective causes vertices that have positive Z coordinates (closer to
-    the viewer) to be scaled up in X and Y, and those futher away (negative Z
-    coordinates) to be scaled down.</p>
-
    <div class=figure> <img
-    alt="Div with a rotateY transform,                     and perspective on its container"
+    alt="Div with a rotateY transform,     and perspective on its container"
     height=190 src="examples/simple-perspective-example.png" width=210></div>
+
+   <p>The inner element has the same transform as in Example 1, but its
+    rendering is now influenced by the perspective property on its parent
+    element. Perspective causes vertices that have positive Z coordinates
+    (closer to the viewer) to be scaled up in X and Y, and those futher away
+    (negative Z coordinates) to be scaled down, giving an appearance of
+    depth.</p>
   </div>
 
   <p> An element with a three-dimensional transform that is contained in a
@@ -1219,6 +1269,9 @@ <h2 id=transform-functions><span class=secno>12. </span> The Transformation
    that is equal to zero is also allowed, which is treated the same as an
    angle of zero degrees.
 
+  <h3 id=two-d-transform-functions><span class=secno>12.1. </span>2D
+   Transformation Functions</h3>
+
   <dl>
    <dt> <span class=prop-value>matrix(&lt;number&gt;, &lt;number&gt;,
     &lt;number&gt;, &lt;number&gt;, &lt;number&gt;, &lt;number&gt;)</span>
@@ -1295,6 +1348,101 @@ <h2 id=transform-functions><span class=secno>12. </span> The Transformation
     transformation along the Y axis</a> by the given angle.
   </dl>
 
+  <h3 id=three-d-transform-functions><span class=secno>12.2. </span>3D
+   Transformation Functions</h3>
+
+  <dl>
+   <dt> <span class=prop-value>matrix3d(&lt;number&gt;, &lt;number&gt;,
+    &lt;number&gt;, &lt;number&gt;, &lt;number&gt;, &lt;number&gt;,
+    &lt;number&gt;, &lt;number&gt;, &lt;number&gt;, &lt;number&gt;,
+    &lt;number&gt;, &lt;number&gt;, &lt;number&gt;, &lt;number&gt;,
+    &lt;number&gt;, &lt;number&gt;)</span>
+
+   <dd> specifies a 3D transformation as a 4x4 homogeneous matrix of 16
+    values in column-major order.
+
+   <dt> <span class=prop-value>translate3d(&lt;translation-value&gt;,
+    &lt;translation-value&gt;, &lt;translation-value&gt;)</span>
+
+   <dd> specifies a 3D translation by the vector [tx,ty,tz], with tx, ty and
+    tz being the first, second and third translation-value parameters
+    respectively. &lt;Percentage&gt; values are not allowed in the tz
+    translation-value, and if present will cause the propery value to be
+    invalid.
+
+   <dt> <span class=prop-value>translateZ(&lt;translation-value&gt;)</span>
+
+   <dd> specifies a <a
+    href="http://www.w3.org/TR/SVG/coords.html#TranslationDefined">translation</a>
+    by the given amount in the Z direction. &lt;Percentage&gt; values are not
+    allowed in the translateZ translation-value, and if present will cause
+    the propery value to be invalid.
+
+   <dt> <span class=prop-value>scale3d(&lt;number&gt;, &lt;number&gt;,
+    &lt;number&gt;)</span>
+
+   <dd> specifies a 3D scale operation by the [sx,sy,sz] scaling vector
+    described by the 3 parameters.
+
+   <dt> <span class=prop-value>scaleZ(&lt;number&gt;)</span>
+
+   <dd> specifies a scale operation using the [1,1,sz] scaling vector, where
+    sz is given as the parameter.
+
+   <dt> <span class=prop-value>rotate3d(&lt;number&gt;, &lt;number&gt;,
+    &lt;number&gt;, &lt;angle&gt;)</span>
+  </dl>
+
+  <div class=todo>Clarify "clockwise". Describe in terms of right-hand rule?</div>
+
+  <dl>
+   <dd> specifies a clockwise 3D rotation by the angle specified in last
+    parameter about the [x,y,z] direction vector described by the first 3
+    parameters. If the direction vector is not of unit length, it will be
+    normalized. A direction vector that cannot be normalized, such as [0, 0,
+    0], will cause the rotation to not be applied. This function is
+    equivalent to <code>matrix3d(1 + (1-cos(angle))*(x*x-1),
+    -z*sin(angle)+(1-cos(angle))*x*y, y*sin(angle)+(1-cos(angle))*x*z, 0,
+    z*sin(angle)+(1-cos(angle))*x*y, 1 + (1-cos(angle))*(y*y-1),
+    -x*sin(angle)+(1-cos(angle))*y*z, 0, -y*sin(angle)+(1-cos(angle))*x*z,
+    x*sin(angle)+(1-cos(angle))*y*z, 1 + (1-cos(angle))*(z*z-1), 0, 0, 0, 0,
+    1)</code>.
+
+   <dt> <span class=prop-value>rotateX(&lt;angle&gt;)</span>
+
+   <dd> specifies a clockwise rotation by the given angle about the X axis.
+
+   <dt> <span class=prop-value>rotateY(&lt;angle&gt;)</span>
+
+   <dd> specifies a clockwise rotation by the given angle about the Y axis.
+
+   <dt> <span class=prop-value>rotateZ(&lt;angle&gt;)</span>
+
+   <dd> specifies a clockwise rotation by the given angle about the Z axis.
+    This is a synonym for <span
+    class=prop-value>rotate(&lt;angle&gt;)</span>.
+
+   <dt> <span class=prop-value>perspective(&lt;length&gt;)</span>
+
+   <dd> specifies a perspective projection matrix. This matrix maps a
+    <em>viewing cube</em> onto a pyramid whose base is infinitely far away
+    from the viewer and whose peak represents the viewer's position. The
+    viewable area is the region bounded by the four edges of the viewport
+    (the portion of the browser window used for rendering the webpage between
+    the viewer's position and a point at a distance of infinity from the
+    viewer). The <em>depth</em>, given as the parameter to the function,
+    represents the distance of the z=0 plane from the viewer. Lower values
+    give a more flattened pyramid and therefore a more pronounced perspective
+    effect. For example, a value of 1000px gives a moderate amount of
+    foreshortening and a value of 200px gives an extreme amount. The matrix
+    is computed by starting with an identity matrix and replacing the value
+    at row 3, column 4 with the value -1/depth. The value for depth must be
+    greater than zero, otherwise the function is invalid.
+    <div class=issue>I think "viewport" is wrong here. It's the border box of
+     the element with perspective.</div>
+  </dl>
+  <!-- ======================================================================================================= -->
+
   <h2 id=transform-values><span class=secno>13. </span> Transform Values and
    Lists</h2>
 
@@ -1306,52 +1454,26 @@ <h2 id=transform-values><span class=secno>13. </span> Transform Values and
    example,
 
   <pre>
-          &lt;div style="transform:translate(-10px,-20px) scale(2) rotate(45deg) translate(5px,10px)"/&gt;
-          </pre>
+&lt;div style="transform:translate(-10px,-20px) scale(2) rotate(45deg) translate(5px,10px)"/&gt;
+</pre>
 
   <p> is functionally equivalent to:
 
   <pre>
-          &lt;div style="transform:translate(-10px,-20px)"&gt;
-            &lt;div style="transform:scale(2)"&gt;
-              &lt;div style="transform:rotate(45deg)"&gt;
-                &lt;div style="transform:translate(5px,10px)"&gt;
-                &lt;/div&gt;
-              &lt;/div&gt;
-            &lt;/div&gt;
-          &lt;/div&gt;
-          </pre>
+&lt;div style="transform:translate(-10px,-20px)"&gt;
+  &lt;div style="transform:scale(2)"&gt;
+    &lt;div style="transform:rotate(45deg)"&gt;
+      &lt;div style="transform:translate(5px,10px)"&gt;
+      &lt;/div&gt;
+    &lt;/div&gt;
+  &lt;/div&gt;
+&lt;/div&gt;
+</pre>
 
   <p> That is, in the absence of other styling that affects position and
    dimensions, a nested set of transforms is equivalent to a single list of
    transform functions, applied from the outside in. The resulting transform
-   is the matrix multiplication of the list of transforms.
-
-  <div class=example>
-   <pre>
-          div {
-              transform: translate(100px, 100px);
-          }
-          </pre>
-   Move the element by 100 pixels in both the X and Y directions.
-   <div class=figure> <img alt="The 100px translation in X and Y"
-    src=transform1.png></div>
-  </div>
-
-  <div class=example>
-   <pre>
-          div {
-              height: 100px; width: 100px;
-              transform: translate(80px, 80px) scale(1.5, 1.5) rotate(45deg);
-          }
-          </pre>
-   Move the element by 80 pixels in both the X and Y directions, then scale
-   the element by 150%, then rotate it 45 degrees clockwise about the Z axis.
-   Note that the scale and rotate operate about the center of the element,
-   since the element has the default transform-origin of 50% 50%.
-   <div class=figure> <img alt="The transform specified above"
-    src="compound_transform.png"></div>
-  </div>
+   is the matrix multiplication of the list of transforms.</p>
   <!-- ======================================================================================================= -->
 
   <h2 id=animation><span class=secno>14. </span> Transitions and animations