ClaFi Graphics

Introduction

Everything a window shows is drawn on its canvas: a Graphics::Canvas the form owns and hands to every paint through the event. A caller states shapes, paths and brushes in the surface's pixels, and the canvas passes each one to the backend behind it - the CPU rasterizer that comes with the core, or Direct2D on Windows. Which of the two draws is the user's choice, made in Settings while the application runs, so a control does not know which one it is drawn by and must not need to.

Both backends answer to one contract: the drawing API promises nothing one of them cannot draw. A translucent brush is a colour with alpha, on both, and nothing beside a brush carries an opacity of its own. What the two still draw differently is listed in Backend differences, each with what to keep to so that a picture comes out the same from either.

What a caller draws with:

• Shapes - rectangles, rounded rectangles with a radius per corner and a choice of sides, ellipses, circles and lines, each drawn as an outline or filled.
• Paths - a PixelPath of lines and curves, drawn as a stack of layers: fill, stroke, glow and shadow.
• Brushes - a solid colour, a linear or a radial gradient, or a point of light.
• State - clips, a transform, opacity layers and kept images, each a push and a pop, with a scoped guard for each.
• Pixels - a bitmap drawn as it is, or a buffer the caller writes into itself.

Quick Start

A paint handler takes the canvas from its event and draws in the rect the event hands it. An icon's PaintIconEvent answers the canvas, the icon's rect, the stroke weights and the inks; a control's PaintEvent answers the same.

void paintAddIcon(PaintIconEvent& event)
{
    Canvas& canvas = event.canvas();
    const FloatRect& box = event.iconRect();
    const float size = std::min(box.width(), box.height());
    const float stroke = event.scaledStrokeWidth(Thickness::Regular);

    // The frame. Its stroke lies inside the rect it is given.
    const float radius = size * 0.2f;
    canvas.drawRoundedRectangle(box, radius, radius, event.textRgb(InkGrade::Muted), stroke);

    // The plus, as a path in the icon's own coordinates placed by a translation.
    PixelPath path;
    path.moveTo(size * 0.5f, size * 0.28f);
    path.lineTo(size * 0.5f, size * 0.72f);
    path.moveTo(size * 0.28f, size * 0.5f);
    path.lineTo(size * 0.72f, size * 0.5f);
    const Matrix3x2 place = Matrix3x2::translation(box.topLeft());
    const Color mark = event.accentRgb(InkGrade::Strongest);
    canvas.drawPath(path, { PathDrawLayer::stroke(mark, stroke) }, &place);
}

Colours come from the event rather than from the code: an ink is resolved against the surface it is drawn on, which is the Colour manual's subject. Everything below is what happens to a colour once it is in hand.

Core Concepts

The canvas and its backend

A canvas is a thin layer over an IBackend it owns. It keeps the clip rectangles and the transform it was told, builds out of paths the few shapes a backend may decline - a partial rounded rectangle, a shadow - and forwards everything else. The backend is what turns a call into pixels, and it is the only part that differs between the CPU and the GPU.

A form's canvas is built by the application and drawn in the form's paint passes, so a paint handler never begins or ends a frame. A canvas of one's own - a picture baked once and cut up, say - is built over a CPU backend, which A canvas of your own shows.

Coordinates

The canvas addresses the surface in its device pixels, from the top left corner, y growing downwards. The rects a paint event hands out are in those pixels already. A size written at design - a radius, a gap, a reach - becomes one through scaleF, and a line's weight through scaledStrokeWidth:

const float radius = event.scaleF(6.0f);                         // a design size in device pixels
const float line = event.scaledStrokeWidth(Thickness::Thin);    // whole pixels, at least one

The weights run Hairline, Thin, Regular, Bold and Heavy. scaledStrokeWidth answers whole pixels, at least one, and from Thin up each grade is a pixel wider than the one below - so a line keeps its weight against its neighbours at every scale the application is drawn at.

