14 Clipping, Masking and Compositing

Contents

• 14.1 Introduction
• 14.2 Simple alpha compositing
• 14.3 Clipping paths
  • 14.3.1 Introduction
  • 14.3.2 The initial clipping path
  • 14.3.3 The Ä�ā‚¬ļæ½overflowÄ�ā‚¬ā„¢ and Ä�ā‚¬ļæ½clipÄ�ā‚¬ā„¢ properties
  • 14.3.4 Clip to viewport vs. clip to Ä�ā‚¬ļæ½viewBoxÄ�ā‚¬ā„¢
  • 14.3.5 Establishing a new clipping path: the Ä�ā‚¬ļæ½clipPathÄ�ā‚¬ā„¢ element
  • 14.3.6 Clipping paths, geometry, and pointer events
• 14.4 Masking
• 14.5 Object and group opacity: the Ä�ā‚¬ļæ½opacityÄ�ā‚¬ā„¢ property
• 14.6 DOM interfaces
  • 14.6.1 Interface SVGClipPathElement
  • 14.6.2 Interface SVGMaskElement

14.1 Introduction

SVG supports the following clipping/masking features:

• clipping paths, which uses any combination of Ä�ā‚¬ļæ½pathÄ�ā‚¬ā„¢, Ä�ā‚¬ļæ½textÄ�ā‚¬ā„¢ and basic shapes to serve as the outline of a (in the absence of anti-aliasing) 1-bit mask, where everything on the "inside" of the outline is allowed to show through but everything on the outside is masked out
• masks, which are container elements which can contain graphics elements or other container elements which define a set of graphics that is to be used as a semi-transparent mask for compositing foreground objects into the current background.

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 anti-aliasing 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).

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:

• Ä�ā‚¬ļæ½color-interpolationÄ�ā‚¬ā„¢
• Ä�ā‚¬ļæ½color-renderingÄ�ā‚¬ā„¢

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 mask wherein those pixels outside the clipping path are black with an alpha value of zero and those pixels inside the clipping path are white with an alpha value of one (with the possible exception of anti-aliasing along the edge of the silhouette).

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

The Ä�ā‚¬ļæ½overflowÄ�ā‚¬ā„¢ property has the same parameter values and has the same meaning as defined in CSS2 ([CSS2], section 11.1.1); however, the following additional points apply:

• The Ä�ā‚¬ļæ½overflowÄ�ā‚¬ā„¢ property applies to elements that establish new viewports (e.g., Ä�ā‚¬ļæ½svgÄ�ā‚¬ā„¢ elements), Ä�ā‚¬ļæ½patternÄ�ā‚¬ā„¢ elements and Ä�ā‚¬ļæ½markerÄ�ā‚¬ā„¢ elements. For all other elements, the property has no effect (i.e., a clipping rectangle is not created).
• For those elements to which the Ä�ā‚¬ļæ½overflowÄ�ā‚¬ā„¢ property can apply, if the Ä�ā‚¬ļæ½overflowÄ�ā‚¬ā„¢ property has the value hidden or scroll, the effect is that a new clipping path in the shape of a rectangle is created. The result is equivalent to defining a Ä�ā‚¬ļæ½clipPathÄ�ā‚¬ā„¢ element whose content is a Ä�ā‚¬ļæ½rectÄ�ā‚¬ā„¢ element which defines the equivalent rectangle, and then specifying the <uri> of this Ä�ā‚¬ļæ½clipPathÄ�ā‚¬ā„¢ element on the Ä�ā‚¬ļæ½clip-pathÄ�ā‚¬ā„¢ property for the given element.
• If the Ä�ā‚¬ļæ½overflowÄ�ā‚¬ā„¢ property has a value other than hidden or scroll, the property has no effect (i.e., a clipping rectangle is not created).
• Within SVG content, the value auto is equivalent to the value visible.
• When an outermost svg element is embedded inline within a parent XML grammar which uses CSS layout ([CSS2], chapter 9) or XSL formatting [XSL], if the Ä�ā‚¬ļæ½overflowÄ�ā‚¬ā„¢ property has the value hidden or scroll, then the user agent will establish an initial clipping path equal to the bounds of the initial viewport; otherwise, the initial clipping path is set according to the clipping rules as defined in CSS2 ([CSS2], section 11.1.1).
• When an outermost svg element is stand-alone or embedded inline within a parent XML grammar which does not use CSS layout or XSL formatting, the Ä�ā‚¬ļæ½overflowÄ�ā‚¬ā„¢ property on the outermost svg element is ignored for the purposes of visual rendering and the initial clipping path is set to the bounds of the initial viewport.
• The initial value for Ä�ā‚¬ļæ½overflowÄ�ā‚¬ā„¢ as defined in [CSS2-overflow] is 'visible', and this applies also to the root Ä�ā‚¬ļæ½svgÄ�ā‚¬ā„¢ element; however, for child elements of an SVG document, SVG's user agent style sheet overrides this initial value and sets the Ä�ā‚¬ļæ½overflowÄ�ā‚¬ā„¢ property on elements that establish new viewports (e.g., Ä�ā‚¬ļæ½svgÄ�ā‚¬ā„¢ elements), Ä�ā‚¬ļæ½patternÄ�ā‚¬ā„¢ elements and Ä�ā‚¬ļæ½markerÄ�ā‚¬ā„¢ elements to the value 'hidden'.

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Ä�ā‚¬ā„¢.

