CSS Masking Module Level 1 (original) (raw)

Abstract

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

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

Clipping describes the visible region of visual elements. The region can be described by using certain SVG graphics elements or basic shapes. Anything outside of this region is not rendered.CSS is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, in speech, etc.

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

Publication as a Last Call Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

The (archived) public mailing listpublic-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 theGraphics Activity).

This document was produced by groups operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures (CSS) and a public list of any patent disclosures (SVG) made in connection with the deliverables of each group; these pages also include instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

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

Table of Contents

• 1Introduction
• 2Module interactions
• 3Values
• 4Terminology
• 5Layered Masks
  • 5.1The mask-image property
  • 5.2The mask-source-type property
  • 5.3The mask-repeat property
  • 5.4The mask-position property
  • 5.5The mask-clip property
  • 5.6The mask-origin property
  • 5.7The mask-size property
  • 5.8The mask property
  • 5.9The mask-type property
  • 5.10The element
  • 5.11The Mask Image Rendering Model
    * 5.11.1Mask Source values
• 6Box-Image Masks
  • 6.1The mask-box-image-source property
  • 6.2The mask-box-image-slice property
  • 6.3The mask-box-image-width property
  • 6.4The mask-box-image-outset property
  • 6.5The mask-box-image-repeat property
  • 6.6The mask-box-image property
  • 6.7Masking with the mask-box-image
• 7Clipping paths
  • 7.1The clip-path property
  • 7.2The clip-rule property
  • 7.3The clip property
  • 7.4The element
  • 7.5Clipping paths, geometry, and pointer events
• 8Security
• 9DOM interfaces
  • 9.1Interface SVGClipPathElement
  • 9.2Interface SVGMaskElement
• Changes since last publication
• Acknowledgments
• Conformance
  • Document conventions
  • Conformance classes
  • Partial implementations
  • Experimental implementations
  • Non-experimental implementations
• References
  • Normative References
  • Informative References
• Index
• Property index

1 Introduction

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

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

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

The mask-image property may reference a 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 element. The mask property serves as a shorthand property for mask-box-image, mask-image and other characterizing properties.

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

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

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

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

2 Module interactions

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

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

3 Values

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

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

4 Terminology

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

bounding client rect

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

local coordinate system

user coordinate system

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

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

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

object bounding box units

The bounding client rect defines the coordinate system in which to resolve values, as defined in object bounding box units [SVG11].

mask source

An off-screen image which has been initialized to transparent black. The graphical object to which the mask is applied will be painted onto the background through the mask, thus completely or partially masking out parts of the graphical object.

clipping path

A combination of SVG graphics element or basic shapes which serve as the outline of a visual element where everything on the "inside" of the outline is allowed to show through but everything on the outside is masked out. (See clip-path.)

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

5 Layered Masks

5.1 The mask-image property

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

= none | |

=

A URL reference to a element (for example url(commonmasks.svg#mask)) or to a CSS image.

none

A value of none counts as an image layer but does not mask the element.

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

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

See the section “Mask source values” for how to process a .

Examples for mask references:

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

5.2 The mask-source-type property

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

= alpha | luminance | auto

Values have the following meanings:

alpha

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

luminance

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

auto

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

If the of the mask-image property is of type 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 element to alpha. The mask-image property has a reference to this 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.

5.3 The mask-repeat property

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

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

Example(s):

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

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

5.4 The mask-position property

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

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

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

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

mask-position: right 3em bottom 10px

5.5 The mask-clip property

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

Values have the following meanings:

border-box

The painted content is rectricted to (clipped to) theborder box respectively painting box for objects without associated layout box.

padding-box

The painted content is rectricted to (clipped to) thepadding box.

content-box

The painted content is rectricted to (clipped to) thecontent box respectively object bounding box [SVG11] for objects without associated layout box.

no-clip

The painted content is not restricted (not clipped). The mask painting area is set to the bounding client rect.

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

5.6 The mask-origin property

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

padding-box

The position is relative to the padding box. (For single boxes0 0 is the upper left corner of the padding edge,100% 100% is the lower right corner.)

border-box

The position is relative to the border box respectively painting box for objects without associated layout box.

content-box

The position is relative to the content box respectively object bounding box [SVG11] for objects without associated layout box.

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

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

5.7 The mask-size property

Specifies the size of the mask images.

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

5.8 The mask property

= ? || [ / ]? || || || [ | no-clip ]

If one value is present then it 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 properties mask-image, mask-repeat, mask-position, mask-clip, mask-origin and mask-size must have no effect if references a element. In this case the element defines position, sizing and clipping of the mask source.

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

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

5.9 The mask-type property

The mask-type property defines whether the content of the 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 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 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 element that is computed to luminance. The mask source is used as an alpha mask.

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

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

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

5.10 The element