Strokes lie inside

Every outline lays its stroke inside the bounds it is given. A rectangle, a rounded rectangle, an ellipse and a partial rounded rectangle drawn over the same bounds as their fill meet it exactly: the outer edge of the stroke is the edge of the shape, and no fill shows past the border.

canvas.fillRoundedRectangle(card, radius, radius, surface);
canvas.drawRoundedRectangle(card, radius, radius, border, line);   // the same rect, not an inset one

A line and a path have no inside. Their stroke straddles the line or the path it follows, half on each side.

Brushes

A Brush is what a shape is filled or stroked with, one of four kinds. Every call that takes a brush also takes a Color, which is a solid brush.

A brush is stated in the coordinates of the shape it fills. For a shape that is the canvas's coordinates; for a path drawn under a transform it is the path's own, so a gradient across a path moves, scales and turns with it.

Stop positions run from 0 to 1 and ascend. A gradient of two colours has a shorthand:

canvas.fillRectangle(band, LinearGradient::simple(band.topLeft(), band.bottomLeft(), top, bottom));
canvas.fillTopBottomGradientRectangle(band, top, bottom);   // the same thing

A radial gradient's origin lies inside its ellipse, and both radii are above zero. An origin on the ellipse or past it, or a radius of zero, is undefined behaviour.

A point of light lights whatever it is painted on. Its spread is the vertical radius, and xRatio divides it for the horizontal one, so 0.5 is a light twice as wide as it is tall. How strong the light is, is its colour's alpha:

canvas.fillRectangle(bounds, PointGlow{
    .lightPos = bounds.center(),
    .lightColor = lamp.withOpacity(0.4f),
    .lightSpread = event.scaleF(60.0f),
    .xRatio = 0.5f
});

Paths and layers

A PixelPath is a list of commands - move, line, quadratic and cubic curve, elliptical arc, close - each absolute or relative, as SVG's path data has them. A moveTo starts a new figure, and close joins a figure's end back to its start; a segment drawn on after a close, with no move between, starts a new figure at that same start. A path starts with a move: anything drawn before its first moveTo is undefined behaviour. An arc is stated as SVG states one: the ellipse's radii and its rotation in degrees, ArcSize::Small or Large for which of the two arcs joining its ends it takes, and ArcSweep::Clockwise or CounterClockwise for the way it turns on the screen. Radii too small to reach its end grow together until they do, a radius of zero makes it a line, and an arc ending where it starts draws nothing. Three helpers build a whole figure and start a fresh path to do it: drawCircle(center, radius), drawEllipse(center, radiusX, radiusY), and drawRoundedRect(width, height, radius), which is centred on the origin, or drawRoundedRect(rect, radiusX, radiusY), which is SVG's rect, each radius cut to half its own side. addRoundedPolygon appends a polygon with its corners rounded, keeping what the path already holds.

A curve is drawn to within half a pixel of itself. A path keeps its curves as curves, and each backend turns them into what it rasterizes: Direct2D tessellates them itself, and the CPU backend cuts each one into straight segments, halving it until every piece lies within half a device pixel of its chord. An arc goes to Direct2D as an arc; the CPU backend first makes it cubics of at most a quarter turn each, none further from the ellipse than 0.03 percent of its radius. The half pixel is measured on the screen, the path's transform and the canvas's included, so a curve drawn larger is cut into more segments and none comes out coarser. No call takes a precision.

A path is drawn as a stack of layers, each a PathDrawLayer: a mode, the geometry options the mode reads, and a brush. The layers are drawn in the order given, so a later one covers an earlier one.

A glow's ramp thins by its GlowFalloff. Linear runs straight to nothing, which is what light wants: a lamp does not thin out, it runs out. Smooth is steep at the shape and level by the time it ends, which is what a shadow wants - a far end faint enough not to read as a border drawn round the shape.

