Copyright © 2009 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
CSS 3D Transforms extends CSS Transforms to allow elements rendered by CSS to be transformed in three-dimensional space.
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-3d-transforms” in the subject, preferably like this: “[css3-3d-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-3d-transforms” series.
transform
’ Property
transform-origin
’ Property
transform-style
’ Property
perspective
’ Property
perspective-origin
’ Property
backface-visibility
’ Property
This section is not normative.
This is an enhancement to the CSS Transforms specification which provides transforms in three dimensions. It should be read in conjunction with that specification.
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 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.
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 position on the Z axis 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.
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.
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. |
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> | left | center | right ] [ <percentage> | <length> | top | center | bottom ]? ] <length> ] | [ [ [ left | center | right ] || [ top | center | bottom ] ] <length> ] |
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: | For <length> the absolute value, otherwise a percentage |
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
’.
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
’, less than or equal to 0 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. |
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> | 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 box itself |
Media: | visual |
Computed value: | Same as specified value. |
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. |
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.
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)
.
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.
from
’ and
‘to
’ transforms are both single
functions of the same type:
from
’ and
‘to
’ transforms are "none":
from
’ or
‘to
’ transforms is "none":
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), translate3d(0, 0, 0), translateX(0), translateY(0), translateZ(0), scale(1), scale3d(1, 1, 1), scaleX(1), scaleY(1), scaleZ(1), rotate(0), rotate3d(1, 1, 1, 0), rotateX(0), rotateY(0), rotateZ(0), skewX(0), skewY(0), matrix(1, 0, 0, 1, 0, 0) and matrix3d(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1).
from
’ and
‘to
’ transforms have the same
number of transform functions and corresponding functions in each
transform list are of the same type:
This section describes the interfaces and functionality added to the DOM to support runtime access to the functionality described above.
The CSSMatrix
interface represents a 4x4 homogeneous
matrix.
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) raises(DOMException); CSSMatrix multiply(in CSSMatrix secondMatrix); CSSMatrix inverse() raises(DOMException); 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); };
m11-m44
of type
float
setMatrixValue
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.
string
of type
DOMString
SYNTAX_ERR
multiply
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.
secondMatrix
of type
CSSMatrix
CSSMatrix
inverse
inverse
method returns a new
matrix which is the inverse of this matrix. This matrix is not
modified.
CSSMatrix
NOT_SUPPORTED_ERROR
translate
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.
x
of type
float
y
of type
float
z
of type
float
CSSMatrix
scale
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.
scaleX
of type
float
scaleY
of type
float
scaleZ
of type
float
CSSMatrix
rotate
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.
rotX
of type
float
rotY
of type
float
rotZ
of type
float
CSSMatrix
rotateAxisAngle
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.
x
of type
float
y
of type
float
z
of type
float
angle
of type
float
CSSMatrix
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.
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; // 3D OperationTypes const unsigned short CSS_TRANSLATEZ = 12; const unsigned short CSS_TRANSLATE3D = 13; const unsigned short CSS_ROTATEX = 14; const unsigned short CSS_ROTATEY = 15; const unsigned short CSS_ROTATEZ = 16; const unsigned short CSS_ROTATE3D = 17; const unsigned short CSS_SCALEZ = 18; const unsigned short CSS_SCALE3D = 19; const unsigned short CSS_PERSPECTIVE = 20; const unsigned short CSS_MATRIX3D = 21; attribute unsigned short operationType; CSSMatrix getCSSMatrix() raises(DOMException); };
operationType
of
type unsigned short
getCSSMatrix
getCSSMatrix
method returns a
CSSMatrix object representing this transform.
CSSMatrix
NOT_SUPPORTED_ERROR
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.
Property | Values | Initial | Applies to | Inh. | Percentages | Media |
---|---|---|---|---|---|---|
backface-visibility | visible | hidden | visible | block-level and inline-level elements | no | N/A | visual |
perspective | none | <number> | none | block-level and inline-level elements | no | N/A | visual |
perspective-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 box itself | visual |
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 ]? ] <length> ] | [ [ [ left | center | right ] || [ top | center | bottom ] ] <length> ] | 50% 50% 0 | block-level and inline-level elements | no | refer to the size of the element's box | visual |
transform-style | flat | preserve-3d | flat | block-level and inline-level elements | no | N/A | visual |