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

Terminology

post-multiply
Term A post-multiplied by term B is equal to A · B.
pre-multiply
Term A pre-multiplied by term B is equal to B · A.
multiply
Multiply term A by term B is equal to A · B.

The DOMPointLiteral dictionary

The following definition might move to CSSOM View

A 2D point or a 3D point can be represented by the following WebIDL dictionary:

unrestricted double x = 0
The x coordinate of the point literal.
unrestricted double y = 0
The y coordinate of the point literal.
unrestricted double z = 0
The z coordinate of the point literal.
unrestricted double w = 1
The perspective of the point literal.

The DOMPoint interface

A 2D point or a 3D point can be represented by the following WebIDL interface:

Constructor()
Creates a DOMPoint. The attribute values for x, y, z default to 0 and for w defaults to 1.
Constructor()
DOMPointLiteral point
A DOMPointLiteral is a dictionary. The attribute values x, y, z and w are initialized to the corresponding dictionary values of point.
Constructor()
unrestricted double x
Sets the x coordinate of the point.
unrestricted double y
Sets the y coordinate of the point.
optional unrestricted double z = 0
Sets the z coordinate of the point.
optional unrestricted double w = 1
Sets the perspective of the point.
attribute unrestricted double x

The x coordinate of the point.

attribute unrestricted double y

The y coordinate of the point.

attribute unrestricted double z

The z coordinate of the point.

attribute unrestricted double w

The perspective of the point.

The DOMMatrix interface

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.

4x4 matrix with items m11 to m44

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.

The constructors

A series of constructors to create a DOMMatrix object.

Constructor()
Creates an identity matrix.
Constructor()
DOMString transformList
A DOMString of transformation functions with the syntax and specifies defined in CSS Transforms [[!CSS3-TRANSFORMS]]. One CSS pixel length maps to one unit less value in the matrix.
The DOMString must consist of a transform function list as specified by CSS Transforms.
              

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

Constructor()
DOMMatrix other
All element values of the current matrix are set to the element values of the other matrix.
Constructor()
Float32array array
Create an identity matrix first. An Float32array [[!TYPED-ARRAYS]] of 6 items sets the element values 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.

Constructor()
Float64array array
Create an identity matrix first. An Float64array [[!TYPED-ARRAYS]] of 6 items sets the element values 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.

Constructor()
sequence<unrestricted double> numberSequence
Create an identity matrix first. A sequence of 6 items sets the element values 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.

Two-dimensional attributes

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.

// These attributes are simple aliases for certain elements of the 4x4 matrix
attribute unrestricted double a

Corresponds to the attribute m11 of the DOMMatrix interface.

attribute unrestricted double b

Corresponds to the attribute m12 of the DOMMatrix interface.

attribute unrestricted double c

Corresponds to the attribute m21 of the DOMMatrix interface.

attribute unrestricted double d

Corresponds to the attribute m22 of the DOMMatrix interface.

attribute unrestricted double e

Corresponds to the attribute m41 of the DOMMatrix interface.

attribute unrestricted double f

Corresponds to the attribute m42 of the DOMMatrix interface.

Three-dimensional attributes

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.

attribute unrestricted double m11

The value of the element in column 1, row 1 of the matrix.

attribute unrestricted double m12

The value of the element in column 1, row 2 of the matrix.

attribute unrestricted double m13

The value of the element in column 1, row 3 of the matrix.

attribute unrestricted double m14

The value of the element in column 1, row 4 of the matrix.

attribute unrestricted double m21

The value of the element in column 2, row 1 of the matrix.

attribute unrestricted double m22

The value of the element in column 2, row 2 of the matrix.

attribute unrestricted double m23

The value of the element in column 2, row 3 of the matrix.

attribute unrestricted double m24

The value of the element in column 2, row 4 of the matrix.

attribute unrestricted double m31

The value of the element in column 3, row 1 of the matrix.

attribute unrestricted double m32

The value of the element in column 3, row 2 of the matrix.

attribute unrestricted double m33

