CSS Transforms

21 April 2008

Authors:
Dave Hyatt (hyatt@apple.com), Apple
Dean Jackson (dino@apple.com), Apple
Chris Marrin (cmarrin@apple.com), Apple

1 Introduction

The CSS visual formatting model describes a coordinate system within which each element is positioned. Positions and sizes in this coordinate space can be thought of as being expressed in pixels, starting in the upper left corner of the parent with positive values proceeding to the right and down.

This coordinate space can be modified with the 'transform' property. Using transform, elements can be translated, rotated and scaled in two or three dimensional space. A perspective transform can also be applied to give a sense of depth to the way elements are displayed. In two dimensions, the coordinate space behaves as described in the coordinate system transformations section of the SVG 1.1 specification. This is a coordinate system with two axes: the X axis increases horizontally to the right; the Y axis increases vertically downwards. In three dimensions, a Z axis is added, with positive z values conceptually rising perpendicularly out of the window toward the user and negative z values falling into the window away from the user.

Specifying a value other than 'none' for the 'transform' property establishes a new local coordinate system at the element that it is applied to. Transformations are cumulative. That is, elements establish their local coordinate system within the coordinate system of their parent. In this way, a 'transform' property effectively accumulates all the 'transform' properties of its ancestors. The accumulation of these transforms defines a current transformation matrix (CTM) for the element.

The transform property does not affect the flow of the content surrounding the transformed element. However, the value of the overflow area takes into account transformed elements. This behavior is similar to what happens when elements are translated via relative positioning. Therefore, if the value of the 'overflow' property is 'scroll' or 'auto', scrollbars will appear as needed to see content that is transformed outside the visible area.

Any value other than 'none' for the transform results in the creation of both a stacking context and a containing block. The object acts as though position: relative has been specified, but also acts as a containing block for fixed positioned descendants. The z position of a transformed element does not affect the order within a stacking context. With elements at the same z-index, objects are drawn in order of increasing z position.

Need to go into more detail here about why fixed positioned objects should do this, i.e., that it's much harder to implement otherwise.
Transforms should perhaps be allowed to affect layout. Using the position property to do this seems to be the logical choice, but there are lots of questions about how this would work.
What do fixed backgrounds do in transforms? They should probably ignore the transform completely, since - even transformed - the object should be acting as "porthole" through which the fixed background can be viewed in its original form.

Note that while 'transform' uses a three-dimensional coordinate system, the elements themselves are not three-dimensional objects. Instead, they exist on a two-dimensional plane (a flat surface) and have no depth.

This property should also be applicable to SVG elements, but since SVG doesn't have stacking contexts we'd have to describe how the painters' model is changed by z position.
We also need to specify that SVG transforms *do* combine with this transform, e.g., if a <foreignObject> is inside transformed SVG and then defines a transform of its own. This means we may potentially have to examine the current SVG transform and combine with it to set the correct transform.

2 The 'transform' Property

A 2D or 3D transformation is applied to an element through the 'transform' property. This property contains a list of transform functions. The final transformation value for an element is obtained by performing a matrix concatenation of each entry in the list. The set of transform functions is similar to those allowed by SVG. There are additional functions to support 3D transformations.

Name: transform
Value: none | <transform-function> [ <transform-function> ]*
Initial: none
Applies to: block-level and inline-level elements
Inherited: no
Percentages: refer to the size of the element's box
Media: visual
Computed value: Same as specified value.

3 The 'transform-origin' Property

The 'transform-origin' property establishes the origin of transformation for an element. This property is applied by first translating the element by the negated value of the property, then applying the element's transform, then translating by the property value. This effectively moves the desired transformation origin of the element to (0,0,0) in the local coordinate system, then applies the element's transform, then moves the element back to its original position.

Name: transform-origin
Value: [ [ <percentage> | <length>]{1,2} | [ <percentage> | <length>]{2} <length> | [top | center | bottom] || [left | center | right] ] ]
The z component can only be a length. Check BNF
Initial: 50% 50% 0
Applies to: block-level and inline-level elements
Inherited: no
Percentages: refer to the size of the element's box
Media: visual
Computed value: Same as specified value.

4 The 'transform-style' Property

The 'transform-style' property defines how nested elements are rendered in 3D space. If the 'transform-style' is 'flat', all children of this element are rendered flattened into the 2D plane of the element. Therefore, rotating the element about the X or Y axes will cause children positioned at positive or negative Z positions to appear on the element's plane, rather than in front of or behind it. If the 'transform-style' is 'preserve-3d', this flattening is not performed, so children maintain their position in 3D space.

