9 Filling, Stroking and Paint Servers


9.1 Introduction

Vector graphics shapes and text objects can be filled (which means painting the interior of the object) and stroked (which means painting along the outline of the object). Filling and stroking both can be thought of in more general terms as painting operations.

With SVG, you can paint (i.e., fill or stroke) with:

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 gradient by including a <gradient> element within a <defs>, assign an ID to that <gradient> object, and then reference that ID in a 'fill' or 'stroke' property:

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

Download this example

9.2 Fill Properties

'fill'
Value:   none |
current-color |
<color> [icc-color(<colorvalue>*)] |
inherit |
<uri> [ none | current-color | <color> [icc-color(<colorvalue>*)] | inherit ]
Initial:   current-color
Applies to:  all elements
Inherited:  see Inheritance of Painting Properties below
Percentages:  N/A
Media:  visual
none
Indicates that the object should not be filled.
current-color
Indicates that the object should filled with the color specified by the 'color' property. This mechanism is provided to facilitate sharing of color attributes between parent grammars such as other (non-SVG) XML. This mechanism allows you to define a style in your HTML which sets the 'color' property and then pass that style to the SVG user agent so that your SVG text will draw in the same color.
<color> [icc-color(<colorvalue>*)]
<color> is the explicit color (in the sRGB color space) to be used to fill the current object. SVG supports all of CSS2's <color> specifications. If an optional [icc-color(<colorvalue>*)] is provided, then the list of <colorvalue>'s is a set ICC-profile-specific color values. On platforms which support ICC-based color management, the icc-color gets precedence over the <color> (which is in the sRGB color space). For more on ICC-based colors, refer to Color.
<uri> [ none | current-color | <color> | inherit ]
The <uri> is how you identify a fancy paint style such as a gradient, a pattern or a custom paint from extensibility. The <uri> should provide the ID of the paint server (e.g., a gradient [??? see link] or a pattern [??? see link] ) to be used to paint the current object. If the XPointer is not valid (e.g., it points to an object that doesn't exist or the object is not a valid paint server), then the paint method following the <uri> (i.e., none | current-color | <color> | inherit) is used if provided; otherwise, no gradient will occur.

Note that graphical objects that are not closed (e.g., a <path> without a closepath at the end or a <polyline>) still can be filled. The fill operation automatically closes all open subpaths by connecting the last point of the subpath with the first point of the subpath before painting the fill.

'fillrule'
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)
'fill-opacity'
Value:   <opacity-value>
Initial:   evenodd
Applies to:  all elements
Inherited:  yes
Percentages:  Allowed
Media:  visual

'fill-opacity' specifies the opacity of the painting operation used to fill the current object. It is important to note that any given object can have three different opacity properties: 'fill-opacity', 'stroke-opacity' and 'opacity'. The 'fill' painting operation is done and blended into the current background (or temporary offscreen buffer, if 'opacity' is not 1.0) using the value of 'fill-opacity'. Next, The 'stroke' painting operation is done and blended into the current background (or temporary offscreen buffer, if 'opacity' is not 1.0) using the value of 'stroke-opacity'. Finally, if 'opacity' is not 1.0, the offscreen holding the object as a whole is blended into the current background.

(The above paragraph needs to be moved someplace else, such as SVG Rendering Model.)

<opacity-value>
The opacity of the painting operation used to fill the current object. If a <number> is provided, then it must be in the range of 0.0 (fully transparent) to 1.0 (fully opaque). If a percentage is provided, then it must be in the range of 0% to 100%. Any values outside of the acceptable range are rounded to the nearest acceptable value.
'fill-params'
Value:   <string> | inherit
Initial:   Empty string
Applies to:  all elements
Inherited:  yes
Percentages:  Paint server-specific.
Media:  visual

'fill-params' specifies an arbitrary <string> which is passed to the current fill paint server. The meaning of <string> is paint server-specific. None of the built-in paint servers use 'fill-params'. It is meant as a way to pass parameters to a custom paint servers defined via paint server extensibility.

<string>
A <string> containing parameters which should be passed to the current fill paint server.

9.3 Stroke Properties

'stroke'
Value:   none |
current-color |
<color> [icc-color(<number>*)] |
inherit |
<uri> [ none | current-color | <color> | inherit ]
Initial:   none
Applies to:  all elements
Inherited:  see Inheritance of Painting Properties below
Percentages:  N/A
Media:  visual
none
(Same meaning as with 'fill'.)
current-color
(Same meaning as with 'fill'.)
<color>
(Same meaning as with 'fill'.)
<uri> [ none | current-color | <color> [icc-color(<colorvalue>*)] | inherit ]
(Same meaning as with 'fill'.)
'stroke-width'
Value:   <width> | inherit
Initial:   1
Applies to:  all elements
Inherited:  yes
Percentages:  Yes
Media:  visual
<width>
The width of the stroke on the current object, either expressed as a <length> in user units, a <length> in Transformed CSS units (??? add link) or as a percentage. If a percentage is used, the <width> is expressed as a percentage of the current viewport (??? add link).
'stroke-linecap'
Value:   butt | round | square | inherit
Initial:   butt
Applies to:  all elements
Inherited:  yes
Percentages:  N/A
Media:  visual

'stroke-linecap' specifies the shape to be used at the end of open subpaths when they are stroked.

butt
See drawing below.
round
See drawing below.
square
See drawing below.

(??? insert drawing here)

'stroke-linejoin'
Value:   miter | round | bevel | inherit
Initial:   miter
Applies to:  all elements
Inherited:  yes
Percentages:  N/A
Media:  visual

'stroke-linejoin' specifies the shape to be used at the corners of paths (or other vector shapes) that are stroked. when they are stroked.

miter
See drawing below.
round
See drawing below.
bevel
See drawing below.

