PeachDrawing.Core

PeachDrawing.Core is the drawing-surface abstraction PeachPDF targets to write PDF: a Canvas to draw shapes, text and images on, a RenderContext to resolve colors, fonts and paint objects from, and the paint-ready value types (Brush, Pen, PaintColor, Rect, and the rest) that connect them. It has no third-party dependencies beyond its own sibling package PeachDrawing.Text (for font/typeface types), is trimmable and Native AOT compatible, and is versioned in lockstep with PeachPDF: the same version number for every release, and PeachPDF depends on it.

dotnet add package PeachDrawing.Core

Status: pre-1.0. The package’s public surface is the Canvas/RenderContext contract and the paint, geometry, path, effect, cursor and semantic types around it - see PublicApi.txt for the exact, machine-checked snapshot. Six concrete Canvas/RenderContext implementations exist today: PeachDrawing.PDF (PdfCanvas, writing PDF, which PeachPDF renders through), PeachDrawing (RasterCanvas, a standalone CPU software rasterizer, also PeachPDF’s raster fallback for effects PDF cannot express as vector content), PeachDrawing.Svg (SvgCanvas, writing vector SVG), PeachDrawing.Win2D (Win2dCanvas, Win2D on Windows), PeachDrawing.Skia (SkiaCanvas, SkiaSharp into a canvas you supply, on any platform) and PeachDrawing.CoreGraphics (CoreGraphicsCanvas, Quartz 2D into a CGContext you supply, on macOS and iOS). Until 1.0, the public API may change between releases.

What this package is for

A document- or drawing-producing library needs somewhere to draw: rectangles, paths, text, images, all composited with clips, transforms and blend modes. PeachDrawing.Core is that surface, deliberately kept independent of any one backend:

PeachPDF is one Canvas implementation among potentially several. Nothing in this package’s public surface names a PDF-specific or raster-specific type - see Implementing your own Canvas below for what that buys you.

RenderContext: colors, fonts and paint objects

A RenderContext is the object a render is built around: it caches resolved brushes, pens and fonts for the life of one render, and is where you register fonts before drawing with them.

using PeachDrawing.Core;

// A concrete RenderContext implementation - PeachDrawing.PDF's PdfRenderContext, or your own.
RenderContext context = ...;

context.AddFontFamily(myFontFamily);
context.AddFontFamilyMapping(fromFamily: "Arial", toFamily: "Liberation Sans");

Font? font = context.GetFont("Liberation Sans", size: 16, PaintFontStyle.Bold);
Brush brush = context.GetSolidBrush(PaintColor.FromArgb(255, 30, 144, 255));
Pen pen = context.GetPen(PaintColor.Black);

Canvas: the drawing surface

Canvas canvas = ...; // a concrete implementation

canvas.PushTransform(Matrix3x2.CreateRotation(float.Pi / 6));
canvas.PushClip(new Rect(0, 0, 200, 100));

canvas.DrawRectangle(brush, x: 10, y: 10, width: 180, height: 80);
canvas.DrawString("Hello, PeachDrawing", font, PaintColor.Black,
    new PaintPoint(20, 40), new Size(160, 20));

canvas.PopClip();
canvas.PopTransform();

Also on Canvas: DrawStringInRect(text, font, color, rect, horizontal, vertical) places a run inside a rectangle by BoxAlignment (Start, Center, End) on each axis, GetClip() returns the current clip rectangle, PushAntiAlias/PopAntiAlias switch anti-aliasing for a scope, and PaintRequiresTransparency(paint) asks whether drawing a callback would need transparency the format cannot express. DrawString takes an optional FontPalette (a base palette index plus color overrides) for COLR/CPAL color fonts and ShapeSettings for OpenType features.

PixelsPerPoint is the scale between this Canvas’s own coordinate space and true PDF points (1.0, the base default, for a Canvas with no such distinction); IsOffscreenTile says whether this Canvas is a tile from CreateTile rather than a page/document’s own surface.