This flattening takes place at each element, so preserving a hierarchy of elements in 3D space requires that each ancestor in the hierarchy have the value 'preserve-3d' for 'transform-style'. But since 'transform-style' affects only an element's children, the leaf nodes in a hierarchy do not require the perspective style.

Name: transform-style
Value: flat | preserve-3d
Initial: flat
Applies to: block-level and inline-level elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: Same as specified value.

For some effects, the author will have to ensure that an ancestor element to a subtree using 'preserve-3d' has a 'transform-style' of 'flat' (or the default). Otherwise, the elements in the 3D tree may be located behind ancestor elements and, thus, invisible (hidden behind an ancestor's background).

Note that while 'preserve-3d' can be specified on an element, the effect may not be possible. Elements that have 'overflow' set to 'hidden' are unable to keep their children in 3D. In this case the element will behave as if the property was set to 'flat'.

Does transform-style: preserve-3d need to establish a stacking context and containing block like transform does?

5 The 'perspective' Property

The 'perspective' property applies the same transform as the perspective(<number>) transform function, except that it applies only to the positioned or transformed children of the element, not to the transform on the element itself.

If the value is 'none' no perspective transform is applied.

The use of this property with any value other than 'none' establishes a stacking context. It also establishes a containing block (somewhat similar to position:relative), just like the 'transform' property does.

Name: perspective
Value: none | <number>
Initial: none
Applies to: block-level and inline-level elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: Same as specified value.

6 The 'perspective-origin' Property

The 'perspective-origin' property establishes the origin for the perspective property. It effectively sets the X and Y position at which the viewer appears to be looking at the children of the element.

Name: perspective-origin
Value: [ [ <percentage> | <length>]{1,2} | [top | center | bottom] | [left | center | right] ] | inherit
Initial: 50% 50%
Applies to: block-level and inline-level elements
Inherited: no
Percentages: refer to the size of the box itself
Media: visual
Computed value: Same as specified value.

7 The 'backface-visibility' Property

The 'backface-visibility' property determines whether or not the "back" side of a transformed element is visible when facing the viewer. With an identity transform, the front side of an element faces the viewer. Applying a rotation about Y of 180 degrees (for instance) would cause the back side of the element to face the viewer.

This property is useful when you place two elements back-to-back, as you would to create a playing card. Without this property, the front and back elements could switch places at times during an animation to flip the card. Another example is creating a box out of 6 elements, but where you want to see the inside faces of the box. This is useful when creating the backdrop for a 3 dimensional stage.

Name: backface-visibility
Value: visible | hidden
Initial: visible
Applies to: block-level and inline-level elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: Same as specified value.

8 The Transformation Functions

The value of the transform property is a list of <transform-functions>, applied in the order provided. The individual transform functions are separated by whitespace. The following is a list of allowed transform functions. In this list the type <translation-value> is defined as a <length> or <percentage> value, and the <angle> type is defined as a <number> followed by a required angle unit identifier. Angle unit identifiers are:

matrix(<number>, <number>, <number>, <number>, <number>, <number>)
specifies a 2D transformation in the form of a transformation matrix of six values. matrix(a,b,c,d,e,f) is equivalent to applying the transformation matrix [a b c d e f].
matrix3d(<number>, <number>, <number>, <number>,
                <number>, <number>, <number>, <number>,
                <number>, <number>, <number>, <number>,
                <number>, <number>, <number>, <number>)
specifies a 3D transformation as a 4x4 homogeneous matrix of 16 values in column-major order.
translate(<translation-value>[, <translation-value>])
specifies a 2D translation by the vector [tx, ty], where tx is the first translation-value parameter and ty is the optional second translation-value parameter. If <ty> is not provided, ty has zero as a value.
translate3d(<translation-value>, <translation-value>, <translation-value>)
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.
translateX(<translation-value>)
specifies a translation by the given amount in the X direction.
translateY(<translation-value>)
specifies a translation by the given amount in the Y direction.
translateZ(<translation-value>)
specifies a translation by the given amount in the Z direction. Note that percentage values are not allowed in the translateZ translation-value, and if present are evaluated as 0.
scale(<number>[, <number>])
specifies a 2D scale operation by the [sx,sy] scaling vector described by the 2 parameters. If the second parameter is not provided, it is takes a value equal to the first.
scale3d(<number>, <number>, <number>)
specifies a 3D scale operation by the [sx,sy,sz] scaling vector described by the 3 parameters.
scaleX(<number>)
specifies a scale operation using the [sx,1,1] scaling vector, where sx is given as the parameter.
scaleY(<number>)
specifies a scale operation using the [1,sy,1] scaling vector, where sy is given as the parameter.
scaleZ(<number>)
specifies a scale operation using the [1,1,sz] scaling vector, where sz is given as the parameter.
rotate(<angle>)
specifies a 2D rotation by the angle specified in the parameter about the origin of the element, as defined by the transform-origin property. The operation corresponds to the matrix [cos(a) sin(a) -sin(a) cos(a) 0 0].
rotate3d(<number>, <number>, <number>, <angle>)
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.
rotateX(<angle>)
specifies a clockwise rotation by the given angle about the X axis.
rotateY(<angle>)
specifies a clockwise rotation by the given angle about the Y axis.
rotateZ(<angle>)
specifies a clockwise rotation by the given angle about the Z axis.
skewX(<angle>)
specifies a skew transformation along the X axis by the given angle.
skewY(<angle>)
specifies a skew transformation along the Y axis by the given angle.
skewZ(<angle>)
specifies a skew transformation along the Z axis by the given angle.
perspective(<number>)
specifies a perspective projection matrix. This matrix maps a viewing cube 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 depth, 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. The value is given in pixels, so a value of 1000 gives a moderate amount of foreshortening and a value of 200 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 3d versions could be folded into the 2d primitives using extra optional arguments. It's really just a question of how user agents that can't do 3d should be handled.

9 Transform Values and Lists

The <translation-value> values are defined as [<percentage> | <length>]. All other value types are described as CSS types. If a list of transforms is provided, then the net effect is as if each transform had been specified separately in the order provided. For example, 

<div style="transform:translate(-10px,-20px) scale(2) rotate(45deg) translate(5px,10px)"/>

is functionally equivalent to: 

<div style="transform:translate(-10px,-20px)">
  <div style="transform:scale(2)">
    <div style="transform:rotate(45deg)">
      <div style="transform:translate(5px,10px)">
      </div>
    </div>
  </div>
</div>

div {
    transform: translate(100px, 100px);
}
Move the element by 100 pixels in both the X and Y directions.
The 100px translation in X and Y 
div {
    height: 100px; width: 100px;
    transform: translate(80px, 80px) scale(1.5, 1.5) rotate(45deg);
}
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%.
The transform specified above

10 DOM Interfaces

This section describes the interfaces and functionality added to the DOM to support runtime access to the functionality described above.

Interface Point

The Point interface represents a point in two-dimensional space.

IDL Definition 
interface Point {
    attribute float x;
    attribute float y;
};
Attributes
x of type float
The value of the point along the X dimension.
y of type float
The value of the point along the Y dimension.
Interface Window

The following 2 functions are added to the Window interface. They provide conversions between the page and node coordinate spaces.

IDL Definition 
interface Window {
  ...
  Point convertPointFromPageToNode(in Node node, in Point point);
  Point convertPointFromNodeToPage(in Node node, in Point point);
  ...
};
Methods
convertPointFromPageToNode
The convertPointFromPageToNode method returns a point in the coordinate space of the passed Node that is at the same location in the page as the passed point, which is in the coordinate space of the page.
Parameters
node of type Node
The Node which defines the desired coordinate space of the returned point.
point of type Point
The point, in the page's coordinate space, for which the desired point, in the Node's coordinate space, should be returned.
Return Value
Point
The resultant point in the coordinate space of the passed Node.
No Exceptions
convertPointFromNodeToPage
The convertPointFromNodeToPage method returns a point in the coordinate space of the page that is at the same location in the page as the passed point, which is in the coordinate space of the passed Node.
Parameters
node of type Node
The Node which defines the coordinate space of the passed point.
point of type Point
The point, in the Node's coordinate space, for which the desired point, in the page's coordinate space, should be returned.
Return Value
Point
The resultant point in the coordinate space of the page.
No Exceptions
Interface CSSMatrix

The CSSMatrix interface represents a 4x4 homogeneous matrix.

IDL Definition 
interface CSSMatrix {
    attribute float m11;
    attribute float m12;
    attribute float m13;
    attribute float m14;
    attribute float m21;
    attribute float m22;
    attribute float m23;
    attribute float m24;
    attribute float m31;
    attribute float m32;
    attribute float m33;
    attribute float m34;
    attribute float m41;
    attribute float m42;
    attribute float m43;
    attribute float m44;
 
    void        setMatrixValue(in DOMString string);
    CSSMatrix   multiply(in CSSMatrix secondMatrix);
    CSSMatrix   inverse();
    CSSMatrix   translate(in float x, in float y, in float z);
    CSSMatrix   scale(in float scaleX, in float scaleY, in float scaleZ);
    CSSMatrix   rotate(in float rotX, in float rotY, in float rotZ);
    CSSMatrix   rotateAxisAngle(in float x, in float y, in float z, in float angle);
};

Attributes
m11-m44 of type float
Each of these attributes represents one of the values in the 4x4 matrix. For instance m12 represents the value in the 2nd column of the first row.
Methods
setMatrixValue
The setMatrixValue method replaces the existing matrix with one computed from parsing the passed string as though it had been assigned to the transform property in a CSS style rule.
Parameters
string of type DOMString
The string to parse.
No Return Value
No Exceptions
multiply
The multiply method returns a new CSSMatrix which is the result of this matrix multiplied by the passed matrix, with the passed matrix to the right. This matrix is not modified.
Parameters
secondMatrix of type CSSMatrix
The matrix to multipy.
Return Value
CSSMatrix
The result matrix.
No Exceptions
inverse
The inverse method returns a new matrix which is the inverse of this matrix. This matrix is not modified.
No Parameters
Return Value
CSSMatrix
The inverted matrix.
No Exceptions
translate
The translate method returns a new matrix which is this matrix post multiplied by a translation matrix containing the passed values. If the z component is undefined, a 0 value is used in its place. This matrix is not modified.
Parameters
x of type float
The X component of the translation value.
y of type float
The Y component of the translation value.
z of type float
The (optional) Z component of the translation value.
Return Value
CSSMatrix
The result matrix.
No Exceptions
scale
The scale method returns a new matrix which is this matrix post multiplied by a scale matrix containing the passed values. If the z component is undefined, a 1 value is used in its place. If the y component is undefined, the x component value is used in its place. This matrix is not modified.
Parameters
scaleX of type float
The X component of the scale value.
scaleY of type float
The (optional) Y component of the scale value.
scaleZ of type float
The (optional) Z component of the scale value.
Return Value
CSSMatrix
The result matrix.
No Exceptions
rotate
The rotate method returns a new matrix which is this matrix post multiplied by each of 3 rotation matrices about the major axes, first X, then Y, then Z. If the y and z components are undefined, the x value is used to rotate the object about the z axis, as though the vector (0,0,x) were passed. All rotation values are in degrees. This matrix is not modified.
Parameters
rotX of type float
The X component of the rotation value, or the Z component if the rotY and rotZ parameters are undefined.
rotY of type float
The (optional) Y component of the rotation value.
rotZ of type float
The (optional) Z component of the rotation value.
Return Value
CSSMatrix
The result matrix.
No Exceptions
rotateAxisAngle
The rotateAxisAngle method returns a new matrix which is this matrix post multiplied by a rotation matrix with the given axis and angle. The right-hand rule is used to determine the direction of rotation. All rotation values are in degrees. This matrix is not modified.
Parameters
x of type float
The X component of the axis vector.
y of type float
The Y component of the axis vector.
z of type float
The Z component of the axis vector.
angle of type float
The angle of rotation about the axis vector, in degrees.
Return Value
CSSMatrix
The result matrix.
No Exceptions
Interface CSSTransformValue

The CSSTransformValue interface represents one transform function in the transform property. The operationType defines which operation is represented. The object also contains a list of values, which are the parameters of the function, in the same order in which they appear in the transform functions.

IDL Definition 
interface CSSTransformValue : CSSValueList {
    // OperationTypes
    const unsigned short CSS_UNKNOWN     = 0;
    const unsigned short CSS_MATRIX      = 1;
    const unsigned short CSS_MATRIX3D    = 2;
    const unsigned short CSS_ROTATE      = 3;
    const unsigned short CSS_ROTATE3D    = 4;
    const unsigned short CSS_TRANSLATE   = 5;
    const unsigned short CSS_TRANSLATE3D = 6;
    const unsigned short CSS_SCALE       = 7;
    const unsigned short CSS_SCALE3D     = 8;
    const unsigned short CSS_SKEWX       = 9;
    const unsigned short CSS_SKEWY       = 10;
    const unsigned short CSS_PERSPECTIVE = 11;
    const unsigned short CSS_ROTATEX     = 12;
    const unsigned short CSS_ROTATEY     = 13;
    const unsigned short CSS_ROTATEZ     = 14;
    const unsigned short CSS_TRANSLATEX  = 15;
    const unsigned short CSS_TRANSLATEY  = 16;
    const unsigned short CSS_TRANSLATEZ  = 17;
    const unsigned short CSS_SCALEX      = 18;
    const unsigned short CSS_SCALEY      = 29;
    const unsigned short CSS_SCALEZ      = 20;

    attribute unsigned short operationType;
};
Attributes
operationType of type unsigned short
One of the listed operation types.

In addition to the interfaces listed above, the getComputedStyle method of the Window object has been updated. The transform property of the style object returned by getComputedStyle contains a single CSSTransformValue with a type of CSS_MATRIX3D. The 16 parameters represent the 4x4 matrix that is the result of applying the individual functions listed in the transform property.