On this page

The draw list

gfx_list.h is the backend neutral draw list. Everything a frame paints, from the ui tree or from your own code, is recorded into a gfx_list in logical units. A backend only ever copies it into its own buffers.

Records

There are four record kinds. gfx_rect is 48 bytes, gfx_glyph is 40 bytes and gfx_curve is 32 bytes, each byte identical to the instance record its shader reads. A flush is therefore one copy into a mapped buffer. gfx_art carries an image or svg draw with its quad or paint.

  • gfx_fill, gfx_round, gfx_outline, gfx_gradient, gfx_glass and gfx_blob each append one rect. gfx_shape appends one you built yourself.
  • gfx_shadow appends a soft shadow with CSS box shadow blur and spread. It is a rect too, one whose border holds minus sigma, so a negative border always means a shadow. gfx_round and gfx_outline clamp a negative border to zero. See shadows and elevation.
  • gfx_curves appends segments, and gfx_polyline builds joined segments from points with a half width, a glow and the GFX_CURVE_ROUND_CAP or GFX_CURVE_GLOW_ONLY flags. See polylines.
  • gfx_image_draw takes a gfx_image_quad from gfx_quad, which covers uv, tint, wash, spin, radius and wobble. gfx_svg_draw takes a gfx_svg_paint from gfx_paint.
  • gfx_glyphs reserves glyph slots for a font. A glyph can turn about its centre, see turned glyphs. gfx_glyphs_tail makes room for a number of glyphs at the tail and reports how many fit in room, you write them there, and gfx_glyphs_placed commits them. Nothing may record into the list between the two.

Layers, clips and runs

gfx_list_begin resets the list for a frame. gfx_list_layer picks the layer new records land on. Layer numbers are unbounded: one draw holds a window of GFX_LAYERS (32) of them, and asking for a layer past its top slides the window up, handing the layers left behind to the sink. Without a sink those records stay on the top layer and a warning is logged. Every layer is drawn in order, and on each one rects, then art, then curves, then glyphs. The ui gives every overlay its own layer, so a later popup covers an earlier one's text. gfx_list_clip and gfx_list_unclip bracket a clipped region, and gfx_list_mask rounds it, see rounded clips.

A clip, mask, layer or font change opens a new gfx_run, and glyph runs carry their font in aux. Records that already sit inside their clip, and clear of every rounded corner, keep the open run, so a clip change that cannot matter costs nothing. gfx_list_shine sets the text softness, thickness and specular terms for the frame.

gfx_list_recorder.cpp
#include "isolenui/gfx/gfx_list.h"

#include <math.h>

// red is the low byte and alpha the high byte, see the colors page
constexpr uint32_t abgr(uint32_t r, uint32_t g, uint32_t b, uint32_t a = 255u)
{
    return r | (g << 8) | (b << 16) | (a << 24);
}

// the struct is small and the records live on the heap, init frees what the
// list held first, so the list must start zeroed
static gfx_list g_list;

// caps are where each record kind starts, past them the list flushes through a
// sink if it has one and grows otherwise
static bool open_list(void)
{
    gfx_list_caps caps = gfx_list_caps_default();
    caps.glyphs = 8192u;
    return gfx_list_init(&g_list, &caps);
}

static void close_list(void)
{
    gfx_list_free(&g_list);
}

static void record_hud(gfx_image logo, gfx_svg icon, float w, float h, float time)
{
    gfx_list_begin(&g_list, w, h, time);

    // layer zero first, a full bleed background
    gfx_list_layer(&g_list, 0u);
    gfx_fill(&g_list, 0.0f, 0.0f, w, h, abgr(0x0a, 0x0a, 0x0a));

    // clip to a card, then a glass fill and an outline inside it
    gfx_list_clip(&g_list, 24.0f, 24.0f, 320.0f, 120.0f);
    gfx_glass(&g_list, 24.0f, 24.0f, 320.0f, 120.0f, 12.0f, 0.5f,
              abgr(0x8a, 0x64, 0xe5, 0x60));
    gfx_outline(&g_list, 24.0f, 24.0f, 320.0f, 120.0f, 12.0f, 1.0f,
                abgr(0xff, 0xff, 0xff, 0x30));
    gfx_list_unclip(&g_list);

    // a glowing trace, curves are their own record kind with round caps
    float xy[64];
    for (uint32_t i = 0; i < 32; ++i) {
        const float t = float(i) / 31.0f;
        xy[i * 2 + 0] = 24.0f + t * 320.0f;
        xy[i * 2 + 1] = 200.0f + 24.0f * sinf(t * 6.28f + time);
    }
    gfx_polyline(&g_list, xy, 32u, 1.5f, 6.0f, abgr(0x6d, 0x98, 0xcc),
                 GFX_CURVE_ROUND_CAP);

    // layer one on top, the art assets
    gfx_list_layer(&g_list, 1u);
    const gfx_image_quad quad = gfx_quad(48.0f, 48.0f, 96.0f, 32.0f);
    gfx_image_draw(&g_list, logo, &quad);
    gfx_svg_paint paint = gfx_paint();
    paint.supersample = true;
    gfx_svg_draw(&g_list, icon, 300.0f, 40.0f, 24.0f, 24.0f, &paint);
}

