> is treated as luminance mask or alpha mask. (See Mask processing.)
<masking-mode> = alpha | luminance | match-source
Values have the following meanings:
: alpha
:: A value of ''mask-mode/alpha'' indicates that the alpha values of the mask layer image should be used as the mask values. See Calculating mask values.
: luminance
:: A value of ''mask-mode/luminance'' indicates that the luminance values of the mask layer image should be used as the mask values. See Calculating mask values.
: match-source
::
If the <> of the 'mask-image' property is of type <> the value specified by the referenced mask element's 'mask-type' property must be used.
If the <> of the 'mask-image' property is of type <> the alpha values of the mask layer 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 ''mask-type/alpha''. The 'mask-image' property has a reference to this
mask element and the 'mask-mode' property has a value of ''mask-mode/luminance''. The 'mask-mode' property will override the definition of 'mask-type' to ''mask-type/luminance''.
The 'mask-mode' property must not affect the masking mode of 'mask-border-source'.
<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-mode: luminance;
}
</style>
<rect width="200" height="200" fill="green"/>
Name: mask-repeat
Value: <>#
Initial: repeat
Applies to: All elements. In SVG, it applies to container elements excluding the defs element, all graphics elements and the use element
Inherited: no
Percentages: n/a
Computed value: list, each item a pair of keywords, one per dimension
Media: visual
Animation type: discrete
mask-image/mask-repeat-1-svg.html
mask-image/mask-repeat-1.html
mask-image/mask-repeat-2-svg.html
mask-image/mask-repeat-2.html
mask-image/mask-repeat-3-svg.html
mask-image/mask-repeat-3.html
parsing/mask-repeat-computed.html
parsing/mask-repeat-invalid.html
parsing/mask-repeat-valid.html
Specifies how mask layer images are tiled after they have been sized and positioned.
See '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;
}
See the section “Layering multiple mask layer images” for how 'mask-repeat' interacts with other comma-separated mask properties to form each mask layer.
## Positioning Mask Images: the 'mask-position' property ## {#the-mask-position}
Name: mask-position
Value: <>#
Initial: 0% 0%
Applies to: All elements. In SVG, it applies to container elements excluding the defs element, all graphics elements and the use element
Inherited: no
Percentages: refer to size of mask painting area minus size of mask layer image; see text 'background-position' [[!CSS3BG]]
Computed value: list, each item consists of two keywords representing the origin and two offsets from that origin, each given as an absolute length (if given a <>), otherwise as a percentage.
Media: visual
Animation type: repeatable list
animations/mask-position-interpolation.html
mask-image/mask-position-1a-svg.html
mask-image/mask-position-1a.html
mask-image/mask-position-1b.html
mask-image/mask-position-1c.html
mask-image/mask-position-2a.html
mask-image/mask-position-2b.html
mask-image/mask-position-3a.html
mask-image/mask-position-3b.html
mask-image/mask-position-4a.html
mask-image/mask-position-4b.html
mask-image/mask-position-4c.html
mask-image/mask-position-4d.html
mask-image/mask-position-5.html
mask-image/mask-position-6.html
mask-image/mask-position-7.html
mask-image/mask-position-8.html
parsing/mask-position-invalid.html
parsing/mask-position-valid.html
See the 'background-position' property [[!CSS3BG]] for the definitions of the property values.
In the example below, the (single) image is placed in the lower-right corner of the viewport.
body {
mask-image: url("logo.png");
mask-position: 100% 100%;
mask-repeat: no-repeat;
}
Mask positions can also be relative to other corners than the top left. E.g., the following puts the background image 10px from the bottom and 3em from the right:
mask-position: right 3em bottom 10px
Name: mask-clip
Value: [ <> | no-clip ]#
Initial: border-box
Applies to: All elements. In SVG, it applies to container elements excluding the defs element, all graphics elements and the use element
Inherited: no
Percentages: n/a
Computed value: list, each item the keyword as specified
Media: visual
Animation type: discrete
mask-image/mask-clip-1.html
mask-image/mask-clip-2.html
mask-image/mask-clip-3.html
mask-image/mask-clip-4.html
mask-image/mask-clip-5.html
mask-image/mask-clip-6.html
mask-image/mask-clip-7.html
mask-image/mask-clip-8.html
For mask layer images that do not reference a mask element, 'mask-clip' determines the mask painting area, which determines the area that is affected by the mask. The painted content of an element must be restricted to this area.
The 'mask-clip' property has no affect on a mask layer image that references a mask element. The x, y, width, height and maskUnits attributes on the mask element determine the mask painting area for mask references.
Values have the following meanings:
: content-box
:: The painted content is restricted to (clipped to) the content box.
: padding-box
:: The painted content is restricted to (clipped to) the padding box.
: border-box
:: The painted content is restricted to (clipped to) the border box.
: fill-box
:: The painted content is restricted to (clipped to) the object bounding box.
: stroke-box
:: The painted content is restricted to (clipped to) the stroke bounding box.
: view-box
::
Uses the nearest SVG viewport as reference box.
If a viewBox attribute is specified for the SVG viewport creating element:
* The reference box is positioned at the origin of the coordinate system established by the viewBox attribute.
* The dimension of the reference box is set to the width and height values of the viewBox attribute.
: no-clip
:: The painted content is not restricted (not clipped).
For SVG elements without associated CSS layout box, the used values for ''mask-clip/content-box'' and ''mask-clip/padding-box'' compute to ''mask-clip/fill-box'' and for ''mask-clip/border-box'' compute to ''mask-clip/stroke-box''.
For elements with associated CSS layout box, the used values for ''mask-clip/fill-box'' compute to ''mask-clip/content-box'' and for ''mask-clip/stroke-box'' and ''mask-clip/view-box'' compute to ''mask-clip/border-box''.
See the section “Layering multiple mask layer images” for how 'mask-clip' interacts with other comma-separated mask properties to form each mask layer.
## Positioning Area: the 'mask-origin' property ## {#the-mask-origin}
Name: mask-origin
Value: <>#
Initial: border-box
Applies to: All elements. In SVG, it applies to container elements excluding the defs element, all graphics elements and the use element
Inherited: no
Percentages: n/a
Computed value: list, each item the keyword as specified
Media: visual
Animation type: discrete
mask-image/mask-origin-1.html
mask-image/mask-origin-3.html
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.
:
content-box
:: The position is relative to the
content box.
:
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.
:
fill-box
:: The position is relative to the
object bounding box.
:
stroke-box
:: The position is relative to the
stroke bounding box.
:
view-box
::
Uses the nearest
SVG viewport as reference box.
If a
viewBox attribute is specified for the
SVG viewport creating element:
* The reference box is positioned at the origin of the coordinate system established by the
viewBox attribute.
* The dimension of the reference box is set to the
width and
height values of the
viewBox attribute.
Name: mask-size
Value: <>#
Initial: auto
Applies to: All elements. In SVG, it applies to container elements excluding the defs element, all graphics elements and the use element
Inherited: no
Percentages: n/a
Computed value: list, each item as specified, but with lengths made absolute
Media: visual
Animation type: repeatable list
mask-image/mask-size-auto-auto.html
mask-image/mask-size-auto-length.html
mask-image/mask-size-auto-percent.html
mask-image/mask-size-auto.html
mask-image/mask-size-contain-clip-border.html
mask-image/mask-size-contain-clip-padding.html
mask-image/mask-size-contain-position-fifty-fifty.html
mask-image/mask-size-contain.html
mask-image/mask-size-cover.html
mask-image/mask-size-length-auto.html
mask-image/mask-size-length-length.html
mask-image/mask-size-length-percent.html
mask-image/mask-size-length.html
mask-image/mask-size-percent-auto.html
mask-image/mask-size-percent-length.html
mask-image/mask-size-percent-percent-stretch.html
mask-image/mask-size-percent-percent.html
mask-image/mask-size-percent.html
Specifies the size of the mask layer images.
See 'background-size' property [[!CSS3BG]] for the definitions of the property values.
See the section “Layering multiple mask layer images” for how 'mask-size' interacts with other comma-separated mask properties to form each mask layer.
## Compositing mask layers: the 'mask-composite' property ## {#the-mask-composite}
Name: mask-composite
Value: <>#
Initial: add
Applies to: All elements. In SVG, it applies to container elements without the defs element and all graphics elements
Inherited: no
Percentages: n/a
Computed value: list, each item the keyword as specified
Media: visual
Animation type: discrete
mask-image/mask-composite-1a.html
mask-image/mask-composite-1b.html
mask-image/mask-composite-1c.html
mask-image/mask-composite-1d.html
mask-image/mask-composite-2a.html
mask-image/mask-composite-2b.html
mask-image/mask-composite-2c.html
mask-image/mask-composite-2d.html
parsing/mask-composite-computed.html
parsing/mask-composite-invalid.html
parsing/mask-composite-valid.html
<compositing-operator> = add | subtract | intersect | exclude
Each keyword represents a Porter-Duff compositing operator [[!COMPOSITING-1]] which defines the compositing operation used on the current mask layer with the mask layers below it.
In the following, the current mask layer is referred to source, all mask layers below it (with the corresponding compositing operators applied) are referred to destination.
If there is no further mask layer, the compositing operator must be ignored. Mask layers must not composite with the element's content or the content behind the element, instead they must act as if they are rendered into an isolated group.
All mask layers below the current mask layer must be composited before applying the compositing operation for the current mask layer.
This example uses two
mask layer images:
circle.svg and
rect.svg.
Both
mask layer images are references with the 'mask-image' property:
mask-image: circle.svg, rect.svg;
The mask layer with
rect.svg is below the mask layer with
circle.svg. That means
circle.svg is closer to the user than
rect.svg.
With the property 'mask-composite' the author may choose different ways to combine multiple mask layers.
* ''mask-composite/add'' paints the
circle.svg on top of
rect.svg. The behavior is described by the compositing operator
source over.
mask-composite: add;
* ''mask-composite/subtract'' paints portions of
circle.svg that do not overlap
rect.svg. The behavior is described by the compositing operator
source out.
mask-composite: subtract;
* ''mask-composite/intersect'' paints portions of
circle.svg that overlap
rect.svg. The behavior is described by the compositing operator
source in.
mask-composite: intersect;
* ''mask-composite/exclude'' paints portions of
circle.svg and
rect.svg that do not overlap. The behavior is described by the compositing operator
XOR.
mask-composite: exclude;
The following example specifies two mask layers and two compositing operators.
mask-image: rect.svg, circle.svg;
mask-composite: add, exclude;
rect.svg and
circle.svg make use of the ''mask-composite/add'' compositing operator. There is no further mask layer to use ''mask-composite/exclude'' and therefore, ''mask-composite/exclude'' is ignored.
This is an example of 3 mask layers with different compositing operators.
mask-image: trapeze.svg, circle.svg, rect.svg;
mask-composite: subtract, add;
First,
circle.svg is “added” to
rect.svg. In a second step, only portions of
trapeze.svg that are not overlapping the compositing result of the previous two layers is visible.
Name: mask
Value: <>#
Initial: see individual properties
Applies to: All elements. In SVG, it applies to container elements excluding the defs element, all graphics elements and the use element
Inherited: no
Percentages: see individual properties
Computed value: see individual properties
Media: visual
Animation type: see individual properties
animations/mask-no-interpolation.html
mask-image/mask-image-clip-exclude.html
mask-shorthand-subproperties-reset.html
parsing/mask-computed.html
parsing/mask-invalid.html
parsing/mask-valid.sub.html
<mask-layer> =
<> ||
<> [ / <> ]? ||
<> ||
<> ||
[ <> | no-clip ] ||
<> ||
<>
If one <> value and the ''no-clip'' keyword are present then <> sets 'mask-origin' and ''no-clip'' sets 'mask-clip' to that value.
If one <> value and no ''no-clip'' keyword are present then <> sets both 'mask-origin' and 'mask-clip' to that value.
If two <> values are present, then the first sets 'mask-origin' and the second 'mask-clip'.
The used value of the properties 'mask-repeat', 'mask-position', 'mask-clip', 'mask-origin' and 'mask-size' must have no effect if <> references a mask element. In this case the element defines position, sizing and clipping of the mask layer image.
The 'mask' shorthand also resets 'mask-border' to its initial value. It is therefore recommended that authors use the 'mask' shorthand, rather than other shorthands or the individual properties, to override any mask settings earlier in the cascade. This will ensure that 'mask-border' has also been reset to allow the new styles to take effect.
## The Mask Image Rendering Model ## {#the-mask-image-rendering-model}
The application of the 'mask-image' property with a value other than ''mask-image/none'' 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' property is a presentation attribute for SVG elements.
### Mask processing ### {#MaskValues}
In the following section, mask image refers either to a mask layer image or to a mask border image.
A mask image 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 image. 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 image. 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.
* If the computed value of 'color-interpolation' on the mask element is ''linearRGB'', convert the original image color values (potentially in the sRGB color space) to the linearRGB color space.
* Then, using non-premultiplied RGB color values, apply the luminance-to-alpha coefficients (as defined in the feColorMatrix filter primitive [[!SVG11]]) to convert the RGB color values to luminance values.
2. Multiply the computed luminance value by the corresponding alpha value to produce the mask value.
Regardless of the method used, the procedure for calculating mask values assumes the content of the mask is a four-channel RGBA graphics object. For other types of graphics objects, special handling is required as follows.
For a three-channel RGB graphics object that is used in a mask (e.g., when referencing a three-channel image file), the effect is as if the object were converted into a four-channel RGBA image with the alpha channel uniformly set to 1.
For a single-channel image that is used in a mask (e.g., when referencing a single-channel grayscale image file), the effect is as if the object were converted into a four-channel RGBA image, where the single channel from the referenced object is used to compute the three color channels and the alpha channel is uniformly set to 1.
Note: When referencing a grayscale image file, the transfer curve relating the encoded grayscale values to linear light values must be taken into account when computing the color channels.
Note: SVG graphics elements (e.g., circle or text) are all treated as four-channel RGBA images for the purposes of masking operations.
The effect of a mask is identical to what would have happened if there were no mask but instead the alpha channel of the given object were multiplied with the mask's resulting mask values.
Regions not covered by a mask image are treated as transparent black. The mask value is 0.
Note: Masks with repeating mask image tiles may have an offset to each other. The space between the mask images is treated as a transparent black mask.
### Layering Multiple Mask Images ### {#layering}
The mask of a box can have multiple layers. The number of layers is determined by the number of comma-separated values for the 'mask-image' property. A value of ''mask-image/none'' in a list of values with other <>s still creates a layer.
See Layering Multiple Background Images [[!CSS3BG]].
'mask-mode' and 'mask-composite' do not have counterparts in CSS Backgrounds and Borders [[!CSS3BG]]. Just like for the mask properties that do have a counterpart, the list of values are matched up from the first value: excess values at the end are not used. If a property doesn’t have enough comma-separated values to match the number of layers, the UA must calculate its used value by repeating the list of values until there are enough.
All mask layer images are transformed to alpha masks (if necessary see Mask processing) and combined by compositing taking the compositing operators specified by 'mask-composite' into account.
# Border-Box Mask # {#mask-borders}
With 'mask-border' an image can be split into nine pieces: four corners, four edges and the middle piece as demonstrated in the figure below.
These pieces may be sliced, scaled and stretched in various ways to fit the size of the mask border image area. This distorted image is then used as a mask. The syntax of 'mask-border' corresponds to the 'border-image' property of CSS Background and Borders [[!CSS3BG]].
The
mask border 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.
div {
background: linear-gradient(bottom, #F27BAA 0%, #FCC8AD 100%);
mask-border-slice: 25 fill;
mask-border-repeat: stretch;
mask-border-source: url(mask.png);
}
Name: mask-border-source
Value: none | <>
Initial: none
Applies to: All elements. In SVG, it applies to container elements excluding the defs element, all graphics elements and the use element
Inherited: no
Percentages: n/a
Computed value: they keyword ''mask-border-source/none'' or the computed <>
Media: visual
Animation type: discrete
animations/mask-border-source-interpolation.html
Specifies an image to be used as mask border image.
An image that is an empty image (zero width or zero height), that fails to download, is non-existent, or that cannot be displayed (e.g. because it is not in a supported image format) is ignored. It still counts as an mask border image but does not mask the element.
See “Mask processing” on how to process the mask border image.
A computed value of other than ''mask-border-source/none'' results in the creation of a stacking context [[!CSS21]] the same way that CSS 'opacity' [[CSS3COLOR]] does for values other than ''1''.
'mask-border-source' and 'mask-image' can be specified independent of each other. If both properties have a value other than ''mask-border-source/none'', the element is masked by both masking operations one after the other.
Note: It does not matter if 'mask-image' is applied to the element before or after 'mask-border-source'. Both operation orders result in the same rendering.
## Mask Border Image Interpretation: the 'mask-border-mode' property ## {#the-mask-border-mode}
Name: mask-border-mode
Value: luminance | alpha
Initial: alpha
Applies to: All elements. In SVG, it applies to container elements excluding the defs element, all graphics elements and the use element
Inherited: no
Percentages: n/a
Computed value: as specified
Media: visual
Animation type: discrete
The 'mask-border-mode' property indicates whether the <> value for 'mask-border-source' is treated as luminance mask or alpha mask. (See Mask processing.)
Values have the following meanings:
The 'mask-mode' and 'mask-type' properties must have no affect on the mask border image type.
## Mask Border Image Slicing: the 'mask-border-slice' property ## {#the-mask-border-slice}
Name: mask-border-slice
Value: [ <> | <> ]{1,4} fill?
Initial: 0
Applies to: All elements. In SVG, it applies to container elements excluding the defs element, all graphics elements and the use element
Inherited: no
Percentages: refer to size of the mask border image
Computed value: as specified
Media: visual
Animation type: by computed value
animations/mask-border-slice-composition.html
animations/mask-border-slice-interpolation-stability.html
animations/mask-border-slice-interpolation.html
This property specifies inward offsets from the top, right, bottom, and left edges of the mask border image, dividing it into nine regions: four corners, four edges and a middle. The middle image part is discarded and treated as fully opaque white (the content covered by the middle part is not masked and shines through) unless the fill keyword is present.
See the 'border-image-slice' property [[!CSS3BG]] for the definitions of the property values.
## Masking Areas: the 'mask-border-width' property ## {#the-mask-border-width}
Name: mask-border-width
Value: [ <> | <> | auto ]{1,4}
Initial: auto
Applies to: All elements. In SVG, it applies to container elements excluding the defs element, all graphics elements and the use element
Inherited: no
Percentages: relative to width/height of the mask border image area
Computed value: all <>s made absolute, otherwise as specified
Media: visual
Animation type: by computed value
animations/mask-border-width-composition.html
animations/mask-border-width-interpolation.html
The mask border image is drawn inside an area called the mask border image area. This is an area whose boundaries by default correspond to the border box, see 'mask-border-outset'.
See the 'border-image-width' property [[!CSS3BG]] for the definitions of the property values.
Note: For SVG elements without an associated layout box the 'border-width' is considered to be ''0''.
## Edge Overhang: the 'mask-border-outset' property ## {#the-mask-border-outset}
Name: mask-border-outset
Value: [ <> | <> ]{1,4}
Initial: 0
Applies to: All elements. In SVG, it applies to container elements excluding the defs element, all graphics elements and the use element
Inherited: no
Percentages: n/a
Computed value: all <>s made absolute, otherwise as specified
Media: visual
Animation type: by computed value
animations/mask-border-outset-composition.html
animations/mask-border-outset-interpolation.html
The values specify the amount by which the mask border 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-border-width', a <> represents a multiple of the corresponding 'border-width'. Negative values are not allowed for any of the 'mask-border-outset' values.
Note: For SVG elements without associated layout box the 'border-width' is considered to be ''0''.
## Mask Border Image Tiling: the 'mask-border-repeat' property ## {#the-mask-border-repeat}
Name: mask-border-repeat
Value: [ stretch | repeat | round | space ]{1,2}
Initial: stretch
Applies to: All elements. In SVG, it applies to container elements excluding the defs element, all graphics elements and the use element
Inherited: no
Percentages: n/a
Computed value: as specified
Media: visual
Animation type: discrete
This property specifies how the images for the sides and the middle part of the mask border image are scaled and tiled. The first keyword applies to the horizontal sides, the second to the vertical ones. If the second keyword is absent, it is assumed to be the same as the first.
See the 'border-image-repeat' property [[!CSS3BG]] for the definitions of the property values.
The exact process for scaling and tiling the mask border image parts is given in the section Masking with the mask border image
## Mask Border Image Shorthand: the 'mask-border' property ## {#the-mask-border}
Name: mask-border
Value: <<'mask-border-source'>> || <<'mask-border-slice'>> [ / <<'mask-border-width'>>? [ / <<'mask-border-outset'>> ]? ]? || <<'mask-border-repeat'>> || <<'mask-border-mode'>>
Initial: See individual properties
Applies to: See individual properties
Inherited: no
Percentages: n/a
Computed value: See individual properties
Media: visual
Animation type: See individual properties
This is a shorthand property for setting 'mask-border-source', 'mask-border-slice', 'mask-border-width', 'mask-border-outset', 'mask-border-repeat' and 'mask-border-mode'. Omitted values are set to their initial values.
Note: The 'mask' shorthand resets the properties 'mask-border', 'mask-border-source', 'mask-border-slice', 'mask-border-width', 'mask-border-outset', 'mask-border-repeat' and 'mask-border-mode'.
## Masking with the mask border image ## {#masking-with-the-mask-border-image}
After the mask border image given by 'mask-border-source' is sliced by the 'mask-border-slice' values, the resulting nine images are scaled, positioned, and tiled into their corresponding mask border image regions in four steps as described in the section Drawing the Border Image [[!CSS3BG]].
The application of the 'mask-border-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-border-source' property has no effect on the geometry or hit-testing of any element's CSS boxes.
# SVG Mask Sources # {#svg-masks}
## The mask element ## {#MaskElement}
| Name: |
mask
|
| Categories: |
container elements, never-rendered element |
| Content model: |
Any number of the following elements, in any order: - animation — animate, animateMotion, animateTransform, set
- descriptive — desc, title, metadata
- shape — circle, ellipse, line, path, polygon, polyline, rect
- structural — defs, g, svg, symbol, use
- gradient — linearGradient, radialGradient
- a
- clipPath
- color-profile
- cursor
- filter
- font
- font-face
- foreignObject
- image
- marker
- mask
- pattern
- script
- style
- switch
- view
- text
- altGlyphDef
|
| Attributes: |
- conditional processing attributes — ‘requiredFeatures’, ‘requiredExtensions’, ‘systemLanguage’
- core attributes — ‘id’, ‘xml:base’, ‘xml:lang’, ‘xml:space’
- presentation attributes — 'alignment-baseline', 'baseline-shift', 'clip', 'clip-path', 'clip-rule', 'color', 'color-interpolation', 'color-interpolation-filters', 'color-profile', 'color-rendering', 'cursor', 'direction', 'display', 'dominant-baseline', 'enable-background', 'fill', 'fill-opacity', 'fill-rule', 'filter', 'flood-color', 'flood-opacity', 'font', 'font-family', 'font-size', 'font-size-adjust', 'font-stretch', 'font-style', 'font-variant', 'font-weight', 'glyph-orientation-horizontal', 'glyph-orientation-vertical', 'image-rendering', 'kerning', 'letter-spacing', 'lighting-color', 'marker', 'marker-end', 'marker-mid', 'marker-start', 'mask', 'opacity', 'overflow', 'pointer-events', 'shape-rendering', 'stop-color', 'stop-opacity', 'stroke', 'stroke-dasharray', 'stroke-dashoffset', 'stroke-linecap', 'stroke-linejoin', 'stroke-miterlimit', 'stroke-opacity', 'stroke-width', 'text-anchor', 'text-decoration', 'text-rendering', 'unicode-bidi', 'visibility', 'word-spacing', 'writing-mode'
- ‘class’
- ‘style’
- ‘x’
- ‘y’
- ‘width’
- ‘height’
- ‘maskUnits’
- ‘maskContentUnits’
|
| DOM Interfaces: |
SVGMaskElement |
mask-svg-content/mask-empty-container-with-filter.svg
mask-svg-content/mask-invalid-reference.svg
mask-svg-content/mask-negative-scale.svg
mask-svg-content/mask-text-001.svg
mask-svg-content/mask-type-001.svg
mask-svg-content/mask-type-002.svg
mask-svg-content/mask-type-003.svg
mask-svg-content/mask-with-filter-clipped-to-region.svg
mask-svg-content/mask-with-filter.svg
mask-svg-content/mask-with-rotation.svg
Attribute definitions:
: maskUnits = "''maskUnits/userSpaceOnUse'' | ''maskUnits/objectBoundingBox''"
::
Defines the coordinate system for attributes x, y, width and height.
: userSpaceOnUse
:: x, y, width and height represent values in the current user coordinate system [[!CSS3-TRANSFORMS]] 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).
: objectBoundingBox
:: x, y, width and height represent fractions or percentages of the object bounding box of the element to which the mask is applied. User coordinates are sized equivalently to the CSS ''px'' unit.
If attribute maskUnits is not specified, then the effect is as if a value of ''maskUnits/objectBoundingBox'' were specified.
Animatable: yes.
: maskContentUnits = "''maskContentUnits/userSpaceOnUse'' | ''maskContentUnits/objectBoundingBox''"
::
Defines the coordinate system for the contents of the mask.
: 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).
: objectBoundingBox
:: The coordinate system has its origin at the top left corner of the bounding box of the element to which the clipping path applies to and the same width and height of this bounding box. User coordinates are sized equivalently to the CSS ''px'' unit.
If attribute maskContentUnits is not specified, then the effect is as if a value of ''maskContentUnits/userSpaceOnUse'' were specified.
Animatable: yes.
: x = "<>"
::
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 = "<>"
::
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 = "<>"
::
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 = "<>"
::
The height of the largest possible offscreen buffer.
A negative value or a value of zero disables rendering of the element.
If the attribute is not specified but at least one of the attributes x, y or width are specified, the effect is as if a value of ''120%'' were specified.
Animatable: yes.
If at least one of the attributes x, y, width or height are specified, the given object and the rectangle defined by x, y, width and height establish a current clipping path. The rendered content of the mask must be clipped by this current clipping path.
CSS properties inherit into the mask element from its ancestors; properties do not inherit from the element referencing the mask element.
mask elements are never rendered directly; their only usage is as something that can be referenced using the 'mask' property. The 'opacity', 'filter' and 'display' properties do not apply to the mask element; thus, mask elements are not directly rendered even if the 'display' property is set to a value other than ''display/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 ''display/none''.
## Mask Source Interpretation: the 'mask-type' property ## {#the-mask-type}
Name: mask-type
Value: luminance | alpha
Initial: luminance
Applies to: mask elements
Inherited: no
Percentages: n/a
Computed value: as specified
Media: visual
Animation type: discrete
parsing/mask-type-computed.html
parsing/mask-type-invalid.html
parsing/mask-type-valid.html
The 'mask-type' property defines whether the content of the mask element is treated as as luminance mask or alpha mask, as described in Calculating mask values.
Values have the following meanings:
: luminance
:: Indicates that the luminance values of the mask should be used.
: alpha
:: Indicates that the alpha values of the mask should be used.
The 'mask-type' property allows the author of the mask element to specify the preferred masking mode. However, the author can override this preference by setting the 'mask-mode' value to something different than ''mask-mode/match-source'' on the masked content.
In the following example the computed value of 'mask-type' is ''mask-type/luminance'' and the computed value of 'mask-mode' is ''mask-mode/match-source''. The UA must follow the preferred masking mode defined on the
mask element.
<svg>
<mask style="mask-type: luminance;" id="mask">
...
</mask>
</svg>
<p style="mask-image: url(#mask); mask-mode: match-source;">
This is the masked content.
</p>
In the next example the computed value of 'mask-mode' is ''mask-mode/alpha'' and overrides the preference on the
mask element that is computed to ''mask-type/luminance''. The
mask layer image is used as an alpha mask.
<svg>
<mask style="mask-type: luminance;" id="mask2">
...
</mask>
</svg>
<p style="mask-image: url(#mask2); mask-mode: alpha;">
This is the masked content.
</p>
Appendix A: The deprecated 'clip' property
Name: clip
Value: <> | ''clip/auto''
Initial: auto
Applies to: Absolutely positioned elements. In SVG, it applies to elements which establish a new viewport, pattern elements and mask elements.
Inherited: no
Percentages: n/a
Computed value: as specified
Media: visual
Animation type: by computed value
animations/clip-interpolation.html
clip/clip-fixed-pos-transform-descendant-001.html
clip/clip-no-stacking-context.html
clip/clip-rect-comma-001.html
clip/clip-rect-comma-002.html
clip/clip-rect-comma-003.html
clip/clip-rect-comma-004.html
clip/clip-rect-scroll.html
parsing/clip-computed.html
parsing/clip-invalid.html
parsing/clip-valid.html
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 mask elements. Values have the following meanings:
: auto
:: The element does not clip.
: rect() = rect( <>, <>, <>, <> )
::
<> and <> specify offsets from the top border edge of the box, and <>, and <> 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 <> value or ''clip/auto''. Negative lengths are permitted. The value ''clip/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., ''clip/auto'' means the same as ''0'' for <> and <>, the same as the used value of the height plus the sum of vertical padding and border widths for <>, and the same as the used value of the width plus the sum of the horizontal padding and border widths for <>, such that four ''clip/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 <> and <> have the same value (or <> and <> have the same value), and conversely that no pixels within the element's border box remain hidden when these values are ''clip/auto''.
The 'clip' property is a presentation attribute for SVG elements.
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:
Appendix B: Compute stroke bounding box
The algorithm to compute the stroke bounding box is as follows, depending on the type of element:
: a graphics element without use or image
: an a element with a text content element
::
1. Let box be a rectangle initialized to the object bounding box of element.
2. If the used value of 'stroke-width' <= 0 or the used value of 'stroke' is ''stroke/none'' return box.
3. Let delta be the inflation value initialized to the half of the 'stroke-width'.
4. If element is not rect, ellipse, circle or image just follow one of the following conditions in the order they apply:
: the used value for 'stroke-linejoin' is ''miter''
::
1. Let miter be the used value of 'stroke-miterlimit'.
2. If miter is smaller than the square root of 2 and if the used value for 'stroke-linecap' is ''square'', multiply delta with the square root of 2. Otherwise, multiply delta with miter.
: the used value for 'stroke-linecap' is ''square''
::
1. Multiply delta with the square root of 2.
5. Inflate box with the value of delta.
6. Return box.
Note: The values of the 'stroke-opacity', 'stroke-dasharray' and 'stroke-dashoffset' do not affect the calculation of the stroke bounding box.
: a container element
: use
::
1. Let parent be the container element if it is one, or the root of the use element's shadow tree otherwise.
2. For each child child of parent
1. Invoke the stroke bounding box algorithm with child.
2. Let childBox be the returned box value of the invoked algorithm.
3. Map childBox from the coordinate space of child to the coordinate space of parent.
3. Let box be the union of all childBoxes.
4. Return box.
: image
::
1. Return the object bounding box of element.
Note: A future version of the SVG specification may override this section.
Appendix C: DOM interfaces
## Interface SVGClipPathElement ## {#InterfaceSVGClipPathElement}
The SVGClipPathElement interface corresponds to the clipPath element.
[Exposed=Window]
interface SVGClipPathElement : SVGElement {
readonly attribute SVGAnimatedEnumeration clipPathUnits;
readonly attribute SVGAnimatedTransformList transform;
};
: Attributes:
::
:
clipPathUnits
:: Corresponds to attribute
clipPathUnits on the given
clipPath element. Takes one of the constants defined in
SVGUnitTypes.
:
transform
:: Corresponds to presentation attribute 'transform' on the given element.
[Exposed=Window]
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;
};
: Attributes:
::
:
maskUnits
:: Corresponds to attribute
maskUnits on the given
mask element. Takes one of the constants defined in
SVGUnitTypes.
:
maskContentUnits
:: Corresponds to attribute
maskContentUnits on the given
mask element. Takes one of the constants defined in
SVGUnitTypes.
:
x
:: Corresponds to attribute
x on the given
mask element.
:
y
:: Corresponds to attribute
y on the given
mask element.
:
width
:: Corresponds to attribute
width on the given
mask element.
:
height
:: Corresponds to attribute
height on the given
mask element.
Changes since last publication
The following changes were made since the 5 August 2021 Candidate Recommendation Draft.
* Added a privacy concern regarding hiding sensitive content
* Separated Security and Privacy sections
* Minor editorial and markup changes
* Added Web Platform Tests coverage
The following changes were made since the 26 August 2014 Candidate Recommendation.
* Allowed the <<'mask-mode'>> value in the 'mask' shorthand to appear anywhere other than between <<'mask-position'>> and <<'mask-size'>>.
* Removed Implements SVGUnitTypes on clipPath and mask elements.
* Apply properties that apply to all graphics elements to the use element as well.
* Change initial value of 'mask-position' to ''0% 0%'' and of 'mask-repeat' to ''mask-repeat/repeat''.
* Remove margin-box as possible value from 'mask-origin' and 'mask-clip'.
* Clarify that 'mask-clip' has no affect on mask layer images that reference a mask element.
* Clarify 'mask' shorthand behavior on appearance of one <> and the ''no-clip'' keyword.
* 'mask-mode' on a mask layer image that is a reference to a mask element with a value of ''match-source'' should take the value of the 'mask-type' property on this mask element.
* Mapping of boxes for SVG elements with and without associated CSS layout box changed to match mapping in Fill and Stroke spec.
* Editorial changes.
The following changes were made since the 22 May 2014 Working Draft.
* Change the inital value of 'mask-size' from border-box to auto.
The following changes were made since the 13 February 2014 Working Draft.
* Renamed mask-box* properties and terms to mask-border*.
* Added support for multiple mask layers. (Similar to multiple background layers for 'background'.)
* Added the 'mask-composite' property to control compositing of multiple mask layer images with the keywords ''add'', ''subtract'', ''intersect'' and ''exclude''.
* 'mask-border-slice' without keyword ''mask-border-slice/fill'' does not clip middle piece of content anymore. Changed initial value from ''0 fill'' to ''0''.
* Better description for 'clip-rule', 'mask-mode' and 'mask-type'.
* Rename ''mask-border-slice/fill'' and ''stroke'' keywords to ''clip-path/fill-box'' and ''clip-path/stroke-box''.
* Added definition for stroke bounding box.
* Better differentiation between mask images: mask layer image and mask border image.
The following changes were made since the 29 October 2013 Last Call Working Draft.
* Remove note that a future version of the spec will allow controlling hit testing on clipping.
* Changed order of sections within the document.
* Make clear that the used value of the properties 'mask-image', 'mask-repeat', 'mask-position', 'mask-clip', 'mask-origin' and 'mask-size' must be ignored for <>, not the properties.
* "Animatable" section of 'mask-size', 'mask-position' described as repeatable list of lists. Changed to a single list.
* Computed value of 'mask-repeat' and 'mask-position' was described as list of items. Changed to have just one value.
* Change link to ED from https://drafts.fxtf.org/masking/ to https://drafts.fxtf.org/css-masking-1/
The following significant changes were made since the 20 June 2013 Working Draft.
* 'mask' resets ''mask-box'' properties.
* Initial values for 'mask-repeat', 'mask-position' and 'mask-origin' changed to ''mask-repeat/no-repeat'', ''mask-position/center'' and ''mask-origin/border-box''.
* Multiple layers of mask images were deferred to a future level of this specification.
* Added security model for pixel operations and fetching of masking and clipping resources.
* Deferred "child" and select() function to next level.
The following significant changes were made since the 15 November 2012 Working Draft.
* Better integration with terms and definitions of CSS Backgrounds and Borders module.
* Syntax changes on 'mask' shorthand property to be conform with 'background' shorthand property.
* Define how the implementation can differ between an SVG resource (mask, clipPath) and an image resource.
* Added 'mask-mode' property to alter between luminance and alpha mask on 'mask-image'.
* Adapt IDL definition of SVGMaskElement and SVGClipPathElement to WebIDL.
* Further editorial changes.
See detailed list of changes in the ChangeLog.
Acknowledgments
Thanks to Elika J. Etemad, Cameron McCormack, Liam R. E. Quin, Björn Höhrmann, Alan Stearns, Jarek Foksa, David Baron, Boris Zbarsky, Markus Stange and Sara Soueidan for their careful reviews, comments, and corrections. Special thanks to CJ Gammon for graphical assets.
