Abstract

This specification provides basic geometric interfaces.
CSS is a language for describing the rendering of structured documents
(such as HTML and XML)
on screen, on paper, in speech, etc.

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

The (archived) public
mailing list public-fx@w3.org (see
instructions) is preferred
for discussion of this specification. When sending e-mail, please put the
text “compositing-1” in the subject, preferably like this:
“[geometry-1] …summary of comment…”

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.

1 Introduction

This specification describes several geometry interfaces [WEBIDL] for the representation of points, quads, rectangles and transformation matrices with the dimension of 3x2 and 4x4.

The SVG interfaces SVGPoint, SVGRect and SVGMatrix [SVG11] are aliasing the here defined interfaces in favor for common interfaces used by SVG, Canvas 2D Context [2DCONTEXT] and CSS Transforms [CSS3-TRANSFORMS].

2
The DOMPoint interfaces

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

When the rectangle has a non-negative width, the rectangle`s horizontal origin is the left edge; otherwise, it is the right edge. Similarly, when the rectangle has a non-negative height, the rectangle`s vertical origin is the top edge; otherwise, it is the bottom edge.

x coordinate

The horizontal distance between the viewport`s left edge and the rectangle`s origin.

y coordinate

The vertical distance between the viewport`s top edge and the rectangle`s origin.

4
The DOMRectList Interface

The length attribute must return the total number of DOMRect objects associated with the object.

The item(index) method, when invoked, must throw an IndexSizeError exception when index is greater than the number of DOMRect objects associated with the object. Otherwise, the DOMRect object at index must be returned.

5
The DOMQuad interface

Objects implementing the DOMQuad interface represents a quadrilateral. DOMQuad objects have an associated bounding rectangle set to a DOMRectReadOnly object when created.

6
The DOMMatrix interfaces

The DOMMatrix and DOMMatrixReadOnly interfaces represent a mathematical matrix with the purpose of describing transformations in a graphical context. The following sections describe the details of the interface.

If array32 has 6 elements set a, b, c, d, e, f to the element values of array32 in element order starting with the first element. Furthermore, set m31, m32, m13, m23, m43, m14, m24, m34 to 0 and m33, m44 to 1.

If array32 has 16 elements set m11 to m44 to the element values of array32 in column-major order.

If array64 has 6 elements set a, b, c, d, e, f to the element values of array64 in element order starting with the first element. Furthermore, set m31, m32, m13, m23, m43, m14, m24, m34 to 0 and m33, m44 to 1.

If array64 has 16 elements set m11 to m44 to the element values of array64 in column-major order.

If invoked with a sequence<unrestricted double> argument numberSequence:

If numberSequence has 6 elements set a, b, c, d, e, f to the element values of numberSequence in element order starting with the first element. Furthermore, set m31, m32, m13, m23, m43, m14, m24, m34 to 0 and m33, m44 to 1.

If numberSequence has 16 elements set m11 to m44 to the element values of numberSequence in column-major order.

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

scale3d(scale, originX, originY, originZ)

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

scaleNonUniform(scaleX, scaleY, scaleZ, originX, originY, originZ)

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

rotate(angle, originX, originY)

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

rotateFromVector(x, y)

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

rotateAxisAngle(x, y, z, angle)

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.

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

scale3dBy(scale, originX, originY, originZ)

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

scaleNonUniformBy(scaleX, scaleY, scaleZ, originX, originY, originZ)

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

rotateBy(angle, originX, originY)

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

rotateFromVectorBy(x, y)

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

rotateAxisAngleBy(x, y, z, angle)

Post-multiplies a rotation transformation on the current matrix. The rotation of the transform is applied around the given vector.

Acknowledgments

The editors would like to thank
Robert O’Callahan
for contributing to this specification.

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:

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.