13.2 Gradients

13.2.1 Introduction

Gradients consist of continuously smooth color transitions
along a vector from one color to another, possibly followed by
additional transitions along the same vector to other colors.
SVG provides for two types of gradients, linear
gradients and radial
gradients.

Once defined, gradients are then referenced using 'fill' or 'stroke' properties on a given graphics element to
indicate that the given element shall be filled or stroked with
the referenced gradient.

Defines the coordinate system for attributes x1, y1, x2, y2.
If gradientUnits="userSpaceOnUse",
x1, y1, x2, y2 represent
values in the coordinate system that results from taking
the current user coordinate system in place at the time
when the gradient element is referenced (i.e., the user
coordinate system for the element referencing the gradient
element via a 'fill' or 'stroke' property) and then
applying the transform specified by attribute gradientTransform.
If gradientUnits="objectBoundingBox",
the user coordinate system for attributes x1, y1, x2, y2 is established
using the bounding box of the element to which the gradient
is applied (see Object bounding box
units) and then applying the transform specified by
attribute gradientTransform.
When gradientUnits="objectBoundingBox"
and gradientTransform is the
identity matrix, the stripes of the linear gradient are
perpendicular to the gradient vector in object bounding box
space (i.e., the abstract coordinate system where (0,0) is
at the top/left of the object bounding box and (1,1) is at
the bottom/right of the object bounding box). When the
object's bounding box is not square, the stripes that are
conceptually perpendicular to the gradient vector within
object bounding box space will render non-perpendicular
relative to the gradient vector in user space due to
application of the non-uniform scaling transformation from
bounding box space to user space.
If attribute gradientUnits
is not specified, then the effect is as if a value of objectBoundingBox were
specified.Animatable:
yes.

Contains the definition of an optional additional
transformation from the gradient coordinate system onto the
target coordinate system (i.e., userSpaceOnUse or
objectBoundingBox). This allows for things such as skewing
the gradient. This additional transformation matrix is
post-multiplied to (i.e., inserted to the right of) any
previously defined transformations, including the implicit
transformation necessary to convert from object bounding box
units to user space.
If attribute gradientTransform is not
specified, then the effect is as if an identity transform
were specified.Animatable:
yes.

x1, y1, x2, y2 define a gradient
vector for the linear gradient. This gradient
vector provides starting and ending points onto which
the gradient stops are mapped.
The values of x1, y1, x2, y2 can be either
numbers or percentages.
If the attribute is not specified, the effect is as if a
value of "0%" were specified.Animatable:
yes.

See x1.
If the attribute is not specified, the effect is as if a
value of "0%" were specified.Animatable:
yes.

spreadMethod = "pad | reflect |
repeat"

Indicates what happens if the gradient starts or ends
inside the bounds of the target rectangle.
Possible values are: pad, which says to use the
terminal colors of the gradient to fill the remainder of
the target region, reflect, which says to reflect
the gradient pattern start-to-end, end-to-start,
start-to-end, etc. continuously until the target
rectangle is filled, and repeat, which says
to repeat the gradient pattern start-to-end, start-to-end,
start-to-end, etc. continuously until the target region is
filled.
If the attribute is not specified, the effect is as if a
value of "pad" were specified.Animatable:
yes.

A URI
reference to a different 'linearGradient' or 'radialGradient' element within
the current SVG document fragment. Any 'linearGradient' attributes
which are defined on the referenced element which are not
defined on this element are inherited by this element. If
this element has no defined gradient stops, and the
referenced element does (possibly due to its own href attribute), then this element
inherits the gradient stop from the referenced element.
Inheritance can be indirect to an arbitrary level; thus, if
the referenced element inherits attribute or gradient stops
due to its own href
attribute, then the current element can inherit those
attributes or gradient stops.Animatable:
yes.

Percentages are allowed for x1, y1, x2, y2.
For gradientUnits="userSpaceOnUse", percentages represent
values relative to the current viewport. For
gradientUnits="objectBoundingBox", percentages represent values
relative to the bounding box for the object.

If x1 = x2 and
y1 = y2, then the area to be
painted will be painted as a single color using the color and
opacity of the last gradient stop.

