14 Clipping, Masking and Compositing


Contents


 

14.1 Introduction

SVG supports the following clipping/masking features:

One key distinction between a clipping path and a mask is that clipping paths are hard masks (i.e., the silhouette consists of either fully opaque pixels or fully transparent pixels, with the possible exception of antialiasing along the edge of the silhouette) whereas masks consist of an image where each pixel value indicates the degree of transparency vs. opacity. In a mask, each pixel value can range from fully transparent to fully opaque.

SVG supports only simple alpha blending compositing (see Simple Alpha Compositing).

(Insert drawings showing a clipping path, a grayscale imagemask, simple alpha blending and more complex blending.)

14.2 Simple alpha compositing

Graphics elements are blended into the elements already rendered on the canvas using simple alpha compositing, in which the resulting color and opacity at any given pixel on the canvas is the result of the following formulas (all color values use premultiplied alpha):

Er, Eg, Eb    - Element color value
Ea            - Element alpha value
Cr, Cg, Cb    - Canvas color value (before blending)
Ca            - Canvas alpha value (before blending)
Cr', Cg', Cb' - Canvas color value (after blending)
Ca'           - Canvas alpha value (after blending)

Ca' = 1 - (1 - Ea) * (1 - Ca)
Cr' = (1 - Ea) * Cr + Er
Cg' = (1 - Ea) * Cg + Eg
Cb' = (1 - Ea) * Cb + Eb

The following rendering properties, which provide information about the color space in which to perform the compositing operations, apply to compositing operations:


14.3 Clipping paths


14.3.1 Introduction

The clipping path restricts the region to which paint can be applied. Conceptually, any parts of the drawing that lie outside of the region bounded by the currently active clipping path are not drawn. A clipping path can be thought of as a 1-bit mask.


14.3.2 The initial clipping path

When an 'svg' element is either the root element in the document or is embedded within a document whose layout is determined according to the layout rules of CSS or XSL, then the user agent must establish an initial clipping path for the SVG document fragment. The 'overflow' and 'clip' properties along with additional SVG user agent processing rules determine the initial clipping path which the user agent establishes for the SVG document fragment:


14.3.3 The 'overflow' and 'clip' properties


'overflow'
Value:   visible | hidden | scroll | auto | inherit
Initial:   see prose
Applies to:   elements which establish a new viewport, 'pattern' elements and 'marker' elements
Inherited:   no
Percentages:   N/A
Media:   visual
Animatable:   yes

The 'overflow' property has the same parameter values and has the same meaning as defined in [CSS2-overflow]; however, the following additional points apply:

As a result of the above, the default behavior of SVG user agents is to establish a clipping path to the bounds of the initial viewport and to establish a new clipping path for each element which establishes a new viewport and each 'pattern' and 'marker' element.

For related information, see Clip to viewport vs. clip to viewBox.

'clip'
Value:   <shape> | auto | inherit
Initial:   auto
Applies to:   elements which establish a new viewport, 'pattern' elements and 'marker' elements
Inherited:   no
Percentages:   N/A
Media:   visual
Animatable:   yes

The 'clip' property has the same parameter values as defined in [CSS2-clip]. Unitless values, which indicate current user coordinates, are permitted on the coordinate values on the <shape>. The value of "auto" defines a clipping path along the bounds of the viewport created by the given element.


14.3.4 Clip to viewport vs. clip to viewBox

It is important to note that initial values for the 'overflow' and 'clip' properties and the user agent style sheet will result in an initial clipping path that is set to the bounds of the initial viewport. When attributes viewBox and preserveAspectRatio attributes are specified, it is sometime desirable that the clipping path be set to the bounds of the viewBox instead of the viewport (or reference rectangle, in the case of 'marker' and 'pattern' elements), particularly when preserveAspectRatio specifies uniform scaling and the aspect ratio of the viewBox does not match the aspect ratio of the viewport.

To set the initial clipping path to the bounds of the viewBox instead of the viewport, set the bounds of 'clip' property to the same rectangle as specified on the viewBox attribute. (Note that the parameters do not match. 'clip' takes values <top>, <right>,<bottom> and <left>, whereas viewBox takes values <min-x>, <min-y>, <width> and <height>.)

