DrawingCanvas API: Replace imperative extension methods with stateful canvas-based drawing model

[JimBobSquarePants]

Prerequisites

• I have written a descriptive pull-request title
• I have verified that there are no overlapping pull-requests open
• I have verified that I am following matches the existing coding patterns and practice as demonstrated in the repository. These follow strict Stylecop rules 👮.
• I have provided test coverage for my change (where applicable)

Breaking Changes: DrawingCanvas API

Fix #106
Fix #244
Fix #344
Fix #367

This is a major breaking change. The library's public API has been completely redesigned around a canvas-based drawing model, replacing the previous collection of imperative extension methods.

What changed

The old API surface — dozens of IImageProcessingContext extension methods like DrawLine(), DrawPolygon(), FillPolygon(), DrawBeziers(), DrawImage(), DrawText(), etc. — has been removed entirely. These methods were individually simple but suffered from several architectural limitations:

• Each call was an independent image processor that rasterized and composited in isolation, making it impossible to batch or reorder operations.
• State (blending mode, clip paths, transforms) had to be passed to every single call.
• There was no way for an alternate rendering backend to intercept or accelerate a sequence of draw calls.

The new model: DrawingCanvas

All drawing now goes through IDrawingCanvas / DrawingCanvas<TPixel>, a stateful canvas that queues draw commands and flushes them as a batch.

Via Image.Mutate() (most common)

using SixLabors.ImageSharp.Drawing;
using SixLabors.ImageSharp.Drawing.Processing;

image.Mutate(ctx => ctx.ProcessWithCanvas(canvas =>
{
    // Fill a path
    canvas.Fill(Brushes.Solid(Color.Red), new EllipsePolygon(200, 200, 100));

    // Stroke a path
    canvas.Draw(Pens.Solid(Color.Blue, 3), new RectangularPolygon(50, 50, 200, 100));

    // Draw a polyline
    canvas.DrawLine(Pens.Solid(Color.Green, 2), new PointF(0, 0), new PointF(100, 100));

    // Draw text
    canvas.DrawText(
        new RichTextOptions(font) { Origin = new PointF(10, 10) },
        "Hello, World!",
        brush: Brushes.Solid(Color.Black),
        pen: null);

    // Draw an image
    canvas.DrawImage(sourceImage, sourceRect, destinationRect);

    // Save/Restore state (options, clip paths)
    canvas.Save(new DrawingOptions
    {
        GraphicsOptions = new GraphicsOptions { BlendPercentage = 0.5f }
    });
    canvas.Fill(brush, path);
    canvas.Restore();

    // Apply arbitrary image processing to a path region
    canvas.Process(path, inner => inner.Brightness(0.5f));

    // Commands are flushed on Dispose (or call canvas.Flush() explicitly)
}));

Standalone usage (without Image.Mutate)

DrawingCanvas<TPixel> can be constructed directly against an image frame:

using var canvas = DrawingCanvas<Rgba32>.FromRootFrame(image, new DrawingOptions());

canvas.Fill(brush, path);
canvas.Draw(pen, path);
canvas.Flush();

using var canvas = DrawingCanvas<Rgba32>.FromImage(image, frameIndex: 0, new DrawingOptions());
// ...

using var canvas = DrawingCanvas<Rgba32>.FromFrame(frame, new DrawingOptions());
// ...

Canvas state management

The canvas supports a save/restore stack (similar to HTML Canvas or SkCanvas):

int saveCount = canvas.Save();             // push current state
canvas.Save(options, clipPath1, clipPath2); // push and replace state

canvas.Restore();              // pop one level
canvas.RestoreTo(saveCount);   // pop to a specific level

State includes DrawingOptions (graphics options, shape options, transform) and clip paths. SaveLayer creates an offscreen layer that composites back on Restore.

IDrawingBackend — bring your own renderer

The library's rasterization and composition pipeline is abstracted behind IDrawingBackend. This interface has the following methods:

Method	Purpose
FlushCompositions<TPixel>	Flushes queued composition operations for the target.
TryReadRegion<TPixel>	Read pixels back from the target (needed for Process() and DrawImage()).

The library ships with DefaultDrawingBackend (CPU, tiled fixed-point rasterizer). An experimental WebGPU compute-shader backend (ImageSharp.Drawing.WebGPU) is also available, demonstrating how alternate backends plug in. Users can provide their own implementations — for example, GPU-accelerated backends, SVG emitters, or recording/replay layers.

Backends are registered on Configuration:

configuration.SetDrawingBackend(myCustomBackend);

Migration guide

Old API	New API
ctx.Fill(color, path)	ctx.ProcessWithCanvas(c => c.Fill(Brushes.Solid(color), path))
ctx.Fill(brush, path)	ctx.ProcessWithCanvas(c => c.Fill(brush, path))
ctx.Draw(pen, path)	ctx.ProcessWithCanvas(c => c.Draw(pen, path))
ctx.DrawLine(pen, points)	ctx.ProcessWithCanvas(c => c.DrawLine(pen, points))
ctx.DrawPolygon(pen, points)	ctx.ProcessWithCanvas(c => c.Draw(pen, new Polygon(new LinearLineSegment(points))))
ctx.FillPolygon(brush, points)	ctx.ProcessWithCanvas(c => c.Fill(brush, new Polygon(new LinearLineSegment(points))))
ctx.DrawText(text, font, color, origin)	ctx.ProcessWithCanvas(c => c.DrawText(new RichTextOptions(font) { Origin = origin }, text, Brushes.Solid(color), null))
ctx.DrawImage(overlay, opacity)	ctx.ProcessWithCanvas(c => c.DrawImage(overlay, sourceRect, destRect))
Multiple independent draw calls	Single ProcessWithCanvas block — commands are batched and flushed together

