[go: up one dir, main page]

W3C

DOMMatrix interface

W3C First Public Working Draft 19 September 2013

This version:
http://www.w3.org/TR/2013/WD-matrix-20130919/
Latest published version:
http://www.w3.org/TR/matrix/
Latest editor's draft:
http://dev.w3.org/fxtf/matrix/
Editors:
Dirk Schulze, Adobe Systems Inc., dschulze@adobe.com
Rik Cabanier, Adobe Systems Inc., cabanier@adobe.com

Copyright © 2013 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.

Abstract

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

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

This document was published by the CSS Working Group (part of the Style Activity) and SVG Working Group (part of the Graphics Activity) as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-fx@w3.org (subscribe, archives). All feedback is welcome.

Publication as a First Public 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.

This document was produced by groups operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures (for the Working Group and the CSS Working Group) made in connection with the deliverables of the groups; those pages also include 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.

Table of Contents

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

2. The Point dictionary

A 2D points and 3D points are represented by the following WebIDL dictionary: 

dictionary Point {
    unrestricted double x = 0;
    unrestricted double y = 0;
    unrestricted double z = 0;
    unrestricted double w = 1;
};

2.1 Dictionary Point Members

w of type unrestricted double, defaulting to 1
The perspective of the point.

A multiplication of a point with a matrix requires 4 values. Implementations usually normalize the point by w. It should be considered to do this here as well.

x of type unrestricted double, defaulting to 0
The x coordinate of the point.
y of type unrestricted double, defaulting to 0
The y coordinate of the point.
z of type unrestricted double, defaulting to 0
The z coordinate of the point.

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

3.1 The constructors

A series of constructors to create a DOMMatrix object. 

[Constructor,
 Constructor (DOMString transformList),
 Constructor (DOMMatrix other),
 Constructor (Float32array array),
 Constructor (Float64array array),
 Constructor (sequence<unrestricted double> numberSequence)]
interface DOMMatrix {
};

3.1.1 Constructors

DOMMatrix
Creates an identity matrix.
No parameters.
DOMMatrix
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].

ParameterTypeNullableOptionalDescription
transformListDOMString✘✘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.
DOMMatrix
ParameterTypeNullableOptionalDescription
otherDOMMatrix✘✘All element values of the current matrix are set to the element values of the other matrix.
DOMMatrix

Throws a DOMException with name SyntaxError if the Float32array parameter does not consist of 6 or 16 items.

ParameterTypeNullableOptionalDescription
arrayFloat32array✘✘ 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.
DOMMatrix

Throws a DOMException with name SyntaxError if the Float64array parameter does not consist of 6 or 16 items.

ParameterTypeNullableOptionalDescription
arrayFloat64array✘✘ 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.
DOMMatrix

Throws a DOMException with name SyntaxError if the number sequence parameter does not consist of 6 or 16 items.

ParameterTypeNullableOptionalDescription
numberSequencesequence<unrestricted double>✘✘ 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.

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

partial interface DOMMatrix {
    // These attributes are simple aliases for certain elements of the 4x4 matrix
    attribute unrestricted double a;
    attribute unrestricted double b;
    attribute unrestricted double c;
    attribute unrestricted double d;
    attribute unrestricted double e;
    attribute unrestricted double f;
};

3.2.1 Attributes

a of type unrestricted double

Corresponds to the attribute m11 of the DOMMatrix interface.

b of type unrestricted double

Corresponds to the attribute m12 of the DOMMatrix interface.

c of type unrestricted double

Corresponds to the attribute m21 of the DOMMatrix interface.

d of type unrestricted double

Corresponds to the attribute m22 of the DOMMatrix interface.

e of type unrestricted double

Corresponds to the attribute m41 of the DOMMatrix interface.

f of type unrestricted double

Corresponds to the attribute m42 of the DOMMatrix interface.

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

partial interface DOMMatrix {
    attribute unrestricted double m11;
    attribute unrestricted double m12;
    attribute unrestricted double m13;
    attribute unrestricted double m14;
    attribute unrestricted double m21;
    attribute unrestricted double m22;
    attribute unrestricted double m23;
    attribute unrestricted double m24;
    attribute unrestricted double m31;
    attribute unrestricted double m32;
    attribute unrestricted double m33;
    attribute unrestricted double m34;
    attribute unrestricted double m41;
    attribute unrestricted double m42;
    attribute unrestricted double m43;
    attribute unrestricted double m44;
};

