CSS Masking Module Level 1

W3C Last Call Working Draft, 29 October 2013

This version:
http://www.w3.org/TR/2013/WD-css-masking-1-20131029/
Latest version:
http://www.w3.org/TR/css-masking-1/
Editor’s Draft:
http://dev.w3.org/fxtf/masking/
Previous Versions:
http://www.w3.org/TR/2013/WD-css-masking-20130620/
http://www.w3.org/TR/2012/WD-css-masking-20121115/
Feedback:
public-fx@w3.org with subject line “[css-masking] … message topic …”(archives)
Test Suite:
http://test.csswg.org/suites/css-masking/nightly-unstable/
Editors:
(Adobe Systems Inc.)
(Mozilla Japan)
Tab Atkins Jr. (Google)

Abstract

CSS Masking provides two means for partially or fully hiding portions of visual elements: masking and clipping.

Masking describes how to use another graphical element or image as a luminance or alpha mask. Typically, rendering an element via CSS or SVG can conceptually described as if the element, including its children, are drawn into a buffer and then that buffer is composited into the element’s parent. Luminance and alpha masks influence the transparency of this buffer before the compositing stage.

Clipping describes the visible region of visual elements. The region can be described by using certain SVG graphics elements or basic shapes. Anything outside of this region is not rendered. 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/.

Publication as a Last Call 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 public-fx@w3.org (see instructions) is preferred for discussion of this specification. When sending e-mail, please put the text “css-masking” in the subject, preferably like this: “[css-masking] …summary of comment…

This document was produced by the CSS Working Group (part of the Style Activity) and the SVG Working Group (part of the Graphics Activity).

This document was produced by groups operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures (CSS) and a public list of any patent disclosures (SVG) made in connection with the deliverables of each group; these 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.

This specification is a Last Call Working Draft. All persons are encouraged to review this document and send comments to the public-fx mailing list as described above. The deadline for comments is 10 December 2013.

Table of Contents

1 Introduction

With CSS Masking it is possible to specify another graphics element, shape or image file to be used as clipping region or an luminance or alpha mask for compositing the current object into the background.

The effect of applying a mask is as if the mask images or mask sources are rendered into an off-screen image which has been initialized to transparent black. The graphical object to which the mask is applied will be painted onto the background through the mask, thus completely or partially masking out parts of the graphical object.

Masks are applied using the mask-image or mask-box-image-source properties.

The mask-image property may reference a <mask> as the mask source. Alternatively, for many simple uses, the mask-image property may refer directly to images to be used as mask, forgoing the need for an explicit <mask> element. The mask property serves as a shorthand property for mask-box-image, mask-image and other characterizing properties.

The mask-box-image-source property splits a mask image into 9 pieces. The pieces may be sliced, scaled and stretched in various ways to fit the size of the mask box image area. The mask-box-image property serves as a shorthand property for mask-box-image-source and other characterizing properties.

A clipping path defines an outline (in the absence of anti-aliasing) of a visual element where everything on the "inside" of the outline is allowed to show through but everything on the outside is masked out. A clipping path is specified by vector paths or shapes.

The clip-path property can reference SVG graphics element or use specified basic shapes as clipping path.

Example Mask

A luminance mask (middle) is applied on a shape filled with a gradient (left). This results in a masked shape (right).

2 Module interactions

This specification defines a set of CSS properties that affect the visual rendering of elements to which those properties are applied; these effects are applied after elements have been sized and positioned according to the Visual formatting model from [CSS21]. Some values of these properties result in the creation of a stacking context. Furthermore, this specification replaces the section Clipping: the clip property from [CSS21].

The compositing model follows the SVG compositing model [SVG11]: first any filter effect [FILTER-EFFECTS] is applied, then any clipping, masking and opacity [CSS3COLOR]. These effects all apply after any other CSS effects such as border [CSS3BG].

3 Values

This specification follows the CSS property definition conventions from [CSS21]. Basic shapes are defined in CSS Shapes Module Level 1 [CSS-SHAPES]. Value types not defined in these specifications are defined in CSS Values and Units Module Level 3 [CSS3VAL].

In addition to the property-specific values listed in their definitions, all properties defined in this specification also accept the inherit keyword as their property value. For readability it has not been repeated explicitly.

4 Terminology

When used in this specification, terms have the meanings assigned in this section.

bounding client rect

The union of all border boxes for the element that has an associated CSS layout box and is not in the http://www.w3.org/2000/svg namespace and its descendant elements. Or the object bounding box [SVG11], if the element does not have an associated CSS layout box and is in the http://www.w3.org/2000/svg namespace. (See getBoundingClientRect [CSSOM-VIEW].)

local coordinate system
user coordinate system

In general, a coordinate system defines locations and distances on the current canvas. The current local coordinate system (also user coordinate system) is the coordinate system that is currently active and which is used to define how coordinates and lengths are located and computed, respectively, on the current canvas [CSS3-TRANSFORMS].

For elements that have an associated CSS layout box, the current user coordinate system has its origin at the top-left corner of the bounding client rect and one unit equals one CSS pixel. The viewport for resolving percentage values is defined by the width and height of the bounding client rect.

If the element does not have an associated CSS layout box and is in the http://www.w3.org/2000/svg namespace, the current local coordinate system has its origin at the top-left corner of the element’s nearest viewport.