(??? insert drawing here)

'stroke-miterlimit'
Value:   <miterlimit> | inherit
Initial:   8
Applies to:  all elements
Inherited:  yes
Percentages:  N/A
Media:  visual

When two line segments meet at a sharp angle and miter joins have been specified for 'stroke-linejoin', it is possible for the miter to extend far beyond the thickness of the line stroking the path. The 'stroke-miterlimit' imposes a limit on the ratio of the miter length to the 'stroke-linewidth'.

<miterlimit>
The limit on the ratio of the miter length to the 'stroke-linewidth'. The value of <miterlimit> must be a number greater than or equal to 1.

(??? insert drawing here)

'stroke-dasharray'
Value:   none | <dasharray> | inherit
Initial:   none
Applies to:  all elements
Inherited:  yes
Percentages:  Yes. See below.
Media:  visual

'stroke-dasharray' controls the pattern of dashes and gaps used to stroke paths. The value of <dasharray> is a list of space- or comma-separated <number>'s that specify the lengths of alternating dashes and gaps.

none
Indicates that no dashing should be used. If stroked, the line should be drawn solid.
<dasharray>
A list of space- or comma-separated <length>'s which can be in user units or in any of the CSS units, including percentages. A percentage represents a distance as a percentage of the current viewport (??? Add link here).

An empty string for 'stroke-dasharray' is equivalent to the value none.

(??? insert drawing here)

'stroke-dashoffset'
Value:   <dashoffset> | inherit
Initial:   0
Applies to:  all elements
Inherited:  yes
Percentages:  Yes. See below.
Media:  visual

'stroke-dashoffset' specifies the distance into the dash pattern to start the dash.

<dashoffset>
A <length> which can be in user units or in any of the CSS units, including percentages. A percentage represents a distance as a percentage of the current viewport (??? Add link here).

(??? insert drawing here)

'stroke-opacity'
Value:   <opacity-value> | inherit
Initial:   evenodd
Applies to:  all elements
Inherited:  yes
Percentages:  Allowed
Media:  visual

'stroke-opacity' specifies the opacity of the painting operation used to stroke the current object. (??? Add link about how different opacity parameters interact.)

<opacity-value>
The opacity of the painting operation used to stroke the current object. If a <number> is provided, then it must be in the range of 0.0 (fully transparent) to 1.0 (fully opaque). If a percentage is provided, then it must be in the range of 0% to 100%. Any values outside of the acceptable range are rounded to the nearest acceptable value.
'stroke-params'
Value:   <string> | inherit
Initial:   Empty string
Applies to:  all elements
Inherited:  yes
Percentages:  Paint server-specific.
Media:  visual

'stroke-params' specifies an arbitrary <string> which is passed to the current stroke paint server. The meaning of <string> is paint server-specific. None of the built-in paint servers use 'stroke-params'. It is meant as a way to pass parameters to a custom paint servers defined via paint server extensibility.

<string>
A <string> containing parameters which should be passed to the current stroke paint server.

9.4 Gradients

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.(??? Include drawing)

Gradients are specified within a <defs> element and are then referenced using 'fill' or 'stroke' or properties on a given graphics object (e.g., a <rect> element) to indicate that the given element should be filled or stroked with the referenced gradient.

9.4.1 Linear Gradients

Linear gradients are defined by a <lineargradient> element. A <lineargradient> element can have the following attributes:

Percentages are allowed for x1, y1, x2, y2. For gradient-units="userspace", percentages represent values relative to the current viewport. For gradient-units="object-bbox", percentages represent values relative to the bounding box for the object.

(??? Need to include some drawings here showing these attributes)

9.4.2 Radial Gradients

Radial gradients are defined by a <radialgradient> element. A <radialgradient> element can have the following attributes:

Percentages are allowed for cx, cy, r, fx, fy. For gradient-units="userspace", percentages represent values relative to the current viewport. For gradient-units="object-bbox", percentages represent values relative to the bounding box for the object.

(??? Need to include some drawings here showing these attributes)

9.4.3 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 July 1999//EN" 
  "http://www.w3.org/Graphics/SVG/svg-19990706.dtd">
<svg width="4in" height="3in">
  <desc>Radial gradient example with three gradient stops
  </desc>
  <g>
    <defs>
      <radialgradient id="MyGradient">
         <stop offset="0%" style="color:white"/>
         <stop offset="50%" style="color:red"/>
         <stop offset="100%" style="color:black"/>
      </radialgradient>
    </defs>
    <circle style="fill: url(#MyGradient)" r="42"/>
  </g>
</svg>

Download this example

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 should be 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.

The color property indicates what color to use at that gradient stop. All valid CSS2 color property specifications are available.

An opacity property can be used to define the opacity of a given gradient stop.

Some notes on gradients:

9.5 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:. The <pattern> element the same attributes as <symbol>, plus the following pattern-specific attributes:

An example:

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

Download this example

9.6 Inheritance of Painting Properties

The values of any of the painting properties described in this chapter can be inherited from a given object's parent. Painting, however, is always done on each leaf-node individually, never at the <g> level. Thus, for the following SVG, two distinct gradients are painted (one for each rectangle):

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG July 1999//EN" 
  "http://www.w3.org/Graphics/SVG/svg-19990706.dtd">
<svg width="4in" height="3in">
  <desc>Gradients apply to leaf nodes
  </desc>
  <g>
    <defs>
      <lineargradient id="MyGradient">
        <stop offset="0%" style="color:#F60"/>
        <stop offset="70%" style="color:#FF6"/>
      </lineargradient>
    </defs>
    <g style="fill: url(#MyGradient)">
      <rect width="20" height="15.8"/>
      <rect width="35" height="8"/>
   </g>
  </g>
</svg>

Download this example