ProcessWithCanvas -> Paint

Author: JimBobSquarePants

README.md

@@ -15,6 +15,17 @@ SixLabors.ImageSharp.Drawing
 </div>
 
 **ImageSharp.Drawing** is a cross-platform 2D drawing library built on top of [ImageSharp](https://github.com/SixLabors/ImageSharp). It provides path construction, polygon manipulation, fills, strokes, gradient brushes, pattern brushes, and text rendering. Built against [.NET 8](https://docs.microsoft.com/en-us/dotnet/standard/net-standard).
+
+## Quick Start
+
+```csharp
+image.Mutate(ctx => ctx.Paint(canvas =>
+{
+    canvas.Fill(Brushes.Solid(Color.White));
+    canvas.Fill(Brushes.Solid(Color.Red), new EllipsePolygon(200, 200, 100));
+    canvas.Draw(Pens.Solid(Color.Blue, 3F), new RectangularPolygon(50, 50, 200, 100));
+}));
+```
 
 ## License
 

samples/DrawShapesWithImageSharp/README.md

@@ -10,7 +10,7 @@ A sample application that demonstrates the core vector drawing capabilities of I
 - **Curves** — Ellipses via `EllipsePolygon` and cubic Bezier arcs via `CubicBezierLineSegment`.
 - **Text as paths** — Converting text to vector outlines using `TextBuilder.GeneratePaths()` with system fonts, including text laid out along a curved path.
 - **Serialized glyph data** — Rendering OpenSans letter shapes ('a' and 'o') from serialized coordinate data as `ComplexPolygon` instances.
-- **Canvas API** — `Fill` for solid backgrounds and shape rendering via `ProcessWithCanvas`.
+- **Canvas API** — `Fill` for solid backgrounds and shape rendering via `Paint`.
 
 ## Running
 

src/ImageSharp.Drawing/Processing/DRAWING_CANVAS.md

@@ -59,6 +59,9 @@ Before looking at the flow, it helps to define the major terms in the sense used
 
 It is not the rasterizer. It is the object that makes the public drawing model coherent.
 
+Most callers reach that model through `IImageProcessingContext.Paint(...)`, while lower-level code can
+also create a canvas directly with the `CreateCanvas(...)` extension methods.
+
 ### Batcher
 
 `DrawingCanvasBatcher<TPixel>` is the deferred command queue. It stores pending `CompositionCommand` values, prepares them during flush, builds a `CompositionScene`, and calls `IDrawingBackend.FlushCompositions(...)`.
@@ -99,7 +102,8 @@ There are two backend-selection paths in the architecture:
 - the ordinary public `DrawingCanvas<TPixel>` constructors resolve the backend from `Configuration`
 - specialized infrastructure can construct a canvas with an explicit backend
 
-The ordinary CPU entry points also include the `CreateCanvas(...)` extension methods on `Image<TPixel>` and `ImageFrame<TPixel>`, which route into those same constructors.
+The ordinary CPU entry points include `Paint(...)` on `IImageProcessingContext` and the `CreateCanvas(...)`
+extension methods on `Image<TPixel>` and `ImageFrame<TPixel>`, which route into those same constructors.
 
 That explicit-backend path matters for the WebGPU helpers. `WebGPUWindow<TPixel>`, `WebGPURenderTarget<TPixel>`, and `WebGPUDeviceContext<TPixel>` create canvases that point directly at their owned `WebGPUDrawingBackend` instance instead of storing that backend on the caller's `Configuration`.
 

src/ImageSharp.Drawing/Processing/IDrawingCanvas.cs

@@ -49,7 +49,7 @@ public interface IDrawingCanvas : IDisposable
     /// Saves the current drawing state and begins an isolated compositing layer.
     /// Subsequent draw commands are recorded into an isolated logical layer. When
     /// <see cref="Restore"/> closes the layer, that layer becomes eligible for
-    /// composition during the next <see cref="Flush"/> or <see cref="System.IDisposable.Dispose"/>.
+    /// composition during the next <see cref="Flush"/> or <see cref="IDisposable.Dispose"/>.
     /// </summary>
     /// <returns>The save count after the layer state has been pushed.</returns>
     public int SaveLayer();
@@ -58,7 +58,7 @@ public interface IDrawingCanvas : IDisposable
     /// Saves the current drawing state and begins an isolated compositing layer.
     /// Subsequent draw commands are recorded into an isolated logical layer. When
     /// <see cref="Restore"/> closes the layer, that layer is composed during the next
-    /// <see cref="Flush"/> or <see cref="System.IDisposable.Dispose"/> using the specified
+    /// <see cref="Flush"/> or <see cref="IDisposable.Dispose"/> using the specified
     /// <paramref name="layerOptions"/> (blend mode, alpha composition, opacity).
     /// </summary>
     /// <param name="layerOptions">
@@ -71,7 +71,7 @@ public interface IDrawingCanvas : IDisposable
     /// Saves the current drawing state and begins an isolated compositing layer
     /// bounded to a subregion. Subsequent draw commands are recorded into that isolated
     /// logical layer. When <see cref="Restore"/> closes the layer, it is composed during
-    /// the next <see cref="Flush"/> or <see cref="System.IDisposable.Dispose"/> using the specified
+    /// the next <see cref="Flush"/> or <see cref="IDisposable.Dispose"/> using the specified
     /// <paramref name="layerOptions"/>.
     /// </summary>
     /// <param name="layerOptions">
@@ -89,7 +89,7 @@ public interface IDrawingCanvas : IDisposable
     /// <remarks>
     /// If the most recently saved state was created by a <c>SaveLayer</c> overload,
     /// the layer is closed in the deferred scene. Actual composition happens during the
-    /// next <see cref="Flush"/> or <see cref="System.IDisposable.Dispose"/>.
+    /// next <see cref="Flush"/> or <see cref="IDisposable.Dispose"/>.
     /// </remarks>
     public void Restore();
 
@@ -101,7 +101,7 @@ public interface IDrawingCanvas : IDisposable
     /// and the last discarded frame becomes the current state.
     /// If any discarded state was created by a <c>SaveLayer</c> overload,
     /// those layers are closed in the deferred scene and are composed during the next
-    /// <see cref="Flush"/> or <see cref="System.IDisposable.Dispose"/>.
+    /// <see cref="Flush"/> or <see cref="IDisposable.Dispose"/>.
     /// </remarks>
     /// <param name="saveCount">The save count to restore to.</param>
     public void RestoreTo(int saveCount);

src/ImageSharp.Drawing/Processing/PaintExtensions.cs

@@ -0,0 +1,45 @@
+// Copyright (c) Six Labors.
+// Licensed under the Six Labors Split License.
+
+namespace SixLabors.ImageSharp.Drawing.Processing;
+
+/// <summary>
+/// Represents the per-frame painting callback executed by <see cref="PaintExtensions.Paint(IImageProcessingContext, CanvasAction)"/>.
+/// </summary>
+/// <param name="canvas">The drawing canvas for the current image frame.</param>
+public delegate void CanvasAction(IDrawingCanvas canvas);
+
+/// <summary>
+/// Adds image-processing extensions that paint each frame through <see cref="IDrawingCanvas"/>.
+/// </summary>
+public static class PaintExtensions
+{
+    /// <summary>
+    /// Paints each image frame using drawing options from the current context.
+    /// </summary>
+    /// <param name="source">The image processing context to paint.</param>
+    /// <param name="action">The per-frame painting callback.</param>
+    /// <returns>The <see cref="IImageProcessingContext"/> so additional processing operations can be chained.</returns>
+    public static IImageProcessingContext Paint(
+        this IImageProcessingContext source,
+        CanvasAction action)
+        => source.Paint(source.GetDrawingOptions(), action);
+
+    /// <summary>
+    /// Paints each image frame using the supplied drawing options.
+    /// </summary>
+    /// <param name="source">The image processing context to paint.</param>
+    /// <param name="options">The drawing options applied when creating each frame canvas.</param>
+    /// <param name="action">The per-frame painting callback.</param>
+    /// <returns>The <see cref="IImageProcessingContext"/> so additional processing operations can be chained.</returns>
+    public static IImageProcessingContext Paint(
+        this IImageProcessingContext source,
+        DrawingOptions options,
+        CanvasAction action)
+    {
+        Guard.NotNull(options, nameof(options));
+        Guard.NotNull(action, nameof(action));
+
+        return source.ApplyProcessor(new PaintProcessor(options, action));
+    }
+}

…Processing/ProcessWithCanvasProcessor.cs …arp.Drawing/Processing/PaintProcessor.cssrc/ImageSharp.Drawing/Processing/ProcessWithCanvasProcessor.cs renamed to src/ImageSharp.Drawing/Processing/PaintProcessor.cs src/ImageSharp.Drawing/Processing/ProcessWithCanvasProcessor.cs renamed to src/ImageSharp.Drawing/Processing/PaintProcessor.cs

@@ -6,16 +6,17 @@
 namespace SixLabors.ImageSharp.Drawing.Processing;
 
 /// <summary>
-/// Defines a processor that executes a canvas callback for each image frame.
+/// Defines the image processor used by <see cref="PaintExtensions.Paint(IImageProcessingContext, DrawingOptions, CanvasAction)"/>
+/// to execute a canvas callback for each image frame.
 /// </summary>
-public sealed class ProcessWithCanvasProcessor : IImageProcessor
+public sealed class PaintProcessor : IImageProcessor
 {
     /// <summary>
-    /// Initializes a new instance of the <see cref="ProcessWithCanvasProcessor"/> class.
+    /// Initializes a new instance of the <see cref="PaintProcessor"/> class.
     /// </summary>
-    /// <param name="options">The drawing options.</param>
-    /// <param name="action">The per-frame canvas callback.</param>
-    public ProcessWithCanvasProcessor(DrawingOptions options, CanvasAction action)
+    /// <param name="options">The drawing options used when creating each frame canvas.</param>
+    /// <param name="action">The per-frame painting callback.</param>
+    public PaintProcessor(DrawingOptions options, CanvasAction action)
     {
         Guard.NotNull(options, nameof(options));
         Guard.NotNull(action, nameof(action));
@@ -25,10 +26,13 @@ public ProcessWithCanvasProcessor(DrawingOptions options, CanvasAction action)
     }
 
     /// <summary>
-    /// Gets the drawing options.
+    /// Gets the drawing options used when creating each frame canvas.
     /// </summary>
     public DrawingOptions Options { get; }
 
+    /// <summary>
+    /// Gets the per-frame painting callback.
+    /// </summary>
     internal CanvasAction Action { get; }
 
     /// <inheritdoc />
@@ -37,5 +41,5 @@ public IImageProcessor<TPixel> CreatePixelSpecificProcessor<TPixel>(
         Image<TPixel> source,
         Rectangle sourceRectangle)
         where TPixel : unmanaged, IPixel<TPixel>
-        => new ProcessWithCanvasProcessor<TPixel>(configuration, this, source, sourceRectangle);
+        => new PaintProcessor<TPixel>(configuration, this, source, sourceRectangle);
 }

…ng/ProcessWithCanvasProcessor{TPixel}.cs …ing/Processing/PaintProcessor{TPixel}.cssrc/ImageSharp.Drawing/Processing/ProcessWithCanvasProcessor{TPixel}.cs renamed to src/ImageSharp.Drawing/Processing/PaintProcessor{TPixel}.cs src/ImageSharp.Drawing/Processing/ProcessWithCanvasProcessor{TPixel}.cs renamed to src/ImageSharp.Drawing/Processing/PaintProcessor{TPixel}.cs

@@ -6,25 +6,26 @@
 namespace SixLabors.ImageSharp.Drawing.Processing;
 
 /// <summary>
-/// Executes a per-frame canvas callback for a specific pixel type.
+/// Executes the <see cref="PaintProcessor"/> callback for a specific pixel type by creating a
+/// <see cref="DrawingCanvas{TPixel}"/> over each frame.
 /// </summary>
 /// <typeparam name="TPixel">The pixel format.</typeparam>
-internal sealed class ProcessWithCanvasProcessor<TPixel> : ImageProcessor<TPixel>
+internal sealed class PaintProcessor<TPixel> : ImageProcessor<TPixel>
     where TPixel : unmanaged, IPixel<TPixel>
 {
-    private readonly ProcessWithCanvasProcessor definition;
+    private readonly PaintProcessor definition;
     private readonly CanvasAction action;
 
     /// <summary>
-    /// Initializes a new instance of the <see cref="ProcessWithCanvasProcessor{TPixel}"/> class.
+    /// Initializes a new instance of the <see cref="PaintProcessor{TPixel}"/> class.
     /// </summary>
     /// <param name="configuration">The processing configuration.</param>
-    /// <param name="definition">The processor definition.</param>
+    /// <param name="definition">The non-generic processor definition that owns the drawing options and callback.</param>
     /// <param name="source">The source image.</param>
-    /// <param name="sourceRectangle">The source bounds.</param>
-    public ProcessWithCanvasProcessor(
+    /// <param name="sourceRectangle">The source bounds passed through the processing pipeline.</param>
+    public PaintProcessor(
         Configuration configuration,
-        ProcessWithCanvasProcessor definition,
+        PaintProcessor definition,
         Image<TPixel> source,
         Rectangle sourceRectangle)
         : base(configuration, source, sourceRectangle)

src/ImageSharp.Drawing/Processing/ProcessWithCanvasExtensions.cs

@@ -38,7 +38,7 @@ public void DrawPathSystemDrawing()
     public void DrawLinesCore()
     {
         using Image<Rgba32> image = new(800, 800);
-        image.Mutate(x => x.ProcessWithCanvas(canvas => canvas.DrawBezier(
+        image.Mutate(x => x.Paint(canvas => canvas.DrawBezier(
             Processing.Pens.Solid(Color.HotPink, 10),
             new PointF(10, 500),
             new PointF(30, 10),

tests/ImageSharp.Drawing.Benchmarks/Drawing/DrawBeziers.cs

@@ -161,7 +161,7 @@ public void SystemDrawing()
 
     [Benchmark]
     public void ImageSharp()
-        => this.image.Mutate(c => c.ProcessWithCanvas(canvas => canvas.Draw(this.isPen, this.imageSharpPath)));
+        => this.image.Mutate(c => c.Paint(canvas => canvas.Draw(this.isPen, this.imageSharpPath)));
 
     [Benchmark]
     public void ImageSharpWebGPU()