// A badge: its glow first, so the fill covers the ramp's inward half, then the fill and its rim.
canvas.drawPath(badge, {
    PathDrawLayer::outerGlow(halo, event.scaleF(6.0f)),
    PathDrawLayer::fill(body),
    PathDrawLayer::stroke(rim, line)
}, &place);

The one-brush calls are a single layer: fillPath(path, brush) is a fill, and drawPath(path, brush, strokeWidth) a stroke with round ends. The transform a path is given places the geometry and the brush together, and scales its stroke widths and reaches with them.

Clips

A clip is a push and a pop. pushClip(rect) keeps what follows inside a rectangle; pushClip(path, transform) inside the area a path fills, antialiased at its edge. Clips nest, and each one pushed inside another is cut down to it.

canvas.pushClip(viewport);
paintRows(canvas);
canvas.popClip();

clipBox() answers the rectangle the canvas has recorded for the clip in force - a path clip's bounding box, cut by the clips around it - which is what a painter asks to skip what cannot show. A frame's own dirty rectangle is the first clip of every frame, and the clips a frame leaves pushed are popped when it ends.

Transforms

The canvas carries one Matrix3x2, applied to everything drawn. A caller composes onto it rather than replacing it, through ScopedCanvasTransform, which puts the previous one back when it goes:

// Grows what follows about a point. The matrix to the right applies first.
const Matrix3x2 grow = Matrix3x2::translation(origin)
    * Matrix3x2::scale(1.1f)
    * Matrix3x2::translation(-origin.x, -origin.y);
const ScopedCanvasTransform scaled{ canvas, grow };

The framework uses the same guard to scale a pressed control about its press origin, so a paint handler is already drawing under a transform at times, and draws the same way whether it is or not. The local matrix is applied first and the one in force after it, so a scaled control inside another lands where both put it.

A uniform scale and a translation draw the same on both backends. A rotation, a shear or a scale that differs between the axes is drawn exactly only by a path: the CPU backend maps a rectangle's top-left and bottom-right corners and draws the upright box between them, and measures radii and widths on the larger axis. Backend differences lists each case.

Opacity layers

Everything drawn between pushOpacity and its pop reaches the surface as one image, at the layer's opacity. Two shapes overlapping inside a layer do not show each other through where they cross, and a shape drawn over another covers it as completely as it would at full strength. That is the reason a layer exists rather than an alpha folded into each brush: a group faded through its brushes shows its own background through its own text.

// One layer for the whole mark: its parts overlap, and faded one by one they would show.
const ScopedCanvasOpacity layer{ canvas, 1.0f - event.disabledAmount() };
paintLeaves(canvas, transform);
paintBlot(canvas, transform);

ScopedCanvasOpacity opens nothing at full opacity, so a caller with a factor that may reach 1 states it there rather than branching round the passage it guards. One shape fading on its own needs no layer: its colour's alpha is the same thing, at no cost.

Shadows

castShadow draws the shadow a rounded rectangle casts on what is already drawn, and not the rectangle. Whatever casts a shadow covers it, so a caller casts the shadow first and draws the shape over it:

const RoundedRectangleParts card{ .bounds = bounds, .radii = uniformCorners(radius) };
const ShadowParams shadow{
    .color = event.inkRgb(InkWell::Black).withOpacity(0.3f),
    .blur = event.scaleF(12.0f),
    .offset = { 0.0f, event.scaleF(2.0f) }
};
canvas.castShadow(card, shadow);
canvas.fillPartialRoundedRectangle(card, event.surfaceRgb());

The colour is the shadow where it is darkest, against the shape's edge, so its alpha is the whole of how heavy the shadow reads. blur is how far the ramp reaches past the shape, offset which way the light falls, and spread how much the shape is grown before its shadow is taken - which moves the whole ramp out rather than stretching it, so a shadow can sit wider without growing softer. A round corner grows with the spread; a square one stays square.

Kept images

