Standard library

Graphics

Draw shapes, antialiased and stroked paths, gradients, bitmap and TrueType text and images into pixel buffers on any target, present them on display panels or through the Display protocol, and test rendering with golden images.

On this page

std/graphics draws into pixel storage you own: a fixed array, an allocation, or a display’s frame buffer. Everything is computed on the CPU with integer arithmetic, so the same program produces byte-identical pixels on a laptop, in WebAssembly and on a Raspberry Pi Pico without an FPU. Nothing is allocated and no operating system is needed.

The family has five imports, and three more drive display panels on microcontrollers:

Import Contents
std/graphics Canvas, colors, rectangles, drawing, antialiased paths, strokes and shapes, gradients, text rendering, the Display protocol, band rendering.
std/graphics/font Built-in 6x8 and 8x16 bitmap fonts for ASCII and Latin-1.
std/graphics/truetype TrueType (.ttf, .ttc) fonts drawn antialiased at any size.
std/graphics/image PPM, QOI, BMP and PNG decoding onto canvases and encoding from them; the full codecs are in std/image.
std/graphics/fake An in-memory Display for tests.
std/embedded/display The SPI and I2C links that panel drivers talk over.
std/embedded/display/st7789 ST7789 colour TFT and IPS panels, RGB565 over SPI.
std/embedded/display/ssd1306 SSD1306 monochrome OLED panels, over I2C or SPI.

To show a canvas on a desktop, open a window with std/window, which implements the Display protocol below like the panel drivers do.

Quickstart

Save this as picture.dodo:

package picture

import "std/fs"
import "std/graphics"
import "std/graphics/font"
import "std/graphics/image"
import "std/platform"

fn main() -> i32 {
    pixels := [0u8; 160 * 90 * 4]
    canvas := match graphics.canvas(&mut pixels, 160, 90, graphics.PixelFormat.Rgba8888) {
        ok(value) => value,
        err(_) => {
            return 1
        },
    }
    canvas.clear(graphics.hex(0x1d2330))
    canvas.fill_circle(40, 45, 30, graphics.hex(0xe5c07b))
    canvas.fill_round_rect(80, 20, 64, 50, 8, graphics.hex(0x61afef))
    label := font.medium()
    canvas.text(&label, 96, 37, "Dodo", graphics.WHITE)

    encoded := [0u8; 160 * 90 * 3 + 32]
    length := match image.encode_ppm(&canvas, &mut encoded) {
        ok(count) => count,
        err(_) => {
            return 2
        },
    }
    workspace := platform.workspace()
    match fs.write_file("picture.ppm", &encoded[..length], &mut workspace) {
        ok() => {
            return 0
        },
        err(_) => {
            return 3
        },
    }
}
dodo run picture.dodo

The program prints nothing, exits 0, and writes picture.ppm: a 160x90 image with a yellow disk and a blue rounded box labelled “Dodo”. Most image viewers open PPM files, including macOS Preview and GIMP. Delete the file when done.

pixels is the canvas’s storage; the canvas borrows it and never copies or grows it. graphics.canvas fails only when the storage is too small for the size and format, or a dimension exceeds graphics.MAX_DIMENSION. Drawing calls never fail: shapes are simply cut off at the canvas edge. Exit 2 means the encode buffer was too small (image.ppm_size gives the exact size), and exit 3 that the file could not be written.

Draw on any display

Code that draws and presents through the graphics.Display protocol works with anything implementing it. Under dodo test, use std/graphics/fake:

package dashboard

import "std/graphics"
import "std/graphics/fake"
import "std/graphics/font"

// Written once against graphics.Display, not against one screen.
fn draw_status<D: graphics.Display>(display: &mut D, canvas: &mut graphics.Canvas, label: &graphics.Font, celsius: i32) -> void!graphics.Error {
    canvas.clear(graphics.BLACK)
    light := if celsius > 30 { graphics.RED } else { graphics.GREEN }
    canvas.fill_rect(0, 0, 8, 8, light)
    canvas.text(label, 12, 0, "TEMP", graphics.WHITE)
    return graphics.present(display, canvas)
}

@test
fn hot_readings_turn_the_light_red() {
    screen := [0u8; 64 * 8 * 2]
    display := fake.Display.new(&mut screen, 64, 8, graphics.PixelFormat.Rgb565)!
    pixels := [0u8; 64 * 8 * 2]
    canvas := graphics.canvas(&mut pixels, 64, 8, graphics.PixelFormat.Rgb565)!
    label := font.small()

    draw_status(&mut display, &mut canvas, &label, 35)!
    assert_eq(display.presents(), 1u32)
    match display.screen().color_at(0, 0) {
        some(color) => assert_eq(color, graphics.RED),
        none => assert(false),
    }
}