object bounding box units
The bounding client rect defines the coordinate system in which to resolve values, as defined in object bounding box units [SVG11].
mask source
An off-screen image which has been initialized to transparent black. The graphical object to which the mask is applied will be painted onto the background through the mask, thus completely or partially masking out parts of the graphical object.
clipping path
A combination of SVG graphics element or basic shapes which serve as the outline of a visual element where everything on the "inside" of the outline is allowed to show through but everything on the outside is masked out. (See clip-path.)

Definitions of CSS properties and values in this specification are analogous to definitions in CSS Backgrounds and Borders [CSS3BG]. To avoid redundancy, this specification relies on descriptions and definitions of CSS Backgrounds and Borders. The following terms in CSS Backgrounds and Borders have the following meaning in this specification:

Term in CSS Masking Term in [CSS3BG]
mask images background images
mask painting area background painting area
mask-size background-size
mask-position background-position
mask positioning area background positioning area
mask box image area border image area

5 Layered Masks

5.1 The mask-image property

Name:mask-image
Value:<mask-reference>
Initial:none
Applies to:All elements. In SVG, it applies to container elements without the <defs> element and all graphics elements
Inherited:no
Media:visual
Computed value:as specified, but with URIs made absolute
Percentages:n/a
Animatable:no

This property sets the mask image or the mask source of an element. Where:

<mask-reference> = none | <image> | <mask-source>
<mask-source> = <url>
<url>
A URL reference to a <mask> element (for example url(commonmasks.svg#mask)) or to a CSS image.
none
A value of none counts as an image layer but does not mask the element.

A computed value of other than none results in the creation of a stacking context [CSS21] the same way that CSS opacity [CSS3COLOR] does.

A mask reference that is an empty image (zero width or zero height), that fails to download, is not a reference to an <mask> element, is non-existent, or that cannot be displayed (e.g. because it is not in a supported image format) is ignored. It still counts as an image layer but does not mask the element.

See the section “Mask source values” for how to process a <mask-source>.

Examples for mask references:

body { mask-image: linear-gradient(black 0%, transparent 100%) }
p { mask-image: none }
div { mask-image: url(resources.svg#mask2) }

5.2 The mask-source-type property

Name:mask-source-type
Value:<source-type>`
Initial:auto
Applies to:All elements. In SVG, it applies to container elements without the <defs> element and all graphics elements
Inherited:no
Media:visual
Computed value:as specified
Percentages:n/a
Animatable:no

The mask-source-type property indicates whether the <mask-reference> is treated as luminance mask or alpha mask. (See Mask Source values.)

<source-type> = alpha | luminance | auto

Values have the following meanings:

alpha
A value of alpha indicates that the alpha values of the mask image should be used as the mask values. See Calculating mask values.

luminance
A value of luminance indicates that the luminance values of the mask image should be used as the mask values. See Calculating mask values.

auto

If the <mask-reference> of the mask-image property is of type <mask-source> the luminance values of the mask image should be used as the mask values.

If the <mask-reference> of the mask-image property is of type <image> the alpha values of the mask image should be used as the mask values.

In the following example, the mask-type property sets the mask type value for the <mask> element to alpha. The mask-image property has a reference to this <mask> element and the mask-source-type property has a value of luminance. The mask-source-type property will override the definition of mask-type to luminance.

<mask id="SVGMask" mask-type="alpha" maskContentUnits="objectBoundingBox">
  <radialGradient id="radialFill">
    <stop stop-color="white" offset="0"/>
    <stop stop-color="black" offset="1"/>
  </radialGradient>
  <circle fill="url(#radialFill)" cx="0.5" cy="0.5" r="0.5"/>
</mask>

<style>
  rect {
    mask-image: url(#SVGMask);
    mask-source-type: luminance;
  }
</style>

<rect width="200" height="200" fill="green"/>

5.3 The mask-repeat property

Name:mask-repeat
Value:<repeat-style>
Initial:no-repeat
Applies to:All elements. In SVG, it applies to container elements without the <defs> element and all graphics elements
Inherited:no
Media:visual
Computed value:A list, each item consisting of: two keywords, one per dimension
Percentages:n/a
Animatable:no

Specifies how mask images are tiled after they have been sized and positioned.

See background-repeat property [CSS3BG] for the definitions of the property values.

Example(s):

body {
background-color: blue;
mask-image: url(dot-mask.png) luminance;
mask-repeat: space;
}

Image of an element with a dotted mask.

The effect of space: the mask image of a dot is tiled to cover the whole mask painting area and the mask images are equally spaced.

5.4 The mask-position property

Name:mask-position
Value:<position>
Initial:center
Applies to:All elements. In SVG, it applies to container elements without the <defs> element and all graphics elements
Inherited:no
Media:visual
Computed value:A list, each item consisting of: two keywords representing the origin and two offsets from that origin, each given as an absolute length (if given a <length>), otherwise as a percentage.
Percentages:refer to size of mask painting area minus size of mask image; see text
Animatable:as repeatable list of simple list of length, percentage, or calc

See the background-position property [CSS3BG] for the definitions of the property values.

In the example below, the (single) image is placed in the lower-right corner of the viewport.

body {
mask-image: url("logo.png");
mask-position: 100% 100%;
mask-repeat: no-repeat;
}

Mask positions can also be relative to other corners than the top left. E.g., the following puts the background image 10px from the bottom and 3em from the right:

mask-position: right 3em bottom 10px

5.5 The mask-clip property

Name:mask-clip
Value:<box> | no-clip
Initial:border-box
Applies to:All elements. In SVG, it applies to container elements without the <defs> element and all graphics elements
Inherited:no
Media:visual
Computed value:as specified
Percentages:n/a
Animatable:no

Determines the mask painting area, which determines the area that is affected by the mask. The painted content of an element may be restricted to this area.

Values have the following meanings:

border-box
The painted content is rectricted to (clipped to) the border box respectively painting box for objects without associated layout box.
padding-box
The painted content is rectricted to (clipped to) the padding box.
content-box
The painted content is rectricted to (clipped to) the content box respectively object bounding box [SVG11] for objects without associated layout box.
no-clip
The painted content is not restricted (not clipped). The mask painting area is set to the bounding client rect.

Note: There is no corresponding box for padding-box on objects without associated layout box and content-box is choosen instead.

5.6 The mask-origin property

Name:mask-origin
Value:<box>
Initial:border-box
Applies to:All elements. In SVG, it applies to container elements without the <defs> element and all graphics elements
Inherited:no
Media:visual
Computed value:as specified
Percentages:n/a
Animatable:no

For elements rendered as a single box, specifies the mask positioning area. For elements rendered as multiple boxes (e.g., inline boxes on several lines, boxes on several pages) specifies which boxes box-decoration-break operates on to determine the mask positioning area.

padding-box
The position is relative to the padding box. (For single boxes 0 0 is the upper left corner of the padding edge, 100% 100% is the lower right corner.)
border-box
The position is relative to the border box respectively painting box for objects without associated layout box.
content-box
The position is relative to the content box respectively object bounding box [SVG11] for objects without associated layout box.

Note: There is no corresponding box for padding-box on objects without associated layout box and content-box is choosen instead.

Note: If mask-clip is padding-box, mask-origin is border-box, mask-position is top left (the initial value), and the element has a non-zero border, then the top and left of the mask image will be clipped.

5.7 The mask-size property

Name:mask-size
Value:<bg-size>
Initial:border-box
Applies to:All elements. In SVG, it applies to container elements without the <defs> element and all graphics elements
Inherited:no
Media:visual
Computed value:as specified, but with lengths made absolute
Percentages:n/a
Animatable:as repeatable list of simple list of length, percentage, or calc (This means keyword values are not animatable.

Specifies the size of the mask images.

See background-size property [CSS3BG] for the definitions of the property values.

5.8 The mask property

Name:mask
Value:<mask-layer>
Initial:border-box
Applies to:All elements. In SVG, it applies to container elements without the <defs> element and all graphics elements
Inherited:no
Media:visual
Computed value:see individual properties
Percentages:see individual properties
Animatable:see individual properties
<mask-layer> = <mask-reference> <source-type>? || <position> [ / <bg-size> ]? ||
    <repeat-style> || <box> || [ <box> | no-clip ]

If one <box> value is present then it sets both mask-origin and mask-clip to that value. If two <box> values are present, then the first sets mask-origin and the second mask-clip.

The properties mask-image, mask-repeat, mask-position, mask-clip, mask-origin and mask-size must have no effect if <mask-reference> references a <mask> element. In this case the element defines position, sizing and clipping of the mask source.

The mask shorthand also resets mask-box-image to its initial value. It is therefore recommended that authors use the mask shorthand, rather than other shorthands or the individual properties, to override any mask settings earlier in the cascade. This will ensure that mask-box-image has also been reset to allow the new styles to take effect.

Note: A future level of this specification will allow different mask layers for various additional masking operations like composited mask layers masking and serial layer masking.

5.9 The mask-type property

Name:mask-type
Value:luminance | alpha
Initial:luminance
Applies to:<mask> elements
Inherited:no
Media:visual
Computed value:as specified
Percentages:n/a
Animatable:no

The mask-type property defines whether the content of the <mask> element is treated as as luminance mask or alpha mask, as described in Calculating mask values.

Values have the following meanings:

luminance
Indicates that the luminance values of the mask should be used.
alpha
Indicates that the alpha values of the mask should be used.

The mask-type property allows the author of the <mask> element to specify the preferred masking operation. However, the author can override this preference by setting the mask-source-type value to something different than auto on the masked content.

In the following example the computed value of mask-type is luminance and the computed value of mask-source-type is auto. The UA must follow the preferred masking operation defined on the <mask> element.


<svg>
  <mask style="mask-type: luminance;" id="mask">
    ...
  </mask>
</svg>

<p style="mask-image: url(#mask); mask-source-type: auto;">
  This is the masked content.
</p>

In the next example the computed value of mask-source-type is alpha and overrides the preference on the <mask> element that is computed to luminance. The mask source is used as an alpha mask.


<svg>
  <mask style="mask-type: luminance;" id="mask2">
    ...
  </mask>
</svg>

<p style="mask-image: url(#mask2); mask-source-type: alpha;">
  This is the masked content.
</p>

The mask-type property is a presentation attribute for SVG elements.

5.10 The <mask> element

Name: mask
Categories: Container element
Content model: Any number of the following elements, in any order:
Attributes:
DOM Interfaces: SVGMaskElement

Attribute definitions:

maskUnits = "userSpaceOnUse | objectBoundingBox"
Defines the coordinate system for attributes x, y, width and height.
If maskUnits="userSpaceOnUse", x, y, width and height represent values in the current user coordinate system in place at the time when the <mask> element is referenced (i.e., the user coordinate system for the element referencing the <mask> element via the mask property).
If maskUnits="objectBoundingBox", x, y, width and height represent fractions or percentages of the bounding box of the element to which the mask is applied. (See object bounding box units.)
If attribute maskUnits is not specified, then the effect is as if a value of objectBoundingBox were specified.
Animatable: yes.
maskContentUnits = "userSpaceOnUse | objectBoundingBox"
Defines the coordinate system for the contents of the <mask>.
If maskContentUnits="userSpaceOnUse", the user coordinate system for the contents of the <mask> element is the current user coordinate system in place at the time when the <mask> element is referenced (i.e., the user coordinate system for the element referencing the <mask> element via the mask property).
If maskContentUnits="objectBoundingBox", the user coordinate system for the contents of the <mask> is established using the bounding box of the element to which the mask is applied. (See object bounding box units.)
If attribute ‘maskContentUnits‘ is not specified, then the effect is as if a value of userSpaceOnUse were specified.
Animatable: yes.
x = "<length> | <percentage>"
The x-axis coordinate of one corner of the rectangle for the largest possible offscreen buffer. If the attribute is not specified but at least one of the attributes y, width or height are specified, the effect is as if a value of '-10%' were specified.
Animatable: yes.
y = "<length> | <percentage>"
The y-axis coordinate of one corner of the rectangle for the largest possible offscreen buffer.
If the attribute is not specified but at least one of the attributes x, width or height are specified, the effect is as if a value of '-10%' were specified.
Animatable: yes.
width = "<length> | <percentage>"
The width of the largest possible offscreen buffer. A negative value or a value of zero disables rendering of the element.
If the attribute is not specified but at least one of the attributes x, y or height are specified, the effect is as if a value of '120%' were specified.
Animatable: yes.
height = "<length> | <percentage>"
The height of the largest possible offscreen buffer.
A negative value or a value of zero disables rendering of the element.
If the attribute is not specified but at least one of the attributes x, y or width are specified, the effect is as if a value of '120%' were specified.
Animatable: yes.

If at least one of the attributes x, y, width or height are specified, the given object and the rectangle defined by x, y, width and height establish a current clipping path. The rendered content of the mask must be clipped by this current clipping path.

CSS properties inherit into the <mask> element from its ancestors; properties do not inherit from the element referencing the <mask> element.

<mask> elements are never rendered directly; their only usage is as something that can be referenced using the mask property. The opacity, filter and display properties do not apply to the <mask> element; thus, <mask> elements are not directly rendered even if the display property is set to a value other than none, and <mask> elements are available for referencing even when the display property on the <mask> element or any of its ancestors is set to none.

5.11 The Mask Image Rendering Model

The application of the mask-image property to an element formatted with the CSS box model establishes a stacking context in the same way that CSS opacity [CSS3COLOR] does, and all the element’s descendants are rendered together as a group with the masking applied to the group as a whole.

The mask-image property has no effect on the geometry or hit-testing of any element’s CSS boxes.

5.11.1 Mask Source values

A mask may be interpreted using one of two different methods with regards to calculating the mask values that will be multiplied with the target alpha values.

The first and simplest method of calculating the mask values is to use the alpha channel of the mask source. In this case the mask value at a given point is simply the value of the alpha channel at that point. The color channels do not contribute to the mask value.

The second method of calculating the mask values is to use the luminance of the mask source. In this case the mask value at a given point is computed from the color channel values and alpha channel value using the following procedure.

  1. Compute a luminance value from the color channel values.
  2. Multiply the computed luminance value by the corresponding alpha value to produce the mask value.

Regardless of the method used, the procedure for calculating mask values assumes the content of the mask is a four-channel RGBA graphics object. For other types of graphics objects, special handling is required as follows.

For a three-channel RGB graphics object that is used in a mask (e.g., when referencing a three-channel image file), the effect is as if the object were converted into a four-channel RGBA image with the alpha channel uniformly set to 1.

For a single-channel image that is used in a mask (e.g., when referencing a single-channel grayscale image file), the effect is as if the object were converted into a four-channel RGBA image, where the single channel from the referenced object is used to compute the three color channels and the alpha channel is uniformly set to 1.

Note: When referencing a grayscale image file, the transfer curve relating the encoded grayscale values to linear light values must be taken into account when computing the color channels.

Note: SVG graphics elements (e.g., <circle> or <text>) are all treated as four-channel RGBA images for the purposes of masking operations.

The effect of a mask is identical to what would have happened if there were no mask but instead the alpha channel of the given object were multiplied with the mask’s resulting mask values.

6 Box-Image Masks

With mask-box-image a mask can be split into nine pieces: four corners, four edges and the middle piece as demonstrated in the figure below.

pieces of a mask box image

Pieces of a mask box image.

These pieces may be sliced, scaled and stretched in various ways to fit the size of the mask box image area. The usage of mask-box-image corresponds to the border-image property of CSS Background and Borders [CSS3BG].

The mask image in the following example is split into four corners with dimensions of 75 pixels, four edges and the middle piece that is stretched and scaled.

Example for 'mask-box-image'

Example for mask-box-image. The object on the left is the object to mask. The second image is the alpha mask and the last image the masked object.

div {
  background: linear-gradient(bottom, #F27BAA 0%, #FCC8AD 100%);
  mask-box-image-slice: 25 fill;
  mask-box-image-repeat: stretch;
  mask-box-image-source: url(mask.png);
}

6.1 The mask-box-image-source property

Name:mask-box-image-source
Value:none | <image>
Initial:none
Applies to:All elements. In SVG, it applies to container elements without the <defs> element and all graphics elements
Inherited:no
Media:visual
Computed value:none or the image with its URI made absolute
Percentages:n/a
Animatable:no

Specifies an image to be used as mask.

An image that is an empty image (zero width or zero height), that fails to download, is non-existent, or that cannot be displayed (e.g. because it is not in a supported image format) is ignored. It still counts as an mask image but does not mask the element.

A computed value of other than none results in the creation of a stacking context [CSS21] the same way that CSS opacity [CSS3COLOR] does.

6.2 The mask-box-image-slice property

Name:mask-box-image-slice
Value:[<number> | <percentage>]{1,4} fill?
Initial:0 fill
Applies to:All elements. In SVG, it applies to container elements without the <defs> element and all graphics elements
Inherited:no
Media:visual
Computed value:as specified
Percentages:refer to size of the mask image
Animatable:no

This property specifies inward offsets from the top, right, bottom, and left edges of the mask image, dividing it into nine regions: four corners, four edges and a middle. The middle image part is discarded (treated as fully transparent black) unless the fill keyword is present.

See the border-image-slice property [CSS3BG] for the definitions of the property values.

6.3 The mask-box-image-width property

Name:mask-box-image-width
Value:[ <length> | <percentage> | <number> | auto ]{1,4}
Initial:auto
Applies to:All elements. In SVG, it applies to container elements without the <defs> element and all graphics elements
Inherited:no
Media:visual
Computed value:all <length>s made absolute, otherwise as specified
Percentages:relative to width/height of the mask box image area
Animatable:no

The mask image is drawn inside an area called the mask box image area. This is an area whose boundaries by default correspond to the mask box, see mask-box-image-outset.

See the border-image-width property [CSS3BG] for the definitions of the property values.

Note: For SVG elements without an associated layout box the border-width is considered to be 0.

6.4 The mask-box-image-outset property

Name:mask-box-image-outset
Value:[ <length> | <number> ]{1,4}
Initial:0
Applies to:All elements. In SVG, it applies to container elements without the <defs> element and all graphics elements
Inherited:no
Media:visual
Computed value:all <length>s made absolute, otherwise as specified
Percentages:n/a
Animatable:no

The values specify the amount by which the mask box image area extends beyond the border box. If it has four values, they set the outsets on the top, right, bottom and left sides in that order. If the left is missing, it is the same as the right; if the bottom is missing, it is the same as the top; if the right is missing, it is the same as the top.

As with mask-box-image-width, a <number> represents a multiple of the corresponding border-width. Negative values are not allowed for any of the mask-box-image-outset values.

Note: For SVG elements without associated layout box the border-width is considered to be 0.

6.5 The mask-box-image-repeat property

Name:mask-box-image-repeat
Value:[ stretch | repeat | round | space ]{1,2}
Initial:stretch
Applies to:All elements. In SVG, it applies to container elements without the <defs> element and all graphics elements
Inherited:no
Media:visual
Computed value:as specified
Percentages:n/a
Animatable:no

This property specifies how the images for the sides and the middle part of the mask image are scaled and tiled. The first keyword applies to the horizontal sides, the second to the vertical ones. If the second keyword is absent, it is assumed to be the same as the first.

See the border-image-repeat property [CSS3BG] for the definitions of the property values.

The exact process for scaling and tiling the mask box image parts is given in the section Masking with the mask-box-image

6.6 The mask-box-image property

Name:mask-box-image
Value:<‘mask-box-image-source’> || <‘mask-box-image-slice’> [ / <‘mask-box-image-width’> | / <‘mask-box-image-width’>? / <‘mask-box-image-outset’> ]? || <‘mask-box-image-repeat’>
Initial:See individual properties
Applies to:See individual properties
Inherited:no
Media:visual
Computed value:See individual properties
Percentages:n/a
Animatable:See individual properties

This is a shorthand property for setting mask-box-image-source, mask-box-image-slice, mask-box-image-width, mask-box-image-outset and mask-box-image-repeat. Omitted values are set to their initial values.

6.7 Masking with the mask-box-image

After the mask-box-image given by mask-box-image-source is sliced by the mask-box-image-slice values, the resulting nine images are scaled, positioned, and tiled into their corresponding mask image regions in four steps as described in the section Drawing the Border Image [CSS3BG].

The application of the mask-box-image-source property to an element formatted with the CSS box model establishes a stacking context in the same way that CSS opacity [CSS3COLOR] does, and all the element’s descendants are rendered together as a group with the masking applied to the group as a whole.

The mask-box-image-source property has no effect on the geometry or hit-testing of any element’s CSS boxes.

7 Clipping paths

The clipping path restricts the region to which paint can be applied, the so-called clipping region. Conceptually, any parts of the drawing that lie outside of this region are not drawn. This includes any content, background, borders, text decoration, outline and visible scrolling mechanism of the element to which the clipping path is applied, and those of its descendants.

An element’s ancestors may also clip portions of their content (e.g., via their own clip or clip-path properties and/or if their overflow property is not visible). What is rendered is the cumulative intersection.

If the clipping region exceeds the bounds of the UA’s document window, content may be clipped to that window by the native operating environment.

7.1 The clip-path property

Name:clip-path
Value:<basic-shape> | <clip-source> | none
Initial:none
Applies to:All elements. In SVG, it applies to container elements without the <defs> element and all graphics elements
Inherited:no
Media:visual
Computed value:as specified, but with <url> values made absolute
Percentages:as specified
Animatable:See shape-outside [CSS-SHAPES]

Specifies a basic shape or references a <clipPath> element to create a clipping path.

<clip-source> = <url>
<basic-shape>
A basic shape function as defined in the CSS Shapes module. The origin of clipping shapes is on the top left of the bounding client rect. Percentage values are resolved against the bounding client rect width and height. (See [CSS-SHAPES].)
none
No clipping path gets created.

A computed value of other than none results in the creation of a stacking context [CSS21] the same way that CSS opacity [CSS3COLOR] does.

If the URI reference is not valid (e.g it points to an object that doesn’t exist or the object is not a <clipPath> element), no clipping is applied.

7.2 The clip-rule property

Name:clip-rule
Value:nonzero | evenodd
Initial:nonzero
Applies to:All elements. In SVG, it applies to container elements without the <defs> element and all graphics elements
Inherited:yes
Media:visual
Computed value:as specified
Percentages:n/a
Animatable:no
nonzero
See description of fill-rule property [SVG11].
evenodd
See description of fill-rule property [SVG11].

The clip-rule property only applies to graphics elements that are contained within a <clipPath> element.

The following fragment of code will cause an evenodd clipping rule to be applied to the clipping path because clip-rule is specified on the <path> element that defines the clipping shape:

<g clip-rule="nonzero">
  <clipPath id="MyClip">
    <path d="..." clip-rule="evenodd" />
  </clipPath>
  <rect clip-path="url(#MyClip)" ... />
</g>

whereas the following fragment of code will not cause an evenodd clipping rule to be applied because the clip-rule is specified on the referencing element, not on the object defining the clipping shape:

<g clip-rule="nonzero">
  <clipPath id="MyClip">
    <path d="..." />
  </clipPath>
  <rect clip-path="url(#MyClip)" clip-rule="evenodd" ... />
</g>

7.3 The clip property

Name:clip
Value:<shape> | auto
Initial:auto
Applies to:Absolutely positioned elements. In SVG, it applies to elements which establish a new viewport, <pattern> elements and <marker> elements.
Inherited:no
Media:visual
Computed value:as specified
Percentages:n/a
Animatable:as rectangle

Note: With this specification the clip property is deprecated. Authors are encouraged to use the clip-path property instead. UAs must support the clip property.

The clip property applies only to absolutely positioned elements. In SVG, it applies to elements which establish a new viewport, <pattern> elements and <marker> elements. Values have the following meanings:

auto
The element does not clip.
<shape>

In CSS 2.1, the only valid <shape> value is: rect(<top>, <right>, <bottom>, <left>) where <top> and <bottom> specify offsets from the top border edge of the box, and <right>, and <left> specify offsets from the left border edge of the box. Authors should separate offset values with commas. User agents must support separation with commas, but may also support separation without commas (but not a combination), because a previous revision of this specification was ambiguous in this respect.

<top>, <right>, <bottom>, and <left> may either have a <length> value or auto. Negative lengths are permitted. The value auto means that a given edge of the clipping region will be the same as the edge of the element’s generated border box (i.e., auto means the same as 0 for <top> and <left>, the same as the used value of the height plus the sum of vertical padding and border widths for <bottom>, and the same as the used value of the width plus the sum of the horizontal padding and border widths for <right>, such that four auto values result in the clipping region being the same as the element’s border box).

When coordinates are rounded to pixel coordinates, care should be taken that no pixels remain visible when <left> and <right> have the same value (or <top> and <bottom> have the same value), and conversely that no pixels within the element’s border box remain hidden when these values are auto.

Example: The following two rules:


p#one { clip: rect(5px, 40px, 45px, 5px); }
p#two { clip: rect(5px, 55px, 45px, 5px); }

and assuming both Ps are 50 by 55 pixel, will create, respectively, the rectangular clipping regions delimited by the dashed lines in the following illustrations:

Values for rect shape

This diagram illustrates two block boxes, one above the other, with rectangular clipping regions of different dimensions. (See long description.)

7.4 The <clipPath> element

Name: clipPath
Categories: None.
Content model: Any number of the following elements, in any order:
Attributes:
DOM Interfaces: SVGClipPathElement

Attribute definitions:

clipPathUnits = "userSpaceOnUse | objectBoundingBox"
Defines the coordinate system for the contents of the <clipPath>.
If clipPathUnits="userSpaceOnUse", the contents of the <clipPath> represent values in the current user coordinate system in place at the time when the <clipPath> element is referenced (i.e., the user coordinate system for the element referencing the <clipPath> element via the clip-path property).
If clipPathUnits="objectBoundingBox", then the user coordinate system for the contents of the <clipPath> element is established using the bounding box of the element to which the clipping path is applied (see object bounding box units).
If attribute ‘clipPathUnits‘ is not specified, then the effect is as if a value of userSpaceOnUse were specified.
Animatable: yes.

CSS properties inherit into the <clipPath> element from its ancestors; properties do not inherit from the element referencing the <clipPath> element.

<clipPath> elements are never rendered directly; their only usage is as something that can be referenced using the clip-path property. The display property does not apply to the <clipPath> element; thus, <clipPath> elements are not directly rendered even if the display property is set to a value other than none, and <clipPath> elements are available for referencing even when the ‘display‘ property on the <clipPath> element or any of its ancestors is set to none.

A <clipPath> element can contain <path> elements, <text> elements, basic shapes (such as <circle>) or a <use> element. If a <use> element is a child of a <clipPath> element, it must directly reference <path>, <text> or basic shapes elements. Indirect references are an error and the <clipPath> element must be ignored.

The raw geometry of each child element exclusive of rendering properties such as fill, stroke, stroke-width within a <clipPath> conceptually defines a 1-bit mask (with the possible exception of anti-aliasing along the edge of the geometry) which represents the silhouette of the graphics associated with that element. Anything outside the outline of the object is masked out. If a child element is made invisible by display or visibility it does not contribute to the clipping path. When the <clipPath> element contains multiple child elements, the silhouettes of the child elements are logically OR’d together to create a single silhouette which is then used to restrict the region onto which paint can be applied. Thus, a point is inside the clipping path if it is inside any of the children of the <clipPath>.

For a given graphics element, the actual clipping path used will be the intersection of the clipping path specified by its clip-path property (if any) with any clipping paths on its ancestors, as specified by the clip-path property on the elements which establish a new viewport. (See [SVG11])

A couple of additions:

7.5 Clipping paths, geometry, and pointer events

A clipping path is conceptually equivalent to a custom viewport for the referencing element. Thus, it affects the rendering of an element, but not the element’s inherent geometry. The bounding client rect of a clipped element (that is, an element which references a <clipPath> element via a clip-path property, or a child of the referencing element) must remain the same as if it were not clipped.

By default, pointer events must not be dispatched on the clipped (non-visible) regions of a shape. For example, a circle with a radius of 10 which is clipped to a circle with a radius of 5 will not receive click events outside the smaller radius. Later versions of this specification may define new properties to enable fine-grained control over the interactions between hit testing and clipping.

8 Security

It is important that the timing to the masking operations is independant of the source and destination pixel. Masking operations must be implemented in such a way that they always take the same amount of time regardless of the pixel values. If this rule is not followed, an attacker could infer information and mount a timing attack.

A timing attack is a method of obtaining information about content that is otherwise protected, based on studying the amount of time it takes for an operation to occur. If, for example, red pixels took longer to draw than green pixels, one might be able to reconstruct a rough image of the element being rendered, without ever having access to the content of the element. <mask-source>s and <clip-source>s have special requirements on fetching resources.

User agents must use the potentially CORS-enabled fetch method defined by the [HTML5] specification for all <mask-source>, <clip-source> and <image> values on the mask-image, mask-box-image-source and clip-path properties. When fetching, user agents must use "Anonymous" mode, set the referrer source to the stylesheet’s URL and set the origin to the URL of the containing document. If this results in network errors, the effect is as if the value none had been specified.

9 DOM interfaces

9.1 Interface SVGClipPathElement

The SVGClipPathElement interface corresponds to the <clipPath> element.

interface SVGClipPathElement : SVGElement {
  readonly attribute SVGAnimatedEnumeration clipPathUnits;
  readonly attribute SVGAnimatedTransformList transform;
};

SVGClipPathElement implements SVGUnitTypes;
Attributes:
clipPathUnits (readonly SVGAnimatedEnumeration)
Corresponds to attribute ‘clipPathUnits‘ on the given <clipPath> element. Takes one of the constants defined in SVGUnitTypes.
transform (readonly SVGAnimatedTransformList)
Corresponds to attribute ‘transform‘ on the given element.

9.2 Interface SVGMaskElement

The SVGMaskElement interface corresponds to the <mask> element.

interface SVGMaskElement : SVGElement {
  readonly attribute SVGAnimatedEnumeration maskUnits;
  readonly attribute SVGAnimatedEnumeration maskContentUnits;
  readonly attribute SVGAnimatedLength x;
  readonly attribute SVGAnimatedLength y;
  readonly attribute SVGAnimatedLength width;
  readonly attribute SVGAnimatedLength height;
};

SVGMaskElement implements SVGUnitTypes;
Attributes:
maskUnits (readonly SVGAnimatedEnumeration)
Corresponds to attribute ‘maskUnits‘ on the given <mask> element. Takes one of the constants defined in SVGUnitTypes.
maskContentUnits (readonly SVGAnimatedEnumeration)
Corresponds to attribute ‘maskContentUnits‘ on the given <mask> element. Takes one of the constants defined in SVGUnitTypes.
x (readonly SVGAnimatedLength)
Corresponds to attribute x on the given <mask> element.
y (readonly SVGAnimatedLength)
Corresponds to attribute y on the given <mask> element.
width (readonly SVGAnimatedLength)
Corresponds to attribute width on the given <mask> element.
height (readonly SVGAnimatedLength)
Corresponds to attribute height on the given <mask> element.

Changes since last publication

The following significant changes were made since the 20 June 2013 Working Draft.

The following significant changes were made since the 15 November 2012 Working Draft.

See detailed list of changes in the ChangeLog.

Acknowledgments

Thanks to Elika J. Etemad, Liam R. E. Quin, Björn Höhrmann and Alan Stearns for their careful reviews, comments, and corrections.

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.

References

Normative References

[CSS-SHAPES]
Vincent Hardy; Rossen Atanassov; Alan Stearns. CSS Shapes Module Level 1. 20 June 2013. W3C Working Draft. URL: http://www.w3.org/TR/2013/WD-css-shapes-1-20130620/
[CSS21]
Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 7 June 2011. W3C Recommendation. URL: http://www.w3.org/TR/2011/REC-CSS2-20110607
[CSS3BG]
Bert Bos; Elika J. Etemad; Brad Kemper. CSS Backgrounds and Borders Module Level 3. 24 July 2012. W3C Candidate Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2012/CR-css3-background-20120724/
[CSS3VAL]
Håkon Wium Lie; Tab Atkins; Elika J. Etemad. CSS Values and Units Module Level 3. 30 July 2013. W3C Candidate Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2013/CR-css3-values-20130730/
[HTML5]
Robin Berjon; et al. HTML5. 6 August 2013. W3C Candidate Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2013/CR-html5-20130806/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. URL: http://www.ietf.org/rfc/rfc2119.txt
[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/

Informative References

[CSS3-TRANSFORMS]
Simon Fraser; et al. CSS Transforms. 11 September 2012. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2012/WD-css3-transforms-20120911/
[CSS3COLOR]
Tantek Çelik; Chris Lilley; L. David Baron. CSS Color Module Level 3. 7 June 2011. W3C Recommendation. URL: http://www.w3.org/TR/2011/REC-css3-color-20110607
[CSSOM-VIEW]
Anne van Kesteren. CSSOM View Module. 4 August 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-cssom-view-20110804/
[FILTER-EFFECTS]
Dean Jackson; Erik Dahlström; Dirk Schulze. Filter Effects 1.0. 23 May 2013. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2013/WD-filter-effects-20130523/

Index

Property index

NameValueInitialApplies toInh.%agesMediaAnimatableComputed value
mask-image<mask-reference>noneAll elements. In SVG, it applies to container elements without the <defs> element and all graphics elementsnon/avisualnoas specified, but with URIs made absolute
mask-source-type<source-type>`autoAll elements. In SVG, it applies to container elements without the <defs> element and all graphics elementsnon/avisualnoas specified
mask-repeat<repeat-style>no-repeatAll elements. In SVG, it applies to container elements without the <defs> element and all graphics elementsnon/avisualnoA list, each item consisting of: two keywords, one per dimension
mask-position<position>centerAll elements. In SVG, it applies to container elements without the <defs> element and all graphics elementsnorefer to size of mask painting area minus size of mask image; see textvisualas repeatable list of simple list of length, percentage, or calcA list, each item consisting of: two keywords representing the origin and two offsets from that origin, each given as an absolute length (if given a <length>), otherwise as a percentage.
mask-clip<box> | no-clipborder-boxAll elements. In SVG, it applies to container elements without the <defs> element and all graphics elementsnon/avisualnoas specified
mask-origin<box>border-boxAll elements. In SVG, it applies to container elements without the <defs> element and all graphics elementsnon/avisualnoas specified
mask-size<bg-size>border-boxAll elements. In SVG, it applies to container elements without the <defs> element and all graphics elementsnon/avisualas repeatable list of simple list of length, percentage, or calc (This means keyword values are not animatable.as specified, but with lengths made absolute
mask<mask-layer>border-boxAll elements. In SVG, it applies to container elements without the <defs> element and all graphics elementsnosee individual propertiesvisualsee individual propertiessee individual properties
mask-typeluminance | alphaluminance<mask> elementsnon/avisualnoas specified
mask-box-image-sourcenone | <image>noneAll elements. In SVG, it applies to container elements without the <defs> element and all graphics elementsnon/avisualnonone or the image with its URI made absolute
mask-box-image-slice[<number> | <percentage>]{1,4} fill?0 fillAll elements. In SVG, it applies to container elements without the <defs> element and all graphics elementsnorefer to size of the mask imagevisualnoas specified
mask-box-image-width[ <length> | <percentage> | <number> | auto ]{1,4}autoAll elements. In SVG, it applies to container elements without the <defs> element and all graphics elementsnorelative to width/height of the mask box image areavisualnoall <length>s made absolute, otherwise as specified
mask-box-image-outset[ <length> | <number> ]{1,4}0All elements. In SVG, it applies to container elements without the <defs> element and all graphics elementsnon/avisualnoall <length>s made absolute, otherwise as specified
mask-box-image-repeat[ stretch | repeat | round | space ]{1,2}stretchAll elements. In SVG, it applies to container elements without the <defs> element and all graphics elementsnon/avisualnoas specified
mask-box-image<‘mask-box-image-source’> || <‘mask-box-image-slice’> [ / <‘mask-box-image-width’> | / <‘mask-box-image-width’>? / <‘mask-box-image-outset’> ]? || <‘mask-box-image-repeat’>See individual propertiesSee individual propertiesnon/avisualSee individual propertiesSee individual properties
clip-path<basic-shape> | <clip-source> | nonenoneAll elements. In SVG, it applies to container elements without the <defs> element and all graphics elementsnoas specifiedvisualSee shape-outside [CSS-SHAPES]as specified, but with <url> values made absolute
clip-rulenonzero | evenoddnonzeroAll elements. In SVG, it applies to container elements without the <defs> element and all graphics elementsyesn/avisualnoas specified
clip<shape> | autoautoAbsolutely positioned elements. In SVG, it applies to elements which establish a new viewport, <pattern> elements and <marker> elements.non/avisualas rectangleas specified