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.

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

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:

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

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

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.

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.

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

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.

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:

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:

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.

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.

Defines the coordinate system for attributes
‘x’, ‘y’, ‘width’ and ‘height’.
If maskUnits="userSpaceOnUse",
‘x’, ‘y’, ‘width’ and ‘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’ and ‘height’
represent fractions or percentages of the bounding box of
the element to which the mask is applied. (See Object bounding box
units.)
If attribute ‘maskUnits’ is
not specified, 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.

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’ and ‘height’.
If the attribute is not specified, the effect is as if a
value of '-10%' were specified.Animatable:
yes.

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’ and ‘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.

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.

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.

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

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.

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.