Painting: Filling, Stroking and Marker Symbols

Introduction

'path' elements, 'text' elements and basic shapes 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.

Certain elements (i.e., 'path', 'polyline', 'polygon' and 'line' elements) can also have marker symbols drawn at their vertices.

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 extensibility

SVG uses the general notion of a paint server. Paint servers are specified using a IRI reference on a 'fill' or 'stroke' property. Gradients and patterns are just specific types of paint servers.

Specifying paint

Properties 'fill' and 'stroke' take on a value of type <paint>, which is specified as follows:

none

Indicates that no paint is applied.

currentColor

Indicates that painting is done using the current animated value of 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> [<icccolor>]

<color> is the explicit color (in the sRGB color space [SRGB]) to be used to paint the current object. SVG supports all of the syntax alternatives for <color> defined in CSS2 ([CSS2], section 4.3.6), with the exception that SVG contains an expanded list of recognized color keywords names. If an optional ICC color specification [ICC42] is provided, then the user agent searches the color profile description database for a color profile description entry whose name descriptor matches the <name> part of the <icccolor> and uses the last matching entry that is found. (If no match is found, then the ICC color specification is ignored.) The comma and/or whitespace separated list of <number>s is a set of ICC-profile-specific color values. (In most cases, the <number>s will be in the range 0 to 1.) On platforms which support ICC-based color management, the <icccolor> gets precedence over the <color> (which is in the sRGB color space). Note that color interpolation occurs in an RGB color space even if an ICC-based color specification is provided (see 'color-interpolation' and 'color-interpolation-filters'). For more on ICC-based colors, refer to Color profile descriptions.

<funciri>
   [ none |
      currentColor |
      <color> [<icccolor>] ]

The <funciri> is used to identify a paint server such as a gradient, a pattern or a custom paint defined by an extension (see Extensibility). The <funciri> points to the paint server (e.g., a gradient or pattern) to be used to paint the current object. If the IRI reference 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 <funciri> (i.e., none | currentColor | <color> [<icccolor>] is used if provided; otherwise, the document is in error (see Error processing).

Fill Properties

The 'fill' property paints the interior of the given graphical element. The area to be painted consists of any areas inside the outline of the shape. To determine the inside of the shape, all subpaths are considered, and the interior is determined according to the rules associated with the current value of the 'fill-rule' property. The zero-width geometric outline of a shape is included in the area to be painted.

The fill operation fills open subpaths by performing the fill operation as if an additional "closepath" command were added to the path to connect the last point of the subpath with the first point of the subpath. Thus, fill operations apply to both open subpaths within 'path' elements (i.e., subpaths without a closepath command) and 'polyline' elements.

The 'fill-rule' property indicates the algorithm which is to be used to determine what parts of the canvas are included inside the shape. For a simple, non-intersecting path, it is intuitively clear what region lies "inside"; however, for a more complex path, such as a path that intersects itself or where one subpath encloses another, the interpretation of "inside" is not so obvious.

The 'fill-rule' property provides two options for how the inside of a shape is determined:

nonzero

This rule determines the "insideness" of a point on the canvas by drawing a ray from that point to infinity in any direction and then examining the places where a segment of the shape crosses the ray. Starting with a count of zero, add one each time a path segment crosses the ray from left to right and subtract one each time a path segment crosses the ray from right to left. After counting the crossings, if the result is zero then the point is outside the path. Otherwise, it is inside. The following drawing illustrates the nonzero rule:

View this example as SVG (SVG-enabled browsers only)

evenodd

This rule determines the "insideness" of a point on the canvas by drawing a ray from that point to infinity in any direction and counting the number of path segments from the given shape that the ray crosses. If this number is odd, the point is inside; if even, the point is outside. The following drawing illustrates the evenodd rule:

View this example as SVG (SVG-enabled browsers only)

(Note: the above explanations do not specify what to do if a path segment coincides with or is tangent to the ray. Since any ray will do, one may simply choose a different ray that does not have such problem intersections.)

'fill-opacity' specifies the opacity of the painting operation used to paint the interior the current object. (See Painting shapes and text.)

<opacity-value>

The opacity of the painting operation used to fill the current 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.)