The value of the element in column 3, row 3 of the matrix.

attribute unrestricted double m34

The value of the element in column 3, row 4 of the matrix.

attribute unrestricted double m41

The value of the element in column 4, row 1 of the matrix.

attribute unrestricted double m42

The value of the element in column 4, row 2 of the matrix.

attribute unrestricted double m43

The value of the element in column 4, row 3 of the matrix.

attribute unrestricted double m44

The value of the element in column 4, row 4 of the matrix.

Immutable transformation methods

The following methods do not modify the current matrix and return new DOMMatrix object.

// Immutable transform methods
DOMMatrix translate()
unrestricted double tx
Translation value along the x-axis.
unrestricted double ty
Translation value along the y-axis.
optional unrestricted double tz = 0
Optional translation value along the z-axis.

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

DOMMatrix scale()
unrestricted double scale
Multiplier for a uniform scale transformation.
optional unrestricted double originX = 0
Transformation origin on the x-axis.
optional unrestricted double originY = 0
Transformation origin on the y-axis.

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

DOMMatrix scale3d()
unrestricted double scale
Multiplier for a uniform scale transformation.
optional unrestricted double originX = 0
Transformation origin on the x-axis.
optional unrestricted double originY = 0
Transformation origin on the y-axis.
optional unrestricted double originZ = 0
Transformation origin on the z-axis.

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

DOMMatrix scaleNonUniform()
unrestricted double scaleX
Multiplier for a non-uniform scale along the x-axis.
optional unrestricted double scaleY = 1
Multiplier for a non-uniform scale along the y-axis.
optional unrestricted double scaleZ = 1
Multiplier for a non-uniform scale along the z-axis.
optional unrestricted double originX = 0
Transformation origin on the x-axis.
optional unrestricted double originY = 0
Transformation origin on the y-axis.
optional unrestricted double originZ = 0
Transformation origin on the z-axis.

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

DOMMatrix rotate()
unrestricted double angle
Rotation angle in degrees.
optional unrestricted double originX = 0
Transformation origin on the x-axis.
optional unrestricted double originY = 0
Transformation origin on the y-axis.

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

DOMMatrix rotateFromVector(unrestricted double x, unrestricted double y)
unrestricted double x
The x coordinate of the vector (x,y)T.
unrestricted double y
The y coordinate of the vector (x,y)T.

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

DOMMatrix rotateAxisAngle(unrestricted double x, unrestricted double y, unrestricted double z, unrestricted double angle)
unrestricted double x
The x coordinate of the vector (x,y,z).
unrestricted double y
The y coordinate of the vector (x,y,z).
unrestricted double z
The z coordinate of the vector (x,y,z).
unrestricted double angle
Rotation angle in degrees.

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

DOMMatrix skewX()
unrestricted double sx
Skew angle along the x-axis in degrees.

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

DOMMatrix skewY()
unrestricted double sy
Skew angle along the y-axis in degrees.

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 multiply()
DOMMatrix other
Other matrix for multiplication
Performs matrix multiplication. This matrix is post-multiplied by the other matrix, returning the resulting new matrix. The current matrix is not modified.
DOMMatrix flipX()
Post-multiplies the transformation DOMMatrix(-1, 0, 0, 1, 0, 0) and returns the resulting matrix. The current matrix is not modified.
DOMMatrix flipY()
Post-multiplies the transformation DOMMatrix(1, 0, 0, -1, 0, 0) and returns the resulting matrix. The current matrix is not modified.
DOMMatrix inverse()
Returns the inverted matrix of the current matrix. The current matrix is not modified.

Mutable transformation methods

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.

// Mutable transform methods
void multiplyBy()
DOMMatrix other
The matrix that gets post-multiplied.
The other matrix gets post-multiplied to the current matrix.
void preMultiplyBy()
DOMMatrix other
The matrix that gets pre-multiplied.
The other matrix gets pre-multiplied to the current matrix.
void translateBy()
unrestricted double tx
Translation value along the x-axis.
unrestricted double ty
Translation value along the y-axis.
optional unrestricted double tz = 0
Optional translation value along the z-axis.

