CSS 2D Transforms Module Level 3 (original) (raw)

is functionally equivalent to:

div { transform: translate(100px, 100px); }

Move the element by 100 pixels in both the X and Y directions.

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%.

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.

• If the ‘from’ and ‘to’ transforms are both single functions of the same type:
  • For translate, translateX, translateY, translateZ, scale, scaleX, scaleY, rotate, skewX and skewY functions:
    * the individual components of the function are interpolated numerically.
  • For matrix:
    * the matrix is decomposed using the method described by unmatrix into separate translation, scale, rotation and skew matrices, then each decomposed matrix is interpolated numerically, and finally combined in order to produce a resulting 3x2 matrix.
• If both the ‘from’ and ‘to’ transforms are "none":
  • There is no interpolation necessary
• If one of the ‘from’ or ‘to’ transforms is "none":
  • The ‘none’ is replaced by an equivalent identity function list for the corresponding transform function list.
    For example, if the ‘from’ transform is "scale(2)" and the ‘to’ transform is "none" then the value "scale(1)" will be used as the ‘to’ value, and animation will proceed using the rule above. Similarly, if the ‘from’ transform is "none" and the ‘to’ transform is "scale(2) rotate(50deg)" then the animation will execute as if the ‘from’ value is "scale(1) rotate(0)".
    The identity functions are translate(0), translateX(0), translateY(0), scale(1), scaleX(1), scaleY(1), rotate(0), rotateX(0), rotateY(0), skewX(0), skewY(0), and matrix(1, 0, 0, 1, 0, 0).
• If both the ‘from’ and ‘to’ transforms have the same number of transform functions and corresponding functions in each transform list are of the same type:
  • Each transform function is animated with its corresponding destination function in isolation using the rules described above. The individual values are then applied as a list to produce resulting transform value.
• Otherwise:
  • The transform function lists are each converted into the equivalent matrix value and animation proceeds using the rule for a single function above.

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 typeNode

The Node which defines the desired coordinate space of the returned point.

point of typePoint

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 typeNode

The Node which defines the coordinate space of the passed point.

point of typePoint

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 typeDOMString

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 typeCSSMatrix

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 typefloat

The X component of the translation value.

y of typefloat

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 typefloat

The X component of the scale value.

scaleY of typefloat

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 typefloat

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, thegetComputedStyle method of the Window object has been updated. The [transform](#effects) 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](#effects) property.

8 References

Normative references

Other references

Property index

Property	Values	Initial	Applies to	Inh.	Percentages	Media
transform	none | [ ]*	none	block-level and inline-level elements	no	refer to the size of the element's box	visual
transform-origin	[ [ |	left	center	right ] [		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

Index

• transform, 2
• transform-origin, 3