3.3.1 Attributes

m11 of type unrestricted double

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

m12 of type unrestricted double

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

m13 of type unrestricted double

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

m14 of type unrestricted double

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

m21 of type unrestricted double

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

m22 of type unrestricted double

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

m23 of type unrestricted double

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

m24 of type unrestricted double

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

m31 of type unrestricted double

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

m32 of type unrestricted double

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

m33 of type unrestricted double

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

m34 of type unrestricted double

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

m41 of type unrestricted double

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

m42 of type unrestricted double

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

m43 of type unrestricted double

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

m44 of type unrestricted double

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

3.4 Immutable transformation methods

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

partial interface DOMMatrix {
    // Immutable transform methods
    DOMMatrix translate (unrestricted double tx, unrestricted double ty, 
                         optional unrestricted double tz = 0);
    DOMMatrix scale (unrestricted double scale, optional unrestricted double originX = 0, 
                     optional unrestricted double originY = 0);
    DOMMatrix scale3d (unrestricted double scale, optional unrestricted double originX = 0, 
                       optional unrestricted double originY = 0, 
                       optional unrestricted double originZ = 0);
    DOMMatrix scaleNonUniform (unrestricted double scaleX, 
                               optional unrestricted double scaleY = 1, 
                               optional unrestricted double scaleZ = 1, 
                               optional unrestricted double originX = 0, 
                               optional unrestricted double originY = 0, 
                               optional unrestricted double originZ = 0);
    DOMMatrix rotate (unrestricted double angle, optional unrestricted double originX = 0, 
                      optional unrestricted double originY = 0);
    DOMMatrix rotateFromVector (unrestricted double x, unrestricted double y);
    DOMMatrix rotateAxisAngle (unrestricted double x, unrestricted double y, 
                               unrestricted double z, unrestricted double angle);
    DOMMatrix skewX (unrestricted double sx);
    DOMMatrix skewY (unrestricted double sy);
    DOMMatrix multiply (DOMMatrix other);
    DOMMatrix flipX ();
    DOMMatrix flipY ();
    DOMMatrix inverse ();
};

3.4.1 Methods

flipX
Post-multiplies the transformation DOMMatrix(-1, 0, 0, 1, 0, 0) and returns the resulting matrix. The current matrix is not modified.
No parameters.
Return type: DOMMatrix
flipY
Post-multiplies the transformation DOMMatrix(1, 0, 0, -1, 0, 0) and returns the resulting matrix. The current matrix is not modified.
No parameters.
Return type: DOMMatrix
inverse
Returns the inverted matrix of the current matrix. The current matrix is not modified.
No parameters.
Return type: DOMMatrix
multiply
Performs matrix multiplication. This matrix is post-multiplied by the other matrix, returning the resulting new matrix. The current matrix is not modified.
ParameterTypeNullableOptionalDescription
otherDOMMatrix✘✘Other matrix for multiplication
Return type: DOMMatrix
rotate

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

ParameterTypeNullableOptionalDescription
angleunrestricted double✘✘Rotation angle in degrees.
originXunrestricted double✘✔ (0)Transformation origin on the x-axis.
originYunrestricted double✘✔ (0)Transformation origin on the y-axis.
Return type: DOMMatrix
rotateAxisAngle

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

ParameterTypeNullableOptionalDescription
xunrestricted double✘✘The x coordinate of the vector (x,y,z).
yunrestricted double✘✘The y coordinate of the vector (x,y,z).
zunrestricted double✘✘The z coordinate of the vector (x,y,z).
angleunrestricted double✘✘Rotation angle in degrees.
Return type: DOMMatrix
rotateFromVector

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

ParameterTypeNullableOptionalDescription
xunrestricted double✘✘The x coordinate of the vector (x,y)T.
yunrestricted double✘✘The y coordinate of the vector (x,y)T.
Return type: DOMMatrix
scale

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

ParameterTypeNullableOptionalDescription
scaleunrestricted double✘✘Multiplier for a uniform scale transformation.
originXunrestricted double✘✔ (0)Transformation origin on the x-axis.
originYunrestricted double✘✔ (0)Transformation origin on the y-axis.
Return type: DOMMatrix
scale3d

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

