Graphics API

Paint a single pixel in the current colour

Horizontal line running right from (x, y)

Note — This is the fastest primitive - it writes whole framebuffer bytes at a time. A fill built from hlines is substantially faster than one built from pixels.

Vertical line running down from (x, y)

Line between two arbitrary points (Bresenham)

Line with a thickness, drawn as a stack of parallel lines

Quadratic Bezier curve through 16 straight segments

Rectangle outline

Rectangle outline with rounded corners

Solid rectangle

Note — Filling with colour 0 erases a region before it is redrawn.

Solid rectangle with rounded corners

Rectangle filled with a dither pattern instead of solid colour

Dithered horizontal line

Dithered vertical line

Dithered filled circle

Dithered rounded rectangle

Rectangle with a vertical dither gradient

Note — Equal top and bottom shades give a flat fill, so this doubles as gfx_fill_rect_dithered() when a gradient is animated in and out.

Rectangle with a horizontal dither gradient

Circle outline, whole or by quadrant

Filled circle, whole or by quadrant

Select what subsequent draw calls do to the pixels they touch

Note — Lasts until the draw callback returns; the next one starts at GFX_COLOR_SET.

Draw a string in the current font and colour

Returns — Width drawn, in pixels - add it to x to continue on the same line

printf-style gfx_draw_str()

Returns — Width drawn, in pixels

Note — `%f` costs far more than the integer conversions. For a value redrawn every frame, scale to an int explicitly: `gfx_draw_strf(gfx, x, y, "%d%%", (int)(v * 100))`.

Warning — The formatted result is built in a shared 128-byte buffer and truncated to fit. Do not call it from an audio or timer callback while the UI thread may also be drawing.

Select the font for subsequent text calls

Note — Sticky, like the colour. Setting a font is cheap; measuring text is not, so hoist gfx_get_str_width() out of loops rather than the gfx_set_font() call.

Measure a string in the current font without drawing it

Returns — Width in pixels

// centre a label
const uint16_t w = gfx_get_str_width(gfx, label);
gfx_draw_str(gfx, SCREEN_CENTER_X - (w >> 1), 120, label);

Blit a 1-bit XBM bitmap

Note — TRANSPARENT by default: 1 bits are painted in the current colour, 0 bits are left alone. gfx_set_bitmap_mode(gfx, false) makes blits opaque (0 bits in the opposite colour) for the rest of the callback. For assets, prefer ui_draw_img(), which takes a gfx_img_t from the asset pipeline and knows its own dimensions; this is the blit for a bitmap built at runtime.

Transparent (default) or opaque bitmap blits, until the draw callback returns

Restrict drawing to a rectangular window

gfx_set_clip(gfx, 10, 40, 390, 200);   // scrolling list body
draw_rows(gfx, m);
gfx_clip_reset(gfx);

Note — Corner-to-corner, not x/y/w/h. It narrows the callback's drawing area (the screen, or the tapp's window/cell - it can never widen it) and lasts until gfx_clip_reset() or the callback's return.

Remove the clip window: restore the whole area this callback draws into (the screen, or the tapp's window / hint cell - never beyond it)

How many frames have been PAINTED

Returns — Frame counter, incremented once per frame actually pushed to the display

Default UI body font

Headings / emphasis

Monospace - counters, numeric readouts