Run it with dodo test dashboard.dodo. A display reports its size() and preferred format() and shows a canvas with present(&canvas, dirty). graphics.present(display, canvas) sends only the canvas’s dirty rectangle and resets it; if presenting fails, the rectangle is marked dirty again so the next call retries. graphics.present_all sends the whole canvas.

A canvas covers canvas.bounds() of the display: all of it when the canvas has the display’s size, or a part of it when it is smaller or has an origin. Displays show only what lies inside both the canvas and the display and ignore the rest, the way drawing ignores pixels outside a canvas. Every display converts other pixel formats, so drawing code works with any canvas.

Display panels

The drivers under std/embedded/display implement graphics.Display for the small panels found on microcontroller boards. A function such as draw_status above therefore runs unchanged on a panel, and its tests keep running against fake.Display.

Driver Panels Format Connected over
st7789.Display 1.14” to 2.4” colour TFT and IPS modules: 240x240, 240x320, 135x240, 240x280, 172x320, 170x320 Rgb565 SPI
ssd1306.Display 0.42” to 1.3” monochrome OLED modules: 128x64, 128x32, 96x16, 64x48, 72x40 Mono1 I2C or SPI

A driver talks to its controller through a display.Interface, which sends command bytes and data bytes. There are two, and a test can pass its own:

Interface Wiring
display.SpiInterface.new(bus, data_command, select) An SPI bus, the panel’s D/C pin (low for commands, high for data), and its chip-select pin, or none when that is wired low.
display.I2cInterface.new(bus, address) An I2C bus and the controller’s 7-bit address, such as ssd1306.ADDRESS (0x3C).

An ST7789 panel on a Raspberry Pi Pico:

bus := b.pins.spi(board.SPI_CLOCK_PIN, board.SPI_TX_PIN, none, hal.SpiMode.Mode3, 62_500_000)!
data_command := b.pins.output(16)!
select := b.pins.output(board.SPI_SELECT_PIN)!
reset := b.pins.output(20)!
display.reset(&mut reset, &mut b.timer)
wiring := display.SpiInterface.new(bus, data_command, some(select))
lcd := st7789.Display.new(wiring, st7789.panel_240x240(), st7789.Rotation.Deg0, &mut b.timer)!

pixels := [0u8; 240 * 240 * 2]
canvas := graphics.canvas(&mut pixels, 240, 240, graphics.PixelFormat.Rgb565)!
canvas.clear(graphics.BLACK)
graphics.present(&mut lcd, &mut canvas)!

st7789.Display.new resets the controller by command, selects 16-bit colour, applies the panel’s colour inversion and subpixel order, and turns the display on, which takes about 300 ms. The panel’s memory keeps whatever it held before, so present a whole frame (or lcd.fill(color)) first. display.reset pulses a reset pin wired to a GPIO; a panel whose reset pin is tied to the board’s reset needs no call. An Rgb565 canvas is sent straight from its storage; other formats are converted on the way.

Rotation.Deg90 and Deg270 turn the picture a quarter turn and swap the display’s width and height: lcd.size() reports the result, which the canvas should match. The controller has memory for 240x320 pixels; a smaller panel shows part of it, and its st7789.Panel holds where. For a module not in the list, fill in a Panel from its datasheet or a working driver: size, column and row offset, colour inversion (on for most IPS panels), and BGR order.

An SSD1306 module on the board’s I2C pins:

bus := b.pins.i2c(board.I2C_SDA_PIN, board.I2C_SCL_PIN, hal.I2C_FAST_HZ)!
oled := ssd1306.Display.new(display.I2cInterface.new(bus, ssd1306.ADDRESS), ssd1306.panel_128x64())!
pixels := [0u8; 128 * 64 / 8]
canvas := graphics.canvas(&mut pixels, 128, 64, graphics.PixelFormat.Mono1)!

ssd1306.Display.new sets the controller up for the panel, clears it, and turns it on. The controller stores eight rows per byte, so the driver keeps a copy of the panel memory (1 KiB): a present changes only the pixels inside its rectangle and sends only the bytes it touched. Colour canvases light the pixels whose luma is 128 or more, as a Mono1 canvas stores them. examples/oled_demo.dodo is a complete program for a 0.96” module: it finds the display on any free I2C pin pair and shows an animation, the uptime and the chip’s temperature.

Method ST7789 SSD1306
size(), format(), present(&canvas, dirty) yes yes
set_inverted(on), set_display_on(on) yes yes
fill(color) yes
sleep(&mut delay), wake(&mut delay) yes
set_contrast(level), set_flipped(on), is_lit(x, y) yes
wiring(), release() the interface the interface

