previous   next   contents   properties   index  

13 Gradients and Patterns


Contents


 

13.1 Introduction

With SVG, you can fill (i.e., paint the interior) or stroke (i.e., paint the outline) of shapes and text using one of the following:

SVG uses the general notion of a paint server. Gradients and patterns are just specific types of paint servers. For example, first you define a linear gradient by including a 'linearGradient' element within a 'defs', assign an ID to that 'linearGradient' element, and then reference that ID in a 'fill' or 'stroke' property: 

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG December 1999//EN" 
  "http://www.w3.org/Graphics/SVG/SVG-19991203.dtd">
<svg width="4in" height="3in">
  <desc>Linear gradient example
  </desc>
  <g>
    <defs>
      <linearGradient id="MyGradient">
        <stop offset="0%" style="stop-color:#F60"/>
        <stop offset="70%" style="stop-color:#FF6"/>
      </linearGradient>
    </defs>
    <rect style="fill: url(#MyGradient)" width="20" height="15.8"/>
  </g>
</svg>

Download this example

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.

Gradients are specified within a 'defs' element and are then referenced using 'fill' or 'stroke' or properties on a given graphics element to indicate that the given element shall be filled or stroked with the referenced gradient.

13.2.2 Linear gradients

Linear gradients are defined by a 'linearGradient' element.
  
<!ENTITY % linearGradientExt "" >
<!ELEMENT linearGradient (stop|animate|set|animateTransform
                   %linearGradientExt;)* >
<!ATTLIST linearGradient
  id ID #IMPLIED
  gradientUnits (userSpace | userSpaceOnUse | objectBoundingBox) 'userSpace'
  gradientTransform CDATA #IMPLIED
  x1 CDATA #IMPLIED
  y1 CDATA #IMPLIED
  x2 CDATA #IMPLIED
  y2 CDATA #IMPLIED
  spreadMethod (pad | reflect | repeat) "pad"
  %xlinkRefAttrs;
  xlink:href CDATA #IMPLIED >

Attribute definitions:

gradientUnits = "userSpace | userSpaceOnUse | objectBoundingBox"
Defines the coordinate system for attributes x1, y1, x2, y2.
If gradientUnits="userSpace" (the default), x1, y1, x2, y2 represent values in the current user coordinate system in place at the time when the 'linearGradient' element is defined.
If gradientUnits="userSpaceOnUse", x1, y1, x2, y2 represent values in the current user coordinate system in place at the time when the 'linearGradient' element is referenced (i.e., the user coordinate system for the element referencing the 'linearGradient' element via a 'fill' or 'stroke' property).
If gradientUnits="objectBoundingBox", then x1, y1, x2, y2 represent values in an abstract coordinate system where (0,0) is the (minx,miny) in user space of the bounding box of the object getting filled with the gradient, 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.)
Animatable: yes.
gradientTransform = "<transform-list>"
Contains the definitions of an optional additional transformation from the gradient coordinate system onto the target coordinate system (i.e., userSpace or objectBoundingBox). This allows for things such as skewing the gradient.
Animatable: yes.
x1 = "<coordinate>"
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 whose meaning is determined by the value of attribute gradientUnits, as follows:

gradientUnits Type of value Meaning of value
"userSpace" a number The value represents a coordinate in the current user coordinate system
"userSpace" a percentage The value represents a percent distance along the X-axis of the current viewport (see Processing rules for CSS units and percentages)
"objectBoundingBox" a number The value represents a fractional position within the bounding box of the given shape, where (0,0) is the (minx,miny) of the shape and (1,1) is the (maxx,maxy) of the shape. (See discussion of gradientUnits="objectBoundingBox".)
"objectBoundingBox" a percentage The value represents a fractional position within the bounding box of the given shape, where (0%,0%) is the (minx,miny) of the shape and (100%,100%) is the (maxx,maxy) of the shape. (See discussion of gradientUnits="objectBoundingBox".)

Default value is "0%".
Animatable: yes.
y1 = "<coordinate>"
See x1. Default value is "0%".
Animatable: yes.
x2 = "<coordinate>"
See x1. Default value is "100%".
Animatable: yes.
y2 = "<coordinate>"
See x1. Default value is "0%".
Animatable: yes.
spreadMethod = "pad | reflect | repeat"
Indicates what happens if the 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.
Animatable: yes.
xlink:href = "<uri>"
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.

Attributes defined elsewhere:
id, %xlinkAttrs;.

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

13.2.3 Radial gradients

Radial gradients are defined by a 'radialGradient' element.
  
<!ENTITY % radialGradientExt "" >
<!ELEMENT radialGradient (stop|animate|set|animateTransform
                   %radialGradientExt;)* >
<!ATTLIST radialGradient
  id ID #IMPLIED
  gradientUnits (userSpace | userSpaceOnUse | objectBoundingBox) 'userSpace'
  gradientTransform CDATA #IMPLIED
  cx CDATA #IMPLIED
  cy CDATA #IMPLIED
  r CDATA #IMPLIED
  fx CDATA #IMPLIED
  fy CDATA #IMPLIED
  %xlinkRefAttrs;
  xlink:href CDATA #IMPLIED >