Related properties: 'stroke-opacity' and 'opacity'.

Stroke Properties

The following are the properties which affect how an element is stroked.

In all cases, all stroking properties which are affected by directionality, such as those having to do with dash patterns, must be rendered such that the stroke operation starts at the same point at which the graphics element starts. In particular, for 'path' elements, the start of the path is the first point of the initial "moveto" command.

For stroking properties such as dash patterns whose computations are dependent on progress along the outline of the graphics element, distance calculations are required to utilize the SVG user agent's standard Distance along a path algorithms.

When stroking is performed using a complex paint server, such as a gradient or a pattern, the stroke operation must be identical to the result that would have occurred if the geometric shape defined by the geometry of the current graphics element and its associated stroking properties were converted to an equivalent 'path' element and then filled using the given paint server.

The 'stroke' property paints along the outline of the given graphical element.

A subpath (see Paths) consisting of a single moveto shall not be stroked. Any zero length subpath shall not be stroked if the 'stroke-linecap' property has a value of butt but shall be stroked if the 'stroke-linecap' property has a value of round or square, producing respectively a circle or a square centered at the given point. Examples of zero length subpaths include 'M 10,10 L 10,10', 'M 20,20 h 0', 'M 30,30 z' and 'M 40,40 c 0,0 0,0 0,0'.

This property specifies the width of the stroke on the current object. If a <percentage> is used, the value represents a percentage of the current viewport. (See Units.)

A zero value causes no stroke to be painted. A negative value is an error (see Error processing).

'stroke-linecap' specifies the shape to be used at the end of open subpaths when they are stroked. For further details see the path implementation notes.

butt

See drawing below.

round

See drawing below.

square

See drawing below.

View this example as SVG (SVG- and CSS-enabled browsers only)

'stroke-linejoin' specifies the shape to be used at the corners of paths or basic shapes when they are stroked. For further details see the path implementation notes.

miter

See drawing below.

round

See drawing below.

bevel

See drawing below.

View this example as SVG (SVG- and CSS-enabled browsers only)

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-width'. When the limit is exceeded, the join is converted from a miter to a bevel.

<miterlimit>

The limit on the ratio of the miter length to the 'stroke-width'. The value of <miterlimit> must be a <number> greater than or equal to 1. Any other value is an error (see Error processing).

The ratio of miter length (distance between the outer tip and the inner corner of the miter) to 'stroke-width' is directly related to the angle (theta) between the segments in user space by the formula:

miterLength / stroke-width = 1 / sin ( theta / 2 )

For example, a miter limit of 1.414 converts miters to bevels for theta less than 90 degrees, a limit of 4.0 converts them for theta less than approximately 29 degrees, and a limit of 10.0 converts them for theta less than approximately 11.5 degrees.

'stroke-dasharray' controls the pattern of dashes and gaps used to stroke paths. <dasharray> contains a list of comma and/or white space separated <length>s and <percentage>s that specify the lengths of alternating dashes and gaps. If an odd number of values is provided, then the list of values is repeated to yield an even number of values. Thus, stroke-dasharray: 5,3,2 is equivalent to stroke-dasharray: 5,3,2,5,3,2.

none

Indicates that no dashing is used. If stroked, the line is drawn solid.

<dasharray>

A list of comma and/or white space separated <length>s (which can have a unit identifier) and <percentage>s. A percentage represents a distance as a percentage of the current viewport (see Units). A negative value is an error (see Error processing). If the sum of the values is zero, then the stroke is rendered as if a value of none were specified. For further details see the path implementation notes.

The grammar for <dasharray> is as follows:

dasharray ::= (length | percentage) (comma-wsp dasharray)?

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

