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 changed | Stages reached | Proportional to | Baseline |
|---|---|---|---|
| nothing | none | — | 0 frames |
| a colour, shadow or border colour | restyle, paint, draw | the ink of the changed elements | — |
| a class toggle or hover | restyle, paint, draw | the same | 10.8 µs (click) |
| a text value | restyle, text, layout, paint, draw | that paragraph's bytes, lines and glyphs | 291 µs (keystroke) |
| a width, padding or gap | restyle, layout, paint, draw | the subtree, up to the first ancestor whose size does not depend on it | — |
| a row inserted or removed | box splice, layout, paint, draw | that row, plus the viewport it enters | 560 µs (recycle frame) |
| a scroll | fragment offset, paint replay, pixel shift | the band the movement uncovers | 44 µs (translation frame) |
| a window resize | layout of every box, paint of what moved | the whole document's layout, but not its shaping | 8.2 ms (gallery) |
| a scale-factor change | everything, plus the caches keyed on device pixels | the 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
| Situation | Cost |
|---|---|
| a still document | 0 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 gallery | 22 µ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.
| Interaction | Measured |
|---|---|
| one hover crossing over a 1 000-row table at 120 Hz | about 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 gallery | 1 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 gallery | 10.8 µs |
| one Tab press, moving focus by one stop, on the gallery | 381 µs |
| one property changed on one of 10 000 controls | 1 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 ancestor | about 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.
| Change | Cost |
|---|---|
| a text hole produces the same string | nothing beyond running the closure; the text node compares |
| a new string | one shaping pass, proportional to the paragraph's bytes, plus line breaking and glyph placement proportional to its output |
| a text colour | no 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.
| Measurement | Value |
|---|---|
| one row shift in the scroll scenario | 8 boxes rebuilt, 29 nodes laid out, 404 primitives emitted |
| one recycle frame over a 10 000-row virtualised list | 560 µ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.
| Frame | Baseline | Counts held |
|---|---|---|
| translation: content only moves | 44 µs (budget 1 000 µs) | 0 restyles, 0 relayouts, 0 hit-index rebuilds |
| recycle: rows enter or leave a virtualised list | 560 µs (budget 1 500 µs) | — |
| one tick of the framework's smooth scroll over the gallery | 610 µ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:
| Document | Cost per box | Boxes | Per frame |
|---|---|---|---|
| virtualised list, any row count | about 28 µs per mounted box | 39 mounted | about 1 ms |
| not virtualised, 10 000 rows | 287 ns | 70 007 | about 20 ms |
| not virtualised, 20 000 rows | 5 660 ns | 140 007 | 792 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.
| Scenario | Baseline | Notes |
|---|---|---|
kitchen.resize, the gallery | 8.2 ms | about 1.0 µs per box |
thread.resize, 250 wrapped messages | 13.2 ms | 0 reshapes per step; re-breaks at most the paragraph count |
shell.resize_step, an app shell | 2.0 ms | 0 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 before | after | 240 Hz before | after | |
|---|---|---|---|---|
| configures delivered per second | 400 | 314 | 403 | 529 |
| frames drawn per second | 400 | 75.1 | 402 | 233 |
| surface configures per second | 400 | 75.1 | 403 | 234 |
| frames drawing a superseded size | 0 | 0 | 0 | 0 |
| resize command to the frame that drew it, p50 | 2.3 ms | 6.4 ms | 2.8 ms | 3.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.
| Interaction | Baseline | Counts held |
|---|---|---|
| a tooltip crossing: one opens and the previous one closes | 1.25 ms (budget 4 ms) | 0 whole box-tree builds |
| one dock drag step of 5 px | 0.30 ms (budget 8.3 ms) | ≤ 8 restyles, 0 hit-index rebuilds, ≤ 2 observation passes, ≤ 1 000 primitives |
| one window resize step | 2.0 ms | 0 truncated observation deliveries |
Vector drawings and canvases
What a pan, zoom or edit costs depends on the route each shape was drawn by.
| Change | Cost |
|---|---|
| a still drawing scrolled or moved by whole pixels | its 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-fill | a repaint; geometry is reused |
| a pan of a path-glyph shape | nothing is rasterised |
| a zoom of a CPU-layer drawing | the nearest cached scale is stretched, then the drawing is rasterised once the zoom settles |
| an edit of one canvas shape in a large tiled layer | only the tiles that shape touches are rasterised |
Writing fast interfaces turns this into guidelines, and Caches lists what is kept.