Attribute definitions:

gradientUnits = "userSpace | userSpaceOnUse | objectBoundingBox"
Defines the coordinate system for attributes cx, cy, r, fx, fy.
If gradientUnits="userSpace" (the default), cx, cy, r, fx, fy represent values in the current user coordinate system in place at the time when the 'linearGradient' element is defined.
If gradientUnits="userSpaceOnUse", cx, cy, r, fx, fy represent values in the current user coordinate system in place at the time when the 'radialGradient' element is referenced (i.e., the user coordinate system for the element referencing the 'radialGradient' element via a 'fill' or 'stroke' property).
If gradientUnits="objectBoundingBox", then cx, cy, r, fx, fy represent values in an abstract coordinate system where (0,0) is the (minx,miny) in user space of the bounding box of the object getting filled with the gradient, 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.)
Animatable: yes.
gradientTransform = "<transform-list>"
Contains the definitions of an optional additional transformation from the gradient coordinate system onto the target coordinate system (i.e., userSpace or objectBoundingBox). This allows for things such as skewing the gradient.
Animatable: yes.
cx = "<coordinate>"
cx, cy, r define the largest/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/outermost circle. Default value is "50%".
Animatable: yes.
cy = "<coordinate>"
See cx. Default value is "50%".
Animatable: yes.
r = "<length>"
See cx. Default value is "50%".
Animatable: yes.
fx = "<coordinate>"
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). The default value is 50%.
Animatable: yes.
fy = "<coordinate>"
See fx. Default value is "50%".
Animatable: yes.
xlink:href = "<uri>"
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.

Attributes defined elsewhere:
id, %xlinkAttrs;.

Percentages are allowed for cx, cy, r, fx, fy. For gradientUnits="userSpace", percentages represent values relative to the current viewport. For gradientUnits="objectBoundingBox", percentages represent values relative to the bounding box for the object.

13.2.4 Gradient stops

The ramp of colors to use on a gradient is defined by the 'stop' elements that are child elements to either the 'linearGradient' element or the 'radialGradient' element. Here is an example of the definition of a linear gradient that consists of a smooth transition from white-to-red-to-black:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG December 1999//EN" 
  "http://www.w3.org/Graphics/SVG/SVG-19991203.dtd">
<svg width="4in" height="3in">
  <desc>Radial gradient example with three gradient stops
  </desc>
  <g>
    <defs>
      <radialGradient id="MyGradient">
         <stop offset="0%" style="stop-color:white"/>
         <stop offset="50%" style="stop-color:red"/>
         <stop offset="100%" style="stop-color:black"/>
      </radialGradient>
    </defs>
    <circle style="fill: url(#MyGradient)" r="42"/>
  </g>
</svg>

Download this example


  
<!ENTITY % stopExt "" >
<!ELEMENT stop (animate|set|animateColor
                   %stopExt;)* >
<!ATTLIST stop
  id ID #IMPLIED
  style CDATA #IMPLIED
  offset CDATA #REQUIRED >

Attribute definitions:

offset = "length"
The offset attribute is either a <number> (usually ranging from 0 to 1) or a percentage (correspondingly 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.

Attributes defined elsewhere:
id, style.

The 'stop-color' property indicates what color to use at that gradient stop. ICC colors can be specified in the same manner as for the 'fill' and 'stroke' properties.

'stop-color'
Value:   <color> | inherit
Initial:   black
Applies to:   'stop' elements
Inherited:  no
Percentages:  N/A
Media:  visual
Animatable:  yes

The 'stop-opacity' property defines the opacity of a given gradient stop.

'stop-opacity'
Value:   <alphavalue> | inherit
Initial:   1
Applies to:   'stop' elements
Inherited:  no
Percentages:  N/A
Media:  visual
Animatable:  yes

Some notes on gradients:

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:.
  
<!ENTITY % patternExt "" >
<!ELEMENT pattern (%descTitleDefs;,
                    (path|text|rect|circle|ellipse|line|polyline|polygon|
                     use|image|svg|g|switch|a
                     %ceExt;%patternExt;)*) >
<!ATTLIST pattern
  id ID #IMPLIED
  xml:lang NMTOKEN #IMPLIED
  xml:space (default|preserve) #IMPLIED
  class NMTOKENS #IMPLIED
  style CDATA #IMPLIED
  patternUnits (userSpace | userSpaceOnUse | objectBoundingBox) 'userSpace'
  patternTransform CDATA #IMPLIED
  x CDATA #IMPLIED
  y CDATA #IMPLIED
  width CDATA #REQUIRED
  height CDATA #REQUIRED
  refX CDATA #IMPLIED
  refY CDATA #IMPLIED
  viewBox CDATA #IMPLIED
  preserveAspectRatio CDATA 'xMidYMid meet'
  %xlinkRefAttrs;
  xlink:href CDATA #IMPLIED >

Attribute definitions:

patternUnits = "userSpace | userSpaceOnUse | objectBoundingBox"
Defines the coordinate system for attributes x, y, width, height and the contents of the 'pattern'.
If patternUnits="userSpace" (the default), x, y, width, height and the contents of the 'pattern' represent values in the current user coordinate system in place at the time when the 'mask' element is defined.
If patternUnits="userSpaceOnUse", x, y, width, height and the contents of the 'pattern' represent values in 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).
If patternUnits="objectBoundingBox", x, y, width, height and the contents of the 'pattern' represent values in the 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.)
Animatable: yes.
patternTransform = "<transform-list>"
Contains the definitions of an optional additional transformation from the pattern coordinate system onto the target coordinate system (i.e., userSpace or objectBoundingBox). This allows for things such as skewing the pattern tiles.
Animatable: yes.
x = "<coordinate>"
x, y, width, height indicate how the pattern tiles are placed and spaced and represent coordinates and values in the coordinate space specified by patternUnits. Default value is "0%".
Animatable: yes.
y = "<coordinate>"
See x. Default value is "0%".
Animatable: yes.
width = "<length>"
See x. Default value is "100%".
Animatable: yes.
height = "<length>"
See x. Default value is "100%".
Animatable: yes.
xlink:href = "<uri>"
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 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 gradient stops.
Animatable: yes.