Other breaking changes in this PR

• AntialiasSubpixelDepth removed — The rasterizer now uses a fixed 256-step (8-bit) subpixel depth. The old AntialiasSubpixelDepth property (default: 16) controlled how many vertical subpixel steps the rasterizer used per pixel row. The new fixed-point scanline rasterizer integrates area/cover analytically per cell rather than sampling at discrete subpixel rows, so the "depth" is a property of the coordinate precision (24.8 fixed-point), not a tunable sample count. 256 steps gives ~0.4% coverage granularity — more than sufficient for all practical use cases. The old default of 16 (~6.25% granularity) could produce visible banding on gentle slopes.
• GraphicsOptions.Antialias — now controls RasterizationMode (antialiased vs aliased). When false, coverage is snapped to binary using AntialiasThreshold.
• GraphicsOptions.AntialiasThreshold — new property (0–1, default 0.5) controlling the coverage cutoff in aliased mode. Pixels with coverage at or above this value become fully opaque; pixels below are discarded.

Benchmarks

The DrawPolygonAll benchmark renders a 7200x4800px path of the state of Mississippi with a 2px stroke.

Due to the fused design of our rasterizer, we're absolutely dominating. 🚀🚀🚀🚀🚀

BenchmarkDotNet=v0.13.1, OS=Windows 10.0.26200
Unknown processor
.NET SDK=10.0.103
  [Host] : .NET 8.0.24 (8.0.2426.7010), X64 RyuJIT

Toolchain=InProcessEmitToolchain  InvocationCount=1  IterationCount=40
LaunchCount=3  UnrollFactor=1  WarmupCount=40

Method	Mean	Error	StdDev	Median	Ratio	RatioSD
SkiaSharp	37.30 ms	0.487 ms	1.510 ms	37.49 ms	1.00	0.00
SystemDrawing	44.03 ms	0.599 ms	1.935 ms	44.60 ms	1.19	0.08
ImageSharp	11.61 ms	0.231 ms	0.731 ms	11.56 ms	0.31	0.02
ImageSharpWebGPUNativeSurface	16.72 ms	0.283 ms	0.912 ms	16.63 ms	0.45	0.03

[JimBobSquarePants]

Btw, once I get going, my strategy would be to implement a backend on top of a modern 2D renderer like Vello or Skia Graphite. I don't trust LLM output for relatively new tech like WebGPU, I think there's insufficient training material out there.

Our WebGPU backend is already very heavily based on Vello. The staged scene pipeline, shader structure, and a lot of the GPU-side execution model follow that design quite closely.

The actual GPU render part is already very fast. The remaining cost is mostly the work around it: scene preparation, encoding, staging, and scheduling. I have already spent weeks pushing that down, so I do not think there is some obvious untapped win left there that would suddenly disappear by wrapping a different renderer.

That is why I would not recommend trying to build a separate backend from scratch on top of Vello or Graphite. At this point, that would mostly mean redoing a large amount of integration work to arrive back at the same class of bottlenecks, because the hard part is not just “having a modern GPU rasterizer”, it is fitting that rasterizer into the rest of the drawing architecture.

[antonfirsov]

redoing a large amount of integration work to arrive back at the same class of bottlenecks, because the hard part is not just “having a modern GPU rasterizer”, it is fitting that rasterizer into the rest of the drawing architecture

I may still do it. The goal is not a fully featured alternative rasterizer, since the main value/outcome is not the alternative rasterizer itself. It's the thoughts arising from discovering and critically looking at the API with fresh eyes while going through the process of "fitting that rasterizer into the rest of the drawing architecture" (and taking the existing backend out of the equation).

But that's just my initial thoughts, I may change my mind. This is the first case of doing something MASSIVE with AI in SixLabors repos while also giving an attempt for a review. If you have other suggestions about how to start critical analysis of an area that's also mostly new to me and for providing tangible help here, I'm open to them.

[JimBobSquarePants]

If you have other suggestions about how to start critical analysis of an area that's also mostly new to me and for providing tangible help here, I'm open to them.

Honestly, I don't know other than pulling it down and having a look at how it works from a user perspective. I'd probably focus on that rather than the backends because that what most developers will be working with.

I am biased of course but I think the new canvas API is a breath of fresh air...

I've spent weeks now testing and refining this. AI isn't nearly capable of writing this stuff on its own and I have been hands on during every step of the design and development. AI was used mainly to bounce ideas off, help rewrite tests and port existing rasterizers to our API not in the design of the APIs themselves.

I found and fixed several pre-existing issues and have managed to simplify and optimize at almost every point of the processing pipeline compared to our current main. No software is perfect and if we discover down the line that the shape of something isn't quite right, we can update it in the next major. I'm more than happy to take that on the chin.

[antonfirsov]

I think the new canvas API is a breath of fresh air

I agree that having this API is a good move, I'm just thinking out loud on how to approach this thing as a reviewer.

having a look at how it works from a user perspective

The backend extension points are also API-s, so I'm really hoping we can bring there as much validation as possible, but you may be right that it's not the no1 priority for V4.

Anyways, I'll pull down the current state, start random experiments and see what happens.