zgui
Performance

Cost model

What each kind of change costs, which pipeline stages it reaches, and the measured figures.

A zgui frame does work for what changed, not for the whole document. This page lists what each kind of change costs: the pipeline stages it reaches, what the cost is proportional to, and what the benchmark suite measures it at. The stages themselves are described in the architecture overview.

Summary

What changedStages reachedProportional toBaseline
nothingnone—0 frames
a colour, shadow or border colourrestyle, paint, drawthe ink of the changed elements—
a class toggle or hoverrestyle, paint, drawthe same10.8 µs (click)
a text valuerestyle, text, layout, paint, drawthat paragraph's bytes, lines and glyphs291 µs (keystroke)
a width, padding or gaprestyle, layout, paint, drawthe subtree, up to the first ancestor whose size does not depend on it—
a row inserted or removedbox splice, layout, paint, drawthat row, plus the viewport it enters560 µs (recycle frame)
a scrollfragment offset, paint replay, pixel shiftthe band the movement uncovers44 µs (translation frame)
a window resizelayout of every box, paint of what movedthe whole document's layout, but not its shaping8.2 ms (gallery)
a scale-factor changeeverything, plus the caches keyed on device pixelsthe whole document—

How the numbers were measured

The figures come from the end-to-end scenarios in crates/zgui-bench, which Measurements describes. Unless a row says otherwise, a scenario runs headless, on a virtual clock, with a null renderer. The gallery document used by several scenarios has 1 851 boxes and 2 363 fragments.

  • Times are the baselines that the scenario bands are recorded against, not the result of one run. They depend on the machine. The most recent stored run had several gallery times outside their bands (details).
  • Counts are exact and read the same on any machine. They are the more useful half: the regressions these scenarios exist to catch are a stage doing the whole document's work for one element's change, and that shows up in a count before it shows up in a time.
  • A budget is what the design was meant to cost. It does not move when a measurement moves.

An idle window

SituationCost
a still document0 frames; one frame is a test failure
one turn of the parked event loop (wake, find nothing, park)about 0.07 µs
one turn with a CSS animation running, over the otherwise untouched gallery22 µs

A running CSS animation keeps the loop drawing at the display's refresh rate.

A class toggle, hover or colour change

Cost: proportional to the ink of the elements whose style changed.

Only the elements involved are restyled; for a hover, that is the element the pointer left and the one it entered. A colour-only change needs a repaint and nothing more, so the box tree, layout, fragment geometry and shaped text all stay valid. The damage is those elements' ink, and every other fragment replays its recorded paint.

InteractionMeasured
one hover crossing over a 1 000-row table at 120 Hzabout 190 µs (budget 500 µs); about 42 primitives emitted per frame (ceiling 200); 96 % of primitives considered are culled against the damage
one hover on the gallery1 element restyled, 11 of 2 363 fragments diffed, 0 rebuilt, 2 primitives emitted, 2 628 pixels damaged (0.16 % of the surface)
a click that toggles one class, on the gallery10.8 µs
one Tab press, moving focus by one stop, on the gallery381 µs
one property changed on one of 10 000 controls1 element restyled, 0 laid out, 6 fragments diffed, 1 primitive emitted, at every size from 1 250 to 10 000 controls
a class toggled on each control, versus on their common ancestorabout 71 ns per control, versus about 1 035 ns

A one-control update does no work proportional to the document, but it still walks it: it visits controls + 17 nodes, and that walk is the whole of the 71 ns per control. NodesVisited counts it.

A text change

Cost: one paragraph reshaped, one box laid out again and repainted.

ChangeCost
a text hole produces the same stringnothing beyond running the closure; the text node compares
a new stringone shaping pass, proportional to the paragraph's bytes, plus line breaking and glyph placement proportional to its output
a text colourno reshaping (why)
one keystroke in a gallery field (kitchen.keystroke)291 µs

Shaping dominates a text change, not the document mutation. Because shaping is proportional to bytes, a large replacement can dominate a frame even though only one paragraph changed. TextBytesShaped records the volume beside TextShaped.

A size change

Cost: layout of the box, its descendants, and its ancestors up to the first whose size does not depend on it.

A geometry change discards cached layout answers on the path to the root, and the layout pass runs over that dirty region only. The box tree is kept: relaying out a box and rebuilding it are different costs.

Inserting or removing a row

Cost: that row's boxes, spliced into the existing tree. Not the document.

MeasurementValue
one row shift in the scroll scenario8 boxes rebuilt, 29 nodes laid out, 404 primitives emitted
one recycle frame over a 10 000-row virtualised list560 µs (budget 1 500 µs)

The 8 boxes and 29 nodes are the row that arrived. The 404 primitives are the viewport.

Scrolling