14.3.5 Establishing a new clipping path

A clipping path is defined with a 'clipPath' element. A clipping path is used/referenced using the 'clip-path' property.

A 'clipPath' element can contain 'path' elements, 'text' elements, other vector graphic 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 vector graphic shape elements. Indirect references are an error (see Error processing). 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.

It is an error if the 'clip-path' property references a non-existent object or if the referenced object is not a 'clipPath' element (see Error processing).

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 ancestor elements, or by the 'overflow' property on ancestor elements which establish a new viewport. Also, see the discussion of the initial clipping path.)

A couple of notes:


 
<!ENTITY % clipPathExt "" >
<!ELEMENT clipPath (%descTitleMetadata;,
                    (path|text|rect|circle|ellipse|line|polyline|polygon|
                     use|animate|set|animateMotion|animateColor|animateTransform
                     %ceExt;%clipPathExt;)*) >
<!ATTLIST clipPath
  %stdAttrs;
  %testAttrs;
  %langSpaceAttrs;
  externalResourcesRequired %Boolean; #IMPLIED
  class %ClassList; #IMPLIED
  style %StyleSheet; #IMPLIED
  %PresentationAttributes-FillStroke;
  %PresentationAttributes-FontSpecification;
  %PresentationAttributes-Graphics;
  %PresentationAttributes-TextContentElements;
  %PresentationAttributes-TextElements;
  transform %TransformList; #IMPLIED
  clipPathUnits (userSpaceOnUse | objectBoundingBox) #IMPLIED >

Attribute definitions:

clipPathUnits = "userSpaceOnUse | objectBoundingBox"
Defines the coordinate system for the contents of the 'clipPath'.
If clipPathUnits="userSpaceOnUse", the contents of the '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).
If clipPathUnits="objectBoundingBox", then the user coordinate system for the contents of the 'clipPath' element is established using the bounding box of the element to which the clipping path is applied (see Object bounding box units).
If attribute clipPathUnits is not specified, then the effect is as if a value of userSpaceOnUse were specified.
Animatable: yes.

Attributes defined elsewhere:
%stdAttrs;, %langSpaceAttrs;, class, transform, %testAttrs;, externalResourcesRequired, style, %PresentationAttributes-FillStroke;, %PresentationAttributes-FontSpecification;, %PresentationAttributes-Graphics;, %PresentationAttributes-TextContentElements;, %PresentationAttributes-TextElements;.

 
'clip-path'
Value:   <uri> | none | inherit
Initial:   none
Applies to:   all elements
Inherited:   no
Percentages:   N/A
Media:   visual
Animatable:   yes
<uri>
A URI reference to another graphical object within the same SVG document fragment which will be used as the clipping path.
'clip-rule'
Value:   nonzero | evenodd | inherit
Initial:   nonzero
Applies to:   graphics elements within a 'clipPath' element
Inherited:   yes
Percentages:   N/A
Media:   visual
Animatable:   yes
nonzero
See description of 'fill-rule' property.
evenodd
See description of 'fill-rule' property.

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 style="clip-rule:nonzero">
  <clipPath id="MyClip">
    <path d="..." style="clip-rule:evenodd" />
  </clipPath>
  <rect style="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 style="clip-rule:nonzero">
  <clipPath id="MyClip">
    <path d="..." />
  </clipPath>
  <rect style="clip-path:url(#MyClip); clip-rule:evenodd" ... />
</g>

14.4 Masking

In SVG, you can specify that any other graphics object or 'g' element can be used as an alpha mask for compositing the current object into the background.

A mask is defined with a 'mask' element. A mask is used/referenced using the 'mask' property.

A 'mask' can contain any graphical elements or grouping elements such as a 'g'.

It is an error if the 'mask' property references a non-existent object or if the referenced object is not a 'mask' element (see Error Processing).

The effect is as if the child elements of the 'mask' are rendered into an offscreen image. Any graphical object which uses/references the given 'mask' element will be painted onto the background through the mask, thus completely or partially masking out parts of the graphical object.