Driver methods report bus failures as hal.Error; present, which the Display protocol defines, reports them as graphics.Error.Device. examples/thermometer_board.dodo is a complete program: the chip’s temperature on an ST7789 panel, with the screen in examples/thermometer.dodo tested against fake.Display. Build it for a board with dodo run examples/thermometer_board.dodo --board pico.

Bands and origins

A full frame does not always fit in memory: 320x240 at Rgb565 is 153,600 bytes, more than half an RP2040’s RAM. canvas.set_origin(x, y) places a canvas at a point of a larger screen. Drawing calls keep using screen coordinates, and the canvas stores only the pixels under it, so the same drawing function renders the whole screen or any part of it.

graphics.Bands moves a canvas down the screen one band at a time:

package banded

import "std/graphics"
import "std/graphics/fake"

fn draw_screen(canvas: &mut graphics.Canvas) {
    canvas.clear(graphics.BLACK)
    canvas.fill_circle(60, 60, 50, graphics.YELLOW)
}

@test
fn bands_draw_the_whole_screen() {
    screen_storage := [0u8; 120 * 120 * 2]
    screen := fake.Display.new(&mut screen_storage, 120, 120, graphics.PixelFormat.Rgb565)!
    pixels := [0u8; 120 * 40 * 2]
    band := graphics.canvas(&mut pixels, 120, 40, graphics.PixelFormat.Rgb565)!
    bands := graphics.Bands.new(120)
    for bands.next(&mut band) {
        draw_screen(&mut band)
        graphics.present_all(&mut screen, &mut band)!
    }
    assert_eq(screen.presents(), 3u32)
    match screen.screen().color_at(60, 60) {
        some(color) => assert_eq(color, graphics.YELLOW),
        none => assert(false),
    }
}

bands.next(&mut canvas) sets the canvas’s origin to the next band and returns true, or returns false after the last band and starts over for the next frame. The scene is drawn once per band, so use the tallest band the memory allows. A last band that hangs below the screen is cut off by the display.

After the first frame, an origin also makes partial updates cheap: move the canvas over the part of the screen that changes, redraw, and present it. examples/thermometer_board.dodo keeps a canvas for a third of the screen and redraws only the rows holding its reading.

bounds(), clip(), dirty() and color_at use screen coordinates. row(y) and pixels() stay relative to the canvas’s own top-left pixel, and equals and diff_bounds compare canvases from their top-left pixels, whatever their origins. set_origin resets the clip to the new bounds and empties the dirty rectangle.

Canvases and pixel formats

Format Bytes per pixel Layout
Rgba8888 4 Red, green, blue, alpha.
Bgra8888 4 Blue, green, red, alpha: Windows DIBs, macOS bitmaps, little-endian X11.
Rgb565 2 5-6-5 bits, high byte first, as ST7789 and ILI9341 SPI panels expect.
Gray8 1 Luminance.
Mono1 1/8 One bit per pixel, leftmost in the most significant bit, rows padded to whole bytes; set bits are white. SSD1306-style panels.

graphics.bytes_needed(width, height, format) is the storage size for tightly packed rows. Canvas.with_stride accepts rows with padding, such as a window system’s shared buffer. canvas.pixels() and canvas.row(y) expose the bytes for presenting or encoding.

Colors are graphics.Color, a u32 holding 0xAARRGGBB, so they copy into every call. Build them with rgb, rgba, or hex(0xRRGGBB), or use constants such as graphics.WHITE. Formats without alpha drop it; Gray8 and Mono1 store graphics.luma(color) (Mono1 lights pixels from 128 up). Drawing stores the color, alpha included. To composite, use blend_rect for a translucent fill, blend to draw one canvas over another, or graphics.over for two colors. Reading a pixel back with color_at widens Rgb565 channels by repeating their high bits.

Clipping and dirty rectangles

Every drawing call is limited to the clip rectangle, the whole canvas until set_clip narrows it. clear fills the clip rectangle. Each call also grows the dirty rectangle to cover exactly the pixels it wrote, which is what makes partial updates cheap: a full 240x240 RGB565 frame is 115,200 bytes over SPI, while a changed label may be a few hundred. dirty() reads it, take_dirty() reads and resets it, and mark_dirty adds an area changed by other means.

Drawing reference

