This specification describes a transformation matrix interface with the dimension of 3x2 and 4x4.
The transformation matrix interface replaces the SVGMatrix interface from SVG [[SVG11]]. It is a common interface used to describe 2D and 3D transformations on a graphical context for SVG, Canvas 2D Context [[CANVAS-2D]] and CSS Transforms [[CSS3-TRANSFORMS]].
The following definition might move to CSSOM View
A 2D point or a 3D point can be represented by the following WebIDL dictionary:
A 2D point or a 3D point can be represented by the following WebIDL interface:
The x coordinate of the point.
The y coordinate of the point.
The z coordinate of the point.
The perspective of the point.
The DOMMatrix interface represents a mathematical matrix with the purpose of describing transformations a graphical contexts. The following sections describe the details of the interface. For the full interface see Interface summary.
DOMMatrix aims to replace the SVGMatrix interface from SVG [[SVG11]]. However, the SVGMatrix interface is mandatory for user agents with support for SVG. The SVGMatrix interface must be an alias to the DOMMatrix interface, the sameway as the HTMLDocument interface is to the Document interface.
A 4x4 matrix representing a DOMMatrix with items m11 to m44.
It needs to be decided if DOMMatrix stored single or double precision floating point numbers.
A series of constructors to create a DOMMatrix object.
In the following example a CSS Transform string is passed to the DOMMatrix constructor.
var matrix = new DOMMatrix("translate(20px,20px), scale(2,3), rotate(45deg)"
The resulting matrix is equal to the following sequence of method calls:
var matrix = new DOMMatrix(); matrix.translateBy(20,20); matrix.scaleNonUniformBy(2,3); matrix.rotateBy(45);
Should unit-less values (like for SVG transform presentation attribute) be allowed too? "translate(20,20)"
Throws a DOMException with name SyntaxError
if the DOMString
parameter does not validate to a transform list [[!CSS3-TRANSFORMS]].
a
to f
. An array of 16 items sets the element values m11
to m44
.
Throws a DOMException with name SyntaxError
if the Float32array
parameter does not consist of 6 or 16 items.
a
to f
. An array of 16 items sets the element values m11
to m44
.
Throws a DOMException with name SyntaxError
if the Float64array
parameter does not consist of 6 or 16 items.
a
to f
. A sequence of 16 items sets the element values m11
to m44
.
Throws a DOMException with name SyntaxError
if the number sequence parameter does not consist of 6 or 16 items.
If a DOMMatrix just consists of 2D transformations the 6 values a
to f
can represent the transformation matrix. If the DOMMatrix object is immutable, a DOMException with name NoModificationAllowedError
must be thrown on setting the attributes.
The following attributes a
to f
are aliases to the two-dimensional elements of the 4x4 matrix.
Corresponds to the attribute m11 of the DOMMatrix interface.
Corresponds to the attribute m12 of the DOMMatrix interface.
Corresponds to the attribute m21 of the DOMMatrix interface.
Corresponds to the attribute m22 of the DOMMatrix interface.
Corresponds to the attribute m41 of the DOMMatrix interface.
Corresponds to the attribute m42 of the DOMMatrix interface.
The following attributes m11
to m44
represent the elements of the 4x4 matrix. The coordinates are in column-major order. If the DOMMatrix object is immutable, a DOMException with name NoModificationAllowedError
must be thrown on setting the attributes.
The value of the element in column 1, row 1 of the matrix.
The value of the element in column 1, row 2 of the matrix.
The value of the element in column 1, row 3 of the matrix.
The value of the element in column 1, row 4 of the matrix.
The value of the element in column 2, row 1 of the matrix.
The value of the element in column 2, row 2 of the matrix.
The value of the element in column 2, row 3 of the matrix.
The value of the element in column 2, row 4 of the matrix.
The value of the element in column 3, row 1 of the matrix.
The value of the element in column 3, row 2 of the matrix.
The value of the element in column 3, row 3 of the matrix.
The value of the element in column 3, row 4 of the matrix.
The value of the element in column 4, row 1 of the matrix.
The value of the element in column 4, row 2 of the matrix.
The value of the element in column 4, row 3 of the matrix.
The value of the element in column 4, row 4 of the matrix.
The following methods do not modify the current matrix and return new DOMMatrix object.
Post-multiplies a translation transformation on the current matrix and returns the resulting matrix. The current matrix is not modified.
The 3D translation matrix is described in CSS Transforms [[!CSS3-TRANSFORMS]].
Post-multiplies a uniform 2D scale transformation (m11 = m22 = scale
) on the current matrix with the given origin and returns the resulting matrix. The current matrix is not modified.
The 2D scale matrix is described in CSS Transforms with sx = sy = scale
. This does not include the origin translation. [[!CSS3-TRANSFORMS]].
Post-multiplies a uniform scale transformation (m11 = m22 = m33 = scale
) on the current matrix with the given origin and returns the resulting matrix. The current matrix is not modified.
The 3D scale matrix is described in CSS Transforms with sx = sy = sz = scale
. This does not include the origin translation. [[!CSS3-TRANSFORMS]].
Post-multiplies a non-uniform scale transformation on the current matrix with the given origin and returns the resulting matrix. The current matrix is not modified.
The 3D scale matrix is described in CSS Transforms with sx = scaleX
, sy = scaleY
and sz = scaleZ
. This does not include the origin translation. [[!CSS3-TRANSFORMS]].
Post-multiplies a rotation transformation on the current matrix with the given origin and returns the resulting matrix. The current matrix is not modified.
The 2D rotation matrix is described in CSS Transforms with alpha = angle
. This does not include the origin translation. [[!CSS3-TRANSFORMS]].
Post-multiplies a rotation transformation on the current matrix and returns the resulting matrix. The rotation angle is determined by the angle between the vector (1,0)^{T} and (x,y)^{T} in the clockwise direction. If x
and y
should both be zero, the angle is specified as zero. The current matrix is not modified.
The 2D rotation matrix is described in CSS Transforms where alpha
is the angle between the vector (1,0)^{T} and (x,y)^{T} in degrees [[!CSS3-TRANSFORMS]].
Post-multiplies a rotation transformation on the current matrix and returns the resulting matrix. The rotation of the transform is applied around the given vector. The current matrix is not modified.
The 3D rotation matrix is described in CSS Transforms with alpha = angle
[[!CSS3-TRANSFORMS]].
Post-multiplies a skewX transformation on the current matrix and returns the resulting matrix. The current matrix is not modified.
The 2D skewX matrix is described in CSS Transforms with alpha = sx
[[!CSS3-TRANSFORMS]].
Post-multiplies a skewX transformation on the current matrix and returns the resulting matrix.
The 2D skewY matrix is described in CSS Transforms with beta = sy
[[!CSS3-TRANSFORMS]].
DOMMatrix(-1, 0, 0, 1, 0, 0)
and returns the resulting matrix. The current matrix is not modified.
DOMMatrix(1, 0, 0, -1, 0, 0)
and returns the resulting matrix. The current matrix is not modified.
The following methods do modify the current matrix. If the DOMMatrix object is immutable, a DOMException with name NoModificationAllowedError
must be thrown on calling the operations below.
Post-multiplies a translation transformation on the current matrix.
The 3D translation matrix is described in CSS Transforms [[!CSS3-TRANSFORMS]].
Post-multiplies a uniform 2D scale transformation (m11 = m22 = scale
) on the current matrix with the given origin.
The 2D scale matrix is described in CSS Transforms with sx = sy = scale
. This does not include the origin translation. [[!CSS3-TRANSFORMS]].
Post-multiplies a uniform 2D scale transformation (m11 = m22 = m33 = scale
) on the current matrix with the given origin.
The 3D scale matrix is described in CSS Transforms with sx = sy = sz = scale
. This does not include the origin translation. [[!CSS3-TRANSFORMS]].
Post-multiplies a non-uniform scale transformation on the current matrix with the given origin.
The 3D scale matrix is described in CSS Transforms with sx = scaleX
, sy = scaleY
and sz = scaleZ
. This does not include the origin translation. [[!CSS3-TRANSFORMS]].
Post-multiplies a rotation transformation on the current matrix with the given origin.
The 2D rotation matrix is described in CSS Transforms with alpha = angle
. This does not include the origin translation. [[!CSS3-TRANSFORMS]].
Post-multiplies a rotation transformation on the current matrix. The rotation angle is determined by the angle between the vector (1,0)^{T} and (x,y)^{T} in the clockwise direction. If x
and y
should both be zero, the angle is specified as zero.
The 2D rotation matrix is described in CSS Transforms where alpha
is the angle between the vector (1,0)^{T} and (x,y)^{T} in degrees [[!CSS3-TRANSFORMS]].
Post-multiplies a rotation transformation on the current matrix. The rotation of the transform is applied around the given vector.
The 3D rotation matrix is described in CSS Transforms with alpha = angle
[[!CSS3-TRANSFORMS]].
Post-multiplies a skewX transformation on the current matrix.
The 2D skewX matrix is described in CSS Transforms with alpha = sx
[[!CSS3-TRANSFORMS]].
Post-multiplies a skewX transformation on the current matrix.
The 2D skewY matrix is described in CSS Transforms with beta = sy
[[!CSS3-TRANSFORMS]].
The following helper methods do not modify the DOMMatrix object.
true
if m13
, m14
, m23
, m24
, m31
, m32
, m34
, m43
are equal to zero and m33
, m44
are equal to one.
point
is not modified.
m11
to m44
of the current matrix in column-major order as Float32Array [[!TYPED-ARRAYS]].
m11
to m44
of the current matrix in column-major order as Float64Array [[!TYPED-ARRAYS]].
matrix
function if the current matrix is a 2D transform or a CSS Transforms matrix3d
else. The syntax is as specified in CSS Transforms [[!CSS3-TRANSFORMS]].
In this example a matrix is created and several methods with 2D transformations are called.
var matrix = new DOMMatrix(); matrix.scaleBy(2); matrix.translateBy(20,20);
The
matrix.toString()
returns the DOM string:"matrix(2,0,0,2,20,20)"
For 3D operations, the stringifier returns DOM string representing a 3D matrix.
var matrix = new DOMMatrix(); matrix.scale3dBy(2);
Calling
matrix.toString()
after the snippet above returns the DOM string:"matrix3d(2,0,0,0,0,2,0,0,0,0,2,0,0,0,0,1)"
Host languages might require an internal 3x2 matrix abstraction of a DOMMatrix. This transformation from a 4x4 matrix to a 3x2 by loosing information is described in section Mathematical Description of Transform Functions of CSS Transforms [[!CSS3-TRANSFORMS]].
Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.
All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [[!RFC2119]]
Examples in this specification are introduced with the words “for example”
or are set apart from the normative text with class="example"
,
like this:
This is an example of an informative example.
Informative notes begin with the word “Note” and are set apart from the
normative text with class="note"
, like this:
Note, this is an informative note.
Conformance to this specification is defined for three conformance classes:
A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.
A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)
An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.
So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported component values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.
To avoid clashes with future CSS features, the CSS2.1 specification reserves a prefixed syntax for proprietary and experimental extensions to CSS.
Prior to a specification reaching the Candidate Recommendation stage in the W3C process, all implementations of a CSS feature are considered experimental. The CSS Working Group recommends that implementations use a vendor-prefixed syntax for such features, including those in W3C Working Drafts. This avoids incompatibilities with future changes in the draft.
Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.
To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.
Further information on submitting testcases and implementation reports can be found from on the CSS Working Group's website at http://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.
Many thanks to Dean Jackson for his initial proposal to make this specification possible.