Paint Servers: Solid Colors, Gradients, and Patterns

This section covers Paint Servers, a method which allows the ‘fill’ or ‘stroke’ of an object to be defined by a resource found elsewhere. It allows resources to be reused throughout a document. See the section Painting: Filling and Stroking for a general discussion of filling and stroking objects.

It seems that all paint servers (except perhaps, mesh gradients, when rendered directly) inherit from their ancestors and do not inherit from the element referencing the paint server. Rather than repeating this for each type of paint server, can the text be moved into the introduction section for paint servers?

SVG 2 Requirement:	Support hatching.
Resolution:	SVG 2 should support hatching without the artifacts that patterns currently impose.
Purpose:	To allow the kinds of patterns required for mapping, engraving, etc. where continuous lines are required.
Owner:	Tav (no action)

SVG 2 Requirement:	Arbitrary fills for shapes.
Resolution:	SVG 2 shall support filling and stroking from arbitrary elements.
Purpose:	To allow for example videos or images to be used as a fill source.
Owner:	Alex? (no action)

Paint servers are used by including an IRI reference in a ‘fill’ or ‘stroke’ property (i.e. fill="#MyLightPurple").

13.2. Solid colors

SVG 2 Requirement:	Support named colors.
Resolution:	Will add ‘solidColor’ element to SVG 2.
Purpose:	To provide an easy mechanism for creating named colors and palettes. Also useful for animation.
Owner:	Tav (no action)

The 'solidColor' element is a paint server that provides a single color with opacity. It can be referenced any place a single color can be used. The 'solidColor' element allows a palette to be defined and used consistently throughout a document. It is also useful as away of animating a palette colors. (See the chapter Color for a more general discussion of color in SVG.)

Properties inherit into the ‘solidColor’ element from its ancestors; properties do not inherit from the element referencing the ‘solidColor’ element.

‘solidColor’ 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 ‘solidColor’ element; thus, ‘solidColor’ elements are not directly rendered even if the ‘display’ property is set to a value other than none, and ‘solidColor’ elements are available for referencing even when the ‘display’ property on the ‘solidColor’ element or any of its ancestors is set to none.

13.2.1. Properties

13.3. Gradients

Gradients consist of smooth color transitions between points on a drawing surface. SVG provides for three types of gradients:

Once a gradient is defined, a graphics element can be filled or stroked with the gradient by setting the ‘fill’ or ‘stroke’ properties to reference the gradient.

Color transitions for linear and radial gradients are defined by a series of color stops along a gradient vector. A gradient normal defines how the colors in a vector are painted to the surface. For a linear gradient, the normal corresponds to lines with the same color. It is perpendicular to the vector in an untransformed gradient. When a graphics element references a gradient, conceptually the graphics element should take a copy of the gradient vector and gradient normal and treat it as part of its own geometry. Any transformations applied to the graphics element geometry also apply to the copied gradient vector and gradient normal. Any gradient transforms that are specified on the reference gradient are applied before any graphics element transformations are applied to the gradient.

Color transitions for mesh gradients are defined by an array of color stops. The mapping of colors to the drawing surface in this case is done by geometric data located in the stops. This is discussed in detail in the mesh gradients section.

13.3.1. Linear gradients

13.3.1.1. Attributes

13.3.1.2. Notes on linear gradients

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.

13.3.2. Radial gradients

Radial gradients are defined by a ‘radialGradient’ element.

‘radialGradient’

Categories:

Gradient element, paint server element

Content model:

Any number of the following elements, in any order:

descriptive elements — ‘desc’, ‘title’, ‘metadata’
paint server elements — ‘solidColor’, ‘linearGradient’, ‘radialGradient’, ‘meshGradient’, ‘pattern’

animate, animateTransform, set, stop

Attributes:

core attributes — ‘id’, ‘xml:base’, ‘xml:lang’, ‘xml:space’
presentation attributes —
style attributes — ‘class’, ‘style’
xlink attributes — ‘xlink:href’, ‘xlink:show’, ‘xlink:actuate’, ‘xlink:type’, ‘xlink:role’, ‘xlink:arcrole’, ‘xlink:title’
‘cx’
‘cy’
‘r’
‘fx’
‘fy’
‘fr’
‘gradientUnits’
‘gradientTransform’
‘spreadMethod’
‘xlink:href’

DOM Interfaces:

SVGRadialGradientElement

13.3.2.1. Attributes

gradientUnits = "userSpaceOnUse | objectBoundingBox"

Defines the coordinate system for attributes ‘cx’, ‘cy’, ‘r’, ‘fx’, ‘fy’, and ‘fr’.

lacuna value: objectBoundingBox
Animatable: yes

userSpaceOnUse

If gradientUnits="userSpaceOnUse", ‘cx’, ‘cy’, ‘r’, ‘fx’, ‘fy’, and ‘fr’ 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’. Percentages represent values relative to the current viewport.