Call Draws
clear(color) The clip rectangle.
pixel(x, y, color) One pixel.
line(x0, y0, x1, y1, color) A one-pixel line including both ends.
rect / fill_rect(x, y, width, height, color), fill(rect, color) Rectangle outline or area.
round_rect / fill_round_rect(x, y, width, height, radius, color) Rounded corners; the radius is limited to half the shorter side.
circle / fill_circle(cx, cy, radius, color) A circle spanning 2 * radius + 1 pixels.
ellipse / fill_ellipse(cx, cy, rx, ry, color) An axis-aligned ellipse.
polygon / fill_polygon(coordinates, color) A closed outline or even-odd fill through x0, y0, x1, y1, ....
blend_rect(x, y, width, height, color) A translucent rectangle.
blit(source, x, y), blit_region(source, rect, x, y) Another canvas, converting its format.
blend(source, x, y), blend_region(...) Another canvas composited by its alpha.
text(font, x, y, text, color) UTF-8 text; returns the bounds of its character cells.

These calls store their color in whole pixels; the antialiased family blends partial pixels instead.

Polygons take a flat [N]i32 of coordinate pairs because a Dodo array of structs cannot be filled by repetition; [0i32; 2 * N] can, so a program can compute its vertices in a loop.

The geometry is exact and deterministic. A filled shape covers the pixels whose centres lie inside it: a circle of radius r covers the pixels within r + 1/2 of its centre, and the matching outline is that disk minus the disk of radius r - 1, so outlines always lie inside their fills. Lines step one pixel per column (or per row, when steep) and round half up. Fills use the even-odd rule, so a pentagram has a hollow centre.

Inputs never trap. Rectangles, circles, text and blits are exact for every i32 and u32 value. Line and polygon vertices are clamped to +/-2^29 and ellipse radii to 16383, which keeps every intermediate product within 64 bits and only matters for shapes hundreds of millions of pixels away. Work is bounded by the visible area: a line between distant points costs at most one step per visible column.

Antialiased drawing

The aa_ calls draw the same shapes with smooth edges. Each pixel is blended with the color by the fraction of its area the shape covers, computed exactly from the shape’s edges in integer arithmetic, so antialiased images are as reproducible as the rest. Unlike the integer primitives, they composite over what is already there; a translucent color is scaled by the coverage.

package smooth

import "std/graphics"

@test
fn edges_blend_and_interiors_fill() {
    pixels := [0u8; 32 * 32 * 4]
    canvas := graphics.canvas(&mut pixels, 32, 32, graphics.PixelFormat.Rgba8888)!
    canvas.clear(graphics.BLACK)
    canvas.aa_fill_circle(15, 15, 10, graphics.WHITE)
    canvas.aa_thick_line(2, 30, 29, 22, 3, graphics.rgba(97, 175, 239, 200))

    match canvas.color_at(15, 15) {
        some(color) => assert_eq(color, graphics.WHITE),
        none => assert(false),
    }
    // A pixel on the rim is only partly covered: a shade of gray.
    match canvas.color_at(15, 5) {
        some(color) => assert(graphics.red(color) > 0 && graphics.red(color) < 255),
        none => assert(false),
    }
}
Call Draws
aa_line(x0, y0, x1, y1, color) A one-pixel line between pixel centres with square ends; axis-aligned lines cover the same pixels as line.
aa_thick_line(x0, y0, x1, y1, width, color) A line width pixels wide with round ends.
aa_circle / aa_fill_circle(cx, cy, radius, color) The ring or disk circle and fill_circle approximate: radius + 1/2 around the centre of pixel (cx, cy).
aa_ellipse / aa_fill_ellipse(cx, cy, rx, ry, color) The same for ellipses.
aa_round_rect / aa_fill_round_rect(x, y, width, height, radius, color) Exactly round corners; radius 0 gives the same pixels as fill_rect.
aa_fill_polygon(coordinates, color) An even-odd polygon through pixel corners, like fill_polygon.
fill_path(path, rule, color), fill_outline(outline, rule, color) Any path or outline.
stroke_path(path, style, color), stroke_outline(outline, style, color) The stroke of a path or outline: its width, joins, caps and dashes.
gradient_rect, gradient_path, gradient_outline, gradient_stroke_path, gradient_stroke_outline The same with a gradient.

Clipping, dirty rectangles, origins and bands work as for every other call, and every pixel format is supported: Mono1 lights a pixel once it is about half covered.

Paths and outlines

Path coordinates are fixed point: graphics.SUBPIXEL (256) units make one pixel, so shapes can sit between pixels. The pixel (x, y) spans x * 256 to (x + 1) * 256, and its centre is x * 256 + 128.

A graphics.Path stores commands in caller-owned i32 words:

storage := [0i32; 256]
path := graphics.Path.new(&mut storage)
path.move_to(4 * graphics.SUBPIXEL, 28 * graphics.SUBPIXEL)
path.cubic_to(10 * 256, 0, 22 * 256, 0, 28 * 256, 28 * 256)
path.quad_to(16 * 256, 16 * 256, 4 * 256, 28 * 256)
path.close()
path.circle(16 * 256, 20 * 256, 3 * 256)       // a whole contour
canvas.fill_path(&path, graphics.FillRule.EvenOdd, graphics.hex(0xe5c07b))

move_to, line_to, quad_to, cubic_to and close build contours; a contour left open is closed by a straight line. rect, round_rect, ellipse and circle each add a closed contour. A move or line takes 3 words, a quadratic curve 5, a cubic 7, close 1, a circle or ellipse 60 and a rounded rectangle 72. Building a path never fails: when a command does not fit, overflowed() turns true and the path draws nothing, so size the storage for the largest shape and check overflowed() in a test.

FillRule.NonZero treats every area the contours wind around as inside, so overlapping contours merge; FillRule.EvenOdd makes each nested contour cut a hole whatever its direction.

A path is one kind of graphics.Outline, the interface the rasterizer draws. Any type with a pub fn trace(&self, pen: &mut graphics.Pen) method is an outline: it describes itself by calling the same five commands on the pen, and needs no storage at all. The rasterizer calls trace several times per drawing call (once for the bounds, then usually once more to collect its edges), so it must describe the same shape each time:

struct Diamond {
    cx: i32
    cy: i32
    radius: i32

    pub fn trace(&self, pen: &mut graphics.Pen) {
        pen.move_to(self.cx, self.cy - self.radius)
        pen.line_to(self.cx + self.radius, self.cy)
        pen.line_to(self.cx, self.cy + self.radius)
        pen.line_to(self.cx - self.radius, self.cy)
    }
}

shape := Diamond { cx: 16 * 256, cy: 16 * 256, radius: 10 * 256 }
canvas.fill_outline(&shape, graphics.FillRule.NonZero, graphics.WHITE)

Curves are flattened to within 1/32 pixel. Path coordinates are clamped to +/-2^29 subpixels (+/-2^21 pixels) and the aa_ calls’ pixel coordinates to +/-2^21, which keeps every product within 64 bits. Work is bounded by the visible part of the shape: rows and columns outside the clip rectangle are never visited. Within it, the cost follows the edges rather than the area: coverage is computed only in the pixels an edge passes through, and solid interiors are filled as whole spans, so an outline or a long thin line costs about as much as its length. The outline is flattened once into at most 256 straight edges at a time. When more edges cross the visible rows, the rows are drawn in bands, each tracing the outline again, and a row crossed by more than 256 edges traces it once per 256 columns, so an outline with thousands of edges is still drawn faster as several smaller ones.

Strokes

stroke_path paints a band of the stroke’s width centred on a path, the way borders, chart lines and icon outlines are drawn. A graphics.Stroke holds the style; its lengths are in subpixels, like path coordinates:

package strokes

import "std/graphics"

@test
fn a_dashed_border() {
    pixels := [0u8; 24 * 24 * 4]
    canvas := graphics.canvas(&mut pixels, 24, 24, graphics.PixelFormat.Rgba8888)!
    canvas.clear(graphics.BLACK)
    storage := [0i32; 64]
    path := graphics.Path.new(&mut storage)
    path.round_rect(3 * 256, 3 * 256, 18 * 256, 18 * 256, 4 * 256)

    style := graphics.Stroke.new(2 * graphics.SUBPIXEL)
    style.set_join(graphics.LineJoin.Round)
    style.set_cap(graphics.LineCap.Round)
    dashes := [4i32 * graphics.SUBPIXEL, 3 * graphics.SUBPIXEL]
    style.set_dashes(&dashes, 0)
    canvas.stroke_path(&path, &style, graphics.hex(0x98c379))

    // The stroke straddles the outline; the inside stays untouched.
    match canvas.color_at(12, 12) {
        some(color) => assert_eq(color, graphics.BLACK),
        none => assert(false),
    }
}
Setting Effect
Stroke.new(width) A solid stroke width subpixels wide; zero or less draws nothing.
set_join(LineJoin.Miter / Round / Bevel) How corners between segments are filled. Miter is the default.
set_miter_limit(limit) The longest a miter may reach, as the ratio of its length to the width in SUBPIXEL units: the default 1024 (4) bevels corners sharper than about 29 degrees.
set_cap(LineCap.Butt / Round / Square) How open ends and dashes end: flat at the end point (the default), round, or flat half the width beyond it.
set_dashes(pattern, offset), clear_dashes() Alternating dash and gap lengths, starting offset into the pattern at each subpath. An odd count repeats to make it even, as in SVG; at most graphics.STROKE_DASHES (16) lengths are kept.