Cost: the band of content the movement uncovers.

FrameBaselineCounts held
translation: content only moves44 µs (budget 1 000 µs)0 restyles, 0 relayouts, 0 hit-index rebuilds
recycle: rows enter or leave a virtualised list560 µs (budget 1 500 µs)—
one tick of the framework's smooth scroll over the gallery610 µs—

In a translation frame, moved fragments are offset rather than composed again, hit-index entries move with their content, and paint records replay at an offset. When one opaque, unobscured scrollport moved by whole device pixels, the renderer also moves the pixels it already composed and draws only the uncovered band (how). If that shift cannot be done safely, the frame falls back to ordinary damage.

How much a scroll frame costs depends on how many rows are mounted. One glide frame costs about nine tenths of repainting the same rows from their styles, so virtualisation is what keeps it small:

DocumentCost per boxBoxesPer frame
virtualised list, any row countabout 28 µs per mounted box39 mountedabout 1 ms
not virtualised, 10 000 rows287 ns70 007about 20 ms
not virtualised, 20 000 rows5 660 ns140 007792 ms

A wheel over a virtualised list costs between −1.7 and +2.5 ns per row of the underlying data, which is indistinguishable from zero across eight times the data.

Resizing the window

Cost: every box is laid out again. Text is not reshaped, and only what moved is repainted.

A resize changes the available width of every box, so layout runs once for each box (twice when a scrollbar appears or disappears). Text is not reshaped, because the shaping key does not include the width; paragraphs are only re-broken into lines. Fragments whose geometry did not change replay their recorded paint. When the renderer keeps its composed picture across the new surface size, as the wgpu renderer does, the damage is what layout moved plus the band a larger window exposes. A change of scale or opacity, or a first frame, still damages the whole surface.

ScenarioBaselineNotes
kitchen.resize, the gallery8.2 msabout 1.0 µs per box
thread.resize, 250 wrapped messages13.2 ms0 reshapes per step; re-breaks at most the paragraph count
shell.resize_step, an app shell2.0 ms0 truncated observation deliveries

A resize to the current size runs no frame. Size changes that arrive less than one display frame after the last resize frame are merged, and the frame runs at the merged deadline. Measured on a real desktop (docs/perf/resize.md):

75 Hz beforeafter240 Hz beforeafter
configures delivered per second400314403529
frames drawn per second40075.1402233
surface configures per second40075.1403234
frames drawing a superseded size0000
resize command to the frame that drew it, p502.3 ms6.4 ms2.8 ms3.0 ms

The added latency is at most one display frame. On a 75 Hz display, merging removes four fifths of the pipeline runs, swap-chain rebuilds and buffer commits.

A scale-factor change

Cost: a miss in every cache keyed on device pixels.

Moving a window to a display with a different scale factor discards every box's cached layout and misses both the shaped paragraphs and the rasterised glyphs, whose keys include the scale. On the gallery (docs/perf/scale.md), its 483 placed glyphs cost 218–230 rasterisations on each move to a new scale, and zero on the move back to 1.0, because those entries were still cached. Caches keyed on device pixels lists every store involved.

Startup

The first frame of the gallery has a headless baseline of 112 ms (measured at 102–111 ms; budget 250 ms). On screen with a real graphics device it is 216–247 ms; the difference is device creation, which the gated number excludes.

Startup includes font enumeration, style sheet parsing, the first cascade, the first layout with nothing cached, and the first encoding of every primitive.

An application shell

The app-shell scenario is a tool-like window: a header of icon buttons with tooltips, a page of component-library controls, and a dock holding a 5 000-line virtualised log in a resizable split.

InteractionBaselineCounts held
a tooltip crossing: one opens and the previous one closes1.25 ms (budget 4 ms)0 whole box-tree builds
one dock drag step of 5 px0.30 ms (budget 8.3 ms)≤ 8 restyles, 0 hit-index rebuilds, ≤ 2 observation passes, ≤ 1 000 primitives
one window resize step2.0 ms0 truncated observation deliveries

Vector drawings and canvases

What a pan, zoom or edit costs depends on the route each shape was drawn by.

ChangeCost
a still drawing scrolled or moved by whole pixelsits paint record replays at an offset; nothing is re-encoded or rasterised
a canvas view transform (pan or zoom)no shape is recognised again; series, quads and marks keep their payloads
a recolour through color or --zgui-filla repaint; geometry is reused
a pan of a path-glyph shapenothing is rasterised
a zoom of a CPU-layer drawingthe nearest cached scale is stretched, then the drawing is rasterised once the zoom settles
an edit of one canvas shape in a large tiled layeronly the tiles that shape touches are rasterised

Writing fast interfaces turns this into guidelines, and Caches lists what is kept.

Next

On this page