6 Clipping, Masking and Compositing


6.1 Introduction

SVG supports the following clipping/masking features:

SVG supports the following blending/compositing features:

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

6.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).

6.3 Clipping path properties

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 new clipping path can be establish by specifying a 'clippath' property on a drawing element or <g> which provides a <uri> of a different drawing element to use as the clipping path.

<g> objects, <use> objects, path objects, shape objects and text objects can be used as clipping paths. (??? Add links to all of these items.) If the <uri> specifies a non-existent object or if the specified object is inappropriate for use as a clipping path (e.g., an image), then the object will be ignored in the computation of the clipping path. Objects defined via extensibility can only be used as clipping paths if they are designed to do so. (??? Need more details here.)

For a given drawing element, the actual clipping path used will be the intersection of its clippath with the clippaths of all ancestors of the drawing element.

(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].)

'clippath'
Value:   <uri> | inherit
Initial:   The bounds of the viewport (see ??? link to viewport).
Applies to:  all elements
Inherited:  yes
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.
'cliprule'
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)

6.4 Masking Properties

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 established by specifying a mask property. In the following example, an image is used to mask a rectangle:

<g>
  <defs>
    <image id="MyMask" ... />
  </defs>
  <rect style="mask: url(#MyMask)" ... />
</g>
'mask'
Value:   <uri> | none | inherit
Initial:   none
Applies to:  all elements
Inherited:  yes
Percentages:  N/A
Media:  visual
<uri>
An XPointer to another graphical object within the same SVG document which will be used as the mask.
'mask-method'
Value:   luminance | alpha-component | per-channel
Initial:   luminance
Applies to:  all elements
Inherited:  yes
Percentages:  N/A
Media:  visual
luminance
(Conceptual description of what the behavior should be. Actual implementations can use different approaches but should achieve equivalent results.) Create a 32-bit (RGBA) offscreen image (SourcePixmap) for the SourceObject (i.e., object being masked) and an 8-bit offscreen image (MaskingPixmap) for MaskingObject (i.e., the object at <uri>). The image width and height for two pixmaps are determined by the current value of properties mask-width and mask-height. The two pixmaps are aligned relative to the drawing surface such that the corners of the pixmaps exactly align with the locations on the surface of the mask-bbox To perform the masking operation, render SourceObject into SourcePixmap and MaskingObject into MaskingPixmap such that the value at each pixel represents the luminance of the MaskingObject's color channels using the formula is (??? this comes from JohnB but needs to be discussed further): 1.0-(.2126*R^2.2+.7152*G^2.2+.0722*B^2.2). Using the current blending mode (??? need a link), blend SourcePixmap through MaskingPixmap into the current background.
<alpha-component>
Same behavior as luminance except that the value of each pixel in MaskingPixmap comes from the (possibly computed) alpha channel of MaskingObject.
<per-channel>
Same behavior as luminance except that MaskingPixmap is a 32-bit pixmap. The blending operation is on a per-channel basis, where the color value at each channel is used as an 8-bit mask for blending SourcePixmap into the current background.
'mask-width'
Value:   auto [<width>] | [<width>] | inherit
Initial:   auto 100
Applies to:  all elements
Inherited:  yes
Percentages:  N/A
Media:  visual
auto [<width>]
Indicates that the image widths of SourcePixmap and MaskingPixmap should determined automatically. Within a Web browser, a recommended choice for auto would be a width which causes the pixmaps to line up with the resolution of the display. For higher resolution devices such as printers, auto should either follow a user preference for printing resolution or use some reasonable tradeoff between memory size and quality printing, such as 300dpi. If the SVG processor has no way of determining either the resolution of the target device, then it should use the optional [<width>] (an <integer>) as its fallback pixmap width. The default fallback pixmap width is 100.
<width>
If <width> is specified by itself (i.e., without auto), then it explicity specifies how many pixels wide SourcePixmap and MaskingPixmap should be for masking operations.
'mask-height'
Value:   auto [<height>] | [<height>] | inherit
Initial:   auto 100
Applies to:  all elements
Inherited:  yes
Percentages:  N/A
Media:  visual
auto [<height>]
Indicates that the image heights of SourcePixmap and MaskingPixmap should determined automatically. Within a Web browser, a recommended choice for auto would be a height which causes the pixmaps to line up with the resolution of the display. For higher resolution devices such as printers, auto should either follow a user preference for printing resolution or use some reasonable tradeoff between memory size and quality printing, such as 300dpi. If the SVG processor has no way of determining either the resolution of the target device, then it should use the optional [<height>] (an <integer>) as its fallback pixmap width. The default fallback pixmap height is 100.
<height>
If <height> is specified by itself (i.e., without auto), then it explicity specifies how many pixels high SourcePixmap and MaskingPixmap should be for masking operations.
'mask-bbox'
Value:   <left> <top> <right> <bottom> |inherit
Initial:   0% 0% 100% 100%
Applies to:  all elements
Inherited:  yes
Percentages:  Yes, relative to the current viewport (??? add link)
Media:  visual
<left> <top> <right> <bottom>
The <left> <top> <right> <bottom> (all <number>s) are the coordinates of the rectangle within which masking should occur. The values are either expressed either as coordinates in user space or as a percentage measurement along the appropriate axis of the current viewport (??? add link) which is then converted internally into a coordinate in user space. The corners of SourcePixmap and MaskingPixmap should exactly align with the corners of this rectangle. (??? need drawing)

6.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 SourcePixmap in viewport space, the object/group opacity setting specifies how to blend the SourcePixmap into the current background.

'opacity'
Value:   <alphavalue> | <pct>
Initial:   100%
Applies to:  all elements
Inherited:  no
Percentages:  Yes, relative to the current viewport (??? add link)
Media:  visual
<alphavalue>
The uniform opacity setting to be applied across an entire object expressed as an <number> between 0 and 255. If the object is a <g>, then the effect is as if the contents of the <g> were blended against the current background using an 8-bit MaskingPixmap where the value of each pixel of MaskingPixmap 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 an 8-bit MaskingPixmap where the value of each pixel of MaskingPixmap is <pct> * 255.