Post-multiplies a translation transformation on the current matrix.

The 3D translation matrix is described in CSS Transforms [[!CSS3-TRANSFORMS]].

void scaleBy()
unrestricted double scale
Multiplier for a uniform scale transformation.
optional unrestricted double originX = 0
Transformation origin on the x-axis.
optional unrestricted double originY = 0
Transformation origin on the y-axis.

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

void scale3dBy()
unrestricted double scale
Multiplier for a uniform scale transformation.
optional unrestricted double originX = 0
Transformation origin on the x-axis.
optional unrestricted double originY = 0
Transformation origin on the y-axis.
optional unrestricted double originZ = 0
Transformation origin on the z-axis.

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

void scaleNonUniformBy()
unrestricted double scaleX
Multiplier for a non-uniform scale along the x-axis.
optional unrestricted double scaleY = 1
Multiplier for a non-uniform scale along the y-axis.
optional unrestricted double scaleZ = 1
Multiplier for a non-uniform scale along the z-axis.
optional unrestricted double originX = 0
Transformation origin on the x-axis.
optional unrestricted double originY = 0
Transformation origin on the y-axis.
optional unrestricted double originZ = 0
Transformation origin on the z-axis.

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

void rotateBy()
unrestricted double angle
Rotation angle in degrees.
optional unrestricted double originX = 0
Transformation origin on the x-axis.
optional unrestricted double originY = 0
Transformation origin on the y-axis.

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

void rotateFromVectorBy(unrestricted double x, unrestricted double y)
unrestricted double x
The x coordinate of the vector (x,y)T.
unrestricted double y
The y coordinate of the vector (x,y)T.

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

void rotateAxisAngleBy(unrestricted double x, unrestricted double y, unrestricted double z, unrestricted double angle)
unrestricted double x
The x coordinate of the vector (x,y,z).
unrestricted double y
The y coordinate of the vector (x,y,z).
unrestricted double z
The z coordinate of the vector (x,y,z).
unrestricted double angle
Rotation angle in degrees.

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

void skewXBy()
unrestricted double sx
Skew angle along the x-axis in degrees.

Post-multiplies a skewX transformation on the current matrix.

The 2D skewX matrix is described in CSS Transforms with alpha = sx [[!CSS3-TRANSFORMS]].

void skewYBy()
unrestricted double sy
Skew angle along the y-axis in degrees.

Post-multiplies a skewX transformation on the current matrix.

The 2D skewY matrix is described in CSS Transforms with beta = sy [[!CSS3-TRANSFORMS]].

void invert()
Inverts the current matrix.

Helper methods

The following helper methods do not modify the DOMMatrix object.

// Helper methods
boolean is2D()
Returns true if m13, m14, m23, m24, m31, m32, m34, m43 are equal to zero and m33, m44 are equal to one.
unrestricted double determinant()
Returns the determinant of the current matrix.
DOMPoint transformPoint()
DOMPoint point
A DOMPoint dictionary.
The point is post-multiplied on the current matrix and returns the resulting point. point is not modified.
Float32Array toFloat32Array()
Returns the serialized 16 elements m11 to m44 of the current matrix in column-major order as Float32Array [[!TYPED-ARRAYS]].
Float64Array toFloat64Array()
Returns the serialized 16 elements m11 to m44 of the current matrix in column-major order as Float64Array [[!TYPED-ARRAYS]].
DOMString stringifier ()
Returns a string in the form of a CSS Transforms 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)"

Transformation to a 3x2 matrix

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

Interface summary

Conformance

Document conventions

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 classes

Conformance to this specification is defined for three conformance classes:

style sheet
A CSS style sheet.
renderer
A UA that interprets the semantics of a style sheet and renders documents that use them.
authoring tool
A UA that writes a style sheet.

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.

Partial implementations

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.

Experimental implementations

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.

Non-experimental implementations

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.

Acknowledgments

Many thanks to Dean Jackson for his initial proposal to make this specification possible.