The defaults (miter joins, a limit of 4, butt caps, solid) are those of SVG and the HTML canvas. Contours are not closed for stroking: an open subpath gets a cap at each end, and only close joins its end to its start. A subpath of no length, such as move_to followed by close, is a dot with round or square caps. Each dash gets the caps; a zero-length dash with round caps is a dot, and a closed subpath whose pattern is on at both ends joins its last dash to its first.

Strokes are rasterized like fills, with exact coverage, so a stroke along pixel edges covers whole pixels: a two pixel wide stroke from (3, 5) to (9, 5) in pixels paints exactly the pixels of fill_rect(3, 4, 6, 2, ...), and a closed square with miter joins is exactly a ring. Curves are flattened as for filling, and round joins and caps are drawn within 1/32 pixel. A translucent stroke paints each pixel once, even where it overlaps itself.

stroke_outline strokes any outline, including procedural shapes and TrueType glyph outlines. graphics.Stroked.new(&outline, &style) is the stroke as an outline of its own, for coverage masks and outline_bounds; fill it by FillRule.NonZero, since a stroke overlaps itself at every join.

A dash pattern shorter than a quarter pixel in all is scaled up to that, since finer dashes only blend to gray. Round or square caps close gaps under 1/4096 of the width, so such a stroke is drawn solid. Widths are limited to 2^30 subpixels. Like fills, strokes cost what is visible: segments, joins and caps outside the clip rectangle are skipped, and only the dashes that cross it are drawn.

Coverage masks

A shape drawn many times can be rasterized once into a coverage mask, one byte per pixel from 0 (outside) to 255 (fully covered), and composited from it afterwards:

bounds := graphics.outline_bounds(&shape)            // the pixels it touches
mask := [0u8; 32 * 32]                               // at least width * height
graphics.coverage_mask(&shape, graphics.FillRule.NonZero, &mut mask, bounds.x, bounds.y, bounds.width, bounds.height)
canvas.fill_mask(&mask, bounds.width, bounds.height, bounds.x + 40, bounds.y, graphics.WHITE)

coverage_mask(outline, rule, mask, x, y, width, height) writes the coverage of the width x height pixels starting at (x, y), in rows of width bytes. fill_mask(mask, width, height, x, y, color) and gradient_mask blend each pixel exactly as fill_outline and gradient_outline would, so a mask moved by whole pixels draws the same pixels as the outline moved by the same amount. Coverage depends on where a shape sits within a pixel, so make one mask per subpixel offset you draw at.

Coverage spans store the same coverage as runs, skipping uncovered pixels and filling fully covered ones whole, so they draw faster and usually take less room than the mask:

buffer := [0u8; 4096]                    // at least spans_bound(width, height)
length := graphics.coverage_spans(&shape, graphics.FillRule.NonZero, &mut buffer, bounds.x, bounds.y, bounds.width, bounds.height)
canvas.fill_spans(&buffer[..length], bounds.width, bounds.height, bounds.x + 40, bounds.y, graphics.WHITE)

coverage_spans returns the length of the spans, or 0 when the buffer is smaller than spans_bound(width, height). fill_spans and gradient_spans draw exactly what fill_mask and gradient_mask draw.

Gradients

A graphics.Gradient paints colors that change across an area:

sky := graphics.Gradient.linear(0, 0, 0, 99, graphics.hex(0x203a5c), graphics.hex(0xf4a259))
sky.add_stop(170, graphics.hex(0xbc4b51))
canvas.gradient_rect(0, 0, 160, 100, &sky)

glow := graphics.Gradient.radial(120, 30, 24, graphics.WHITE, graphics.TRANSPARENT)
canvas.gradient_rect(96, 6, 48, 48, &glow)

Gradient.linear(x0, y0, x1, y1, start, end) runs from start at pixel (x0, y0) to end at pixel (x1, y1). Gradient.radial(cx, cy, radius, inner, outer) runs from the centre of pixel (cx, cy) outward. Colors are sampled at pixel centres, so the end pixels get exactly the end colors. add_stop(offset, color) inserts a color at offset, from 0 (start) to 255 (end); a gradient holds up to graphics.GRADIENT_STOPS (8) stops, and two stops at the same offset make a hard edge. color_at(x, y) returns the color a pixel gets.

