The CPU backend
gfx_backend_cpu draws the same draw list with no graphics api at all. It rasterises in bands on a worker pool with SIMD and presents only the bands that changed.
When it runs
It is built into every Windows and mac build and sits last in the platform order: Vulkan then CPU on Windows, and Metal then CPU on mac. D3D12 is in the Windows order but not built yet, so it is skipped. gfx_backend_auto only reaches it when the GPU backends cannot open. Pick it directly with --cpu, --backend cpu, desc.backend = gfx_backend_cpu or live with isolen_set_backend. See choosing a backend.
How a frame is drawn
- The target is split into bands of 64 rows, sized so a band of BGRA8 pixels stays inside L2.
- Every record is binned into the bands it touches, and each band gets a hash of what lands in it.
- A band whose hash matches last frame is skipped. An idle frame with no change redraws and presents nothing.
- Dirty bands are shared across a thread pool. It runs one lane per hardware thread less one, up to 16, and the calling thread is one of those lanes. The pool runs one caller at a time, so two devices drawing at once take turns rather than sharing lanes.
- The inner loops use AVX2, SSE2 or NEON, picked at compile time, with a scalar fallback.
- Each layer draws rects, then art, then curves, then glyphs, the same order the GPU backends flush in. Images mip and sample like the GPU does.
- On Windows the target is a DIB section, so a damaged band is one blit. On mac each band is its own layer with two IOSurfaces, and only damaged bands swap.
- With vsync on it waits on the platform pacer, since a CPU present never blocks on a drawable.
- A record under a rounded clip only pays where the mask can touch it. Rows and columns clear of the corners draw as is, and the rim draws over a saved copy of the pixels and is pulled back toward it by what the mask cuts, so the corner edge is anti aliased. The mask is part of the band hash. A frame holds up to 65,535 masks, and past that the rest draw square with a warning.
- A zoomed draw,
gfx_frame_draw_view, rewrites each record on the way in, so the rasteriser never sees a view and text stays sharp at the zoomed size. Masks follow the zoom too, and turned glyphs keep their turn throughgfx_glyph_scale_range. Once a glyph is magnified so one atlas texel spans two pixels or more, the rasteriser samples the distance field on a lattice every two pixels and reads between the samples, and a 4 by 4 tile that is clearly inside or outside the glyph is filled or skipped whole. Corners, where the field bends faster than the lattice follows, still take the exact path. Panning a page zoomed to 3x went from 33.5 ms a frame to 8.35 ms with it. - With
transparenton, the clear drops to alpha zero and the present hands the premultiplied pixels to the compositor. See a device without the ui.
The log reports the workers and SIMD width at startup. Every five seconds it adds the average and worst frame time, bands per frame and idle frames. When the damage pattern changes it also logs a band mask such as [..##....].
Level two on the CPU
isolenui/gfx/gfx_cpu.h is the CPU counterpart of the Vulkan and Metal headers. It has no platform types.
| Call | What it does |
|---|---|
gfx_cpu_frame_of(f, &out) | Fills gfx_cpu_frame: pixels, stride in pixels, width, height, band_rows and srgb. False outside a CPU frame. |
gfx_cpu_flush(f) | Rasterises everything recorded so far, so your own pixels go on top. |
gfx_cpu_damage(f, y, height) | Marks the rows you wrote so their bands are presented. Flushes first if you have not. |
gfx_cpu_bands(f, &redrawn, &total) | How many bands the last presented frame redrew, out of all of them. |
gfx_cpu_target(f) | Inline. The pixel pointer, or null on another backend. |
As with the GPU backends, call isolen_flush_ui first so the tree is recorded before you flush. See level 2.
#include "isolenui/app/app.h"
#include "isolenui/gfx/gfx_cpu.h"
// a meter painted straight into the cpu target over the tree
static void view(isolen_frame* f, void* user)
{
const float level = *static_cast<float*>(user);
ui::ctx* u = f->ui;
ui_box(u, ui::col().grow().pad(24.0f))
{
ui::text(u, "cpu level two", ui::body(u));
}
// the tree is recorded, then rasterised so these pixels land on top
isolen_flush_ui(f->app);
gfx_cpu_frame cf;
if (!gfx_cpu_frame_of(&f->native, &cf) || !gfx_cpu_flush(&f->native)) {
return;
}
const uint32_t h = 8u;
const uint32_t y0 = cf.height - h;
const uint32_t w = uint32_t(float(cf.width) * level);
for (uint32_t y = y0; y < cf.height; ++y) {
uint32_t* row = cf.pixels + size_t(y) * cf.stride;
for (uint32_t x = 0; x < w; ++x) {
// bgra8, read as one word it is 0xaarrggbb
row[x] = 0xff38c172u;
}
}
// the rows written, so their bands are presented
gfx_cpu_damage(&f->native, y0, h);
}
int main(int argc, char** argv)
{
static float level = 0.6f;
isolen_app_desc d = isolen_app_defaults();
d.title = "meter";
d.backend = gfx_backend_cpu;
d.view = view;
d.user = &level;
return isolen_run(&d, argc, argv);
}