Properties
inherit into the 'linearGradient' element from its
ancestors; properties do not inherit from the element
referencing the 'linearGradient' element.

'linearGradient' elements
are never rendered directly; their only usage is as something
that can be referenced using the 'fill' and 'stroke' properties. The 'display' property does not apply
to the 'linearGradient'
element; thus, 'linearGradient' elements are not
directly rendered even if the 'display' property is set to a
value other than none, and
'linearGradient' elements are
available for referencing even when the 'display' property on the 'linearGradient' element or any of
its ancestors is set to none.

Example lingrad01 shows how
to fill a rectangle by referencing a linear gradient paint
server.

Defines the coordinate system for attributes cx, cy, r, fx, fy.
If gradientUnits="userSpaceOnUse",
cx, cy, r, fx, fy represent
values in the coordinate system that results from taking
the current user coordinate system in place at the time
when the gradient element is referenced (i.e., the user
coordinate system for the element referencing the gradient
element via a 'fill' or 'stroke' property) and then
applying the transform specified by attribute gradientTransform.
If gradientUnits="objectBoundingBox",
the user coordinate system for attributes cx, cy, r, fx, fy is established
using the bounding box of the element to which the gradient
is applied (see Object bounding box
units) and then applying the transform specified by
attribute gradientTransform.
When gradientUnits="objectBoundingBox"
and gradientTransform is the
identity matrix, then the rings of the radial gradient are
circular with respect to the object bounding box space
(i.e., the abstract coordinate system where (0,0) is at the
top/left of the object bounding box and (1,1) is at the
bottom/right of the object bounding box). When the object's
bounding box is not square, the rings that are conceptually
circular within object bounding box space will render as
elliptical due to application of the non-uniform scaling
transformation from bounding box space to user space.
If attribute gradientUnits
is not specified, then the effect is as if a value of objectBoundingBox were
specified.Animatable:
yes.

Contains the definitions of an optional additional
transformation from the gradient coordinate system onto the
target coordinate system (i.e., userSpaceOnUse or
objectBoundingBox). This allows for things such as skewing
the gradient. This additional transformation matrix is
post-multiplied to (i.e., inserted to the right of) any
previously defined transformations, including the implicit
transformation necessary to convert from object bounding box
units to user space.
If attribute gradientTransform is not
specified, then the effect is as if an identity transform
were specified.Animatable:
yes.

cx, cy, r define the largest (i.e.,
outermost) circle for the radial gradient. The gradient
will be drawn such that the 100% gradient stop is mapped to the
perimeter of this largest (i.e., outermost) circle.
If the attribute is not specified, the effect is as if a
value of "50%" were specified.Animatable:
yes.

See cx.
A negative value is an error (see Error processing).
A value of zero will cause the area to be painted as a
single color using the color and opacity of the last gradient stop.
If the attribute is not specified, the effect is as if a
value of "50%" were specified.Animatable:
yes.

fx, fy define the focal point for the
radial gradient. The gradient will be drawn such that the
0% gradient stop is mapped to
(fx, fy).
If attribute fx is not
specified, fx will coincide
with cx.Animatable:
yes.

See fx.
If attribute fy is not
specified, fy will coincide
with cy.Animatable:
yes.

spreadMethod = "pad | reflect |
repeat"

Indicates what happens if the gradient starts or ends
inside the bounds of the object(s) being painted by the
gradient. Has the same values and meanings as the spreadMethod attribute on 'linearGradient'
element.Animatable:
yes.

A URI
reference to a different 'linearGradient' or 'radialGradient' element within
the current SVG document fragment. Any 'radialGradient' attributes
which are defined on the referenced element which are not
defined on this element are inherited by this element. If
this element has no defined gradient stops, and the
referenced element does (possibly due to its own href attribute), then this element
inherits the gradient stop from the referenced element.
Inheritance can be indirect to an arbitrary level; thus, if
the referenced element inherits attribute or gradient stops
due to its own href
attribute, then the current element can inherit those
attributes or gradient stops.Animatable:
yes.