Interpolation uses premultiplied alpha, so fading to TRANSPARENT thins a color out instead of darkening it. set_spread(Spread.Repeat) and Spread.Reflect continue the gradient beyond its end instead of extending the end colors (Spread.Pad). set_dither(true) adds a 4x4 ordered dither when drawing on Rgb565 and Mono1 canvases, trading the bands those formats show for a fine pattern; on Mono1 a mid gray becomes a checkerboard. Gradients composite over the canvas like the antialiased calls.

Text and fonts

font.small() returns 6x8 character cells and font.medium() 8x16; both cover U+0020 through U+00FF, including accented Latin-1 letters. Bind a font once and pass a reference to each call. font.medium().scaled(2) draws each glyph pixel as a 2x2 block (factors 1 to 64).

small := font.small()
size := small.measure("Hello")          // 30 x 8
bounds := canvas.text(&small, 4, 4, "Hello\nworld", graphics.WHITE)

"\n" returns to the starting x on the next line and "\r" is ignored. Only glyph pixels are drawn; fill bounds (or measure first) for a background. Characters outside a font draw as an outlined box the size of the cell.

A graphics.Font is a plain description of a bitmap, so you can supply your own: graphics.Font.new(glyph_width, glyph_height, first, count, &bitmap). Glyphs are stored for consecutive code points from first, each glyph_height rows of ceil(glyph_width / 8) bytes with the leftmost pixel in the most significant bit. Put the bitmap in a static array so firmware keeps it in flash.

TrueType fonts

std/graphics/truetype draws TrueType fonts antialiased at any size. A font is read in place from its bytes, a file loaded with std/fs or bytes compiled into the program; nothing is copied or allocated, and each glyph’s outline is decoded straight from the font data while drawing.

import "std/fs"
import "std/graphics"
import "std/graphics/truetype"
import "std/platform"

storage := [0u8; 1048576]
workspace := platform.workspace()
report := fs.read_file("DejaVuSans.ttf", &mut storage, &mut workspace)?
font := truetype.Font.new(&storage[..report.read])?

bounds := font.draw(&mut canvas, 8, 8, "Grüße, 50 €", 24, graphics.WHITE)
size := font.measure("Hello", 16)

draw(canvas, x, y, text, size, color) places the top-left corner of the first line at (x, y), with size the em size in pixels, and returns the area that measure(text, size) reports: the widest line’s advance by the line count times line_height(size). Each line’s baseline is baseline(size) pixels below its top. "\n" starts a new line, kerning pairs from the font’s kern table are applied, and glyphs are placed to 1/256 pixel, so spacing stays even at small sizes. draw_gradient takes a gradient instead of a color, and font.glyph(index, x, y, size) returns a single glyph as a graphics.Outline for fill_outline, positioned by its baseline origin in subpixels.

Font.new opens a .ttf file or the first font of a .ttc collection; truetype.font_count(data) and Font.from_collection(data, index) reach the others. Lower-level lookups work in font units: glyph_index(code_point) (0, the box-shaped .notdef glyph, when the font has none), advance_width, left_side_bearing, kerning, glyph_box, units_per_em, ascent, descent and line_gap.

Supported are TrueType outlines, simple and composite glyphs, and character maps in formats 0, 4, 6 and 12, which cover all of Unicode. Fonts with CFF outlines (.otf files beginning with OTTO) return Error.Unsupported; other errors are Malformed and NoSuchFont. Untrusted fonts are safe: every offset is checked, composite glyphs are limited in depth and size, and a damaged glyph draws as much of its outline as is valid.

Glyph cache

Font.draw rasterizes every glyph from its outline each time. Text that is drawn again, such as labels and counters redrawn every frame, is much faster through a truetype.GlyphCache, which keeps each rasterized glyph as coverage spans in storage you provide:

cache_storage := [0u8; 65536]
cache := truetype.GlyphCache.new(&font, &mut cache_storage)

cache.draw(&mut canvas, 8, 8, "Score: 1200", 14, graphics.WHITE)

cache.draw and cache.draw_gradient take the same arguments and return the same area as the Font calls. The first time a glyph appears at a size it is rasterized into the cache; afterwards drawing it only blends its stored coverage. On an Apple M-series machine at -O2, repeated 14-pixel text drew about 13 times faster than with Font.draw (0.17 µs instead of 2.3 µs per glyph) and 96-pixel text about 6 times faster (0.64 µs instead of 3.7 µs). The gain is largest at small sizes, where rasterizing costs the most per pixel drawn.

The one visible difference is placement: the cache positions glyphs to a quarter pixel horizontally, where Font.draw uses 1/256 pixel, and keeps a separate copy for each of the four quarter-pixel offsets a glyph is drawn at. Glyphs that land on a quarter pixel draw exactly as Font.draw draws them.

