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:

• a single color
• a gradient (linear or radial)
• a pattern (vector or image, possibly tiled)
• custom paints available via the extensibility mechanism (??? add link to Paint Server Extensibility)

SVG uses the general notion of a paint server. gradients (??? add link) and patterns (??? add link) 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:

<g>
  <defs>
    <gradient id="MyGradient"... >
	  <!-- Define gradient here -->
    </gradient>
  </defs>

  <rect style="fill: url(#MyGradient)" .../>
</g>

9.2 Fill Properties

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 HTML and SVG. This mechanism allows you to define a style in your HTML which sets the 'color' property and then pass that style to the SVG processor 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.

evenodd

(??? Need detailed description plus drawings)

nonzero

(??? Need detailed description plus drawings)

'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' 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

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

<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-antialiasing' indicates whether the outline of the current object should be antialiased (see drawing below). This attribute does not apply if 'stroke' is none.

true

The stroke of the current object should be antialiased to eliminate jaggies and blend smoothly into the background.

false

The stroke of the current object should be not be antialiased, resulting in a less smooth appearance but faster rendering.

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

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

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

(??? insert drawing here)

'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' 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' 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. For example:

<g>
  <defs>
    <lineargradient id="MyGradient" ...>
       <!-- Definition of the gradient -->
    </lineargradient>
  </defs>
  <rect style="fill: url(#MyGradient)" ... /> 
</g>

9.4.1 Linear Gradients

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

• vector-start-x, vector-start-y, vector-length and vector-angle. These attributes define a normative gradient vector for the linear gradient. This gradient vector provides starting and ending points onto which the <gradientstops> are mapped (i.e., a gradient stop at 0% is mapped to the start of the gradient vector and a gradient stop at 100% is mapped to the end of the gradient vector). Attributes vector-start-x, vector-start-y and vector-length are expressed either as <number>'s, in which case they represent a fraction within a unit square, or as a percentage, in which case they represent a percentage of the unit square. The default values for vector-start-x, vector-start-y, vector-length and vector-angle are 0%, 0%, 100%, and 0 degrees, respectively. (??? Add drawing.)
• target-type, target-left, target-top, target-right, target-bottom indicate the target rectangle onto which the linear gradient's unit square should be mapped. target-type can have the values viewport (which means target-left, target-top, target-right, target-bottom represent fractions or percentages of the current viewport), userspace (which means target-left, target-top, target-right, target-bottom represent coordinates in user space or percentages of the current viewport) or current-object (which means target-left, target-top, target-right, target-bottom represent fractions or percentages of the bounding box of the current object before any clipping).
• matrix, a set of six real <number>'s representing a 2x3 transformation matrix (i.e., a b c d e f) that should be applied to all coordinates and lengths defining the gradient. The matrix is applied after mapping the unit square onto the target rectangle. (??? Reference to matrix chapter)
• spread-method indicates what happens if the the gradient starts or ends inside the bounds of the target rectangle. Possible values are: stick (??? Need a better word. We mentioned one at the face-to-face), which says to use the terminal colors of the gradient to fill the remainder of the target rectangle, 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 rectangle is filled.

(??? 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:

• innermost-x, innermost-y, outermost-origin-x, outermost-origin-y and outermost-radius define the radial gradient's innermost focus point and outermost circle (which can transformed into an ellipse using matrix) within a normative unit square. The attributes are expressed either as <number>'s, in which case they represent a fraction within a unit square, or as a percentage, in which case they represent a percentage of the unit square.The default values for all of these attributes are 50%. (??? Add drawings to illustrate these attributes.)
• target-type, target-left, target-top, target-right, target-bottom indicate the target rectangle onto which the radial gradient's unit square should be mapped. These attributes have the same meaning as for linear gradients.
• matrix, a set of six real <number>'s representing a 2x3 transformation matrix (i.e., a b c d e f) that should be applied to all coordinates and lengths defining the gradient. The matrix is applied after mapping the unit square onto the target rectangle. This attribute has the same meaning as for linear gradients.
• spread-method indicates what happens if the the gradient starts or ends inside the bounds of the target rectangle. This attribute has the same meaning as for linear gradients.

(??? 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 <gradientstop> 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:

  <lineargradient id="white-to-red-to-black" >
    <gradientstop offset="0%" color="white"/>
    <gradientstop offset="50%" color="red"/>
    <gradientstop offset="100%" color="black"/>
  </gradient>

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 normative gradient vector. For radial gradients, it represents a percentage distance along the radius of the radial gradient.

The color attribute indicates what color to use at that gradient stop. The possible values for color match the same possible color values available for the 'fill' and 'stroke' properties.

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. The <pattern> element defines the pattern to use. To paint with the pattern, set parameter the <uri> on the 'fill' or 'stroke' properties to the name of the pattern.

This defines a pattern named "fourstar" and then uses this pattern to fill a rectangle:

<g>
  <defs>
    <pattern id="fourstar" ... >
      <!-- Define the pattern using standard graphics elements
           such as paths, images, text and shapes -->
    </pattern>
  </defs>
  <rectangle style="fill: url(#fourstar)" ... />
</g>

(We are still working on patterns. Some of the things we will clearly need: (1) Definition of some sort of viewport within the <pattern> element to define an initial coordinate system for the pattern's graphics (2) Something like the target-type, target-left, target-top, target-right and target-bottom attributes which gradients have to indicate the target rectangle onto which the pattern's bounding box should be mapped. (3) A matrix attribute to apply a transformation on the pattern after mapping the pattern's bounding box onto the target rectangle. (4) Some attribute to indicate whether to tile in x, y, both or neither (5) Some attributes to replace colors (vector graphics only?).)

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

<g>
  <defs>
    <lineargradient id="MyGradient"... >
      <!-- Define gradient here -->
    </gradient>
  </defs>

  <g style="fill: url(#MyGradient)">
    <rect .../>
    <rect .../>
  </g>
</g>