The Ä�ā‚¬ļæ½clipÄ�ā‚¬ā„¢ property has the same parameter values as defined in CSS2 ([CSS2], section 11.1.2). 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Ä�ā‚¬ā„¢, 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: the Ä�ā‚¬ļæ½clipPathÄ�ā‚¬ā„¢ element

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, basic 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 basic shape elements. Indirect references are an error (see Error processing).

The raw geometry of each child element exclusive of rendering properties such as Ä�ā‚¬ļæ½fillÄ�ā‚¬ā„¢, Ä�ā‚¬ļæ½strokeÄ�ā‚¬ā„¢, Ä�ā‚¬ļæ½stroke-widthÄ�ā‚¬ā„¢ within a Ä�ā‚¬ļæ½clipPathÄ�ā‚¬ā„¢ conceptually defines a 1-bit mask (with the possible exception of anti-aliasing along the edge of the geometry) which represents the silhouette of the graphics associated with that element. Anything outside the outline of the object is masked out. If a child element is made invisible by Ä�ā‚¬ļæ½displayÄ�ā‚¬ā„¢ or Ä�ā‚¬ļæ½visibilityÄ�ā‚¬ā„¢ it does not contribute to the clipping path. When the Ä�ā‚¬ļæ½clipPathÄ�ā‚¬ā„¢ element contains multiple child elements, 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. Thus, a point is inside the clipping path if it is inside any of the children of the Ä�ā‚¬ļæ½clipPathÄ�ā‚¬ā„¢.

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:

• The Ä�ā‚¬ļæ½clipPathÄ�ā‚¬ā„¢ element itself and its child elements do not inherit clipping paths from the ancestors of the Ä�ā‚¬ļæ½clipPathÄ�ā‚¬ā„¢ element.
• The Ä�ā‚¬ļæ½clipPathÄ�ā‚¬ā„¢ element or any of its children can specify property Ä�ā‚¬ļæ½clip-pathÄ�ā‚¬ā„¢.
  If a valid Ä�ā‚¬ļæ½clip-pathÄ�ā‚¬ā„¢ reference is placed on a Ä�ā‚¬ļæ½clipPathÄ�ā‚¬ā„¢ element, the resulting clipping path is the intersection of the contents of the Ä�ā‚¬ļæ½clipPathÄ�ā‚¬ā„¢ element with the referenced clipping path.
  If a valid Ä�ā‚¬ļæ½clip-pathÄ�ā‚¬ā„¢ reference is placed on one of the children of a Ä�ā‚¬ļæ½clipPathÄ�ā‚¬ā„¢ element, then the given child element is clipped by the referenced clipping path before OR'ing the silhouette of the child element with the silhouettes of the other child elements.