For a four-channel RGBA graphics object that is used as a mask, both the color channels and the alpha channel of the mask contribute to the masking operation. The alpha mask that is used to composite the current object into the background represents the product of the luminance of the color channels (determined using the luminance-to-alpha formulas as defined in the 'feColorMatrix' filter primitive) and the alpha channel from the mask.

For a three-channel RGB graphics object that is used as a mask (e.g., when referencing a 3-channel image file), the effect is as if the object were converted into a 4-channel RGBA image with the alpha channel uniformly set to 1.

For a single-channel image that is used as a mask (e.g., when referencing a 1-channel grayscale image file), the effect is as if the object were converted into a 4-channel RGBA image, where the single channel from the referenced object is used as the alpha channel and the color channels are set to 100% white.

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 alpha values (i.e., the product of the mask's luminance from its color channels multiplied by the mask's alpha channel).

Note that SVG 'path''s, shapes (e.g., 'circle') and 'text' are all treated as four-channel RGBA images for the purposes of masking operations.

Example mask01 uses an image to mask a rectangle.

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20001102//EN" 
  "http://www.w3.org/TR/2000/CR-SVG-20001102/DTD/svg-20001102.dtd">
<svg width="8cm" height="3cm">
  <desc>Example mask01 - blue text masked with gradient against red background
  </desc>
  <defs>
    <linearGradient id="Gradient" x1="0cm" y1="0cm" x2="8cm" y2="0cm">
      <stop offset="0" style="stop-color:black; stop-opacity:0"/>
      <stop offset="1" style="stop-color:black; stop-opacity:1"/>
    </linearGradient>
    <mask id="Mask">
      <rect x="0cm" y="0cm" width="8cm" height="3cm" style="fill:url(#Gradient)" />
    </mask>
    <text id="Text" x="4cm" y="2cm" 
          style="font-family:Verdana; font-size:1cm; text-anchor:middle">
      Masked text
    </text>
  </defs>

  <!-- Draw a pale red rectangle in the background -->
  <rect x="0cm" y="0cm" width="8cm" height="3cm" style="fill:#FF8080"/>
  
  <!-- Draw the text string twice. First, filled blue, with the mask applied.
       Second, outlined in black without the mask. -->
  <use xlink:href="#Text" style="fill:blue; mask:url(#Mask)"/>
  <use xlink:href="#Text" style="fill:none; stroke:black; stroke-width:.02cm"/>
</svg>
Example mask01
Example mask01 - blue text masked with gradient against red background

View this example as SVG (SVG-enabled browsers only)
 

<!ENTITY % maskExt "" >
<!ELEMENT mask (desc|title|metadata|defs|
                   path|text|rect|circle|ellipse|line|polyline|polygon|
                   use|image|svg|g|view|switch|a|altGlyphDef|
                   script|style|symbol|marker|clipPath|mask|
                   linearGradient|radialGradient|pattern|filter|cursor|font|
                   animate|set|animateMotion|animateColor|animateTransform|
                   color-profile|font-face
                   %ceExt;%maskExt;)*  >
<!ATTLIST mask
  %stdAttrs;
  %testAttrs;
  %langSpaceAttrs;
  externalResourcesRequired %Boolean; #IMPLIED
  class %ClassList; #IMPLIED
  style %StyleSheet; #IMPLIED
  %PresentationAttributes-All;
  transform %TransformList; #IMPLIED
  maskUnits (userSpaceOnUse | objectBoundingBox) #IMPLIED
  maskContentUnits (userSpaceOnUse | objectBoundingBox) #IMPLIED
  x %Coordinate; #IMPLIED
  y %Coordinate; #IMPLIED
  width %Length; #IMPLIED
  height %Length; #IMPLIED >

Attribute definitions:

maskUnits = "userSpaceOnUse | objectBoundingBox"
Defines the coordinate system for attributes x, y, width, height.
If maskUnits="userSpaceOnUse", x, y, width, 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).
If maskUnits="objectBoundingBox", x, y, width, height represent fractions or percentages of the bounding box of the element to which the mask is applied. (See Object bounding box units.)
then the effect is as if a value of objectBoundingBox were specified.
Animatable: yes.
maskContentUnits = "userSpaceOnUse | objectBoundingBox"
Defines the coordinate system for the contents of the 'mask'.
If maskContentUnits="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).
If maskContentUnits="objectBoundingBox", the user coordinate system for the contents of the 'mask' is established using the bounding box of the element to which the mask is applied. (See Object bounding box units.)
If attribute maskContentUnits is not specified, then the effect is as if a value of userSpaceOnUse were specified.
Animatable: yes.
x = "<coordinate>"
The x-axis coordinate of one corner of the rectangle for the largest possible offscreen buffer. Note that the clipping path used to render any graphics within the mask will consist of the intersection of the current clipping path associated with the given object and the rectangle defined by x, y, width, height.
If the attribute is not specified, the effect is as if a value of "-10%" were specified.
Animatable: yes.
y = "<coordinate>"
The y-axis coordinate of one corner of the rectangle for the largest possible offscreen buffer.
If the attribute is not specified, the effect is as if a value of "-10%" were specified.
Animatable: yes.
width = "<length>"
The width of the largest possible offscreen buffer. Note that the clipping path used to render any graphics within the mask will consist of the intersection of the current clipping path associated with the given object and the rectangle defined by x, y, width, height.
A negative value is an error (see Error processing). A value of zero disables rendering of the element.
If the attribute is not specified, the effect is as if a value of "120%" were specified.
Animatable: yes.
height = "<length>"
The height of the largest possible offscreen buffer.
A negative value is an error (see Error processing). A value of zero disables rendering of the element.
If the attribute is not specified, the effect is as if a value of "120%" were specified.
Animatable: yes.

Attributes defined elsewhere:
%stdAttrs;, %langSpaceAttrs;, class, transform, %testAttrs;, externalResourcesRequired, style, %PresentationAttributes-All;.

The following is a description of the 'mask' property.

'mask'
Value:   <uri> | none | inherit
Initial:   none
Applies to:   all elements
Inherited:   no
Percentages:   N/A
Media:   visual
Animatable:   yes
<uri>
A URI reference to another graphical object which will be used as the mask.

14.5 Object and group opacity: the 'opacity' property

There are several opacity properties within SVG:

Except for object/group opacity (described just below), all other opacity properties are involved in intermediate rendering operations. Object/group opacity can be thought of conceptually as a postprocessing operation. Conceptually, after the object/group is rendered into an RGBA offscreen image, the object/group opacity setting specifies how to blend the offscreen image into the current background.

'opacity'
Value:   <alphavalue> | inherit
Initial:   1
Applies to:   all elements
Inherited:   no
Percentages:   N/A
Media:   visual
Animatable:   yes
<alphavalue>
The uniform opacity setting to be applied across an entire object. Any values outside the range 0.0 (fully transparent) to 1.0 (fully opaque) will be clamped to this range. (See Clamping values which are restricted to a particular range.) If the object is a container element such as a 'g', then the effect is as if the contents of the 'g' were blended against the current background using a mask where the value of each pixel of the mask is <alphavalue>. (See Simple alpha compositing.)

Example opacity01, illustrates various usage of the 'opacity' property on elements and groups.

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20001102//EN" 
  "http://www.w3.org/TR/2000/CR-SVG-20001102/DTD/svg-20001102.dtd">
