W3C

CSS Masking

Editor's Draft 10 March 2013

This version:
http://dvcs.w3.org/hg/FXTF/raw-file/default/masking/index.html
Latest version:
http://www.w3.org/TR/css-masking/
Editor's draft:
http://dvcs.w3.org/hg/FXTF/raw-file/default/masking/index.html
Editors:
Dirk Schulze, Adobe Systems,
Brian Birtles, Mozilla Japan,
Tab Atkins Jr., Google, Inc.

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.

Status of this document

This is a public copy of the editors' draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don't cite this document other than as 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.

Table of contents

1. Introduction

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

A mask is applied using the ‘mask’, ‘mask-image’ or ‘mask-box-image’ properties. The mask source may be defined using a mask element referenced by the ‘mask’ property. Alternatively, for many simple uses, the ‘mask-image’ property may refer directly to graphical elements or images to be used as mask forgoing the need for an explicit mask element. The ‘mask’ property is also a shorthand for other masking properties. ‘mask-box-image’ 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 image area.

The effect of applying a mask is as if the mask images or mask source elements 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.

Clipping defines a visible region of a visual element. The region can be specified with SVG graphics element or basic shapes. Everything outside of a region does not get rendered.

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 containing block, and/or the creation of a stacking context.

Definitions of CSS properties and values in this specification comply with defintions in CSS Backgrounds and Borders [CSS3BG]. To avoid redundancy, this specification relies on descriptions and definitions of CSS Backgrounds and Borders. Every reference will be marked clearly. The following terms in CSS Backgrounds and Borders have the following meaning in this specification:

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

Some property and element definitions in this specification require an SVG 1.1 implementation [SVG11]. UAs without support for SVG must not implement the ‘mask-type’ and ‘clip-rule’ properties as well as the mask and clipPath elements. Furthermore, the ‘mask’ and ‘clip-path’ properties must not support references to mask and clipPath elements.

3. Values

This specification follows the CSS property definition conventions from [CSS21]. Value types not defined in this specification 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. Definitions

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 it's 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

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.

user coordinate system
See definition of local coordinate system.
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
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.
mask source
A mask defined by a mask element.
clipping path
A combination of the SVG elements path, text and basic shapes which serve as the outline of a (in the absence of anti-aliasing) 1-bit mask, where everything on the "inside" of the outline is allowed to show through but everything on the outside is masked out. See ‘clip-path’.

5. The Mask Rendering Model

The application of the ‘clip-path’, ‘mask’ or ‘mask-image’ properties to an element formatted with the CSS box model establishes a stacking context the same way that CSS ‘opacity’ 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’ and ‘mask-image’ properties have no effect on the geometry of the target element's CSS boxes.

The compositing model follows the SVG compositing model [SVG11]: first any filter effect is applied, then any clipping, masking and opacity. These effects all apply after any other CSS effects such as ‘border’. As per SVG, the application of ‘mask’ or ‘mask-image’ has no effect on hit-testing.

5.1. Layering Multiple Mask Images

The mask of a box can have multiple layers. The number of layers is determined by the number of comma-separated values in the ‘mask-image’ property. Note that a value of ‘none’ still creates a layer. See Layering Multiple Background Images [CSS3BG].

The first layer is the layer closest to the user, the next one is painted behind the first, and so on. All mask images are transformed to alpha masks (if necessary) and combined by compositing on the mask.

5.2. Calculating mask 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 that 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 that 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. Mask

6.1. The ‘mask-image’ property

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

This property sets the mask image(s) or the mask source of an element. Images are drawn with the first specified one on top (closest to the user) and each subsequent image behind the previous one. Where:

<mask-reference> = <mask-image># | <mask-element>
<mask-image> = <image> | none 
<mask-element> = <url> | child | <child-selector>
<child-selector> = select(<compound-selector>#)

A <mask-element> can just be specified as a single value and can not contibute to a list of <mask-reference> values. Otherwise the specified value of the property is invalid. (See examples below.)

<url>
A URL reference to a mask element (for example ‘url(commonmasks.svg#mask)’) or an <image>.
child
A keyword to indicate that the last direct sibling mask element of the element the ‘mask-image’ property is applied should be used as the mask source. It is equivalent to ‘select(mask:last-of-type)’.
<child-selector>
A comma-separated list of compound selectors scoped at the element to which the ‘mask-image’ property is applied. The first matching element in tree order (as defined in [DOM]) as a result of evaluating the list of selectors is taken as the mask source. If there are no matching elements the mask source is invalid.
<compound-selector>
A compound selector as defined in [SELECTORS4].
<image>
A 2D image. (See [CSS3-IMAGES].)
none
A value of ‘none’ counts as an image layer but does not mask the element.

If the URI in the ‘url()’ function has a fragment identifier, the <mask-reference> is treated as <mask-element>, otherwise as <mask-image>.

An invalid or non-existent mask source is ignored and no masking is applied.

A mask image that is empty (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. No masking is applied.

See the section “Layering multiple mask images” for how ‘mask-image’ interacts with other comma-separated mask properties to form each mask image layer.

Some examples specifying mask images:

body { mask-image: linear-gradient(black 0%, transparent 100%) }
p { mask-image: none }
div { mask-image: url(tl.png), url(tr.png) }

Some examples of a specified mask source:

img { mask-image: url(#mask) }
span { mask-image: url(resources.svg#mask2) }

Examples of invalid mask source usages:

p { mask-image: url(#mask), url(tl.png) }
img { mask-image: url(#mask), url(resources.svg#mask2) }

A <mask-element> value that is either used together with another <mask-element> value or an <mask-image> value makes the whole specified ‘mask-image’ value list invalid.

6.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 and graphics elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: as specified
Animatable: no

The ‘mask-source-type’ property indicates whether the <mask-reference> is treated as luminance mask or alpha mask. (See Calculating mask 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-image> 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 <mask-element> 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"/>

6.3. The ‘mask-repeat’ property

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

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

<repeat-style> = repeat-x | repeat-y | [repeat | space | round | no-repeat]{1,2}

See Tiling Images: the ‘background-repeat’ property [CSS3BG] for the defintions 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.

See the section “Layering multiple mask images” for how ‘mask-repeat’ interacts with other comma-separated mask properties to form each mask image layer.

6.4. The ‘mask-position’ property

Name: mask-position
Value: <position>#
Initial: 0% 0%
Applies to: All elements. In SVG, it applies to container elements and graphics elements
Inherited: no
Percentages: refer to size of mask painting area minus size of mask image; see text
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.
Animatable: as repeatable list of simple list of length, percentage, or calc

Where

<position> = [
  [ left | center | right | top | bottom | <percentage> | <length> ]
|
  [ left | center | right | <percentage> | <length> ]
  [ top | center | bottom | <percentage> | <length> ]
|
  [ center | [ left | right ] [ <percentage> | <length> ]? ] &&
  [ center | [ top | bottom ] [ <percentage> | <length> ]? ]
]

See Positioning Images: the ‘background-position’ property [CSS3BG] for the defintions 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

See the section “Layering multiple mask images” for how ‘mask-position’ interacts with other comma-separated mask properties to form each mask image layer.

6.5. The ‘mask-clip’ property

Name: mask-clip
Value: <clip-box>#
Initial: border-box
Applies to: All elements. In SVG, it applies to container elements and graphics elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: as specified
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 resricted to this area. The syntax of the property is given with

<clip-box> = <box> | no-clip
<box> = border-box | padding-box | content-box

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 that there is no corresponding box for ‘padding-box’ on objects without associated layout box and ‘content-box’ is choosen instead.

See the section “Layering multiple mask images” for how ‘mask-clip’ interacts with other comma-separated mask properties to form each mask image layer.

6.6. The ‘mask-origin’ property

Name: mask-origin
Value: <box>#
Initial: padding-box
Applies to: All elements. In SVG, it applies to container elements and graphics elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: as specified
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(s).

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 that there is no corresponding box for ‘padding-box’ on objects without associated layout box and ‘content-box’ is choosen instead.

Note that 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.

See the section “Layering multiple mask images” for how ‘mask-origin’ interacts with other comma-separated mask properties to form each mask image layer.

6.7. The ‘mask-size’ property

Name: mask-size
Value: <mask-size>#
Initial: auto
Applies to: All elements. In SVG, it applies to container elements and graphics elements
Inherited: no
Percentages: see text
Media: visual
Computed value: as specified, but with lengths made absolute
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. Where

<mask-size> = [ <length> | <percentage> | auto ]{1,2} | cover | contain

See Sizing Images: the ‘background-size’ property [CSS3BG] for the defintions of the property values.

See the section “Layering multiple mask images” for how ‘mask-size’ interacts with other comma-separated mask properties to form each mask image layer.

6.8. The ‘mask’ property

Name: mask
Value: <mask-layer>#
Initial: see individual properties
Applies to: All elements. In SVG, it applies to container elements and graphics elements
Inherited: no
Percentages: see individual properties
Media: visual
Computed value: see individual properties
Animatable: see individual properties

Where

<mask-layer> = <mask-reference> <source-type>? || <position> [ / <mask-size> ]? || <repeat-style> || <box> || <clip-box>

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

Note that the properties ‘mask-image’, ‘mask-repeat’, ‘mask-position’, ‘mask-clip’, ‘mask-origin’ and ‘mask-size’ have no affect on mask elements.

6.9. The ‘mask-type’ property

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

The ‘mask-type’ property defines whether the content of the mask 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 is a presentation attribute for SVG elements.

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

Note that 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.

7. Mask Box Image

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 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);
}

7.1. The ‘mask-box-image-source’ property

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

Specifies an image to be used as mask. If the value is ‘none’ or if the image cannot be displayed (or the property doesn't apply), the content won't get masked.

7.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 and graphics elements.
Inherited: no
Percentages: refer to size of the mask image
Media: visual
Computed value: as specified
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 Image Slicing: the ‘border-image-slice’ property [CSS3BG] for the defintions of the property values.

7.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 and graphics elements.
Inherited: no
Percentages: relative to width/height of the mask box image area
Media: visual
Computed value: all <length>s made absolute, otherwise as specified
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 Drawing Areas: the ‘border-image-width’ property [CSS3BG] for the defintions of the property values.

Note that for SVG elements without an associated layout box the ‘border-width’ is considered to be ‘0’.

7.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 and graphics elements.
Inherited: no
Percentages: N/A
Media: visual
Computed value: all <length>s made absolute, otherwise as specified
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 that for SVG elements without associated layout box the ‘border-width’ is considered to be ‘0’.

7.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 and graphics elements.
Inherited: no
Percentages: N/A
Media: visual
Computed value: as specified
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 Image Tiling: the ‘border-image-repeat’ property [CSS3BG] for the defintions 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.

7.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
Percentages: N/A
Media: visual
Computed value: See individual properties
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.

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

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

8.1. The ‘clip-path’ property

Name: clip-path
Value: <shape> | <clip-source> | none
Initial: none
Applies to: All elements. SVG container elements, graphics elements and clipPath
Inherited: no
Percentages: as specified
Media: visual
Computed value: as specified, but with <url> values made absolute
Animatable: See shape-inside and shape-outside [CSS3-EXCLUSIONS]
<clip-source> = <url> | child | <child-selector>
<shape>
A basic shape function as defined in CSS3 Exclusions. 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 [CSS3-EXCLUSIONS].)
child
A keyword to indicate that the last direct sibling clipPath element of the element the ‘clip-path’ property is applied should be used as the clip source. It is equivalent to ‘select(clipPath:last-of-type)’.
<child-selector>
A comma-separated list of compound selectors scoped at the element to which the ‘clip-path’ property is applied. The first matching element in tree order (as defined in [DOM]) as a result of evaluating the list of selectors is taken as the clip source. If there are no matching elements the clip source is invalid.

8.2. The ‘clip-rule’ property

Name: clip-rule
Value: nonzero | evenodd
Initial: nonzero
Applies to: graphics elements within a clipPath element
Inherited: yes
Percentages: N/A
Media: visual
Computed value: as specified
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>

8.3. The ‘clip’ property

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

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

8.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 notes:

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

9. Security

9.1. Origin Restrictions

External references to resources like mask or clipPath must not violate the same origin restrictions [CORS].

This restriction includes:

If content falls under this restriction, the resource must be rejected. The element is drawn as if the resource was not specified (i.e. the ‘clip-path’ or ‘mask’ property were set to ‘none’).

10. DOM interfaces

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

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

References

Normative references

[CORS]
Anne van Kesteren. Cross-Origin Resource Sharing. 29 January 2013. W3C Candidate Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2013/CR-cors-20130129/
[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/
[CSS3-EXCLUSIONS]
Vincent Hardy; Rossen Atanassov; Alan Stearns. CSS Exclusions and Shapes Module Level 3. 3 May 2012. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2012/WD-css3-exclusions-20120503/
[CSS3-IMAGES]
Elika J. Etemad; Tab Atkins Jr. CSS Image Values and Replaced Content Module Level 3. 17 April 2012. W3C Candidate Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2012/CR-css3-images-20120417/
[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. 28 August 2012. W3C Candidate Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2012/CR-css3-values-20120828/
[DOM]
Anne van Kesteren; et al. DOM4. 6 December 2012. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2012/WD-dom-20121206/
[SELECTORS4]
Elika J. Etemad. Selectors Level 4. 23 August 2012. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2012/WD-selectors4-20120823/
[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/
[SVG2]
Cameron McCormack; et al. Scalable Vector Graphics (SVG) 2. 28 August 2012. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2012/WD-SVG2-20120828/

Other 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/
[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/

Index

Property index

Property Values Initial Applies to Inh. Percentages Media
clip <shape> | auto see individual properties Absolutely positioned elements. In SVG, it applies to elements which establish a new viewport, ‘pattern’ elements and ‘marker’ elements. no N/A visual
clipPath
clip-path <shape> | <clip-source> | none none All elements. SVG container elements, graphics elements and ‘clipPath’ no as specified visual
clip-rule nonzero | evenodd nonzero graphics elements within a ‘clipPath’ element yes N/A visual
mask
mask <mask-layer># see individual properties All elements. In SVG, it applies to container elements and graphics elements no see individual properties visual
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 properties See individual properties no N/A visual
mask-box-image-outset [ <length> | <number> ]{1,4} 0 All elements. In SVG, it applies to container elements and graphics elements. no N/A visual
mask-box-image-repeat [ stretch | repeat | round | space ]{1,2} stretch All elements. In SVG, it applies to container elements and graphics elements. no N/A visual
mask-box-image-slice [<number> | <percentage>]{1,4} && fill? 0 fill All elements. In SVG, it applies to container elements and graphics elements. no refer to size of the mask image visual
mask-box-image-source <mask-image> none All elements. In SVG, it applies to container elements and graphics elements. no N/A visual
mask-box-image-width [ <length> | <percentage> | <number> | auto ]{1,4} auto All elements. In SVG, it applies to container elements and graphics elements. no relative to width/height of the mask box image area visual
mask-clip <clip-box># border-box All elements. In SVG, it applies to container elements and graphics elements no N/A visual
mask-image <mask-reference> none All elements. In SVG, it applies to container elements and graphics elements no N/A visual
mask-origin <box># padding-box All elements. In SVG, it applies to container elements and graphics elements no N/A visual
mask-position <position># 0% 0% All elements. In SVG, it applies to container elements and graphics elements no refer to size of mask painting area minus size of mask image; see text visual
mask-repeat <repeat-style># repeat All elements. In SVG, it applies to container elements and graphics elements no N/A visual
mask-size <mask-size># auto All elements. In SVG, it applies to container elements and graphics elements no see text visual
mask-source-type <source-type># auto All elements. In SVG, it applies to container elements and graphics elements no N/A visual
mask-type luminance | alpha luminance ‘mask’ elements no N/A visual