Brush and Pen: what you draw with

Brush is an abstract base with a closed set of concrete, plain-data subtypes - not an opaque handle a Canvas implementation has to downcast to reach real data out of:

Brush solid = context.GetSolidBrush(PaintColor.FromArgb(255, 231, 76, 60));

Brush gradient = context.GetLinearGradientBrush(
    new PaintPoint(0, 0), new PaintPoint(200, 0),
    [(PaintColor.White, 0), (PaintColor.Black, 1)]);

if (gradient is LinearGradientBrush linear)
{
    // linear.Start, linear.End, linear.Stops (GradientStop: PaintColor + Position), linear.Spread
}

A Canvas implementation pattern-matches on the concrete Brush subtype to build whatever native paint representation it needs - the same discriminated-union dispatch this codebase’s own CssImage/ CssImagePainter.Paint already uses for background/gradient/list-marker images.

Pen is a concrete, mutable class - Width, MiterLimit, DashStyle, LineCap, LineJoin, DashPattern/DashOffset (or SetDashPattern(pattern, offset) to set both at once) and Paint (a Brush - a pen strokes with any brush, not just a solid color, for e.g. an SVG stroke="url(#gradient)").

GraphicsPath: recording and flattening vector geometry

using GraphicsPath path = canvas.GetGraphicsPath();
path.Start(0, 0);
path.LineTo(100, 0);
path.AddBezierTo(150, 0, 150, 100, 100, 100);
path.CloseFigure();

canvas.DrawPath(brush, path);

// Read the path's geometry back, independent of whatever native representation the concrete
// implementation also built - what a raster fallback, or your own Canvas, needs:
foreach (PathContour contour in path.Flatten(tolerance: 0.1))
{
    // contour.Points is a polyline within `tolerance` of the true curve; contour.Closed says
    // whether it was closed (CloseFigure) - an open subpath gets caps, a closed one a join.
}

GraphicsPath’s recorder methods (Start, LineTo, ArcTo - a CSS border-radius-style corner arc -, AddMove, AddBezierTo, AddArc - a general SVG-style endpoint-parameterized arc -, CloseFigure, Transform, AddPath) are virtual, not abstract: the base implementation also records a concrete, backend-agnostic segment list (every arc converted to an equivalent cubic Bézier at record time), so Flatten works for any subclass with no extra work - a subclass overriding a recorder method to also build its own native representation still calls base.MethodName(...) to keep the shared list in sync. FillMode (Nonzero/EvenOdd, PDF 32000-1 §8.5.3’s two fill rules) and ClipToRect/Dispose are the only genuinely abstract members.

Flatten gives you polylines; when the geometry has to stay curved, GetCurveContours() gives you the same subpaths as CurveContour values instead - a Start point, the PathCommand lines and cubic Béziers that follow it (an arc is already recorded as cubics, so there is no third kind), and whether the subpath was closed. It is a snapshot: editing the path afterwards does not change a list you already hold.

PeachDrawing.Core.Geometry.PolygonClipper.ClipToRect clips a closed polygon (convex, concave or self-intersecting) to an axis-aligned rectangle. Fewer than three points back means nothing with area is left inside.

Shapes, measuring and combining paths

The PeachDrawing.Core.Geometry namespace works on a GraphicsPath without drawing it.

using PeachDrawing.Core.Geometry;

using GraphicsPath badge = canvas.GetGraphicsPath();
badge.AddRoundedRectangle(new Rect(10, 10, 200, 80), radius: 12);   // per-corner elliptical radii also work
badge.AddStar(cx: 110, cy: 50, outerRadius: 30, innerRadius: 12, points: 5);

