CSS Masking Module Level 1

W3C Last Call Working Draft, 22 May 2014

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

Abstract

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

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

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

Status of this document

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

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

The (archived) public mailing list [email protected] (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 includes 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 19 June 2014.

Table of Contents

1 Introduction

This section is not normative.

This specification defines two different graphical operations which both fully or partly hide portions of an object: clipping and masking.

1.1 Clipping

A closed vector path, shape or polygon defines a so called clipping path. This clipping path is a region (in the absence of anti-aliasing) where everything on the “inside” of this region is allowed to show through but everything on the outside is “clipped out” and does not appear on the canvas.

Example Mask

A clipping path (middle) is applied on a polygon shaded with different colors (left). This results in a “clipped out” shape (right).

The clip-path property can use specified basic shapes as clipping path or reference an clipPath element with graphics elements to be used as clipping path.

1.2 Masking

The effect of applying a mask to a graphical object is as if the graphical object will be painted onto the background through a mask, thus completely or partially masking out parts of the graphical object.

Example Mask

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

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

The mask-image property may reference a mask element. The content of the mask element serves as the mask.

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. This mask can then be sized and positioned just like CSS background images using the mask-position, mask-size and other characterizing properties.

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

The mask property serves as a shorthand property for all mask-border and mask-image affiliated properties.

Note: While masking gives many possibilities for enhanced graphical effects and in general provides more control over the “visible portions” of the content, clipping paths can perform better and basic shapes are easier to interpolate.

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 the element is styled under absence of filter effects, masking, clipping and opacity. Then the element and its descendants are drawn on a temporary canvas. In a last step the following effects are applied to the element in order: filter effects [FILTER-EFFECTS], clipping, masking and opacity.

This specification allows compositing multiple mask layers with the Porter Duff compositing operators defined in CSS Compositing and Blending [COMPOSITING-1].

The term object bounding box follows the definition in SVG 1.1 [SVG11].

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 CSS-wide keywords such as inherit as their property value [CSS3VAL]. For readability it has not been repeated explicitly.

4 Terminology

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 layer image background images
mask painting area background painting area
mask-size background-size
mask-position background-position
mask positioning area background positioning area
mask border image border-image
mask border image area border image area

5 Clipping Paths

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

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

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

A clipping path affects the rendering of an element. It does not affect the element’s inherent geometry. The geometry of a clipped element (i.e. 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.

Consider a shape that is clipped by a clipping path applied to an ancestor:


  

The shape is referenced by a element:


The geometry of the shape is not influenced by the circular clipping path.

By default, pointer events must not be dispatched on the clipped-out (non-visible) regions of a shape. For example, an element with a dimension of 10px to 10px which is clipped to a circle with a radius of 5px will not receive click events outside the clipping region.

5.1 Clipping Shape: the clip-path property

Name:clip-path
Value: | [ || ] | none
Initial:none
Applies to:All elements. In SVG, it applies to container elements excluding the element and all graphics elements
Inherited:no
Media:visual
Computed value:as specified, but with values made absolute
Percentages:as specified
Animatable:as specified for [CSS-SHAPES], otherwise no

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

 = 
 =  | fill-box | stroke-box | view-box
A basic shape function as defined in the CSS Shapes module [CSS-SHAPES]. A basic shape makes use of the specified reference box to size and position the basic shape. If no reference box is specified, the border-box will be used as reference box.

If specified in combination with a it provides the reference box for the .

If specified by itself, uses the edges of the specified box, including any corner shaping (e.g. defined by border-radius [CSS3BG]), as clipping path. See also “Shapes from box values” [CSS-SHAPES].

fill-box
Uses the object bounding box as reference box.
stroke-box
Uses the stroke bounding box as reference box.
view-box

Uses the nearest SVG viewport as reference box.

If a ‘viewBox‘ attribute is specified for the SVG viewport creating element:

none
No clipping path gets created.

For SVG elements without associated CSS layout box, the used value for content-box, padding-box, border-box and margin-box is fill-box.

For elements with associated CSS layout box, the used value for fill-box, stroke-box and view-box is border-box.

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

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-path: polygon(15px 99px, 30px 87px, 65px 99px, 85px 55px,
              122px 57px, 184px 73px, 198px 105px, 199px 150px,
              145px 159px, 155px 139px, 126px 120px, 112px 138px,
              80px 128px, 39px 126px, 24px 104px);

clip-path: url("#clip1");


  

6 SVG Clipping Path Sources

6.1 The clipPath element

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