A kept image is a picture the size of the surface that outlives the frame it was drawn in, named by an index. Everything drawn between pushImage(index) and its pop goes into it rather than onto the surface, and drawImage(index, opacity) puts it back at an opacity. A caller holding two can build the next picture of a crossfade out of the last one and trade them over.

if (!canvas.hasImage(0))
{
    const ScopedCanvasImage into{ canvas, 0 };
    paintScene(canvas);
}
canvas.drawImage(0, fade);

An image is drawn into under the canvas's transform and put back on the surface's own pixels, whatever transform is in force when it is. A new image is transparent, and a push does not clear it: what a caller leaves uncovered keeps what was there before.

Pixels

A Bitmap is a block of pixels the caller owns, and drawBitmap(bitmap, position) draws it as it is. decodePng reads one out of a PNG file's bytes, from ClaFi.Core.Graphics.Png, and decodeDib and decodeBmpFile out of a bitmap's, from ClaFi.Core.Graphics.Dib. A PixelView is a window onto such a block - its bounds, its clip and its scan lines - and drawPixelView draws one.

stagingDraw goes the other way: it hands the caller a view to write pixels into itself, and draws what was written when the callback returns. Whatever the caller writes there is outside the canvas transform by construction, so the transform is handed in beside the view, in the coordinates the caller already works in:

canvas.stagingDraw(rect, [&](PixelView view, const Matrix3x2& canvasTransform) {
    const Matrix3x2 place = canvasTransform * Matrix3x2::translation(rect.topLeft());
    rasterize(view, place);
});

Pixels are where the backends differ most - what a view holds before the caller writes, whether a bitmap follows the transform, and how either meets what is already drawn. Backend differences has each of them, and the rule that keeps both the same: write opaque pixels, read none back, and draw a bitmap under no transform and no path clip.

Reference

Canvas

Every call that takes a Brush also takes a Color. A stroke width left out is one pixel.

Brush

using Brush = std::variant<SolidColor, LinearGradient, RadialGradient, PointGlow>;

struct SolidColor { Color color; };
struct GradientStop { float position; Color color; };

struct LinearGradient
{
    FloatPoint startPoint;
    FloatPoint endPoint;
    std::vector<GradientStop> stops;
    static LinearGradient simple(FloatPoint start, FloatPoint end, Color startColor, Color endColor);
};

struct RadialGradient
{
    FloatPoint center;
    FloatPoint offset;     // where the stops start from, relative to the centre
    float radiusX;
    float radiusY;
    std::vector<GradientStop> stops;
};

struct PointGlow
{
    FloatPoint lightPos;
    Color lightColor;              // its alpha is the light's strength
    float lightSpread;             // the vertical radius
    float xRatio{ 1.0f };           // the horizontal radius is lightSpread / xRatio
    GlowShape shape{ GlowShape::Circle };
};

PathDrawLayer

struct PathGeometryOptions
{
    PathRenderMode mode = PathRenderMode::Fill;
    float strokeWidth = 1.0f;                       // a stroke's width, a glow's reach
    StrokeCap strokeCap = StrokeCap::Round;           // Round, Butt or Square
    GlowFalloff falloff = GlowFalloff::Linear;      // read by OuterGlow and Shadow
};

struct PathDrawLayer { PathGeometryOptions geometry; Brush brush; };

PixelPath

Matrix3x2

An affine transform, binary compatible with Direct2D's D2D1_MATRIX_3X2_F. In a * b, b applies first - the opposite order to Direct2D's own operator*, which matters only to code that mixes the two.

Matrix3x2::identity();
Matrix3x2::translation(dx, dy);    Matrix3x2::translation(point);
Matrix3x2::scale(s);               Matrix3x2::scale(sx, sy);
Matrix3x2::rotation(radians);     Matrix3x2::rotationDeg(degrees);

FloatPoint p = m.transform(point);         // a point
FloatPoint v = m.transformVector(vector);  // a direction, translation left out
FloatRect r = m.mapRect(rect);             // the upright box between the two mapped corners
float k = m.getScaleFactor();             // the larger of the two axes' scales