• An empty clipping path will completely clip away the element that had the Ä�ā‚¬ļæ½clip-pathÄ�ā‚¬ā„¢ property applied.

Properties inherit into the Ä�ā‚¬ļæ½clipPathÄ�ā‚¬ā„¢ element from its ancestors; properties do not inherit from the element referencing the Ä�ā‚¬ļæ½clipPathÄ�ā‚¬ā„¢ element.

Ä�ā‚¬ļæ½clipPathÄ�ā‚¬ā„¢ elements are never rendered directly; their only usage is as something that can be referenced using the Ä�ā‚¬ļæ½clip-pathÄ�ā‚¬ā„¢ property. The Ä�ā‚¬ļæ½displayÄ�ā‚¬ā„¢ property does not apply to the Ä�ā‚¬ļæ½clipPathÄ�ā‚¬ā„¢ element; thus, Ä�ā‚¬ļæ½clipPathÄ�ā‚¬ā„¢ elements are not directly rendered even if the Ä�ā‚¬ļæ½displayÄ�ā‚¬ā„¢ property is set to a value other than none, and Ä�ā‚¬ļæ½clipPathÄ�ā‚¬ā„¢ elements are available for referencing even when the Ä�ā‚¬ļæ½displayÄ�ā‚¬ā„¢ property on the Ä�ā‚¬ļæ½clipPathÄ�ā‚¬ā„¢ element or any of its ancestors is set to none.

<funciri>

