previous   next   contents   properties   index  

5 Clipping, Masking and Compositing


Contents


 

5.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 Blending/Compositing).

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

5.2 Simple Alpha Blending/Compositing

[Insert discussion about color spaces and compositing techniques.]

It is likely that our default compositing colorspace will be linearized-sRGB, where it is linearized with respect to light energy. Any colors specified in sRGB would be composited after linearizing with the formula (alpha*src^2.2 + (1-alpha)*dst^2.2)^(1/2.2).

5.3 Clipping paths

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.

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 and are processed as if the <use> element were not present. 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.

If the 'clip-path' property references a non-existent object or if the referenced object is not a <clipPath> element, then the 'clip-path' property will be ignored.

For a given drawing element, the actual clipping path used will be the intersection of its specified clip-path with the clipping paths of all its ancestors.

(There will be a mechanism for ensuring that an initial clipping path is set to the bounds of the entire viewport into which the SVG is being drawn. The working group is also investigating ways to allow an SVG drawing to draw outside of the initial viewport [i.e., initial clipping path goes beyond the bounds of the initial viewport].)
  
<!ELEMENT clipPath (desc?,title?,
                    (path|text|rect|circle|ellipse|line|polyline|polygon|
                     use)*) >
<!ATTLIST clipPath
  id ID #IMPLIED
  xml:lang NMTOKEN #IMPLIED
  xml:space (default|preserve) #IMPLIED
  class NMTOKENS #IMPLIED
  style CDATA #IMPLIED >


Attributes defined elsewhere:
id, xml:lang, xml:space, class, style.

 
'clip-path'
Value:   <uri> | none
Initial:   The bounds of the viewport (see ??? link to viewport).
Applies to:  all elements
Inherited:  no
Percentages:  N/A
Media:  visual
<uri>
An XPointer to another graphical object within the same SVG document which will be used as the clipping path.
'clip-rule'
Value:   evenodd | nonzero | inherit
Initial:   evenodd
Applies to:  all elements
Inherited:  yes
Percentages:  N/A
Media:  visual
evenodd
(??? Need detailed description plus drawings)
nonzero
(??? Need detailed description plus drawings)

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

If the 'mask' property references a non-existent object or if the referenced object is not a <mask> element, then the 'mask' property will be ignored.

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.

The following processing rules apply:

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.

In the following example, an image is used to mask a rectangle: 

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG July 1999//EN" 
  "http://www.w3.org/Graphics/SVG/svg-19990730.dtd">
<svg width="4in" height="3in">
  <desc>Example of using a mask
  </desc>
  <g>
    <defs>
      <mask id="MyMask">
        <image xlink:href="transp.png" />
      </mask>
    </defs>
    <rect style="mask: url(#MyMask)" width="12.5" height="30" />
  </g>
</svg>

Download this example

A <mask> element can define a region on the canvas for the mask using the following attributes:


  
<!ELEMENT mask (defs?,desc?,title?,
                    (path|text|rect|circle|ellipse|line|polyline|polygon|
                     use|image|svg|g|switch|a)*)>
<!ATTLIST mask
  id ID #IMPLIED
  xml:lang NMTOKEN #IMPLIED
  xml:space (default|preserve) #IMPLIED
  class NMTOKENS #IMPLIED
  style CDATA #IMPLIED
  maskUnits (userSpace | objectBoundingBox) "userSpace"
  x CDATA #IMPLIED
  y CDATA #IMPLIED
  width CDATA #IMPLIED
  height CDATA #IMPLIED >

Attribute definitions:

maskUnits = "userSpace | objectBoundingBox"
Defines the coordinate system for attributes x, y, width, height. If maskUnits="userSpace" (the default), x, y, width, height represent values in the current user coordinate system in place at the time when the <mask> element is defined. If maskUnits="objectBoundingBox", then x, y, width, height represent values in an abstract coordinate system where (0,0) is the (minx,miny) in user space of the tight bounding box of the object referencing the mask, and (1,1) is the (maxx,maxy) corner of the bounding box. (Note: the bounding box represents the maximum extent of the shape of the object in X and Y with respect to the user coordinate system of the object exclusive of stroke-width.)
x = "x-coordinate"
The x-coordinate of one corner of the rectangle for the largest possible offscreen buffer, where the values are either relative to the current user coordinate system (if maskUnits="userSpace") or relative to the current object (if maskUnits="objectBoundingBox"). Note that the clipping path used to render any graphics within the mask will consists of the intersection of the current clipping path associated with the given object and the rectangle defined by x, y, width, height. The default value for x is 0%.
y = "y-coordinate"
The y-coordinate of one corner of the rectangle for the largest possible offscreen buffer.The default value for y is 0%.
width = "length"
The width of the largest possible offscreen buffer, where the values are either relative to the current user coordinate system (if maskUnits="userSpace") or relative to the current object (if maskUnits="objectBoundingBox"). Note that the clipping path used to render any graphics within the mask will consists of the intersection of the current clipping path associated with the given object and the rectangle defined by x, y, width, height. The default value for width is 100%.
height = "length"
The height of the largest possible offscreen buffer. The default value for height is 100%.

Attributes defined elsewhere:
id, xml:lang, xml:space, class, style.

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

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

5.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> | <pct>
Initial:   100%
Applies to:  all elements
Inherited:  no
Percentages:  Yes, relative to the current viewport
Media:  visual
<alphavalue>
The uniform opacity setting to be applied across an entire object expressed as an <number> between 0 and 1. If the object is 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>.
<pct>
The uniform opacity setting to be applied across an entire object expressed as a percentage (100% means fully opaque). If the object is 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 <pct> * 100.