Attributes defined elsewhere:
id, xml:lang, xml:space, class, style, refX, refY, viewBox, preserveAspectRatio, %xlinkAttrs;.

An example:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG December 1999//EN" 
  "http://www.w3.org/Graphics/SVG/SVG-19991203.dtd">
<svg width="4in" height="3in" >
  <defs>
    <pattern id="TrianglePattern" 
             patternUnits="userSpace"
             x="0" y="0" width="25" height="25"
             patternTransform="skewX(45)"
             viewBox="0 0 10 10" >
      <path d="M 0 0 L 10 0 L 5 10 z" />
    </pattern> 
  </defs>
  <!-- Fill this ellipse with the above pattern -->
  <ellipse style="fill: url(#TrianglePattern)" rx="40" ry="27" />
</svg>

Download this example


13.4 DOM interfaces


13.4.1 Interface SVGGradientElement

The SVGGradientElement interface is a base interface used by SVGLinearGradientElement and SVGRadialGradientElement. 

interface SVGGradientElement : SVGElement {
  // gradientUnits Types
  const unsigned short kSVG_GRADIENTUNITS_UNKNOWN           = 0;
  const unsigned short kSVG_GRADIENTUNITS_USERSPACE         = 1;
  const unsigned short kSVG_GRADIENTUNITS_USERSPACEONUSE    = 2;
  const unsigned short kSVG_GRADIENTUNITS_OBJECTBOUNDINGBOX = 3;
  attribute unsigned short gradientUnits;
  attribute SVGTransformList gradientTransform;
};

13.4.2 Interface SVGLinearGradientElement

The SVGLinearGradientElement interface corresponds to the 'linearGradient' element. 

interface SVGLinearGradientElement : SVGGradientElement {
  attribute SVGLength x1;
  attribute SVGLength y1;
  attribute SVGLength x2;
  attribute SVGLength y2;

  // spreadMethod Types
  const unsigned short kSVG_SPREADMETHOD_PAD     = 0;
  const unsigned short kSVG_SPREADMETHOD_REFLECT = 1;
  const unsigned short kSVG_SPREADMETHOD_REPEAT  = 2;
  attribute  unsigned short spreadMethod;
};

13.4.3 Interface SVGRadialGradientElement

The SVGRadialGradientElement interface corresponds to the 'radialGradient' element. 

interface SVGRadialGradientElement : SVGGradientElement {
  attribute SVGLength cx;
  attribute SVGLength cy;
  attribute SVGLength r;
  attribute SVGLength fx;
  attribute SVGLength fy;
};

13.4.4 Interface SVGStopElement

The SVGStopElement interface corresponds to the 'stop' element. 

interface SVGStopElement : SVGStyledElement {
  attribute float offset;
};

13.4.5 Interface SVGPatternElement

The SVGPatternElement interface corresponds to the 'pattern' element. 

interface SVGPatternElement : SVGStyledElement {
  // patternUnits Types
  const unsigned short kSVG_PATTERNUNITS_UNKNOWN           = 0;
  const unsigned short kSVG_PATTERNUNITS_USERSPACE         = 1;
  const unsigned short kSVG_PATTERNUNITS_USERSPACEONUSE    = 2;
  const unsigned short kSVG_PATTERNUNITS_OBJECTBOUNDINGBOX = 3;
  attribute unsigned short patternUnits;
  attribute SVGTransformList patternTransform;
  attribute SVGLength x;
  attribute SVGLength y;
  attribute SVGLength width;
  attribute SVGLength height;
  attribute SVGLength refX;
  attribute SVGLength refY;
  attribute SVGRect viewBox;
  attribute SVGPreserveAspectRatio preserveAspectRatio;
};

previous   next   contents   properties   index