RoundedRectangleParts

struct RoundedRectangleParts
{
    FloatRect bounds;
    CornerRadii radii{ k_squareCorners };         // top left, top right, bottom right, bottom left
    RectSidesBoolArray sides{ k_allRectSidesTrue }; // top, right, bottom, left
};

A corner is round while its radius is above zero, and no corner reaches past the middle of the shorter side. uniformCorners(r) gives every corner the same radius.

sides says which edges an outline draws; a fill covers the whole shape whatever it holds. A corner arc is drawn while either side it joins is. An open end runs to the edge of the bounds rather than stopping at the outline, so two shapes sharing an edge - the cells of a grid - join into one unbroken line.

ShadowParams

struct ShadowParams
{
    Color color{};                                // the darkest point; its alpha is the shadow's weight
    float blur{ 0.0f };                             // how far the ramp reaches past the shape
    FloatPoint offset{};                          // which way the light falls
    float spread{ 0.0f };                           // how much the shape grows first
    GlowFalloff falloff{ GlowFalloff::Smooth };
};

A shadow with no blur, no alpha or empty bounds draws nothing.

Scoped guards

A canvas of your own

A picture drawn once and used many times - the window's shadow is baked this way and cut into tiles - is drawn on a canvas over a CPU backend, which needs nothing but a size. The frame is begun and ended as a form's is, and the end hands back the pixels:

auto backend = std::make_unique<Graphics::Cpu::CpuBackend>(size);
backend->setTransparentBase(true);   // start from nothing, not from what the buffer held
Graphics::Canvas canvas{ std::move(backend) };

const IntRect whole = { 0, 0, size.x, size.y };
canvas.beginPaint(nullptr, whole);
canvas.castShadow(silhouette, shadow);
Graphics::Bitmap* painted = nullptr;
canvas.endPaint(nullptr, whole, painted);   // the backend's own buffer, alive as long as the canvas

Draw between the two calls. A CPU canvas draws outside a frame as well, but nothing promises that of a backend, and Direct2D draws nothing there.

The Backends

Which backend draws

The CPU backend is always there. It is the core's own, it is the only one on Wayland, and it draws everything made off-screen whatever the platform. A GPU backend is the application's to name, in its type:

// Win32: Direct2D beside the CPU backend.
using Win32Application = Application<Win32Platform, Direct2DBackend>;

// Wayland: no GPU backend.
using WaylandApplication = Application<WaylandPlatform>;

An application that names one shows GPU acceleration on its Settings page, kept in its config and on by default. One that names none shows no such setting and keeps no answer about it. A change of the setting reaches every window at the top of its next frame, so a switch asked for from inside a click cannot land between the passes of a frame being painted.

canvas.backend()->type() answers BackendType::Cpu or BackendType::Direct2D. Asking is for platform code - the text engine asks, to reach DirectWrite's own glyph drawing. A control that draws one way on one backend and another way on the other is a gap in the contract, and belongs in the table below.

Backend differences

These are the calls the two backends draw differently. Each row is a gap in the contract rather than a feature of either backend, and the last column is what to keep to so that a picture comes out the same from both.

Do and Don't

How It Works

The canvas

The canvas forwards nearly every call as it is. What it keeps is what the backend interface does not report: the clip rectangles, for clipBox, and the transform, so a guard can compose onto it and put it back.

Three calls a backend may decline - fillPartialRoundedRectangle, drawPartialRoundedRectangle and castShadow - by answering false, and the canvas then builds the shape out of a path and draws that. The CPU backend answers the two partial rectangles with painters of its own and declines the shadow, since its glow is already a distance field; Direct2D declines the partial rectangles and answers the shadow. A backend with no view of its own surface to hand a staging callback - Direct2D - is given a cleared buffer by the canvas instead.

The CPU backend

