Tab Atkins Jr." name=dcterms.creator>
Copyright © 2013 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.
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.
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 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.
mask-image
’ property
mask-source-type
’ property
mask-repeat
’ property
mask-position
’ property
mask-clip
’ property
mask-origin
’ property
mask-size
’ property
mask
’ property
mask-type
’ property
<mask>
element
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>
element
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-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 image area.
The ‘mask-box-image
’ property serves as a shorthand
property for ‘mask-box-image-source
’ and other
characterizing properties.
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.
A luminance mask (middle) is applied on a shape filled with a gradient (left). This results in a masked shape (right).
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].
This specification follows the CSS property definition conventions from [CSS21]. Basic shapes are defined in CSS Exclusions and Shapes Module Level 3 [CSS3-EXCLUSIONS]. 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.
When used in this specification, terms have the meanings assigned in this section.
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].)
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.
<mask>
element.
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 |
mask-image
’ propertyName: | 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 |
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-source>
<mask-image> = <image> | none
<mask-source> = <url> | child | <child-selector>
<child-selector> = select(<compound-selector>#)
A <mask-source> can just be specified as a single value and can not contribute to a list of <mask-reference> values. Otherwise the specified value of the property is invalid. (See examples below.)
<mask>
element (for example ‘url(commonmasks.svg#mask)
’).
child
’
<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)
’.
<mask>
element in tree
order (as defined in [DOM]).
none
’
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-source>,
otherwise as <mask-image>.
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 of a mask source is not valid (e.g it points to an
object that doesn't exist or the object is not a <mask>
element), 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-source> value
that is either used together with another <mask-source> value or an <mask-image> value makes the
whole specified ‘mask-image
’ value list invalid.
mask-source-type
’ propertyName: | 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 |
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 Mask
Source values.)
<source-type> = alpha | luminance | auto
Values have the following meanings:
alpha
’
alpha
’
indicates that the alpha values of the mask image should be used as the
mask values. See Calculating mask values.
luminance
’
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 <mask-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"/>
mask-repeat
’
propertyName: | mask-repeat |
---|---|
Value: | <repeat-style># |
Initial: | repeat |
Applies to: | All elements. In SVG, it applies to container
elements without the <defs> element and all 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.
See Tiling
Images: the ‘background-repeat
’
property [CSS3BG] for the definitions of the
property values.
body { background-color: blue; mask-image: url(dot-mask.png) luminance; mask-repeat: space; }
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.
mask-position
’
propertyName: | mask-position |
---|---|
Value: | <position># |
Initial: | 0% 0% |
Applies to: | All elements. In SVG, it applies to container
elements without the <defs> element and all 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 |
See Positioning
Images: 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
See the section “Layering multiple mask
images” for how ‘mask-position
’ interacts with other
comma-separated mask properties to form each mask image layer.
mask-clip
’ propertyName: | 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 |
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 restricted to this area.
Values have the following meanings:
border-box
’
padding-box
’
content-box
’
no-clip
’
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.
mask-origin
’
propertyName: | mask-origin |
---|---|
Value: | <box># |
Initial: | padding-box |
Applies to: | All elements. In SVG, it applies to container
elements without the <defs> element and all 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
’
0 0
’ is the upper left corner of the padding
edge, ‘100% 100%
’ is the lower right corner.)
border-box
’
content-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.
mask-size
’ propertyName: | mask-size |
---|---|
Value: | <bg-size># |
Initial: | auto |
Applies to: | All elements. In SVG, it applies to container
elements without the <defs> element and all 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.
See Sizing Images: the ‘background-size’ property [CSS3BG] for the definitions 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.
mask
’ propertyName: | mask |
---|---|
Value: | <mask-layer># |
Initial: | see individual properties |
Applies to: | All elements. In SVG, it applies to container
elements without the <defs> element and all 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> [ / <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
’.
Note that the properties ‘mask-image
’, ‘mask-repeat
’, ‘mask-position
’,
‘mask-clip
’,
‘mask-origin
’
and ‘mask-size
’
have no affect on <mask>
elements.
The ‘mask
’ property does not influence the ‘mask-box-image
’
properties. ‘mask: none
’ does not remove any
masking defined by ‘mask-box-image
’.
mask-type
’ propertyName: | 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>
element is treated as as luminance
mask or alpha mask, as described in Calculating mask
values.
Values have the following meanings:
luminance
’
alpha
’
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.
<mask>
elementName: | mask |
---|---|
Categories: | Container element |
Content model: | Any number of the following elements, in any order: |
Attributes: | |
DOM Interfaces: | SVGMaskElement |
Attribute definitions:
x
’,
‘y
’, ‘width
’ and ‘height
’.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).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.)maskUnits
’ is not specified, then the effect
is as if a value of ‘objectBoundingBox
’ were specified.<mask>
.<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).<mask>
is
established using the bounding box of the element to which the mask is
applied. (See object
bounding box units.)maskContentUnits
’ is not specified, then the
effect is as if a value of ‘userSpaceOnUse
’ were specified.y
’,
‘width
’ or ‘height
’ are specified, the effect is as if a
value of ‘-10%
’
were specified.x
’, ‘width
’ or ‘height
’ are specified, the effect is as if a
value of ‘-10%
’
were specified.x
’, ‘y
’ or
‘height
’ are specified, the effect is as if a
value of ‘120%
’
were specified.x
’, ‘y
’ or
‘width
’ are specified, the effect is as if a
value of ‘120%
’
were specified.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.
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.
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].
All mask images are transformed to alpha masks (if necessary) and combined by compositing on the mask.
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.
color-interpolation
’ on the <mask>
element is ‘linearRGB
’, convert the
original image color values (potentially in the sRGB color space) to
the linear RGB color space.
<feColorMatrix>
filter primitive [SVG11]) to convert
the RGB color values to luminance values.
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.
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.
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
’. 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); }
mask-box-image-source
’ propertyName: | 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.
A computed value of other than ‘none
’ results
in the creation of a stacking context [CSS21] the same way
that CSS ‘opacity
’ [CSS3COLOR] does.
mask-box-image-slice
’ propertyName: | 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 |
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 definitions of the
property values.
mask-box-image-width
’ propertyName: | 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 |
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 definitions of the property values.
Note that for SVG elements without an associated layout box
the ‘border-width
’ is considered to be
‘0
’.
mask-box-image-outset
’ propertyName: | 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 |
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
’.
mask-box-image-repeat
’ propertyName: | 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 |
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 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.
mask-box-image
’
propertyName: | 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.
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.
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.
clip-path
’ propertyName: | 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, all graphics
elements and <clipPath> .
|
Inherited: | no |
Percentages: | as specified |
Media: | visual |
Computed value: | as specified, but with <url> values made absolute |
Animatable: | See ‘shape-outside ’ [CSS3-EXCLUSIONS]
|
Specifies a basic shape or references a <clipPath>
element to create a
clipping path.
<clip-source> = <url> | child | <child-selector>
child
’
<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)
’.
<clipPath>
element in tree
order (as defined in [DOM]).
none
’
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.
clip-rule
’ propertyName: | 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
’
fill-rule
’ property [SVG11].
evenodd
’
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>
clip
’ propertyName: | 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
’
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:
This diagram illustrates two block boxes, one above the other, with rectangular clipping regions of different dimensions. (See long description.)
<clipPath>
elementName: | clipPath |
---|---|
Categories: | None. |
Content model: | Any number of the following elements, in any order: |
Attributes: | |
DOM Interfaces: | SVGClipPathElement |
Attribute definitions:
<clipPath>
.<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).<clipPath>
element is established using
the bounding box of the element to which the clipping path is applied
(see object bounding box units).clipPathUnits
’ is not specified, then the
effect is as if a value of ‘userSpaceOnUse
’ were specified.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:
<clipPath>
element itself and its child
elements do not inherit clipping paths from the ancestors of the
<clipPath>
element.
<clipPath>
element or any of its
children can specify property ‘clip-path
’.clip-path
’ reference is placed on a <clipPath>
element, the resulting clipping path is the intersection of the contents
of the <clipPath>
element with the referenced
clipping path.clip-path
’ reference is placed on one of the
children of a <clipPath>
element, then the given child
element is clipped by the referenced clipping path before OR'ing the
silhouette of the child element with the silhouettes of the other child
elements.
clip-path
’
property applied.
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.
The following description of the security model is not sufficient and detailed enough. See public-fx mailing list.
External references to resources like <mask>
or <clipPath>
must not violate the same origin restrictions [CORS].
This restriction includes:
xlink:href
’ or <use>
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
’).
The SVGClipPathElement
interface corresponds to the <clipPath>
element.
interface SVGClipPathElement : SVGElement { readonly attribute SVGAnimatedEnumeration clipPathUnits; readonly attribute SVGAnimatedTransformList transform; }; SVGClipPathElement implements SVGUnitTypes;
clipPathUnits
’ on the given <clipPath>
element. Takes one of the
constants defined in SVGUnitTypes.transform
’ on the given element.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;
maskUnits
’ on the given <mask>
element. Takes one of the constants defined in SVGUnitTypes.maskContentUnits
’ on the given <mask>
element. Takes one of the constants defined in SVGUnitTypes.Some property and element definitions in this specification require an
SVG 1.1 implementation [SVG11]. UAs without support for SVG
must not implement any of the following properties and elements: ‘mask-type
’, ‘clip-rule
’, <clipPath>
element, <mask>
element. For UAs without support
for SVG, the ‘mask
’
and ‘clip-path
’
properties must neither support references to <mask>
elements nor to <clipPath>
elements.
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 to this is defined for three conformance classes:
A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.
A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)
An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.
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.
To avoid clashes with future CSS features, the CSS 2.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.
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.
Thanks to Elika J. Etemad, Liam R. E. Quin, Björn Höhrmann for their careful reviews, comments, and corrections.
The following significant changes were made since the 15 November 2012 Working Draft.
mask
’ shorthand property to be conform with
‘background
’ shorthand property.
<mask>
, <clipPath>
) and an image resource.
mask-source-type
’ property to alter between
luminance and alpha mask on ‘mask-image
’.
See detailed list of changes in the ChangeLog.
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 | <basic-shape> | <clip-source> | none | none | All elements. In SVG, it applies to container elements without the <defs> element, all 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 without the <defs> element and all 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 without the <defs> element and all 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 without the <defs> element and all 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 without the <defs> element and all 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 without the <defs> element and all graphics elements. | no | relative to width/height of the mask box image area | visual |
mask-clip | [ <box> | no-clip ]# | border-box | All elements. In SVG, it applies to container elements without the <defs> element and all graphics elements. | no | N/A | visual |
mask-image | <mask-reference> | none | All elements. In SVG, it applies to container elements without the <defs> element and all graphics elements. | no | N/A | visual |
mask-origin | <box># | padding-box | All elements. In SVG, it applies to container elements without the <defs> element and all graphics elements. | no | N/A | visual |
mask-position | <position># | 0% 0% | All elements. In SVG, it applies to container elements without the <defs> element and all 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 without the <defs> element and all graphics elements. | no | N/A | visual |
mask-size | <bg-size># | auto | All elements. In SVG, it applies to container elements without the <defs> element and all graphics elements. | no | see text | visual |
mask-source-type | <source-type># | auto | All elements. In SVG, it applies to container elements without the <defs> element and all graphics elements. | no | N/A | visual |
mask-type | luminance | alpha | luminance | <mask> elements | no | N/A | visual |
alpha
’, 5.2.
auto
’, 5.2.
content-box
’, 5.6.
evenodd
’, 7.2.
luminance
’, 5.2.
nonzero
’, 7.2.