objectBoundingBox

If gradientUnits="objectBoundingBox", the user coordinate system for attributes ‘cx’, ‘cy’, ‘r’, ‘fx’, ‘fr’, and ‘fr’ 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’. Percentages represent values relative to the bounding box for the object.

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.

gradientTransform = "<transform-list>"

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.

lacuna value: identity transform
Animatable: yes

cx = "<length>"

‘cx’, ‘cy’ and ‘r’ define the end circle for the radial gradient. The gradient will be drawn such that the 100% gradient stop is mapped to the perimeter of this end circle.

lacuna value: 50%
Animatable: yes

cy = "<length>"

See ‘cx’.

lacuna value: 50%
Animatable: yes

r = "<length>"

See ‘cx’.

A negative value is an error (see Error processing).

lacuna value: 50%
Animatable: yes

fx = "<length>"

‘fx’, ‘fy’, and ‘fr’ define the start circle for the radial gradient. The gradient will be drawn such that the 0% gradient stop is mapped to the perimeter of this start circle.

lacuna value: see below
Animatable: yes

If attribute ‘fx’ is not specified, ‘fx’ will coincide with the presentational value of ‘cx’ for the element whether the value for 'cx' was inherited or not. If the element references an element that specifies a value for 'fx', then the value of 'fx' is inherited from the referenced element.

Diagram of various radial gradient attributes.

This diagram shows how the geometric attributes are defined for the case where ‘fr’ is 50% of ‘r’. The small circle marks the center of the outermost circle (‘cx’,‘cy’), while the cross marks the center of the innermost circle (‘fx’,‘fy’). The dashed lines show two gradient vectors. Vectors connect corresponding points on the inner and outer most circles. The region outside the outer circle is painted with the the last ‘stop-color’ while the region inside the inner circle is painted with the first ‘stop-color’.

fy = "<length>"

See ‘fx’.

lacuna value: see below
Animatable: yes

If attribute ‘fy’ is not specified, ‘fy’ will coincide with the presentational value of ‘cy’ for the element whether the value for 'cy' was inherited or not. If the element references an element that specifies a value for 'fy', then the value of 'fy' is inherited from the referenced element.

fr = "<length>"

New in SVG 2. Added to align with Canvas.

‘fr’ is the radius of the focal circle. See ‘fx’.

A negative value is an error (see Error processing).

lacuna value: 0%, see below
Animatable: yes

If the attribute is not specified, the effect is as if a value of '0%' were specified. If the element references an element that specifies a value for 'fr', then the value of 'fr' is inherited from the referenced element.

SVG 2 Requirement:	Allow specifying focal circle radius in radial gradients.
Resolution:	Add an ‘fr’ attribute to ‘radialGradient’> for SVG 2.
Purpose:	To align with Canvas. The zero-offset stop would be along the circle defined by the ‘fx’, ‘fy’ and ‘fr’ attributes.
Owner:	Erik (ACTION-3098)

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.

lacuna value: pad
Animatable: yes

xlink:href = "<iri>"

An IRI 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 ‘xlink: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 ‘xlink:href’ attribute, then the current element can inherit those attributes or gradient stops.

lacuna value: empty
Animatable: yes

SVG 2 Requirement:	Clarify radial gradients with focal point on the circle.
Resolution:	When the focal point is on the circle edge, with repeat, then the distance between the first and last stop for the repeating colors is 0 and the paint should generate a color that is the average of all the gradient stops.
Purpose:	To improve interoperability of radial gradients.
Owner:	Erik (ACTION-3097)
Note:	SVG 1.1 does not define what to do when the focal point is on the circle edge, with 'repeat'. The distance between the first and last stop for the repeating colors is 0. It was resolved that the paint should generate a color that is the weighted average (by offset) of all the gradient stops.

13.3.2.2. Notes on radial gradients

Changed in SVG 2. SVG 1.1 required that the focal point, if outside the end circle, be moved to be on the end circle. The change was made to align with Canvas.

Allowing the focal point to lie outside the end circle was resolved at the Rigi Kaltbad working group meeting.

If the start circle defined by ‘fx’, ‘fy’ and ‘fr’ lies outside the end circle defined by ‘cx’, ‘cy’, and ‘r’, effectively a cone is created, touched by the two circles. Areas outside the cone stay untouched by the gradient (transparent black).

If the start circle fully overlaps with the end circle, no gradient is drawn. The area stays untouched (transparent black).

Image of a radial gradient with the focal (start circle) outside
the start circle.

A radial gradient with the focal (start) circle outside the start circle. The focal circle is the larger circle on the left. The gradient has spreadMethod="reflect".

Image of two radial gradients, one with the focus just inside the circumference
and one with the focus on the circumference.

Two radial gradients with spreadMethod="repeat". On the left, the focal point is just inside the right side of the circle defined by by ‘cx’, ‘cy’, and ‘r’. On the right, the focal point is on the circle. In this case, the area painted to the right of the circumference has a fill equal to the weighted average of the colors in the gradient vector.