An IRI reference to another graphical object within the same SVG document fragment which will be used as the clipping path. If the IRI reference is not valid (e.g it points to an object that doesn't exist or the object is not a Ä�ā‚¬ļæ½clipPathÄ�ā‚¬ā„¢ element) the Ä�ā‚¬ļæ½clip-pathÄ�ā‚¬ā„¢ property must be treated as if it hadn't been specified.

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

14.3.6 Clipping paths, geometry, and pointer events

A clipping path is conceptually equivalent to a custom viewport for the referencing element. Thus, it affects the rendering of an element, but not the element's inherent geometry. The bounding box of a clipped element (that is, 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.

By default, pointer-events must not be dispatched on the clipped (non-visible) regions of a shape. For example, a circle with a radius of 10 which is clipped to a circle with a radius of 5 will not receive 'click' events outside the smaller radius. Later versions of SVG may define new properties to enable fine-grained control over the interactions between hit testing and clipping.

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 container 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 which has been initialized to transparent black. 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 any graphics object that is used as a mask, the mask value at any point is computed from the color channel values and alpha channel value as follows. First a luminance value is computed from the color channel values:

• If the computed value of Ä�ā‚¬ļæ½color-interpolationÄ�ā‚¬ā„¢ on the Ä�ā‚¬ļæ½maskÄ�ā‚¬ā„¢ element is linearRGB, first convert the original image color values (potentially in the sRGB color space) to the linear RGB color space (see Rendering properties). Then, using non-premultiplied linear RGB color values, apply the luminance-to-alpha coefficients (as defined in the Ä�ā‚¬ļæ½feColorMatrixÄ�ā‚¬ā„¢ filter primitive) to convert the linear RGB color values to linear luminance values.
• If the computed value of Ä�ā‚¬ļæ½color-interpolationÄ�ā‚¬ā„¢ on the Ä�ā‚¬ļæ½maskÄ�ā‚¬ā„¢ element is sRGB then the luminance value is calculated by taking the non-premultiplied RGB color values, applying the luminance-to-alpha coefficients (as defined in the Ä�ā‚¬ļæ½feColorMatrixÄ�ā‚¬ā„¢ filter primitive) to convert the RGB color values to luminance values.

Finally if the graphics object also includes an alpha channel, then the computed luminance value is multiplied by the corresponding alpha value to produce the mask value.

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 (see previous paragraph) 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 to compute the three color channels and the alpha channel is uniformly set to 1. Note that 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.

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 1.1//EN" 
  "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="8cm" height="3cm" viewBox="0 0 800 300" version="1.1"
     xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
  <desc>Example mask01 - blue text masked with gradient against red background
  </desc>
  <defs>
    <linearGradient id="Gradient" gradientUnits="userSpaceOnUse"
                    x1="0" y1="0" x2="800" y2="0">
      <stop offset="0" stop-color="white" stop-opacity="0" />
      <stop offset="1" stop-color="white" stop-opacity="1" />
    </linearGradient>
    <mask id="Mask" maskUnits="userSpaceOnUse"
          x="0" y="0" width="800" height="300">
      <rect x="0" y="0" width="800" height="300" fill="url(#Gradient)"  />
    </mask>
    <text id="Text" x="400" y="200" 
          font-family="Verdana" font-size="100" text-anchor="middle" >
      Masked text
    </text>
  </defs>

  <!-- Draw a pale red rectangle in the background -->
  <rect x="0" y="0" width="800" height="300" 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" fill="blue" mask="url(#Mask)" />
  <use xlink:href="#Text" fill="none" stroke="black" stroke-width="2" />
</svg>

Example mask01

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

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

The following is a description of the Ä�ā‚¬ļæ½maskÄ�ā‚¬ā„¢ property.

<funciri>

A IRI 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:

• Ä�ā‚¬ļæ½fill-opacityÄ�ā‚¬ā„¢, which specifies the opacity of a fill operation;
• Ä�ā‚¬ļæ½stroke-opacityÄ�ā‚¬ā„¢, which specifies the opacity of a stroking operation;
• Ä�ā‚¬ļæ½stop-opacityÄ�ā‚¬ā„¢, which specifies the opacity of a gradient stop; and
• Ä�ā‚¬ļæ½opacityÄ�ā‚¬ā„¢, which specifies object/group opacity and which is described in this section.

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>

The uniform opacity setting to be applied across an entire object, as a <number>. 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 <opacity-value>. (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 1.1//EN" 
  "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="12cm" height="3.5cm" viewBox="0 0 1200 350"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Example opacity01 - opacity property</desc>

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

  <!-- Background blue rectangle -->
  <rect x="100" y="100" width="1000" height="150" fill="#0000ff"  />

  <!-- Red circles going from opaque to nearly transparent -->
  <circle cx="200" cy="100" r="50" fill="red" opacity="1"  />
  <circle cx="400" cy="100" r="50" fill="red" opacity=".8"  />
  <circle cx="600" cy="100" r="50" fill="red" opacity=".6"  />
  <circle cx="800" cy="100" r="50" fill="red" opacity=".4"  />
  <circle cx="1000" cy="100" r="50" fill="red" opacity=".2"  />

  <!-- Opaque group, opaque circles -->
  <g opacity="1" >
    <circle cx="182.5" cy="250" r="50" fill="red" opacity="1"  />
    <circle cx="217.5" cy="250" r="50" fill="green" opacity="1"  />
  </g>
  <!-- Group opacity: .5, opacity circles -->
  <g opacity=".5" >
    <circle cx="382.5" cy="250" r="50" fill="red" opacity="1"  />
    <circle cx="417.5" cy="250" r="50" fill="green" opacity="1"  />
  </g>
  <!-- Opaque group, semi-transparent green over red -->
  <g opacity="1" >
    <circle cx="582.5" cy="250" r="50" fill="red" opacity=".5"  />
    <circle cx="617.5" cy="250" r="50" fill="green" opacity=".5"  />
  </g>
  <!-- Opaque group, semi-transparent red over green -->
  <g opacity="1" >
    <circle cx="817.5" cy="250" r="50" fill="green" opacity=".5"  />
    <circle cx="782.5" cy="250" r="50" fill="red" opacity=".5"  />
  </g>
  <!-- Group opacity .5, semi-transparent green over red -->
  <g opacity=".5" >
    <circle cx="982.5" cy="250" r="50" fill="red" opacity=".5"  />
    <circle cx="1017.5" cy="250" r="50" fill="green" opacity=".5"  />
  </g>
</svg>

Example opacity01

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:

• The first group shows the opaque case for reference. The group has opacity of 1, as do the circles.
• The second group shows group opacity when the elements in the group are opaque.
• The third and fourth group show that opacity is not commutative. In the third group (which has opacity of 1), a semi-transparent green circle is drawn on top of a semi-transparent red circle, whereas in the fourth group a semi-transparent red circle is drawn on top of a semi-transparent green circle. Note that area where the two circles intersect display different colors. The third group shows more green color in the intersection area, whereas the fourth group shows more red color.
• The fifth group shows the multiplicative effect of opacity settings. Both the circles and the group itself have opacity settings of .5. The result is that the portion of the red circle which does not overlap with the green circle (i.e., the top/right of the red circle) will blend into the blue rectangle with accumulative opacity of .25 (i.e., .5*.5), which, after blending into the blue rectangle, results in a blended color which is 25% red and 75% blue.

14.6 DOM interfaces

14.6.1 Interface SVGClipPathElement

interface SVGClipPathElement : SVGElement,
                               SVGTests,
                               SVGLangSpace,
                               SVGExternalResourcesRequired,
                               SVGStylable,
                               SVGTransformable,
                               SVGUnitTypes {
  readonly attribute SVGAnimatedEnumeration clipPathUnits;
};

Attributes:

clipPathUnits (readonly SVGAnimatedEnumeration)

Corresponds to attribute Ä�ā‚¬ļæ½clipPathUnitsÄ�ā‚¬ā„¢ on the given Ä�ā‚¬ļæ½clipPathÄ�ā‚¬ā„¢ element. Takes one of the constants defined in SVGUnitTypes.

14.6.2 Interface SVGMaskElement

interface SVGMaskElement : SVGElement,
                           SVGTests,
                           SVGLangSpace,
                           SVGExternalResourcesRequired,
                           SVGStylable,
                           SVGUnitTypes {
  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 (readonly SVGAnimatedEnumeration)

Corresponds to attribute Ä�ā‚¬ļæ½maskUnitsÄ�ā‚¬ā„¢ on the given Ä�ā‚¬ļæ½maskÄ�ā‚¬ā„¢ element. Takes one of the constants defined in SVGUnitTypes.

maskContentUnits (readonly SVGAnimatedEnumeration)

Corresponds to attribute Ä�ā‚¬ļæ½maskContentUnitsÄ�ā‚¬ā„¢ on the given Ä�ā‚¬ļæ½maskÄ�ā‚¬ā„¢ element. Takes one of the constants defined in SVGUnitTypes.

x (readonly SVGAnimatedLength)

Corresponds to attribute Ä�ā‚¬ļæ½xÄ�ā‚¬ā„¢ on the given Ä�ā‚¬ļæ½maskÄ�ā‚¬ā„¢ element.

y (readonly SVGAnimatedLength)

Corresponds to attribute Ä�ā‚¬ļæ½yÄ�ā‚¬ā„¢ on the given Ä�ā‚¬ļæ½maskÄ�ā‚¬ā„¢ element.

width (readonly SVGAnimatedLength)

Corresponds to attribute Ä�ā‚¬ļæ½widthÄ�ā‚¬ā„¢ on the given Ä�ā‚¬ļæ½maskÄ�ā‚¬ā„¢ element.

height (readonly SVGAnimatedLength)

Corresponds to attribute Ä�ā‚¬ļæ½heightÄ�ā‚¬ā„¢ on the given Ä�ā‚¬ļæ½maskÄ�ā‚¬ā„¢ element.