var measure = new PathMeasure(badge);
double length = measure.Length;               // along every subpath, not counting the jump between them
double area = measure.Area;                   // holes (subpaths wound the other way) subtract
Rect box = measure.Bounds;                    // tight: includes where a curve bulges past its end points
PathSample halfway = measure.PointAtLength(length / 2);   // X, Y and the direction of travel there

Layers and effects

canvas.BeginLayer(new LayerOptions(...)) starts an isolated group. Draw onto layer.Canvas in the same coordinates as canvas; disposing the layer composites everything drawn as one piece.

// CSS "opacity" semantics: overlapping shapes inside do not show through each other.
using (var layer = canvas.BeginLayer(new LayerOptions(Opacity: 0.5)))
{
    layer.Canvas.DrawRectangle(red, 10, 10, 100, 100);
    layer.Canvas.DrawRectangle(red, 60, 60, 100, 100);
}

// A soft shadow: the layer is drawn into a bitmap covering Bounds, blurred, then composited.
var effects = new LayerEffect[] { new BlurEffect(sigma: 4) };
var (mx, my) = RasterLayerEffects.GetInkMargin(effects);          // how far the blur spreads
var bounds = new Rect(x - mx, y - my, w + 2 * mx, h + 2 * my);
using (var shadow = canvas.BeginLayer(new LayerOptions(Bounds: bounds, Effects: effects)))
    shadow?.Canvas.DrawRectangle(grey, x, y, w, h);

LayerOptions carries the layer’s opacity, blend mode, an optional ColorMatrix and a Bounds region; Effects adds BlurEffect, DropShadowEffect and ColorMatrixEffect. BeginLayer returns null when the canvas cannot make a layer (a measure-only pass) or, for a layer with effects, cannot apply them - draw straight onto the canvas then. The default implementation builds a layer from CreateTile and the DrawImage… methods, so every Canvas gets one; a canvas that can apply effects overrides SupportsLayerEffects and ApplyLayerEffects (the PeachDrawing package’s RasterLayerEffects.Apply does the work on a RasterSurface). A canvas whose layers apply their effects itself, on the graphics hardware, says so with HasNativeLayerEffects (Win2dCanvas, SkiaCanvas and CoreGraphicsCanvas do), and a caller that can express a blurred shadow, a filter or a blurred backdrop either way draws it as a layer with effects when that is true instead of rendering it into a bitmap. BlurEffect.ClampEdges asks for the layer’s edge pixels to be held rather than faded, for content that continues past the layer’s bounds.

Retained layers

A layer from BeginLayer is composited once, when it is disposed. A RetainedLayer is for content that stays the same while the way it is placed changes, such as a box that an animation moves or fades: record it once, then draw it as often as you like.

using var layer = canvas.CreateRetainedLayer(new Rect(10, 10, 100, 60))!;   // the region it covers, in this canvas's coordinates
layer.Recorder.DrawRectangle(brush, 10, 10, 100, 60);                      // record in the same coordinates
layer.Seal();                                                              // finish recording

layer.Draw(canvas);                                                        // where it was recorded
canvas.PushTransform(Matrix3x2.CreateRotation(0.3f, new Vector2(60, 40)));
layer.Draw(canvas, opacity: 0.5);                                          // again, rotated, half transparent
canvas.PopTransform();

layer.Draw(canvas, opacity: 1.0, new LayerEffect[] { new BlurEffect(sigma: 6) });   // blurred, from the same recording

Draw places the layer under the target’s current transform and takes the opacity of that one draw; the content is not recorded again. CanDraw(target) says whether a canvas can still draw it (a lost graphics device or another document makes the answer no, and the layer is recorded anew). CreateRetainedLayer returns null for an empty region or a canvas that cannot make one. The default is built from CreateTile, so every Canvas gets one and a draw replays the tile; Win2dCanvas overrides it to keep a texture on the GPU, and so does SkiaCanvas (the group is drawn once into a bitmap and kept as an image, uploaded to the render context’s GpuContext when it has one), so a draw is one textured quad.

