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

This document was produced by the CSS Working Group (part of the Style Activity) and the SVG Working Group (part of theGraphics Activity) as aCandidate Recommendation.

This document takes into account comments during previous last Calls; see Disposition of Comments for the most recent Last Call and the one before that. A preliminary implementation report is also available. There are no features at risk.

A Candidate Recommendation is a document that has been widely reviewed and is ready for implementation. W3C encourages everybody to implement this specification and return comments to the (archived) public mailing listpublic-fx@w3.org (see instructions). When sending e-mail, please put the text “css-masking” in the subject, preferably like this: “[css-masking] _…summary of comment…_”

Publication as a Candidate Recommendation 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.

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 withsection 6 of the W3C Patent Policy.

A test suite and implementation report for CSS Masking Module Level 1 will be developed during the Candidate Recommendation phase, which will last a minimum of six months, and at least until 26 February 2015. See the section “CR exit criteria” for more details.

Table of Contents

• 1 Introduction
  • 1.1 Clipping
  • 1.2 Masking
• 2 Module interactions
• 3 Values
• 4 Terminology
• 5 Clipping Paths
  • 5.1 Clipping Shape: the clip-path property
• 6 SVG Clipping Path Sources
  • 6.1 The clipPath element
  • 6.2 Winding Rules: the clip-rule property
• 7 Positioned Masks
  • 7.1 Mask Image Source: the mask-image property
  • 7.2 Mask Image Interpretation: the mask-mode property
  • 7.3 Tiling Mask Images: The mask-repeat property
  • 7.4 Positioning Mask Images: the mask-position property
  • 7.5 Masking Area: the mask-clip property
  • 7.6 Positioning Area: the mask-origin property
  • 7.7 Sizing Mask Images: the mask-size property
  • 7.8 Compositing mask layers: the mask-composite property
  • 7.9 Mask Shorthand: the mask property
  • 7.10 The Mask Image Rendering Model
    * 7.10.1 Mask processing
    * 7.10.2 Layering Multiple Mask Images
• 8 Border-Box Mask
  • 8.1 Mask Border Image Source: the mask-border-source property
  • 8.2 Mask Border Image Interpretation: the mask-border-mode property
  • 8.3 Mask Border Image Slicing: the mask-border-slice property
  • 8.4 Masking Areas: the mask-border-width property
  • 8.5 Edge Overhang: the mask-border-outset property
  • 8.6 Mask Border Image Tiling: the mask-border-repeat property
  • 8.7 Mask Border Image Shorthand: the mask-border property
  • 8.8 Masking with the mask border image
• 9 SVG Mask Sources
  • 9.1 The mask element
  • 9.2 Mask Source Interpretation: the mask-type property
• 10 Security
• Appendix A: The deprecated clip property
• Appendix B: Compute stroke bounding box
• Appendix C: DOM interfaces
  • Interface SVGClipPathElement
  • Interface SVGMaskElement
• Changes since last publication
• Acknowledgments
• Conformance
  • Document conventions
  • Conformance classes
  • Partial implementations
  • Experimental implementations
  • Non-experimental implementations
  • CR exit criteria
• References
  • Normative References
  • Informative References
• Index
• Property index

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.

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.

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:

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:

<g clip-path="circle()">
<path id="shape" d="M0,0 L10,10, L 20,0 z"/>
</g>

The shape is referenced by a element:

<use xlink:href="#shape"/>

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

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:

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

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.

This example demonstrates the use of the basic shape <polygon()> as clipping path. Each space separated length pair represents one point of the polygon. The visualized clipping path can be seen in the introduction.

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

In this example, the clip-path property references an SVG clipPath element. Each comma separated length pair represents one point of the polygon. As for the previous example, the visualized clipping path can be seen in the introduction.

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

<clipPath id="clip1">
    <polygon points="15,99 30,87 65,99 85,55 122,57 184,73 198,105
      199,150 145,159 155,139 126,120 112,138 80,128 39,126
      24,104"/>
</clipPath>

6 SVG Clipping Path Sources

6.1 The clipPath element