Rounded clips

A clip can have rounded corners. gfx_mask is a box in logical units, x y w h, and four radii that run top left, top right, bottom right, bottom left. gfx_list_mask(l, &m) cuts everything recorded after it to that rounded box, on top of the rectangular clip. The edge is anti aliased like the records themselves.

  • All zero radii, or a null mask, lift it. gfx_mask_on(m) is true when any radius is above zero.
  • The mask survives gfx_list_clip, so narrowing the clip for a nested part keeps the corners. gfx_list_unclip lifts the clip and the mask together.
  • Every gfx_run and every gfx_art carries the mask it was recorded under in mask. A record that sits clear of every corner is stored with no mask, so it draws on the plain scissor path.
  • The Vulkan, Metal and CPU backends all honour it, and it follows the page zoom. See writing a backend for how a pass reads it.

You rarely set one by hand. The ui sets it for you: a box with a fill, a border or a look is the wall its children paint inside, and it now clips them to its rounded padding box, the box inset by the border width and rounded by the radius less that width. Nested rounded clips meet as one: the boxes intersect, and a corner keeps the larger radius of the clips that share it. Scrollbars follow the same corners. See raw layout for the solver side.

draw_rounded_clip.cpp
#include "isolenui/gfx/gfx_list.h"

// a card with a one unit border and a radius of 12, its rows scroll under the
// rounded corners instead of poking out of them
static void record_card(gfx_list* l, float x, float y, float w, float h, float scroll)
{
    const float border = 1.0f;
    const float radius = 12.0f;
    gfx_round(l, x, y, w, h, radius, 0xff1c1c1cu);
    gfx_outline(l, x, y, w, h, radius, border, 0x30ffffffu);

    // the padding box, inset by the border and rounded by what is left
    const float in = radius - border;
    const gfx_mask m = { { x + border, y + border, w - border * 2.0f, h - border * 2.0f },
                         { in, in, in, in } };
    gfx_list_clip(l, m.box[0], m.box[1], m.box[2], m.box[3]);
    gfx_list_mask(l, &m);

    for (uint32_t i = 0; i < 12u; ++i) {
        const float row = y + border + float(i) * 28.0f - scroll;
        gfx_fill(l, x + border, row, w - border * 2.0f, 27.0f,
                 i & 1u ? 0xff242424u : 0xff202020u);
    }

    // a narrower clip alone keeps the mask, so a nested part still loses the corners
    gfx_list_clip(l, x + border, y + h - 40.0f, w - border * 2.0f, 40.0f - border);
    gfx_fill(l, x + border, y + h - 40.0f, w - border * 2.0f, 40.0f, 0xff2d2d2du);

    // unclip lifts the mask too
    gfx_list_unclip(l);
}

Polylines

gfx_polyline turns points into segments that join. Each joint is cut along one line both neighbours share, so a polyline covers each pixel once and a half transparent line has no darker knots at its turns. A polyline whose last point repeats its first, with more than three points, is closed and joins around.

  • A turn too sharp for the shared line splits on the start of the next segment instead, when a whole cap fits there.
  • Where the segments are too short for either, the joint is left open with round ends, the overlap blends twice, and the log says so up to four times.
  • Zero length segments draw nothing. The open ends of the line are round with GFX_CURVE_ROUND_CAP and square without.

gfx_polyline_fill(out, xy, points, first, count, half_width, glow, rgba, flags) writes the count segments from first into your own array, joined to their neighbours outside that window too. A long line can therefore be written in chunks, each passed to gfx_curves, and the seams still look like one line. Pass only GFX_CURVE_ROUND_CAP and GFX_CURVE_GLOW_ONLY in flags. The joint bits, GFX_CURVE_JOIN_START, GFX_CURVE_JOIN_END, GFX_CURVE_SPLIT_END, GFX_CURVE_ROUND_START and GFX_CURVE_ROUND_END, are written by the fill along with each joint's direction as a 12 bit angle.