The third form of Draw takes layer effects (a blur, a drop shadow, a color matrix) that are applied to the layer as a whole each time it is drawn, before opacity. The content is still recorded once, so an animation of a blur radius or a shadow costs a composite per frame and not a repaint, and on a canvas that applies effects on the GPU (HasNativeLayerEffects) the effect runs there on the kept texture. The effect needs room to spread into, so the layer is composited from a region larger than Bounds by the effects’ ink margin (three standard deviations of each blur and shadow, plus a shadow’s offset). A canvas that cannot make an effect layer draws the layer without the effects. The default is built on BeginLayer, so it works on every canvas; a RetainedLayer subclass with a better way can override it.

A format with hyperlinks does not need a side channel for them: they are Canvas calls, so whatever draws a page can say what is clickable on it.

canvas.AddLink(new Rect(40, 170, 160, 20), "https://example.com/");     // a link to an address
canvas.AddDestination("terms", top: 120);                                // name a place on this page...
other.AddDestinationLink(new Rect(40, 200, 90, 14), "terms");           // ...and link to it, from this page or another

All of these do nothing by default, which is right for a canvas of pixels. PeachDrawing.PDF writes link annotations and named destinations, and PeachDrawing.Svg writes <a href> elements. A tile or a measuring canvas, which belongs to no page, writes nothing.

Tile and hatch brushes

A TileBrush repeats a picture across the plane, so a shape filled with it shows the part of the grid under it and neighboring shapes continue the same pattern.

var (tile, image) = canvas.CreateTile(20, 20)!.Value;
tile.DrawRectangle(dark, 0, 0, 10, 20);
tile.Dispose();

// 20 x 20 cells, the whole grid turned 30 degrees.
var brush = new TileBrush(image, 20, 20, Matrix3x2.CreateRotation(MathF.PI / 6));
canvas.DrawPath(brush, shape);

canvas.DrawRectangle(new HatchBrush(HatchStyle.DiagonalCross, PaintColor.Black, PaintColor.White, spacing: 8), 0, 0, 200, 100);

On a PDF canvas a tile made by CreateTile stays vector content and becomes a real PDF tiling pattern: written once, however many cells the shape covers. A tile of pixels is embedded once inside the pattern, and TileBrush.Sampling says whether a viewer may smooth it. Two things to know about PDF output. A viewer draws a rotated or skewed tiling pattern cell by cell with anti-aliased edges, which shows as hairline seams, so a grid that the brush transform or the canvas transform turns is instead painted as separate cells under a clip (unless that would be over ten thousand cells, when the pattern is used). And a viewer may round the size of a pattern cell to whole device pixels, so a pattern whose cells are not a whole number of pixels at the viewer’s zoom can drift slightly from its true period. The raster canvas reads the tile’s bitmap with wrap-around filtering, so cells join without a seam. HatchBrush draws one cell of lines through CreateTile; ToTileBrush gives that cell for a canvas that has no hatch of its own. A pen can stroke with either brush.

Anti-aliasing and image sampling

canvas.PushAntiAlias(false) / PopAntiAlias() turn edge smoothing off or on for the shapes drawn in between, and nest like the other state stacks. On a raster canvas this is exact; the render-wide setting (RasterAntiAliasing) is a ceiling, so a request for smoothing never overrides a render that turned it off. The default implementation can only honor true, through the older SetAntiAliasSmoothingMode pair it is built on.

canvas.DrawImage(image, destRect, ImageSampling.…) picks how the image’s pixels are read: Automatic (what the image’s own Interpolate asks for), Nearest, Bilinear, Bicubic (Catmull-Rom over sixteen pixels; the raster canvas has a real one, others treat it as Bilinear) or Pixelated (hard-edged when enlarging, filtered when shrinking). Without per-draw sampling of its own a canvas falls back to switching Interpolate for the duration of the draw.

Font, FontFamily and Image

