W3C

CSS 2D Transforms Module Level 3

W3C Working Draft 20 March 2009

This version:
http://www.w3.org/TR/2009/WD-css3-2d-transforms-20090320
Latest version:
http://www.w3.org/TR/css3-2d-transforms
Previous version:
none
Editors:
Dean Jackson (Apple Inc)
David Hyatt (Apple Inc)
Chris Marrin (Apple Inc)

Abstract

CSS 2D Transforms allows elements rendered by CSS to be transformed in two-dimensional space.

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

The (archived) public mailing list www-style@w3.org (see instructions) is preferred for discussion of this specification. When sending e-mail, please put the text “css3-2d-transforms” in the subject, preferably like this: “[css3-2d-transforms] …summary of comment…

This document was produced by the CSS Working Group (part of the Style Activity).

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This is the first public Working Draft of the “css3-2d-transforms” series.

Table of contents

1 Introduction

This section is not normative.

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 dimensional space. 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.

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.

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.
There are two roles for transformations in layout: (1) transformations that adjust the position of the affected content without changing the normal layout of that content (much like relative positioning) and (2) transformation of the content prior to layout that affects the layout of that content. See http://lists.w3.org/Archives/Public/www-style/2007Oct/0209 for examples of both cases. The "transform" property (as defined in this document) is equally useful for both roles. This document is focused on satisfying the first role. There is, however, an architectural question that arises because there needs to be a way to distinguish which role an author of a stylesheet wants. The key question is which is the default behavior/role for the "transform" property and how is the other behavior/role indicated by a stylesheet author. One possibility is to use the position property, particularly position: relative, to trigger the first role; another possibility is to make the first role the default which leaves the question as to how to indicate the second role. If you have an opinion on this topic, please send feedback.
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.
This property should also be applicable to SVG elements.
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 two-dimensional 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.

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) 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> | left | center | right ] [ <percentage> | <length> | top | center | bottom ]? ] | [ [ left | center | right ] || [ top | center | bottom ] ]
Initial: 50% 50%
Applies to: block-level and inline-level elements
Inherited: no
Percentages: refer to the size of the element's box
Media: visual
Computed value: For <length> the absolute value, otherwise a percentage

4 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 by CSS Values and Units.

none
specifies an identity transform.
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].
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.
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.
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.
scaleX(<number>)
specifies a scale operation using the [sx,1] scaling vector, where sx is given as the parameter.
scaleY(<number>)
specifies a scale operation using the [1,sy] scaling vector, where sy 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.
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.
skew(<angle> [, <angle>])
specifies a skew transformation along the X and Y axes. The first angle parameter specifies the skew on the X axis. The second angle parameter specifies the skew on the Y axis. If the second parameter is not given then a value of 0 is used for the Y angle (ie. no skew on the Y axis).

5 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

6 Transitions and animations between transform values

When animating or transitioning the value of a transform property the rules described below are applied. The ‘from’ transform is the transform at the start of the transition or current keyframe. The ‘end’ transform is the transform at the end of the transition or current keyframe.

7 DOM Interfaces

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

7.1 Point

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.

7.2 Window

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

7.3 CSSMatrix

Interface CSSMatrix

The CSSMatrix interface represents a 4x4 homogeneous matrix.

IDL Definition
  interface CSSMatrix {
      attribute float a;
      attribute float b;
      attribute float c;
      attribute float d;
      attribute float e;
      attribute float f;

      void        setMatrixValue(in DOMString string) raises(DOMException);
      CSSMatrix   multiply(in CSSMatrix secondMatrix);
      CSSMatrix   inverse() raises(DOMException);
      CSSMatrix   translate(in float x, in float y);
      CSSMatrix   scale(in float scaleX, in float scaleY);
      CSSMatrix   rotate(in float angle);
  };

Attributes
a-f of type float
Each of these attributes represents one of the values in the 3x2 matrix.
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
Exceptions
SYNTAX_ERR
Thrown when the provided string can not be parsed into a CSSMatrix.
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.
Exceptions
NOT_SUPPORTED_ERROR
Thrown when the CSSMatrix can not be inverted.
translate
The translate method returns a new matrix which is this matrix post multiplied by a translation matrix containing the passed values. 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.
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.
Return Value
CSSMatrix
The result matrix.
No Exceptions
rotate
The rotate method returns a new matrix which is this matrix post multiplied by a rotation matrix. The rotation value is in degrees. This matrix is not modified.
Parameters
angle of type float
The angle of rotation.
Return Value
CSSMatrix
The result matrix.
No Exceptions

7.4 CSSTransformValue

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 {

      // 2D OperationTypes
      const unsigned short CSS_TRANSLATE   = 1;
      const unsigned short CSS_TRANSLATEX  = 2;
      const unsigned short CSS_TRANSLATEY  = 3;
      const unsigned short CSS_ROTATE      = 4;
      const unsigned short CSS_SCALE       = 5;
      const unsigned short CSS_SCALEX      = 6;
      const unsigned short CSS_SCALEY      = 7;
      const unsigned short CSS_SKEW        = 8;
      const unsigned short CSS_SKEWX       = 9;
      const unsigned short CSS_SKEWY       = 10;
      const unsigned short CSS_MATRIX      = 11;

      attribute unsigned short operationType;

      CSSMatrix getCSSMatrix() raises(DOMException);
  };    
  
Attributes
operationType of type unsigned short
One of the listed operation types.
Methods
getCSSMatrix
The getCSSMatrix method returns a CSSMatrix object representing this transform.
No Parameters
Return Value
CSSMatrix
The result matrix.
Exceptions
NOT_SUPPORTED_ERROR
Thrown when the CSSTranformValue can not be converted into a CSSMatrix, such as when the CSSTransformValue contains percentage units and is being called on an object with unknown dimensions.

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_MATRIX. The 6 parameters represent the 3x2 matrix that is the result of applying the individual functions listed in the transform property.

8 References

Normative references

Other references

Property index

Property Values Initial Applies to Inh. Percentages Media
transform none | <transform-function> [ <transform-function> ]* none block-level and inline-level elements no refer to the size of the element's box visual
transform-origin [ [ <percentage> | <length> | left | center | right ] [ <percentage> | <length> | top | center | bottom ]? ] | [ [ left | center | right ] || [ top | center | bottom ] ] 50% 50% block-level and inline-level elements no refer to the size of the element's box visual

Index