The CPU backend rasterizes into a pixel buffer with no transform stage, so the canvas transform is folded into the geometry where each call arrives: a rect's corners are mapped, and radii and widths are scaled by the transform's scale factor. Rectangles, rounded rectangles and circles each have a painter of their own, written for axis-aligned spans; everything else is a path.

A path is baked into segments first. An arc is turned from SVG's endpoint form into its centre, radii and angles, and cut into cubics of at most a quarter turn. A curve is halved until each piece lies within a tolerance of its chord, and the tolerance is divided by the scale the path is drawn at, the larger axis's under a transform that scales the two apart, so it holds on the screen. A piece halved thirteen times is taken as its chord, flat or not. The tolerance is a CurveQuality, and everything the canvas draws, a path clip included, is baked at Medium: half a device pixel. Low, High and VeryHigh - two pixels, a tenth and a hundredth - are for code that bakes a BakedPixelPath of its own, which nothing in the framework does. Each pixel's coverage comes from its distance to the nearest segment, and inside or outside from the segments its row crosses, which is the even-odd rule. A stroke is the band within half its width of a segment, so its corners come out round; a glow is the same distance taken as a ramp. The coverage is held as a mask, and the brush is composited through it.

A gradient is read from a ramp of 257 colours, built from its stops once per draw. A linear gradient places a pixel on the ramp by how far along its axis the pixel stands. A radial gradient takes the pixel back through the transform into the brush, and solves for the stop position at which the ellipse, shrunk toward the origin, passes through it.

A path clip is such a mask the size of its bounds, and a clip inside another is the two masks multiplied. An opacity layer is a buffer the size of the surface, kept for reuse, that starts as a copy of what is under it - every painter mixes toward its colour by coverage, which is the arithmetic of drawing on something opaque - and is mixed back when the layer closes. A frame that carries alpha clears its dirty rectangle first; any other frame keeps what the last one left, which costs nothing while the children cover every pixel.

Text reaches the backend as glyph coverage, cached once per glyph at a whole pixel origin and composited for a whole run through one mask, the fraction of each pen position resolved by sampling. On Windows the coverage is DirectWrite's, averaged to one value a pixel.

The Direct2D backend

Direct2D carries the canvas transform on its render target, so every primitive and every brush is mapped by the device. An outline is moved in by half its stroke, Direct2D stroking centred on a shape. Strokes take the cap a layer asks for and miter their corners. A path's arc goes into the geometry as an arc, its radii grown first by the same conversion the CPU backend makes, so the two agree on the ellipse wherever the radii given are too small.

Direct2D has no distance field, so a glow is laid down as rings: one stroke of the outline per pixel of reach, the widest first, each given what it has to add to what is already down to leave the falloff standing. A Shadow layer is the rings under a layer that masks out the silhouette, and then the silhouette filled, both aliased so that the two meet on the same pixels.

castShadow skips the rings. A rounded rectangle's distance field is made of pieces a gradient states exactly: beside a straight edge a linear gradient out from it, round a corner a radial one from the arc's centre, and between them the silhouette solid. Each piece is an axis-aligned rectangle drawn aliased, so no pixel is painted twice, and the ramp is stated in sixteen steps of the falloff.

Staged pixels are uploaded into one bitmap the size of the surface and drawn back texel for texel, untransformed - they were rasterized at the animated size already. Native brushes are cached for a frame and let go at its end. A lost device is reported by the frame's end; the backend drops what the device owned, builds again on the next frame and asks for a whole repaint.

A switch of backend

The setting is a config node, and its change is what reaches the application's context. The context states the answer once and tells every window. Each form takes it at the top of its next frame: it builds a backend through the factory the application named and hands it to its canvas. Everything the old backend held goes with it - its brushes, its geometries, its kept images - which is what a resize already drops, so nothing above the canvas is told. The whole surface is drawn again, and a window opened after the switch is built on what the application wears at that moment.