If the point defined by fx and fy lies outside the circle defined
by cx, cy and r, then the user agent shall set
the focal point to the intersection of the line from (cx, cy) to (fx, fy) with the circle defined by cx, cy and r.

Properties
inherit into the 'radialGradient' element from its
ancestors; properties do not inherit from the element
referencing the 'radialGradient' element.

'radialGradient' elements
are never rendered directly; their only usage is as something
that can be referenced using the 'fill' and 'stroke' properties. The 'display' property does not apply
to the 'radialGradient'
element; thus, 'radialGradient' elements are not
directly rendered even if the 'display' property is set to a
value other than none, and
'radialGradient' elements are
available for referencing even when the 'display' property on the 'radialGradient' element or any of
its ancestors is set to none.

Example radgrad01 shows how
to fill a rectangle by referencing a radial gradient paint
server.

The offset attribute is
either a <number>
(usually ranging from 0 to 1) or a <percentage>
(usually ranging from 0% to 100%) which indicates where the
gradient stop is placed. For linear gradients, the offset attribute represents a
location along the gradient vector. For radial
gradients, it represents a percentage distance from (fx,fy)
to the edge of the outermost/largest circle.Animatable:
yes.

The 'stop-color' property
indicates what color to use at that gradient stop. The keyword
currentColor and ICC colors can
be specified in the same manner as within a <paint>
specification for the 'fill' and 'stroke' properties.

Gradient offset values less than 0 (or less than 0%) are
rounded up to 0%. Gradient offset values greater than 1 (or
greater than 100%) are rounded down to 100%.

It is necessary that at least two stops defined to have a
gradient effect. If no stops are defined, then painting shall
occur as if 'none' were specified as the paint style. If one
stop is defined, then paint with the solid color fill using
the color defined for that gradient stop.

Each gradient offset value is required to be equal to or
greater than the previous gradient stop's offset value. If a
given gradient stop's offset value is not equal to or greater
than all previous offset values, then the offset value is
adjusted to be equal to the largest of all previous offset
values.

If two gradient stops have the same offset value, then the
latter gradient stop controls the color value at the
overlap point. In particular:

which is a gradient that goes smoothly from white to red,
then abruptly shifts from red to blue, and then goes
smoothly from blue to black.

13.3 Patterns

A pattern is used to fill or stroke an object using a
pre-defined graphic object which can be replicated ("tiled") at
fixed intervals in x and y to cover the areas
to be painted. Patterns are defined using a 'pattern' element and then
referenced by properties 'fill' and 'stroke' on a given graphics element to
indicate that the given element shall be filled or stroked with
the referenced pattern.

Attributes x, y, width, height and patternUnits define a reference
rectangle somewhere on the infinite canvas. The reference
rectangle has its top/left at (x,y) and its bottom/right at (x+width,y+height). The tiling theoretically
extends a series of such rectangles to infinity in X and Y
(positive and negative), with rectangles starting at (x + m*width, y + n*height) for each possible integer
value for m and n.

Defines the coordinate system for attributes x, y, width, height.
If patternUnits="userSpaceOnUse",
x, y, width, height
represent values in the coordinate system that results from
taking the current user coordinate system in place at the
time when the 'pattern'
element is referenced (i.e., the user coordinate system for
the element referencing the 'pattern' element via a 'fill' or 'stroke' property) and then
applying the transform specified by attribute patternTransform.
If patternUnits="objectBoundingBox",
the user coordinate system for attributes x, y, width, height is established
using the bounding box of the element to which the pattern
is applied (see Object bounding box
units) and then applying the transform specified by
attribute patternTransform.
If attribute patternUnits
is not specified, then the effect is as if a value of objectBoundingBox were
specified.Animatable:
yes.

patternContentUnits =
"userSpaceOnUse | objectBoundingBox"

