Paint Builder – Configure SVG Fill and Stroke in C#

What Is PaintBuilder?

The Aspose.SVG Builder API allows developers to configure SVG fill and stroke properties programmatically using a fluent syntax. The PaintBuilder class simplifies the creation of SVG paint values, including solid colors and references to paint servers such as patterns and gradients, in C# applications.

SVG paint configuration is commonly used for creating reusable backgrounds, decorative textures, chart styles, icon fills, and vector graphics effects. With nested builders and chained configuration methods, the Builder API makes SVG generation more readable and easier to maintain.

This article explains how to use PaintBuilder, a builder class for creating paint values for SVG elements. This class is used to specify the value of the stroke or fill attributes for SVG shapes and elements when applying colors, patterns, or gradients.

PaintBuilder is part of the Aspose.SVG Builder API and is used to configure SVG fill and stroke values. It supports multiple SVG paint values, including:

• Solid colors
• SVG pattern references
• SVG gradient references
• Other paint server references

The Builder API uses a fluent configuration model that simplifies SVG element creation and styling.

Create SVG Pattern Fills

SVG patterns allow you to fill shapes using repeating graphical elements instead of solid colors. Patterns are defined once and can be reused across multiple SVG elements. In the following example, the PaintServerId() method of the PaintBuilder class sets the fill value to reference a paint server by its Id.

using Aspose.Svg.Builder;
using System.Drawing;
using System.IO;

// Create SVG pattern with polygons and apply as fill to rectangle using C# Builder API

using (SVGDocument document = new SVGDocument())
{
    SVGSVGElement svg = new SVGSVGElementBuilder()
        .Width(100, LengthType.Percentage).Height(100, LengthType.Percentage)
        .ViewBox(0, 0, 400, 400)
        .AddG(g => g
            .AddPattern(p => p.Id("stars")
                .ViewBox(0, 0, 20, 20)
                .Width(5, LengthType.Percentage)
                .Height(5, LengthType.Percentage)
                .PatternUnits(CoordinateUnits.UserSpaceOnUse)
                .AddPolygon(points: new double[] { 5, 0, 7, 3, 10, 5, 7, 7, 5, 10, 3, 7, 0, 5, 3, 3 }, fill: Color.Teal)
                .AddPolygon(points: new double[] { 15, 0, 17, 3, 20, 5, 17, 7, 15, 10, 13, 7, 10, 5, 13, 3 }, fill: Color.DarkRed)
                .AddPolygon(points: new double[] { 15, 10, 17, 13, 20, 15, 17, 17, 15, 20, 13, 17, 10, 15, 13, 13 }, fill: Color.DarkBlue)
            )
            .AddRect(r => r.Rect(20, 40, 440, 80).Fill(pt => pt.PaintServerId("stars")))
            )
        .Build(document.FirstChild as SVGSVGElement);
    document.Save(Path.Combine(OutputDir, "pattern-stars.svg"));
}

In this example, a pattern is first defined using AddPattern(), where various colored polygons are combined to create a complex fill pattern. The AddPattern() method adds a <pattern> element configuration to the builder. The pattern is given an identifier stars. Subsequently, this pattern is applied to a rectangle element using the Fill() method with PaintServerId("stars"), which references the previously defined pattern.

Apply Patterns to SVG Shapes

Pattern fills can be applied to various SVG elements, including rectangles, circles, paths, polygons, and text elements. Any SVG element that supports the fill property can use a paint server reference created with PaintBuilder.

The following C# code example demonstrates how to create SVG patterns and apply them to shapes within the document. The code showcases the “builder within a builder” approach, which uses nested builder classes to facilitate the construction of complex objects and provides a modular, structured approach to SVG document creation:

using Aspose.Svg.Builder;
using System.Drawing;
using System.IO;

// Create SVG patterns with reusable elements and apply them to circles using C# Builder API