Joints hold under a pinch zoom too. The Metal and Vulkan curve passes shift the joint lines by the same offset as the zoomed viewport, so a zoomed polyline still covers each pixel once.

draw_polyline_chunks.cpp
#include "isolenui/gfx/gfx_list.h"

#include <math.h>

// a closed ring repeats its first point last, so the last segment joins the first
static void record_ring(gfx_list* l, float cx, float cy, float r, uint32_t rgba)
{
    float xy[2u * 65u];
    for (uint32_t i = 0; i < 64u; ++i) {
        const float a = float(i) * (6.28318531f / 64.0f);
        xy[i * 2u] = cx + r * cosf(a);
        xy[i * 2u + 1u] = cy + r * sinf(a);
    }
    xy[128] = xy[0];
    xy[129] = xy[1];
    // half transparent and still no darker joints, each pixel is covered once
    gfx_polyline(l, xy, 65u, 2.0f, 0.0f, rgba, GFX_CURVE_ROUND_CAP);
}

// a long trace written a window at a time, every chunk still joins its
// neighbours outside the window so the seams look like one line
static void record_trace(gfx_list* l, const float* xy, uint32_t points, uint32_t rgba)
{
    gfx_curve seg[256];
    const uint32_t total = points - 1u;
    for (uint32_t first = 0; first < total; first += 256u) {
        const uint32_t count = total - first < 256u ? total - first : 256u;
        gfx_polyline_fill(seg, xy, points, first, count, 1.5f, 4.0f, rgba, GFX_CURVE_ROUND_CAP);
        gfx_curves(l, seg, count);
    }
}
A half transparent line that folds back on itself within its own stroke width, a hairpin, still doubles where the two sides overlap. Every turn wider than that covers each pixel once.

Turned glyphs

A glyph record can turn about the centre of its quad, which is how text follows a curve. gfx_glyph_turn(&g, radians) stores the turn, positive clockwise on screen, in px_range: its sign bit marks the glyph as turned (GFX_GLYPH_TURNED), the high half keeps the range as a bfloat16 and the low half holds the angle in GFX_GLYPH_TURN_STEPS (65536) steps. The record stays 40 bytes.

  • gfx_glyph_turned(g) says whether a record is turned, gfx_glyph_angle(g) reads the turn in radians and gfx_glyph_range(g) the distance field range either way.
  • gfx_glyph_box(g, out) is the box the glyph covers on screen, turned or not, as x y w h.
  • gfx_glyph_scale_range(&g, k) multiplies the range by k and keeps the turn, which is what a zoomed draw needs. Scaling px_range by hand would destroy the packed angle.
  • All three backends draw turned glyphs, and they stay turned under a pinch zoom on every backend. Code that reads px_range itself must go through gfx_glyph_range.

text_font_lay_dir lays out a line you can then bend, see the low level text surface, and arc labels are built from both.

Capacities and sinks

The gfx_list struct is 256 bytes and its records live on the heap. gfx_list_init allocates them once from a gfx_list_caps, and null caps means gfx_list_caps_default: 1024 rects, 2048 glyphs, 2048 curves, 32 art records and 64 runs of each kind. gfx_list_begin initialises a list with the defaults if nothing did. gfx_list_free releases it. Init frees what the list held first, so the list must start zeroed.

A list that fills up first hands its lowest layers to its sink, set with gfx_list_sink_set. The sink draws the chunk and returns true so the records can be reused. When there is no sink, or the sink returns false, the list grows instead, doubling up to 1,048,576 records of a kind. Runs stop at GFX_RUN_LIMIT (1024) and art at GFX_ART_LIMIT (256). Growth is logged, since it means the caps are too small. gfx_list_flush hands everything to the sink now and keeps the clip and layer. gfx_list_empty is true when nothing is recorded.

CounterMeaning
flushes, grownHow often the list flushed through its sink or grew.
lateRecords asked for under a layer a chunk had already drawn. They land on top of it instead.
droppedRecords refused this frame. That only happens when memory runs out.

The app's tree list has a sink that draws each chunk into the frame. The frame list in isolen_frame::list is written before the tree paints, so it has no sink and grows. Both start from isolen_app_desc::lists, the frame list at a quarter of it.

Last updated 6 October 2026