Defines the coordinate system for the contents of the
'pattern'. Note that this
attribute has no effect if attribute viewBox is specified.
If patternContentUnits="userSpaceOnUse",
the user coordinate system for the contents of the 'pattern' element is the
coordinate system that results from taking the current user
coordinate system in place at the time when the 'pattern' element is referenced
(i.e., the user coordinate system for the element
referencing the 'pattern'
element via a 'fill' or 'stroke' property) and then
applying the transform specified by attribute patternTransform.
If patternContentUnits="objectBoundingBox",
the user coordinate system for the contents of the 'pattern' element is
established using the bounding box of the element to which
the pattern is applied (see Object bounding box
units) and then applying the transform specified by
attribute patternTransform.
If attribute patternContentUnits is not
specified, then the effect is as if a value of userSpaceOnUse were
specified.Animatable:
yes.

Contains the definition of an optional additional
transformation from the pattern coordinate system onto the
target coordinate system (i.e., userSpaceOnUse or
objectBoundingBox). This allows for things such as skewing
the pattern tiles. This additional transformation matrix is
post-multiplied to (i.e., inserted to the right of) any
previously defined transformations, including the implicit
transformation necessary to convert from object bounding box
units to user space.
If attribute patternTransform is not specified,
then the effect is as if an identity transform were
specified.Animatable:
yes.

x, y, width, height indicate how the
pattern tiles are placed and spaced. These attributes
represent coordinates and values in the coordinate space
specified by the combination of attributes patternUnits and patternTransform.
If the attribute is not specified, the effect is as if a
value of zero were specified.Animatable:
yes.

See x.
A negative value is an error (see Error processing).
A value of zero disables rendering of the element (i.e., no
paint is applied).
If the attribute is not specified, the effect is as if a
value of zero were specified.Animatable:
yes.

See x.
A negative value is an error (see Error processing).
A value of zero disables rendering of the element (i.e., no
paint is applied).
If the attribute is not specified, the effect is as if a
value of zero were specified.Animatable:
yes.

A URI
reference to a different 'pattern' element within the
current SVG document fragment. Any attributes which are
defined on the referenced element which are not defined on
this element are inherited by this element. If this element
has no children, and the referenced element does (possibly
due to its own href
attribute), then this element inherits the children from
the referenced element. Inheritance can be indirect to an
arbitrary level; thus, if the referenced element inherits
attributes or children due to its own href attribute, then the current
element can inherit those attributes or children.Animatable:
yes.

SVG's user agent style
sheet sets the 'overflow' property for 'pattern' elements to hidden, which causes a rectangular
clipping path to be created at the bounds of the pattern tile.
Unless the 'overflow' property is overridden,
any graphics within the pattern which goes outside of the
pattern rectangle will be clipped. Example pattern01
below shows the effect of clipping to the pattern tile.

The contents of the 'pattern' are relative to a new
coordinate system. If there is a viewBox attribute, then the new
coordinate system is fitted into the region defined by the x, y, width, height and patternUnits attributes on the
'pattern' element using the
standard rules for viewBox and preserveAspectRatio. If there is
no viewBox attribute, then the new
coordinate system has its origin at (x,y), where x is
established by the x attribute on the 'pattern' element, and y is
established by the y attribute on the 'pattern' element. Thus, in the
following example:

the rectangle has its top/left located 5 units to the right
and 5 units down from the origin of the pattern tile.

The viewBox attribute introduces a
supplemental transformation which is applied on top of any
transformations necessary to create a new pattern coordinate
system due to attributes x, y, width, height and patternUnits.

Properties
inherit into the 'pattern'
element from its ancestors; properties do not inherit
from the element referencing the 'pattern' element.

'pattern' elements are
never rendered directly; their only usage is as something that
can be referenced using the 'fill' and 'stroke' properties. The 'display' property does not apply
to the 'pattern' element;
thus, 'pattern' elements are
not directly rendered even if the 'display' property is set to a
value other than none, and
'pattern' elements are
available for referencing even when the 'display' property on the 'pattern' element or any of its
ancestors is set to none.

Event attributes
and event listeners
attached to the contents of a 'pattern' element are not
processed; only the rendering aspects of 'pattern' elements are
processed.

Example pattern01 shows how
to fill a rectangle by referencing a pattern paint server. Note
how the blue stroke of each triangle has been clipped at the
top and the left. This is due to SVG's user agent style sheet
setting the 'overflow' property for 'pattern' elements to hidden, which causes the pattern to
be clipped to the bounds of the pattern tile.