ParameterTypeNullableOptionalDescription
scaleunrestricted double✘✘Multiplier for a uniform scale transformation.
originXunrestricted double✘✔ (0)Transformation origin on the x-axis.
originYunrestricted double✘✔ (0)Transformation origin on the y-axis.
originZunrestricted double✘✔ (0)Transformation origin on the z-axis.
Return type: DOMMatrix
scaleNonUniform

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

ParameterTypeNullableOptionalDescription
scaleXunrestricted double✘✘Multiplier for a non-uniform scale along the x-axis.
scaleYunrestricted double✘✔ (1)Multiplier for a non-uniform scale along the y-axis.
scaleZunrestricted double✘✔ (1)Multiplier for a non-uniform scale along the z-axis.
originXunrestricted double✘✔ (0)Transformation origin on the x-axis.
originYunrestricted double✘✔ (0)Transformation origin on the y-axis.
originZunrestricted double✘✔ (0)Transformation origin on the z-axis.
Return type: DOMMatrix
skewX

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

ParameterTypeNullableOptionalDescription
sxunrestricted double✘✘Skew angle along the x-axis in degrees.
Return type: DOMMatrix
skewY

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

ParameterTypeNullableOptionalDescription
syunrestricted double✘✘Skew angle along the y-axis in degrees.
Return type: DOMMatrix
translate

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

ParameterTypeNullableOptionalDescription
txunrestricted double✘✘Translation value along the x-axis.
tyunrestricted double✘✘Translation value along the y-axis.
tzunrestricted double✘✔ (0)Optional translation value along the z-axis.
Return type: DOMMatrix

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

partial interface DOMMatrix {
    // Mutable transform methods
    void multiplyBy (DOMMatrix other);
    void preMultiplyBy (DOMMatrix other);
    void translateBy (unrestricted double tx, unrestricted double ty, 
                      optional unrestricted double tz = 0);
    void scaleBy (unrestricted double scale, optional unrestricted double originX = 0, 
                  optional unrestricted double originY = 0);
    void scale3dBy (unrestricted double scale, optional unrestricted double originX = 0, 
                    optional unrestricted double originY = 0, 
                    optional unrestricted double originZ = 0);
    void scaleNonUniformBy (unrestricted double scaleX, 
                            optional unrestricted double scaleY = 1, 
                            optional unrestricted double scaleZ = 1, 
                            optional unrestricted double originX = 0, 
                            optional unrestricted double originY = 0, 
                            optional unrestricted double originZ = 0);
    void rotateBy (unrestricted double angle, optional unrestricted double originX = 0, 
                   optional unrestricted double originY = 0);
    void rotateFromVectorBy (unrestricted double x, unrestricted double y);
    void rotateAxisAngleBy (unrestricted double x, unrestricted double y, unrestricted double z, 
                            unrestricted double angle);
    void skewXBy (unrestricted double sx);
    void skewYBy (unrestricted double sy);
    void invert ();
};

3.5.1 Methods

invert
Inverts the current matrix.
No parameters.
Return type: void
multiplyBy
The other matrix gets post-multiplied to the current matrix.
ParameterTypeNullableOptionalDescription
otherDOMMatrix✘✘The matrix that gets post-multiplied.
Return type: void
preMultiplyBy
The other matrix gets pre-multiplied to the current matrix.
ParameterTypeNullableOptionalDescription
otherDOMMatrix✘✘The matrix that gets pre-multiplied.
Return type: void
rotateAxisAngleBy

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

ParameterTypeNullableOptionalDescription
xunrestricted double✘✘The x coordinate of the vector (x,y,z).
yunrestricted double✘✘The y coordinate of the vector (x,y,z).
zunrestricted double✘✘The z coordinate of the vector (x,y,z).
angleunrestricted double✘✘Rotation angle in degrees.
Return type: void
rotateBy

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

ParameterTypeNullableOptionalDescription
angleunrestricted double✘✘Rotation angle in degrees.
originXunrestricted double✘✔ (0)Transformation origin on the x-axis.
originYunrestricted double✘✔ (0)Transformation origin on the y-axis.
Return type: void
rotateFromVectorBy

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

ParameterTypeNullableOptionalDescription
xunrestricted double✘✘The x coordinate of the vector (x,y)T.
yunrestricted double✘✘The y coordinate of the vector (x,y)T.
Return type: void
scale3dBy

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