If a <percentage> is used, the value represents a percentage of the current viewport (see Units).

Values can be negative.

'stroke-opacity' specifies the opacity of the painting operation used to stroke the current object. (See Painting shapes and text.)

<opacity-value>

The opacity of the painting operation used to stroke the current 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.)

Related properties: 'fill-opacity' and 'opacity'.

Controlling visibility

SVG uses two properties, 'display' and 'visibility', to control the visibility of graphical elements or (in the case of the 'display' property) container elements.

The differences between the two properties are as follows:

• When applied to a container element, setting 'display' to none causes the container and all of its children to be invisible; thus, it acts on groups of elements as a group. 'visibility', however, only applies to individual graphics elements. Setting 'visibility' to hidden on a 'g' will make its children invisible as long as the children do not specify their own 'visibility' properties as visible. Note that 'visibility' is not an inheritable property.
• When the 'display' property is set to none, then the given element does not become part of the rendering tree. With 'visibility' set to hidden, however, processing occurs as if the element were part of the rendering tree and still taking up space, but not actually rendered onto the canvas. This distinction has implications for the 'tspan', 'tref' and 'altGlyph' elements, event processing, for bounding box calculations and for calculation of clipping paths. If 'display' is set to none on a 'tspan', 'tref' or 'altGlyph' element, then the text string is ignored for the purposes of text layout; however, if 'visibility' is set to hidden, the text string is used for text layout (i.e., it takes up space) even though it is not rendered on the canvas. Regarding events, if 'display' is set to none, the element receives no events; however, if 'visibility' is set to hidden, the element might still receive events, depending on the value of property 'pointer-events'. The geometry of a graphics element with 'display' set to none is not included in bounding box and clipping paths calculations; however, even if 'visibility' is to hidden, the geometry of the graphics element still contributes to bounding box and clipping path calculations.

A value of display: none indicates that the given element and its children shall not be rendered directly (i.e., those elements are not present in the rendering tree). Any value other than none or inherit indicates that the given element shall be rendered by the SVG user agent.

The 'display' property only affects the direct rendering of a given element, whereas it does not prevent elements from being referenced by other elements. For example, setting display: none on a 'path' element will prevent that element from getting rendered directly onto the canvas, but the 'path' element can still be referenced by a 'textPath' element; furthermore, its geometry will be used in text-on-a-path processing even if the 'path' has display: none.

The 'display' property affects direct rendering into offscreen canvases also, such as occurs with the implementation model for masks. Thus, setting display: none on a child of a 'mask element' will prevent the given child element from being rendered as part of the mask. Similarly, setting display: none on a child of a 'clipPath element' element will prevent the given child element from contributing to the clipping path.

Elements with display: none do not take up space in text layout operations, do not receive events, and do not contribute to bounding box and clipping paths calculations.

Except for any additional information provided in this specification, the normative definition of the 'display' property is the CSS2 definition ([CSS2], section 9.2.6).

visible

The current graphics element is visible.

hidden or collapse

The current graphics element is invisible (i.e., nothing is painted on the canvas).

Note that if the 'visibility' property is set to hidden on a 'tspan', 'tref' or 'altGlyph' element, then the text is invisible but still takes up space in text layout calculations.

Depending on the value of property 'pointer-events', graphics elements which have their 'visibility' property set to hidden still might receive events.

Except for any additional information provided in this specification, the normative definition of the 'visibility' property is the CSS2 definition ([CSS2], section 11.2).

Markers

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" 
  "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="4in" height="2in" 
     viewBox="0 0 4000 2000" version="1.1"
     xmlns="http://www.w3.org/2000/svg">
  <defs>
    <marker id="Triangle"
      viewBox="0 0 10 10" refX="0" refY="5" 
      markerUnits="strokeWidth"
      markerWidth="4" markerHeight="3"
      orient="auto">
      <path d="M 0 0 L 10 5 L 0 10 z" />
    </marker>
  </defs>
  <rect x="10" y="10" width="3980" height="1980"
       fill="none" stroke="blue" stroke-width="10" />
  <desc>Placing an arrowhead at the end of a path.
  </desc>
  <path d="M 1000 750 L 2000 750 L 2500 1250"
        fill="none" stroke="black" stroke-width="100" 
        marker-end="url(#Triangle)"  />