Beyond GetFont, a RenderContext registers fonts from bytes (AddFontFromBytes), a URL (AddFontFamilyFromUrl) or an installed face (AddLocalFontFamily), maps one family name to another (AddFontFamilyMapping), asks whether a family exists (IsFontExists), drops cached fonts (ClearFontCache) and decodes an Image from a stream (ImageFromStream). TextHinting and TextStemDarkening tune glyph rendering for raster canvases, and RasterizationDpi/MaxRasterPixels bound the bitmaps a vector backend falls back to. IntRect is the integer pixel rectangle (Left, Top, Right, Bottom, Intersect) used for raster regions.

Font is a resolved, sized typeface, built from a PeachDrawing.Text.Typeface (Font.Typeface) plus whatever synthetic bold/italic a match required (Font.SyntheticStyle) - deliberately still a size-bound “font” object, unlike Typeface itself, because it’s the paint-ready object Canvas.DrawString actually needs. FontFamily is the family a font was matched from. Image (Width, Height, Interpolate, GetPixels()) is a drawable raster or vector image; GetPixels() returns a PixelBuffer (premultiplied RGBA8) for an image whose pixels a Canvas implementation needs to read directly, or null for one with none (a vector tile from CreateTile, say). An animated image (a GIF or WebP with more than one frame) reports FrameCount, GetFrameDuration(index) and LoopCount (0 is forever), and draws the frame CurrentFrame names, which whoever plays the animation sets (PeachBrackets.HtmlDocument.AdvanceAnimations does); every use of the image shows the same frame. A still image has one frame and ignores CurrentFrame. RasterRenderContext and Win2dRenderContext decode animated images this way; a backend that does not shows the first frame.

Implementing your own Canvas

Nothing in Canvas’s or RenderContext’s public surface names a PDF-specific or raster-specific type - that’s the actual point of publishing this package separately from PeachPDF. A Canvas implementation needs to:

  1. Derive from RenderContext, implementing its abstract members (GetCssMediaType, color resolution, image decoding, font creation) for whatever backend you’re targeting.
  2. Derive from Canvas, implementing its abstract drawing/clip/transform/blend-mode members against your backend’s own native drawing calls.
  3. Derive from GraphicsPath only if you need your own native path representation alongside the shared one Flatten already gives you for free - many backends can get away with the base implementation entirely.
  4. Derive from Image/FontFamily/Font as your backend’s font/image loading needs.

PeachDrawing.PDF’s PdfRenderContext/PdfCanvas (writing vector PDF content), PeachDrawing.Svg’s SvgRenderContext/SvgCanvas (writing vector SVG, and the smallest complete backend to read), PeachDrawing.Win2D’s Win2dRenderContext/Win2dCanvas (a hardware-accelerated Windows backend, with the resource-lifetime rules a native-handle backend needs), PeachDrawing.Skia’s SkiaRenderContext/SkiaCanvas (the cross-platform one, drawing into a host-supplied surface), PeachDrawing.CoreGraphics’s CoreGraphicsRenderContext/CoreGraphicsCanvas (the Apple one, drawing into a host-supplied CGContext), PeachPDF’s use of RasterCanvas (rasterizing effects PDF can’t express as vector content, such as filter: blur()), and PeachDrawing’s own standalone RasterCanvas/RasterRenderContext (see docs/peachdrawing.md) are all independent, complete implementations of exactly this - reading their source is the closest thing to a worked example. A few things worth knowing before you start:

Drawing shaped text, paragraphs and color glyphs on any Canvas

The package also holds the logic every Canvas shares for text that PeachDrawing.Text has already shaped, so an implementation gets it by implementing DrawGlyphs and the path/clip/brush members:

Licenses

PeachDrawing.Core is BSD 3-Clause. It carries no third-party code of its own; its one dependency, PeachDrawing.Text, carries its own notices in its THIRD-PARTY-LICENSES.md. See License for the whole list.