ParameterTypeNullableOptionalDescription
scaleunrestricted double✘✘Multiplier for a uniform scale transformation.
originXunrestricted double✘✔ (0)Transformation origin on the x-axis.
originYunrestricted double✘✔ (0)Transformation origin on the y-axis.
originZunrestricted double✘✔ (0)Transformation origin on the z-axis.
Return type: void
scaleBy

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

ParameterTypeNullableOptionalDescription
scaleunrestricted double✘✘Multiplier for a uniform scale transformation.
originXunrestricted double✘✔ (0)Transformation origin on the x-axis.
originYunrestricted double✘✔ (0)Transformation origin on the y-axis.
Return type: void
scaleNonUniformBy

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

ParameterTypeNullableOptionalDescription
scaleXunrestricted double✘✘Multiplier for a non-uniform scale along the x-axis.
scaleYunrestricted double✘✔ (1)Multiplier for a non-uniform scale along the y-axis.
scaleZunrestricted double✘✔ (1)Multiplier for a non-uniform scale along the z-axis.
originXunrestricted double✘✔ (0)Transformation origin on the x-axis.
originYunrestricted double✘✔ (0)Transformation origin on the y-axis.
originZunrestricted double✘✔ (0)Transformation origin on the z-axis.
Return type: void
skewXBy

Post-multiplies a skewX transformation on the current matrix.

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

ParameterTypeNullableOptionalDescription
sxunrestricted double✘✘Skew angle along the x-axis in degrees.
Return type: void
skewYBy

Post-multiplies a skewX transformation on the current matrix.

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

ParameterTypeNullableOptionalDescription
syunrestricted double✘✘Skew angle along the y-axis in degrees.
Return type: void
translateBy

Post-multiplies a translation transformation on the current matrix.

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

ParameterTypeNullableOptionalDescription
txunrestricted double✘✘Translation value along the x-axis.
tyunrestricted double✘✘Translation value along the y-axis.
tzunrestricted double✘✔ (0)Optional translation value along the z-axis.
Return type: void

3.6 Helper methods

The following helper methods do not modify the DOMMatrix object. 

partial interface DOMMatrix {
    // Helper methods
    boolean             is2D ();
    unrestricted double determinant ();
    Point               transformPoint (Point point);
    Float32Array        toFloat32Array ();
    Float64Array        toFloat64Array ();
    void                stringifier ();
};

3.6.1 Methods

determinant
Returns the determinant of the current matrix.
No parameters.
Return type: unrestricted double
is2D
Returns true if m13, m14, m23, m24, m31, m32, m34, m43 are equal to zero and m33, m44 are equal to one.
No parameters.
Return type: boolean
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].

Should be stringifier;. Bug in old respec tool.

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)"
No parameters.
Return type: void
toFloat32Array
Returns the serialized 16 elements m11 to m44 of the current matrix in column-major order as Float32Array [TYPED-ARRAYS].
No parameters.
Return type: Float32Array
toFloat64Array
Returns the serialized 16 elements m11 to m44 of the current matrix in column-major order as Float64Array [TYPED-ARRAYS].
No parameters.
Return type: Float64Array
transformPoint
The point is post-multiplied on the current matrix and returns the resulting point. point is not modified.
ParameterTypeNullableOptionalDescription
pointPoint✘✘A Point dictionary.
Return type: Point

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

A. Interface summary

dictionary Point {
    unrestricted double w = 1;
    unrestricted double x = 0;
    unrestricted double y = 0;
    unrestricted double z = 0;
};

[Constructor,
 Constructor (DOMString transformList),
 Constructor (DOMMatrix other),
 Constructor (Float32array array),
 Constructor (Float64array array),
 Constructor (sequence<unrestricted double> numberSequence)]
interface DOMMatrix {

    // These attributes are simple aliases for certain elements of the 4x4 matrix
    attribute unrestricted double a;
    attribute unrestricted double b;
    attribute unrestricted double c;
    attribute unrestricted double d;
    attribute unrestricted double e;
    attribute unrestricted double f;
    attribute unrestricted double m11;
    attribute unrestricted double m12;
    attribute unrestricted double m13;
    attribute unrestricted double m14;
    attribute unrestricted double m21;
    attribute unrestricted double m22;
    attribute unrestricted double m23;
    attribute unrestricted double m24;
    attribute unrestricted double m31;
    attribute unrestricted double m32;
    attribute unrestricted double m33;
    attribute unrestricted double m34;
    attribute unrestricted double m41;
    attribute unrestricted double m42;
    attribute unrestricted double m43;
    attribute unrestricted double m44;

