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_glassandgfx_blobeach append one rect.gfx_shapeappends one you built yourself.gfx_shadowappends a soft shadow with CSS box shadow blur and spread. It is a rect too, one whoseborderholds minus sigma, so a negative border always means a shadow.gfx_roundandgfx_outlineclamp a negative border to zero. See shadows and elevation.gfx_curvesappends segments, andgfx_polylinebuilds joined segments from points with a half width, a glow and theGFX_CURVE_ROUND_CAPorGFX_CURVE_GLOW_ONLYflags. See polylines.gfx_image_drawtakes agfx_image_quadfromgfx_quad, which covers uv, tint, wash, spin, radius and wobble.gfx_svg_drawtakes agfx_svg_paintfromgfx_paint.gfx_glyphsreserves glyph slots for a font. A glyph can turn about its centre, see turned glyphs.gfx_glyphs_tailmakes room for a number of glyphs at the tail and reports how many fit inroom, you write them there, andgfx_glyphs_placedcommits 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.
#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_uncliplifts the clip and the mask together. - Every
gfx_runand everygfx_artcarries the mask it was recorded under inmask. 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.
#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_CAPand 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.
#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);
}
}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 andgfx_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 bykand keeps the turn, which is what a zoomed draw needs. Scalingpx_rangeby 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_rangeitself must go throughgfx_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.
| Counter | Meaning |
|---|---|
flushes, grown | How often the list flushed through its sink or grew. |
late | Records asked for under a layer a chunk had already drawn. They land on top of it instead. |
dropped | Records 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.