</svg>

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" 
  "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="4in" height="2in" 
     viewBox="0 0 4000 2000" version="1.1"
     xmlns="http://www.w3.org/2000/svg">
  <desc>File which produces the same effect
      as the marker example file, but without
      using markers.
  </desc>
  <rect x="10" y="10" width="3980" height="1980"
       fill="none" stroke="blue" stroke-width="10" />
  <!-- The path draws as before, but without the marker properties -->
  <path d="M 1000 750 L 2000 750 L 2500 1250"
        fill="none" stroke="black" stroke-width="100"  />
  <!-- The following logic simulates drawing a marker 
       at final vertex of the path. -->
  <!-- First off, move the origin of the user coordinate system
       so that the origin is now aligned with the end point of the path. -->
  <g transform="translate(2500,1250)" >
    <!-- Rotate the coordinate system 45 degrees because
         the marker specified orient="auto" and the final segment
         of the path is going in the direction of 45 degrees. -->
    <g transform="rotate(45)" >
      <!-- Scale the coordinate system to match the coordinate system
           indicated by the 'markerUnits' attributes, which in this case has
           a value of 'strokeWidth'. Therefore, scale the coordinate system
           by the current value of the 'stroke-width' property, which is 100. -->
      <g transform="scale(100)" >
        <!-- Translate the coordinate system by 
             (-refX*viewBoxToMarkerUnitsScaleX, -refY*viewBoxToMarkerUnitsScaleY)
             in order that (refX,refY) within the marker will align with the vertex.
             In this case, we use the default value for preserveAspectRatio
             ('xMidYMid meet'), which means find a uniform scale factor
             (i.e., viewBoxToMarkerUnitsScaleX=viewBoxToMarkerUnitsScaleY)
             such that the viewBox fits entirely within the viewport ('meet') and 
             is center-aligned ('xMidYMid'). In this case, the uniform scale factor
             is markerHeight/viewBoxHeight=3/10=.3. Therefore, translate by
             (-refX*.3,-refY*.3)=(0*.3,-5*.3)=(0,-1.5). -->
        <g transform="translate(0,-1.5)" >
          <!-- There is an implicit clipping path because the user agent style
               sheet says that the 'overflow' property for markers has the value
               'hidden'. To achieve this, create a clipping path at the bounds
               of the viewport. Note that in this case the viewport extends
               0.5 units to the left and right of the viewBox due to 
               a uniform scale factor, different ratios for markerWidth/viewBoxWidth
               and markerHeight/viewBoxHeight, and 'xMidYMid' alignment -->
          <clipPath id="cp1" >
            <rect x="-0.5" y="0" width="4" height="3" />
          </clipPath>
          <g clip-path="url(#cp1)" >
            <!-- Scale the coordinate system by the uniform scale factor
                 markerHeight/viewBoxHeight=3/10=.3 to set the coordinate
                 system to viewBox units. -->
            <g transform="scale(.3)" >
              <!-- This 'g' element carries all property values that result from
                   cascading and inheritance of properties on the original 'marker' element.
                   In this example, neither fill nor stroke was specified on the 'marker'
                   element or any ancestors of the 'marker', so the initial values of
                   "black" and "none" are used, respectively. -->
             <g fill="black" stroke="none" >
                <!-- Expand out the contents of the 'marker' element. -->
                <path d="M 0 0 L 10 5 L 0 10 z" />
              </g>
            </g>
          </g>
        </g>
      </g>
    </g>
  </g>
</svg>

Rendering properties

Color interpolation properties: 'color-interpolation' and 'color-interpolation-filters'