The treatment of the area to the right of the gradient in the right-hand side of the above figure is different from that of Canvas where the area would be transparent black. The difference is to maintain compatibility with SVG 1.1.

The color space for the weighted average is the same as in which the gradient is interpolated. See Rigi Kaltbad working group meeting.

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.

<?xml version="1.0" standalone="no"?>
<svg xmlns="http://www.w3.org/2000/svg"
     version="1.1"
     viewBox="0 0 300 200" >
  <title>Example radgrad01</title>
  <desc>Fill a rectangle by referencing a radial gradient paint server.</desc>

  <defs>
    <radialGradient id="MyGradient"
		    gradientUnits="userSpaceOnUse"
		    cx="150" cy="100"
		    r="100">
      <stop offset="0%"   stop-color="#A8F" />
      <stop offset="50%"  stop-color="#FDC" />
      <stop offset="100%" stop-color="#A8F" />
    </radialGradient>
  </defs>

  <!-- The rectangle is filled using a radial gradient paint server -->
  <rect fill="url(#MyGradient)"
	stroke="black"
	stroke-width="2"
	x="25" y="25" width="250" height="150"/>
</svg>

Example radgrad01

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

13.3.3. Mesh gradients

New in SVG 2. Added to allow shadings along curved lines. This is needed, for example, in creating life-like drawings.

The mesh gradients in SVG are based on an array of Coons Patches. A Coons Patch is a shading defined by colors place at the corners of an area enclosed by four Bézier curves.

A Coons Patch is equivalent to a bi-cubic Ferguson patch where the distance between a cubic Bézier end point and its nearest control point is one-third the length of the corresponding Ferguson tangent line.

The corner colors are mapped to the patch area with a two step process. First the colors are placed at the corners of a unit square the area inside the square is colored using a bilinear interpolation. Second, the points inside the square are mapped to points inside the patch using the following formula (u, and v are the coordinates inside the unit square):

Come up with better explanation of the mapping with diagram. The subtraction term in the above formula ensures that the boundary conditions are met.

For a mesh, the individual patches are placed in an array. There are two reasons for using an array. The first is that an array of meshes is a natural result for most content creation processes (start with a path and then subdivide its area into rows and columns of patches). The second is that the data can be compacted by sharing sides and corners. The array structure is conceptual only. The actual mesh can be distorted in any way possible. The mesh gradient syntax is designed so that it is easy to simulate other types of gradients such as conical gradients or triangle meshes as shown in the examples below.

SVG 2 Requirement:	Support photorealistic gradients.
Resolution:	Mesh gradients are accepted by the WG for SVG 2.
Purpose:	To allow more complex gradients such as those found in nature.
Owner:	Tav (ACTION-3121)

TODO: Define ‘x’, ‘y’, ‘gradientUnits’ ‘gradientTransform’ and ‘href’ attributes.

13.3.4. Gradient stops

The vector (linear and radial gradients) or array (mesh gradients) of colors to use in a gradient is defined by the ‘stop’ elements that are child elements to a ‘linearGradient’, ‘radialGradient’, or ‘meshPatch’ element.

In SVG 1.1, the above read: "The ramp of colors..." but "ramp" is used nowhere else in this section.

13.3.4.1. Attributes

13.3.4.2. Properties

13.3.4.3. Notes on gradient stops

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

13.4.1. Attributes

13.4.2. Notes on patterns

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. Note that if the ‘overflow’ property is set to visible the rendering behavior for the pattern is undefined. 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.

Example pattern01 shows how to fill a rectangle by referencing a pattern paint server. Note how the blue stroke of each triangle has been slightly 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.

Chapter 13: Paint Servers: Solid Colors, Gradients, and Patterns

Contents

13.1. Introduction

13.2. Solid colors

13.2.1. Properties

13.3. Gradients

13.3.1. Linear gradients

13.3.1.1. Attributes

13.3.1.2. Notes on linear gradients

13.3.2. Radial gradients

13.3.2.1. Attributes

13.3.2.2. Notes on radial gradients

13.3.3. Mesh gradients

13.3.4. Gradient stops

13.3.4.1. Attributes

13.3.4.2. Properties

13.3.4.3. Notes on gradient stops

13.4. Patterns

13.4.1. Attributes

13.4.2. Notes on patterns

13.5. DOM interfaces

13.5.1. Interface SVGSolidColorElement

13.5.2. Interface SVGGradientElement

13.5.3. Interface SVGLinearGradientElement

13.5.4. Interface SVGRadialGradientElement

13.5.5. Interface SVGMeshGradientElement

13.5.6. Interface SVGMeshRowElement

13.5.7. Interface SVGMeshPatchElement

13.5.8. Interface SVGStopElement

13.5.9. Interface SVGPatternElement