<svg width="12cm" height="3.5cm" viewBox="0 0 1200 350">
  <desc>Example opacity01 - opacity property</desc>

  <rect x="1" y="1" width="1198" height="348"
        style="fill:none; stroke:blue"/>

  <!-- Background blue rectangle -->
  <rect x="1cm" y="1cm" width="10cm" height="1.5cm" style="fill:#0000ff" />

  <!-- Red circles going from opaque to nearly transparent -->
  <circle cx="2cm" cy="1cm" r=".5cm" style="fill:red; opacity:1" />
  <circle cx="4cm" cy="1cm" r=".5cm" style="fill:red; opacity:.8" />
  <circle cx="6cm" cy="1cm" r=".5cm" style="fill:red; opacity:.6" />
  <circle cx="8cm" cy="1cm" r=".5cm" style="fill:red; opacity:.4" />
  <circle cx="10cm" cy="1cm" r=".5cm" style="fill:red; opacity:.2" />

  <!-- Opaque group, opaque circles -->
  <g style="opacity:1">
    <circle cx="1.825cm" cy="2.5cm" r=".5cm" style="fill:red; opacity:1" />
    <circle cx="2.175cm" cy="2.5cm" r=".5cm" style="fill:green; opacity:1" />
  </g>
  <!-- Group opacity: .5, opacity circles -->
  <g style="opacity:.5">
    <circle cx="3.825cm" cy="2.5cm" r=".5cm" style="fill:red; opacity:1" />
    <circle cx="4.175cm" cy="2.5cm" r=".5cm" style="fill:green; opacity:1" />
  </g>
  <!-- Opaque group, semi-transparent green over red -->
  <g style="opacity:1">
    <circle cx="5.825cm" cy="2.5cm" r=".5cm" style="fill:red; opacity:.5" />
    <circle cx="6.175cm" cy="2.5cm" r=".5cm" style="fill:green; opacity:.5" />
  </g>
  <!-- Opaque group, semi-transparent red over green -->
  <g style="opacity:1">
    <circle cx="8.175cm" cy="2.5cm" r=".5cm" style="fill:green; opacity:.5" />
    <circle cx="7.825cm" cy="2.5cm" r=".5cm" style="fill:red; opacity:.5" />
  </g>
  <!-- Group opacity .5, semi-transparent green over red -->
  <g style="opacity:.5">
    <circle cx="9.825cm" cy="2.5cm" r=".5cm" style="fill:red; opacity:.5" />
    <circle cx="10.175cm" cy="2.5cm" r=".5cm" style="fill:green; opacity:.5" />
  </g>
</svg>
Example opacity01
Example opacity01 - opacity property

View this example as SVG (SVG-enabled browsers only)
 

In the example above, the top row of circles have differing opacities, ranging from 1.0 to 0.2. The bottom row illustrates five 'g' elements, each of which contains overlapping red and green circles, as follows:


14.6 DOM interfaces

The following interfaces are defined below: SVGClipPathElement, SVGMaskElement.


Interface SVGClipPathElement

The SVGClipPathElement interface corresponds to the 'clipPath' element.


IDL Definition
interface SVGClipPathElement : 
                SVGElement,
                SVGTests,
                SVGLangSpace,
                SVGExternalResourcesRequired,
                SVGStylable,
                SVGTransformable,
                SVGUnitTypes { 

  readonly attribute SVGAnimatedEnumeration clipPathUnits;
};

Attributes
readonly SVGAnimatedEnumeration clipPathUnits
Corresponds to attribute clipPathUnits on the given 'clipPath' element. Takes one of the constants defined in SVGUnitTypes.

Interface SVGMaskElement

The SVGMaskElement interface corresponds to the 'mask' element.


IDL Definition
interface SVGMaskElement : 
                SVGElement,
                SVGTests,
                SVGLangSpace,
                SVGExternalResourcesRequired,
                SVGStylable,
                SVGTransformable,
                SVGUnitTypes { 

  readonly attribute SVGAnimatedEnumeration maskUnits;
  readonly attribute SVGAnimatedLength      x;
  readonly attribute SVGAnimatedLength      y;
  readonly attribute SVGAnimatedLength      width;
  readonly attribute SVGAnimatedLength      height;
};

Attributes
readonly SVGAnimatedEnumeration maskUnits
Corresponds to attribute maskUnits on the given 'mask' element. Takes one of the constants defined in SVGUnitTypes.
readonly SVGAnimatedLength x
Corresponds to attribute x on the given 'mask' element.
readonly SVGAnimatedLength y
Corresponds to attribute y on the given 'mask' element.
readonly SVGAnimatedLength width
Corresponds to attribute width on the given 'mask' element.
readonly SVGAnimatedLength height
Corresponds to attribute height on the given 'mask' element.