The SVG user agent performs color interpolations and compositing at various points as it processes SVG content. Two properties, 'color-interpolation' and 'color-interpolation-filters', control which color space is used for particular categories of graphics operations. The following table shows which property applies to which graphics operations:

Both properties choose between color operations occurring in the sRGB color space or in a (light energy linear) linearized RGB color space. Having chosen the appropriate color space, component-wise linear interpolation is used.

The conversion formulas between the sRGB color space (i.e., nonlinear with 2.2 gamma curve) and the linearized RGB color space (i.e., color values expressed as sRGB tristimulus values without a gamma curve) can be found in the sRGB specification [SRGB]. For illustrative purposes, the following formula shows the conversion from sRGB to linearized RGB:

  R[sRGB] = R[sRGB-8bit] / 255
  G[sRGB] = G[sRGB-8bit] / 255
  B[sRGB] = B[sRGB-8bit] / 255
If R[sRGB], G[sRGB], B[sRGB] <= 0.04045
  R[linearRGB] = R[sRGB] / 12.92
  G[linearRGB] = G[sRGB] / 12.92
  B[linearRGB] = B[sRGB] / 12.92
else if R[sRGB], G[sRGB], B[sRGB] > 0.04045
  R[linearRGB] = ((R[sRGB] + 0.055) / 1.055) ^ 2.4
  G[linearRGB] = ((G[sRGB] + 0.055) / 1.055) ^ 2.4
  B[linearRGB] = ((B[sRGB] + 0.055) / 1.055) ^ 2.4
  R[linearRGB-8bit] = R[linearRGB] * 255
  G[linearRGB-8bit] = G[linearRGB] * 255
  B[linearRGB-8bit] = B[linearRGB] * 255

Out-of-range color values, if supported by the user agent, also are converted using the above formulas. (See Clamping values which are restricted to a particular range.)

auto

Indicates that the user agent can choose either the sRGB or linearRGB spaces for color interpolation. This option indicates that the author doesn't require that color interpolation occur in a particular color space.

sRGB

Indicates that color interpolation should occur in the sRGB color space.

linearRGB

Indicates that color interpolation should occur in the linearized RGB color space as described above.

The 'color-interpolation' property specifies the color space for gradient interpolations, color animations and alpha compositing.

When a child element is blended into a background, the value of the 'color-interpolation' property on the child determines the type of blending, not the value of the 'color-interpolation' on the parent. For gradients which make use of the 'xlink:href' attribute to reference another gradient, the gradient uses the 'color-interpolation' property value from the gradient element which is directly referenced by the 'fill' or 'stroke' property. When animating colors, color interpolation is performed according to the value of the 'color-interpolation' property on the element being animated.

auto

Indicates that the user agent can choose either the sRGB or linearRGB spaces for filter effects color operations. This option indicates that the author doesn't require that color operations occur in a particular color space.

sRGB

Indicates that filter effects color operations should occur in the sRGB color space.

linearRGB

Indicates that filter effects color operations should occur in the linearized RGB color space.

The 'color-interpolation-filters' property specifies the color space for imaging operations performed via filter effects.

Note that 'color-interpolation-filters' has a different initial value than 'color-interpolation'. 'color-interpolation-filters' has an initial value of linearRGB, whereas 'color-interpolation' has an initial value of sRGB. Thus, in the default case, filter effects operations occur in the linearRGB color space, whereas all other color interpolations occur by default in the sRGB color space.

The 'color-rendering' property

The creator of SVG content might want to provide a hint to the implementation about how to make speed vs. quality tradeoffs as it performs color interpolation and compositing. The 'color-rendering' property provides a hint to the SVG user agent about how to optimize its color interpolation and compositing operations.

'color-rendering' takes precedence over 'color-interpolation-filters'. For example, assume color-rendering: optimizeSpeed and color-interpolation-filters: linearRGB. In this case, the SVG user agent should perform color operations in a way that optimizes performance, which might mean sacrificing the color interpolation precision as specified by color-interpolation-filters: linearRGB.