using (SVGDocument document = new SVGDocument())
{
    SVGSVGElement svg = new SVGSVGElementBuilder()
        .Width(100, LengthType.Percentage).Height(100, LengthType.Percentage)
        .ViewBox(0, 0, 600, 600)
        .AddG(g => g
            .FontFamily("Arial")
            .FontSize(10)
            .AddPattern(p => p.Id("Pat3a")
                .Rect(0, 0, 20, 20)
                .PatternUnits(CoordinateUnits.UserSpaceOnUse)
                .AddRect(r => r.Rect(0, 0, 10, 10).Fill(Color.LightSlateGray))
                .AddRect(r => r.Rect(10, 0, 10, 10).Fill(Color.Teal))
                .AddRect(r => r.Rect(0, 10, 10, 10).Fill(Color.DarkRed))
                .AddRect(r => r.Rect(10, 10, 10, 10).Fill(Color.Gold))
            )
            .AddPattern(p => p.Id("Pat3b")
                .Href("#Pat3a")
                .Width(23).Height(23)
            )
            .AddPattern(p => p.Id("Pat3c")
                .Href("#Pat3a")
                .Width(15).Height(15)
            )
            .AddCircle(circle => circle.Cx(90).Cy(130).R(70).Fill(pt => pt.PaintServerId("Pat3a")))
            .AddText(t => t.X(55).Y(50)
                .AddContent("Pattern #Pat3a")
            )
            .AddCircle(circle => circle.Cx(240).Cy(130).R(70).Fill(pt => pt.PaintServerId("Pat3b")))
            .AddText(t => t.X(205).Y(50)
                .AddContent("Pattern #Pat3b")
            )
            .AddCircle(circle => circle.Cx(390).Cy(130).R(70).Fill(pt => pt.PaintServerId("Pat3c")))
            .AddText(t => t.X(355).Y(50)
                .AddContent("Pattern #Pat3c")
            )
        )
        .Build(document.FirstChild as SVGSVGElement);
    document.Save(Path.Combine(OutputDir, "patterns.svg"));
}

How the Pattern Works

The <pattern> element defines a reusable tile that repeats across the filled shape. In this example:

• Width() and Height() define the size of the repeating pattern tile;
• PatternUnits(UserSpaceOnUse) uses fixed coordinates for pattern repetition;
• the circle element defines the repeated graphical content inside the pattern.

The pattern can be reused for multiple SVG elements by referencing the same pattern ID. Smaller pattern dimensions create denser repetitions, while larger values increase spacing between repeated elements.

In the example, three different patterns, named Pat3a, Pat3b, and Pat3c, are added to the SVG document.

• For Pat3a, a pattern is defined using the AddPattern() method within the AddG() method. Within this pattern, four rectangles are added to define different colored sections within a 20x20 unit space (a tile).
• Pat3b and Pat3c are defined as references to Pat3a, with different tile sizes specified using the Width() and Height() methods.

The height and width of a tile in a pattern element define the size of the repeated pattern unit in the SVG document. This size determines how the pattern will look when applied to shapes or elements in the document. In pattern Pat3b, increasing the height and width of the tile enlarges the pattern unit, resulting in unfilled (transparent) areas. In the pattern Pat3c, reducing the height and width of the tile makes the pattern appear denser, creating a different visual effect.

So, adjusting the height and width of the tile in an SVG <pattern> element allows you to control the density and repetition of the pattern within the SVG document and enables the creation of diverse visual effects.

Create Linear Gradient Fills

Aspose.SVG Builder API allows you to create reusable SVG linear gradients and apply them to SVG shapes programmatically. Gradient fills are commonly used for backgrounds, buttons, charts, decorative graphics, and UI elements.

using Aspose.Svg.Builder;
using System.Drawing;
using System.IO;