    // Immutable transform methods
    DOMMatrix           translate (unrestricted double tx, unrestricted double ty, 
                                   optional unrestricted double tz = 0);
    DOMMatrix           scale (unrestricted double scale, 
                               optional unrestricted double originX = 0, 
                               optional unrestricted double originY = 0);
    DOMMatrix           scale3d (unrestricted double scale, 
                                 optional unrestricted double originX = 0, 
                                 optional unrestricted double originY = 0, 
                                 optional unrestricted double originZ = 0);
    DOMMatrix           scaleNonUniform (unrestricted double scaleX, 
                                         optional unrestricted double scaleY = 1, 
                                         optional unrestricted double scaleZ = 1, 
                                         optional unrestricted double originX = 0, 
                                         optional unrestricted double originY = 0, 
                                         optional unrestricted double originZ = 0);
    DOMMatrix           rotate (unrestricted double angle, 
                                optional unrestricted double originX = 0, 
                                optional unrestricted double originY = 0);
    DOMMatrix           rotateFromVector (unrestricted double x, unrestricted double y);
    DOMMatrix           rotateAxisAngle (unrestricted double x, unrestricted double y, 
                                         unrestricted double z, unrestricted double angle);
    DOMMatrix           skewX (unrestricted double sx);
    DOMMatrix           skewY (unrestricted double sy);
    DOMMatrix           multiply (DOMMatrix other);
    DOMMatrix           flipX ();
    DOMMatrix           flipY ();
    DOMMatrix           inverse ();

    // Mutable transform methods
    void                multiplyBy (DOMMatrix other);
    void                preMultiplyBy (DOMMatrix other);
    void                translateBy (unrestricted double tx, unrestricted double ty, 
                                     optional unrestricted double tz = 0);
    void                scaleBy (unrestricted double scale, 
                                 optional unrestricted double originX = 0, 
                                 optional unrestricted double originY = 0);
    void                scale3dBy (unrestricted double scale, 
                                   optional unrestricted double originX = 0, 
                                   optional unrestricted double originY = 0, 
                                   optional unrestricted double originZ = 0);
    void                scaleNonUniformBy (unrestricted double scaleX, 
                                           optional unrestricted double scaleY = 1, 
                                           optional unrestricted double scaleZ = 1, 
                                           optional unrestricted double originX = 0, 
                                           optional unrestricted double originY = 0, 
                                           optional unrestricted double originZ = 0);
    void                rotateBy (unrestricted double angle, 
                                  optional unrestricted double originX = 0, 
                                  optional unrestricted double originY = 0);
    void                rotateFromVectorBy (unrestricted double x, unrestricted double y);
    void                rotateAxisAngleBy (unrestricted double x, unrestricted double y, 
                                           unrestricted double z, unrestricted double angle);
    void                skewXBy (unrestricted double sx);
    void                skewYBy (unrestricted double sy);
    void                invert ();

    // Helper methods
    boolean             is2D ();
    unrestricted double determinant ();
    Point               transformPoint (Point point);
    Float32Array        toFloat32Array ();
    Float64Array        toFloat64Array ();
    void                stringifier ();
};

B. Conformance

B.1 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.

B.2 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.

B.3 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.

B.4 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.

B.5 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.

C. Acknowledgments

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

D. References

D.1 Normative references

[CSS3-TRANSFORMS]
Simon Fraser; Dean Jackson; David Hyatt; Chris Marrin; Edward O'Connor; Dirk Schulze; Aryeh Gregor. CSS Transforms. URL: http://www.w3.org/TR/css3-transforms/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[TYPED-ARRAYS]
David Herman, Kenneth Russell. Typed Arrays Khronos Working Draft. (Work in progress.) URL: https://www.khronos.org/registry/typedarray/specs/latest/

D.2 Informative references

[CANVAS-2D]
Rik Cabanier; Eliot Graff; Jay Munro; Tom Wiltzius; Ian Hickson. HTML Canvas 2D Context. 17 December 2012. W3C Candidate Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2dcontext/
[SVG11]
Erik Dahlström; et al. Scalable Vector Graphics (SVG) 1.1 (Second Edition). 16 August 2011. W3C Recommendation. URL: http://www.w3.org/TR/2011/REC-SVG11-20110816/