auto

Indicates that the user agent shall make appropriate tradeoffs to balance speed and quality, but quality shall be given more importance than speed.

optimizeSpeed

Indicates that the user agent shall emphasize rendering speed over quality. For RGB display devices, this option will sometimes cause the user agent to perform color interpolation and compositing in the device RGB color space.

optimizeQuality

Indicates that the user agent shall emphasize quality over rendering speed.

The 'shape-rendering' property

The creator of SVG content might want to provide a hint to the implementation about what tradeoffs to make as it renders vector graphics elements such as 'path' elements and basic shapes such as circles and rectangles. The 'shape-rendering' property provides these hints.

auto

Indicates that the user agent shall make appropriate tradeoffs to balance speed, crisp edges and geometric precision, but with geometric precision given more importance than speed and crisp edges.

optimizeSpeed

Indicates that the user agent shall emphasize rendering speed over geometric precision and crisp edges. This option will sometimes cause the user agent to turn off shape anti-aliasing.

crispEdges

Indicates that the user agent shall attempt to emphasize the contrast between clean edges of artwork over rendering speed and geometric precision. To achieve crisp edges, the user agent might turn off anti-aliasing for all lines and curves or possibly just for straight lines which are close to vertical or horizontal. Also, the user agent might adjust line positions and line widths to align edges with device pixels.

geometricPrecision

Indicates that the user agent shall emphasize geometric precision over speed and crisp edges.

The 'text-rendering' property

The creator of SVG content might want to provide a hint to the implementation about what tradeoffs to make as it renders text. The 'text-rendering' property provides these hints.

auto

Indicates that the user agent shall make appropriate tradeoffs to balance speed, legibility and geometric precision, but with legibility given more importance than speed and geometric precision.

optimizeSpeed

Indicates that the user agent shall emphasize rendering speed over legibility and geometric precision. This option will sometimes cause the user agent to turn off text anti-aliasing.

optimizeLegibility

Indicates that the user agent shall emphasize legibility over rendering speed and geometric precision. The user agent will often choose whether to apply anti-aliasing techniques, built-in font hinting or both to produce the most legible text.

geometricPrecision

Indicates that the user agent shall emphasize geometric precision over legibility and rendering speed. This option will usually cause the user agent to suspend the use of hinting so that glyph outlines are drawn with comparable geometric precision to the rendering of path data.

The 'image-rendering' property

The creator of SVG content might want to provide a hint to the implementation about how to make speed vs. quality tradeoffs as it performs image processing. The 'image-rendering' property provides a hint to the SVG user agent about how to optimize its image rendering.

auto

Indicates that the user agent shall make appropriate tradeoffs to balance speed and quality, but quality shall be given more importance than speed. The user agent shall employ a resampling algorithm at least as good as nearest neighbor resampling, but bilinear resampling is strongly preferred. For Conforming High-Quality SVG Viewers, the user agent shall employ a resampling algorithm at least as good as bilinear resampling.

optimizeQuality

Indicates that the user agent shall emphasize quality over rendering speed. The user agent shall employ a resampling algorithm at least as good as bilinear resampling.

optimizeSpeed

Indicates that the user agent shall emphasize rendering speed over quality. The user agent should use a resampling algorithm which achieves the goal of fast rendering, with the requirement that the resampling algorithm shall be at least as good as nearest neighbor resampling. If performance goals can be achieved with higher quality algorithms, then the user agent should use the higher quality algorithms instead of nearest neighbor resampling.

In all cases, resampling must be done in a truecolor (e.g., 24-bit) color space even if the original data and/or the target device is indexed color.

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 graphics element individually, never at the container element (e.g., a 'g') level. Thus, for the following SVG, even though the gradient fill is specified on the 'g', the gradient is simply inherited through the 'g' element down into each rectangle, each of which is rendered such that its interior is painted with the gradient.

Example Inheritance