using (SVGDocument document = new SVGDocument())
{
    SVGSVGElement svg = new SVGSVGElementBuilder()
        .Width(400).Height(200)
        .ViewBox(0, 0, 400, 200)
        .AddDefs(defs => defs
            .AddLinearGradient(gradient => gradient
                .Id("gradientFill")
                .X1(0, LengthType.Percentage).Y1(0, LengthType.Percentage)
                .X2(100, LengthType.Percentage).Y2(0, LengthType.Percentage)
                .AddStop(stop => stop
                    .Offset(0, StopUnitType.Percentage)
                    .Attribute("stop-color", "gold"))
                .AddStop(stop => stop
                    .Offset(100, StopUnitType.Percentage)
                    .Attribute("stop-color", "teal"))))
        .AddRect(rect => rect
            .Rect(20, 20, 360, 160)
            .Fill(paint => paint.PaintServerId("gradientFill")))
        .Build(document.FirstChild as SVGSVGElement);

    document.Save(Path.Combine(OutputDir, "linear-gradient-fill.svg"));
}

How the Gradient Works

The example creates a reusable SVG <linearGradient> definition inside the <defs> section and applies it to a rectangle fill.

• AddLinearGradient() defines the gradient direction and identifier;
• AddStop() defines color transition points;
• PaintServerId("gradientFill") applies the gradient paint server to the rectangle fill, producing a url(#gradientFill) reference in the SVG output;
• the gradient can be reused across multiple SVG elements.

Common Mistakes and Fixes

Problem	Cause	Fix
Pattern is not visible	Incorrect pattern ID	Ensure PaintServerId() matches the pattern Id()
Pattern appears stretched	Tile size is too large	Adjust pattern Width() and Height()
Pattern does not repeat correctly	Incorrect PatternUnits value	Use UserSpaceOnUse when fixed tile sizes are required
Fill is not applied	Pattern is defined outside accessible scope	Define patterns before applying them

FAQ

1. What is a paint server in SVG?
A paint server is an SVG resource used to provide fill or stroke values. Common paint servers include patterns and gradients referenced through url(#id).

2. Can I reuse the same SVG pattern for multiple shapes?
Yes. A single SVG pattern can be reused across multiple elements by referencing the same pattern ID with PaintServerId().

3. What is the difference between the CoordinateUnits: UserSpaceOnUse and ObjectBoundingBox?
UserSpaceOnUse uses fixed coordinates for pattern rendering, while ObjectBoundingBox scales the pattern relative to the size of the target element.

4. Why does my SVG pattern appear stretched?
This usually happens when the pattern tile size is too large or when the pattern coordinate system does not match the target SVG element dimensions.

5. Can I apply SVG patterns to text elements?
Yes. SVG text elements support the fill property and can use pattern fills in the same way as shapes.

6. Are SVG gradients supported by PaintBuilder?
Yes. PaintBuilder supports gradient paint server references for configuring SVG gradient fills programmatically.

Related Resources

• The SVG Builder API article explains how to create and manipulate SVG elements programmatically in C# using the Aspose.SVG Builder API. Learn how fluent builders simplify SVG generation and improve code readability in .NET applications.
• The Element Builders article explores SVG element builders in Aspose.SVG for .NET. Learn how specialized builder classes simplify the creation of SVG shapes, graphics, and document structures in C#.
• The Path Builder article explains how to create SVG paths programmatically in C#. Learn how the PathBuilder class simplifies the generation of complex SVG shapes, curves, and vector graphics using fluent syntax.
• The Rule Builder article explains how to create CSS style rules for SVG documents in C# using the RuleBuilder class. Learn how to configure SVG styles programmatically in .NET applications.
• The SVG Filters article explains how to create SVG filter effects such as Gaussian blur, drop shadows, lighting, and saturation in C#. Learn how to apply SVG filters programmatically using Aspose.SVG for .NET.
• The SVG Gradients article explains how to create SVG linear and radial gradients in C#. Learn how to define reusable SVG gradient fills in XML and generate them programmatically using Aspose.SVG for .NET.
• The SVG Drawing Basics section covers the fundamentals of SVG graphics creation, including shapes, paths, fills, gradients, filters, and transformations using C# and Aspose.SVG for .NET.