Any amount of storage works, and more holds more glyphs: 64 KiB holds several hundred glyphs at 14 pixels or a few dozen at 96. A full cache evicts the glyphs it cached longest ago. A glyph whose bounding box covers more pixels than about a quarter of the storage’s bytes is drawn from its outline without being cached, so one huge glyph cannot flush the rest. len(), hits() and misses() show how well the storage fits the text, and clear() empties the cache. The cache borrows the font, so it cannot outlive it; use one cache per font.

Images

std/graphics/image decodes image files onto canvases and encodes canvases into files, from and into byte buffers; read and write files with std/fs or embed the bytes. It is a thin layer over the codec packages of std/image, which add every pixel layout (16-bit and float included), color information, EXIF/XMP/ICC metadata, APNG frames and encoder options. Like the rest of the family it needs no floating point.

header := image.info(&data)?              // format, width, height, has_alpha
pixels := [0u8; 64 * 64 * 4]
sprite := image.decode(&data, &mut pixels, graphics.PixelFormat.Rgba8888)?
image.draw(&data, &mut canvas, 10, 10)?   // straight onto an existing canvas
Format Decodes Encodes
Netpbm Binary PPM (P6) and PGM (P5), any maxval, comments; PAM (P7) and PFM P6, ppm_size bytes
QOI RGB and RGBA RGBA, at most qoi_max_size bytes
BMP 1, 4, 8-bit palettes, RLE8 and RLE4; 16, 24, 32-bit with or without bit-field masks; bottom-up or top-down 24-bit, bmp_size bytes
PNG Every color type and bit depth (gray, RGB, palette, gray and RGB with alpha; 1 to 16 bits), tRNS transparency, Adam7 interlacing; the default image of an APNG 8-bit RGBA: uncompressed, png_size bytes; or compressed, at most png_compressed_max_size bytes

PPM and BMP encoding drop alpha; QOI and PNG keep it. Errors are those of std/image (image.Error is pixels.Error): Truncated, Malformed, Unsupported (ASCII PPM, an unknown critical PNG chunk), TooLarge, and BufferTooSmall. Every length is checked before use, so untrusted files are safe to decode; a failure part-way through draw can leave part of the image drawn.

Colors are converted to 8 bits as they are drawn: 16-bit samples are rounded, and color information is not applied, so samples are taken as sRGB. PNG decoding checks every chunk’s CRC and the zlib Adler-32, and skips unknown ancillary chunks. Unfiltering needs two rows of raw image data: decode and draw keep image.PNG_SCRATCH_LEN (16 KiB) bytes of them on the stack and fail with BufferTooSmall for wider rows, such as RGBA wider than 2047 pixels. Pass your own storage of image.png_scratch_size(&data) bytes to decode_png or draw_png instead. The zlib decoder adds about 40 KiB of stack either way.

scratch := [0u8; 32768]                   // png_scratch_size(&data) or more
image.draw_png(&data, &mut canvas, 0, 0, &mut scratch)?

encode_png writes stored (uncompressed) deflate blocks with no row filters: the size is exact and nothing beyond the output buffer is needed, which suits firmware. encode_png_compressed picks a filter for each row and compresses with std/compress; it borrows deflate.ENCODER_BUFFER_LEN bytes and deflate.WORKSPACE_LEN words of storage, about 350 KiB together, which static storage provides best.

Test rendering

Because rendering is integer-only, a rendered image can be compared byte for byte across machines. canvas.equals(&other) compares decoded colors, so two canvases in different formats can be equal; canvas.diff_bounds(&other) returns the rectangle covering every differing pixel. fake.Display keeps its own copy of the screen, updated only inside each presented rectangle: compare display.screen() with the canvas to catch a dirty rectangle that was too small, and use fail_next to exercise retry paths.

For golden-image tests, render a scene, encode it with image.encode_qoi, and compare it with a checked-in file. The standard library’s own goldens live in tests/graphics/golden/; tests/graphics/golden_test.dodo shows the pattern, including regenerating every image with DODO_UPDATE_GOLDEN=1.

Limits

There is no floating point and no GPU path: both are deliberate for predictable results on microcontrollers. TrueType text is not hinted, and there is no text shaping: no ligatures, GPOS kerning, right-to-left or vertical text, and characters map one to one to glyphs.

The panel drivers write pixels through the SPI or I2C bus protocol, so a transfer keeps the processor busy; there is no DMA path for them yet. ST7789 panels are the only colour panels with a driver: ILI9341 and similar controllers use the same window commands but different setup, and SH1106 OLED controllers lack the SSD1306’s addressing mode.

Search every guide, reference page, and API declaration.