Measurements
Measure your own application with frame probes, counters and the latency trace, then the scenarios, gates and benches behind zgui's own numbers.
zgui ships instruments for finding out what your own frames do: frame probes, work counters and a latency trace. The same instruments drive the benchmark suite that holds the framework to the figures in the cost model. This page starts with your application and then documents the suite.
Measure your own application
Work through these steps in order. Each one is cheaper than the next.
Count frames. Install a frame probe and check whether frames are drawn at all. A still window must draw zero. A window that draws when nothing happened is a different bug from one whose frames are slow.
Read the counters for one slow interaction. They report work as numbers rather than durations, so the answer holds on any machine.
Set ZGUI_FULL_DAMAGE=1 and restart, if something looks wrong on screen. If the artefact
disappears, the bug is in damage tracking, not in drawing.
Record a latency trace with
ZGUI_LATENCY=/tmp/trace.jsonl and reproduce the problem. The trace shows when each stage started
and ended, including gaps nobody named.
Open the inspector with F12 in a program that includes the devtools, to see what an element computed to and why it has its size.
Count frames with a probe
A frame probe is called once at the end of every frame with the window as it stands. That is the only moment a frame's state can be read before the next frame replaces it.
use std::cell::Cell;
use std::rc::Rc;
use zgui::prelude::*;
use zgui::runtime::{FrameProbe, Window};
/// Counts frames and remembers how many rectangles the last one redrew.
#[derive(Default)]
struct Frames {
frames: Cell<u64>,
rects: Cell<usize>,
}
impl FrameProbe for Frames {
fn frame_ended(&self, window: &Window) {
self.frames.set(self.frames.get() + 1);
self.rects.set(window.damage().len());
}
}
fn main() -> Result<(), zgui::Error> {
app()
.with_probe(Rc::new(Frames::default()))
.run(|| view! { column() })
}frame_ended takes &self and returns nothing, so a probe cannot change the frame it measures; keep
its state in a Cell or a signal. An application has one probe, and installing another replaces it.
The devtools inspector is itself a frame probe, and redraws every frame while it is open.
Window method | Returns |
|---|---|
scene() | the display list the frame built |
damage() | the rectangles the frame redrew |
placements() | what every coordinate system resolves to |
layout() | the boxes, their results and their fragments |
scroll() | every scroll container's offset |
content() | the glyph tiles and decoded images the window draws from |
renderer() | the renderer |
scale() | device pixels per CSS pixel |
refresh_interval() | the length of one display frame |
last_budget_report() | what every budgeted cache held at the last budget step |
declined_frames() | offered frames refused for a reconfiguration not yet visible |
deferred_resizes() | size changes that did not get a frame of their own |
surface_configures() | times the renderer was pointed at a new surface size |
is_occluded() | whether the surface is entirely hidden |
Count work with counters
Counters record how much work a frame did: elements restyled, boxes rebuilt, glyphs rasterised. They
live in zgui-profile, which zgui uses but does not re-export. Add it as a dependency, or as a
dev-dependency if you only read counters in tests:
[dependencies]
zgui-profile = { version = "0.1", features = ["counters"] }Counters are process-wide and accumulate until counter::reset(). Take a snapshot before and after
an interaction and subtract:
use zgui_profile::{COUNTERS_ENABLED, Counter, counter};
assert!(COUNTERS_ENABLED, "this build has no counters compiled in");
let _guard = counter::exclusive(); // in tests: keep other tests from moving the counters
let before = counter::snapshot();
// … the interaction …
let moved = before.delta(&counter::snapshot());
println!("{moved:?}"); // only the non-zero counters, as snake_case fields
assert_eq!(moved.get(Counter::GlyphsRasterised), 0);COUNTERS_ENABLED is true in debug builds and wherever the counters feature is on. Because zgui
enables that feature, counters are on in every zgui application, release builds included, even
though zgui-profile's own documentation says they are compiled out of optimised builds. Each count
is a relaxed atomic add, which a pinned A/B test over 300 resize frames could not separate from
noise.
Which counter answers which question:
| Question | Counter | Healthy answer |
|---|---|---|
| Did one change restyle more than it should? | ElementsRestyled | the elements you changed |
| Is a stage walking the whole document? | NodesVisited | close to the number of dirty nodes |
| Was the box tree rebuilt? | BoxesRebuilt, BoxTreeBuilds | zero for a colour, class or hover; whole builds almost never |
| Did layout run? | LayoutsHeld against NodesRelaidOut | held, for a frame that moved no box |
| Did layout start from the root? | LayoutReachedRoot | rarely: a resize, a scale change, the first frame |
| Are intrinsic sizes measured again? | SizesHeld against SizesMeasured | mostly held once settled |
| Is text being reshaped? | TextShaped, TextBytesShaped, TextRebroken | shaping only for strings that changed |
| Are glyphs rasterised again? | GlyphsRasterised against GlyphsPlaced | zero on a repaint of unchanged text |
| Is paint replayed? | ChunksTranslated against ChunksReencoded | translated, for anything that only moved |
| Is culling working? | PrimitivesCulled against PrimitivesEmitted | most primitives culled on a small change |
| Are ancestors forcing offscreen targets? | GroupTargets | one per genuinely isolated subtree |
| Is the hit index rebuilt? | HitIndexRebuilds | zero while scrolling |
| Do size observers settle? | ObservationPasses, ObservationsTruncated | truncated stays zero |
| Which vector routes ran? | VectorRoute* | analytic, marks, path glyphs or layers for stable content |
| Is the event loop spinning? | Wakes | one per thing that asked for one |
Read paired counters together. A counter of avoided work, such as LayoutsHeld, reads zero both when
everything was reused and when nothing ran at all. The counter reference lists
every counter.
Time the stages with the latency trace
Counters say how much work happened; the latency trace says when. It records an instant at each stage boundary, so the gaps between stages, and the time an event waited for a frame, are visible even where nothing named what filled them.
ZGUI_LATENCY=/tmp/trace.jsonl cargo run --releaseThe file is newline-delimited JSON, one object per mark:
{"t":142900,"base_unix_ns":1785456583000000000,"stage":"b.why","note":"owed=1 spliced=1 noroot=false rebuild=false"}The winit backend writes the file each time its event loop parks. The native Wayland backend writes
it only when the loop finishes, so for a file that survives an interrupted run, set
ZGUI_PLATFORM=winit.
| Mark prefix | Stage |
|---|---|
loop.wake, evt.in, wait.in, wait.out | the event loop |
f.* | frame stages: f.begin, f.restyle, f.boxes, f.layout, f.fragments, f.observe, f.paint, f.end, and others |
b.why | why boxes were rebuilt: elements owed, elements spliced, and whether the whole tree was built |
p.* | paint: p.emit, p.upload, p.budget, p.draw |
r.* | the renderer: r.tables, r.vectors, r.plan, r.encoder, r.buffers, r.record |
pres.out | presentation |
r.record carries a note when the upload belt had to allocate chunks during the preceding
r.buffers, which explains an occasional spike in GPU buffer updates. docs/perf/endtoend.md in the
zgui repository lists the marks in the order one turn produces them. ZGUI_LATENCY_ELEMENTS=1 (or
latency::trace_elements(true)) adds a mark per restyled element; it is off by default because its
volume is the size of the document.
To read the trace from inside the process, for example in an inspector panel, call
latency::retain(n) to keep the last n marks in a ring, latency::recent() to read them, and
latency::retain(0) to stop. The first non-zero call fixes the ring's capacity.
Adding marks of your own costs one relaxed atomic load when nothing is recording. Build a note that allocates lazily so that cost holds:
use zgui_profile::latency;
latency::mark("f.fragments");
latency::note_with("f.restyled", || restyled.to_string());Scenarios and bands
The scenarios, gates and benches below live in the zgui repository; zgui-bench and xtask are not
published. Run them from a checkout.
A scenario drives one interaction over one document, headless, on a virtual clock, with a null renderer, in a process of its own. It settles the document before measuring, reports the median, and always records primitives emitted, culled and inserted into the bounds tree.
Every measurement has a band, and some also have a budget:
| Meaning | When violated | |
|---|---|---|
| time band | a recorded baseline plus a tolerance | fails cargo xtask perf |
| count band | a ceiling with no tolerance | fails cargo xtask perf |
| budget | what the design was meant to cost; it never moves with the measurement | reported as missed; the run still passes |
Times depend on the machine, so a time band's tolerance has to clear ordinary run-to-run spread. A
lost fast path usually costs several times over, so a wide band still catches it. Counts depend only
on the design, so a count band has no tolerance; widening it would admit the regression it exists to
catch. The bands are defined in crates/zgui-bench/src/scenario/band.rs:
| Tolerance | Value | Applies to |
|---|---|---|
INTERACTION_TOLERANCE | 40 % | microsecond interactions |
STARTUP_TOLERANCE | 25 % | millisecond measurements |
IDLE_TURN_TOLERANCE | 100 % | idle.turn only, which is mostly timer resolution; its baseline is rounded up to 1 µs |
cargo xtask perf runs every scenario in release and then:
- stores the run under
docs/perf/runs/<unix-seconds>.tsv, whatever the result; - regenerates
docs/performance.mdfrom it; - fails, naming every measurement outside its band rather than only the first.
Each time measurement reports p50, p95, p99, max and its sample count, and each scenario reports how
many of its frames were late (longer than 1.5 times the interval it was driven at). The tails gate
checks that both are present.
The seven scenarios
| Scenario | Document | Exercises |
|---|---|---|
idle | 833 rows of six elements (about 5 000 nodes); 600 turns at 60 Hz with nothing touched | the decision not to draw |
hover-storm | a 1 000-row table; 240 pointer crossings at 120 Hz | a two-element style change staying proportional to two |
scroll | a virtualised list of 10 000 rows; 600 ticks, a wheel notch every 40 | translation frames against recycle frames |
cold-start | the shipped gallery (s13, 1 851 boxes), measured once | everything, with no cache to hit yet |
kitchen-sink | the same gallery; 32 repeats per interaction and 240 untouched turns | resize, click, keystroke, Tab, smooth-scroll tick, an animating window |
thread-resize | a chat-like document of 250 wrapped messages | a text-heavy resize, and a paced drag of one size change per millisecond at 75 Hz |
app-shell | 12 tooltip triggers, 48 rows of component-library controls, a dock with a 5 000-line virtualised log | tooltips, a dock drag, a window resize |
Some scenario rules exist to keep the numbers honest:
idledoes not use the gallery, because the gallery has a running progress animation and is supposed to draw every refresh.hover-stormfails if no element was restyled, because a pointer aimed at empty space would pass every band.scrollclassifies a frame as a translation byboxes_rebuilt == 0and then asserts other counters (restyles, relayouts, hit-index rebuilds), so the classification and the claim never share a number.kitchen-sinkruns its interactions in a fixed order: the keystroke first (its field is found by tabbing from the top), the resize last (every step leaves the window a new width).
All bands
| Measurement | Unit | Band | Limit | Budget |
|---|---|---|---|---|
idle.frames | frames | ceiling | 0 | 0 |
idle.turn | µs | 1.0 +100 % | 2.0 | — |
hover.crossing | µs | 190 +40 % | 266 | 500 |
hover.primitives_emitted | prims | ceiling | 200 | 200 |
scroll.translation | µs | 44 +40 % | 61.6 | 1 000 |
scroll.recycle | µs | 560 +40 % | 784 | 1 500 |
scroll.translation.restyles | elements | ceiling | 0 | 0 |
scroll.translation.relayouts | nodes | ceiling | 0 | 0 |
scroll.translation.hit_rebuilds | rebuilds | ceiling | 0 | 0 |
cold.first_frame | ms | 112 +25 % | 140 | 250 |
kitchen.resize | ms | 8.2 +25 % | 10.25 | — |
kitchen.click | µs | 10.8 +40 % | 15.12 | — |
kitchen.keystroke | µs | 291 +40 % | 407.4 | — |
kitchen.untouched_turn | µs | 22 +40 % | 30.8 | — |
kitchen.glide_tick | µs | 610 +40 % | 854 | — |
kitchen.tab_traversal | µs | 381 +40 % | 533.4 | — |
thread.resize | ms | 13.2 +25 % | 16.5 | 8 |
thread.resize_p95 | ms | 15 +25 % | 18.75 | — |
thread.rebreaks_per_step | paragraphs | ceiling | the paragraph count | — |
thread.reshapes_per_step | paragraphs | ceiling | 0 | 0 |
thread.relayouts_per_step | nodes | ceiling | twice the box count | — |
thread.hit_rebuilds_per_step | rebuilds | ceiling | 2 | — |
thread.drag.layouts | layouts | ceiling | elapsed time over the refresh interval | — |
shell.tooltip_crossing | µs | 1 250 +40 % | 1 750 | 4 000 |
shell.tooltip_tree_builds | builds | ceiling | 0 | 0 |
shell.tooltip_hit_rebuilds | rebuilds | ceiling | 5 | — |
shell.drag_step | µs | 300 +40 % | 420 | 8 333 |
shell.drag_restyled | elements | ceiling | 8 | — |
shell.drag_hit_rebuilds | rebuilds | ceiling | 0 | — |
shell.drag_observation_passes | passes | ceiling | 2 | — |
shell.drag_primitives_emitted | prims | ceiling | 1 000 | — |
shell.resize_step | µs | 2 000 +40 % | 2 800 | — |
shell.resize_truncated | deliveries | ceiling | 0 | 0 |
reshape.paragraphs_forgotten (every scenario) | paragraphs | ceiling | 0 | — |
reshape.boxes_marked_all_dirty (every scenario) | boxes | ceiling | 0 | — |
The two reshape.* counts catch an interaction that throws away every shaped paragraph, or marks
every box dirty, to service one element. Only a scale change or a shaping cache over its budget
should do that, and no scenario does either.
The latest stored run
docs/performance.md holds the run that last regenerated it. At the time of writing that is a run
from 2026-08-13 (129 runs stored), which predates the thread-resize and app-shell scenarios and
the tightening of the scroll.recycle band from 1 030 µs to 560 µs. Every count was inside its
ceiling and every budget was met, but several gallery times were outside their bands:
| Measurement | Value | Band limit | Result |
|---|---|---|---|
idle.turn | 0.07 µs | 2.0 | ok |
hover.crossing | 195.5 µs | 266 | ok |
hover.primitives_emitted | 41.6 | 200 | ok |
scroll.translation | 48.0 µs | 61.6 | ok |
cold.first_frame | 182.4 ms | 140 | over |
kitchen.resize | 8.63 ms | 10.25 | ok |
kitchen.click | 27.8 µs | 15.12 | over |
kitchen.keystroke | 591.7 µs | 407.4 | over |
kitchen.untouched_turn | 57.5 µs | 30.8 | over |
kitchen.glide_tick | 857.4 µs | 854 | over |
kitchen.tab_traversal | 381.0 µs | 533.4 | ok |
Run cargo xtask perf for a current answer on your own machine.
Standing gates
Each gate is a step of cargo xtask ci and a subcommand of its own.
| Gate | What it checks |
|---|---|
skips | every counter of avoided work names the counter of work done and has a non-vacuity test |
budget | a cache over its soft limit comes back under it without thrashing, and no replay uses an evicted raster (details) |
cadence | an animation and the overscroll spring each get one frame per refresh at 60, 75 and 240 Hz |
wall-clock | the absolute-duration ceilings in zgui, zgui-layout and zgui-platform-wayland, in release |
resize | the resize slope (µs per box over four document sizes) as a ratio of a whole-document change in the same run |
workloads | the reference workloads against their same-run ratios |
hits, a11y-geom | hit testing and accessibility rectangles in a live window match a window that recomputed everything |
verify | the display list and geometry of a live window match one rebuilt from nothing, at every document size |
perf, tails | the scenarios against their bands, and that every published time carries its distribution |
growth | every live gauge after 1 000 scroll ticks equals its value after 10 |
budget and cadence run tests that live beside the code. The gate names them, so a test that was
emptied or renamed fails the gate instead of disappearing silently.
cargo xtask ci --hosted, which the hosted CI runs, skips perf and tails (their bands are times
taken on the reference machine), and also resize, workloads, verify and growth. Only a run on
the reference machine checks them.
cargo xtask perf pacing [size] [seconds] measures a scripted scroll's frame intervals on the real
display. It is run by hand and is never a CI step, because it measures the machine's compositor.
Wall-clock ceilings
The wall-clock gate runs a suite in release, behind the wall-clock feature, that asserts absolute
durations against generous ceilings. It does not look for a machine twice as slow; it looks for a
stage that has gone back to doing the whole document's work.
| Interaction | Ceiling | Measured on the development machine |
|---|---|---|
| a click | 3 ms | 0.058 ms, over a 136-box document with 28 lines of text |
| a hover on and off | 3 ms | 0.066 ms |
| a resize step | 8 ms | 0.78 ms |
The ceilings are about fifty times the measurement, because the regression they were written for, a click rebuilding the whole box tree, cost 36 ms. Counts are asserted beside the times:
- a click and a hover rasterise zero glyphs;
- a resize rasterises fewer than a tenth of the document's glyphs over 32 steps;
- a click runs exactly three frames (move, press, release);
- a resize to the current size runs no frame, and a settled application runs none at all.
Reference workloads
A reference workload is a document that a claim is measured against. Every criterion is a slope or a same-run ratio, never an absolute time. Both halves are measured in the same process minutes apart, so a faster machine divides both by the same factor.
| Workload | Document | Varied | Gate |
|---|---|---|---|
| gallery script | the shipped gallery, 42 steps | four document sizes | verify |
static-slope | 10 000 control elements | 1 250 → 10 000 controls | workloads |
list-slope | a virtualised list of 100 000 rows | 12 500 → 100 000 rows; scrollport 200 → 1 600 px | workloads |
resize-slope | four documents, 135 → 1 031 boxes | document size | resize |
unvirtualised-probe | the same rows with every one mounted | 2 500 → 20 000 rows | none |
glide-split | the same rows in sections | 1 250 → 10 000 rows | none |
| Criterion | Ratio of | Allowed | Measured |
|---|---|---|---|
STATIC-locality | a one-control update ÷ the same property changed on every control | ≤ 0.09 | 0.0679–0.0702 |
STATIC-restyle-locality | elements restyled per control | ≤ 0.001 | 0.0000 |
STATIC-visit-locality | nodes visited per control | ≤ 1.10 | 1.0000 |
LIST-virtualisation-wheel | a wheel over 100 000 rows ÷ over 12 500 | ≤ 1.05 | 0.9991–1.0123 |
LIST-virtualisation-touchpad | the same, touchpad | ≤ 1.05 | 0.9970–1.0042 |
LIST-damage-wheel | share of the surface one glide frame damaged | ≤ 0.97 | 0.9460 |
LIST-damage-touchpad | the same, during a held gesture | ≤ 0.55 | 0.4830 |
LIST-full-frames | scroll frames that damaged the whole surface | ≤ 0 | 0 |
LIST-rebuilds-wheel | fragments rebuilt per glide frame | ≤ 12 | 7.52 |
LIST-rebuilds-touchpad | the same, during a held gesture | ≤ 12 | 7.06 |
LIST-glide | one glide frame ÷ a full repaint of the same rows | 0.92 ± 12 % | 0.9037–0.9193 |
RESIZE | a resize ÷ a whole-document content change | 0.865 ± 10 % | 0.8582–0.8750 |
A ceiling is used where the ideal is zero or the number should only fall, because a two-sided band
would fail an engine that got better. A band is used where the number is a proportion between two
real pieces of work. A workload whose measurement stops working reports Broken, which fails: a
missing number is not a pass.
unvirtualised-probe and glide-split are deliberately not gates. unvirtualised-probe mounts
twenty thousand rows, and gating on it would let a scrolling change justify itself on a document no
application ships. The workloads gate asserts by name that neither is in its list. Their results
are in the cost model.
Diagnostic benches
These print numbers and gate nothing. Each is cargo run --release -p zgui-bench followed by the
arguments shown.
| Arguments | Measures |
|---|---|
--bin zgui-bench -- vector <scenario|all> [variant] | vector drawing cost per route, with the vector counters per stretch |
--bin zgui-bench -- passes s13 1 | the vector pass plan across a scroll |
--bin label-churn [count] | one frame relabelling 30 axis labels: the fixed cost of short paragraphs |
--bin unvirtualised-probe | glide cost per box with every row mounted (about ten minutes) |
--bin glide-split | how the scroll-offset walk divides its cost (about forty seconds) |
cargo run --release -p zgui-text-parley --example label_shaping [system] times one short label
through the real key, shape and break path.
The vector scenarios and their variants:
| Scenario | Variants |
|---|---|
scatter-pan | mask-512, mask-2k, markers-200, 10k, 100k, waves, series-100k, series-1m, waves-view, triangles-10k, series-path-100k, line-5m, series-zoom |
icons-scroll | icons, gallery |
svg-static | grid, huge |
map-pan | map |
Each variant runs in its own process and prints VECTOR (paint and render times per stretch),
VCOUNT (route, layer, series and encoding counters) and VLIVE (atlas, mask-tile and layer-byte
gauges at the start and end). Renderer-specific counters (vector_backend_built, vello_renders,
the encode counts) move only with ZGUI_BENCH_GPU=1. ZGUI_BENCH_FRAMES=1 prints per-frame detail.
Run the benchmarks
cargo xtask ci # every gate: the whole definition of done
cargo xtask perf # the seven scenarios, the bands, docs/performance.md
cargo xtask skips # every counter of avoided work names its pair
cargo xtask budget # caches come back under their soft limits
cargo xtask cadence # one frame per refresh at 60, 75 and 240 Hz
cargo xtask wall-clock # the absolute-duration ceilings, in release
cargo xtask workloads # the reference workloads against their ratios
cargo xtask resize # the resize slope against a same-run baseline
cargo xtask verify # a live window's display list against a rebuild's
cargo xtask growth # live gauges stay flat over a long scrollThe harness underneath:
# Every scenario, stored and compared. This is what `cargo xtask perf` runs.
cargo run --release -p zgui-bench --bin zgui-bench -- scenarios
# One scenario, printed, with no verdict.
cargo run --release -p zgui-bench --bin zgui-bench -- scenario app-shell
# One phase at one gallery size, with a latency trace.
ZGUI_LATENCY=/tmp/trace.jsonl \
cargo run --release -p zgui-bench --bin zgui-bench -- click s13 24
# The vector scenarios on this machine's GPU.
ZGUI_BENCH_GPU=1 cargo run --release -p zgui-bench --bin zgui-bench -- vector allGallery sizes are s0, s1, s2, s4, s8, s13 (the shipped gallery) and s26. all runs
every size, smallest first, and stops at the first failure. The reference workloads are binaries of
their own: --bin static-slope, --bin list-slope, --bin resize-slope.
Counter reference
crates/zgui-profile/src/counter/table.rs declares 132 counters. Each is a Counter variant
(ElementsRestyled) and a field of the Counters snapshot (elements_restyled).
Groups
| Group | Meaning | Consequence |
|---|---|---|
BackendNeutral | independent of what draws the result | safe to assert under a stub renderer |
RendererSpecific | incremented by the GPU renderer | reads zero under a renderer that submits nothing |
Skip { done } | counts work not done, and names the counter of the work done instead | never assert on it alone |
Live | a gauge, set each frame to how many of something exist now | read early and late in a run; growth means a leak |
The six skip counters and their pairs are LayoutsHeld (NodesRelaidOut), SizesHeld
(SizesMeasured), PlaceWritesWithoutReemit (PlaceWritesWithReemit), ChunksTranslated
(ChunksReencoded), PrimitivesCulled (PrimitivesEmitted) and SpritesResolvedAtPush
(SpritesFixedUp).
Counters by area
| Area | Counters |
|---|---|
| style | ElementsRestyled, ElementsRecascaded, ElementsTraversed, SelectorMatches, CustomSubtreesSkipped, CustomMapsRefreshed, NodesVisited, DirtyWalkSteps |
| box tree and layout | BoxesRebuilt, BoxTreeBuilds, BoxesMarkedAllDirty, NodesRelaidOut, NodesChanged, LayoutReachedRoot, LayoutsHeld, SizesHeld, SizesMeasured, GuttersExamined, LayoutBatchesDistributed, ObservationPasses, ObservationsTruncated |
| text | TextShaped, TextBytesShaped, TextRebroken, ParagraphsForgotten, ParagraphsEvicted, BoxesReshaped |
| fragments and hit testing | FragmentsDiffed, FragmentsRebuilt, BoxesShifted, HitEntriesUpdated, HitEntriesMovedInPlace, HitEntriesReinserted, HitIndexRebuilds, HitRetests, PointerMovesCoalesced |
| accessibility | A11yProjected, A11yRemeasured |
| animation | TierBTransitions, TierCPlacements, PlaceWritesWithoutReemit, PlaceWritesWithReemit, OrderBandEscapes |
| paint | Repaints, StylesLowered, StylesLoweredFromCache, GroupTargets, ChunksReencoded, ChunksTranslated, ChunksIncomplete, ChunksRetainedUnvisited, ChunksEvicted, FragmentsRetired, PrimitivesEmitted, PrimitivesCulled, BoundsTreeInserts, SpritesFixedUp, SpritesResolvedAtPush, PaintsReanchored |
| glyphs and images | GlyphsPlaced, GlyphsRasterised, RebuiltAfterEviction, AtlasTilesEvicted, ImageInsertFailed, EncodedImageBytes, RecordTilesRetained, RecordTilesReleased |
| vector routing | VectorRouteAnalytic, VectorRouteMarks, VectorRoutePathGlyphs, VectorRouteMask, VectorRouteLayer, VectorRouteGeneral, VectorTierChanges, VectorReplaysMoved, VelloPasses, VectorClipLayers, VectorFramesDropped |
| marks and series | MarksUnionBins, MarksPayloadBytes, MarksUncached, SeriesPayloadsBuilt, SeriesBuildsAsync, SeriesDrawsProvisional, SeriesChunksDrawn, SeriesChunksCulled |
| masks and path glyphs | VectorMaskMisses, VectorMaskBudgetOverflow, PathGlyphTilesRasterised |
| CPU layers | VectorLayersRasterised, VectorLayerRasterUs, VectorLayerBytesUploaded, VectorLayersProvisional, VectorLayersDeferred, VectorLayersDemoted, VectorLayersEvicted, VectorLayerFallbacks, VectorLayerTilesRasterised, VectorLayerTilesDeferred, VectorLayerTilesReused |
| general vector rasteriser | VectorBackendBuilt, VelloRenders, VectorEncodeHits, VectorEncodeMisses |
| renderer and uploads | DrawCalls, DamagePx, BytesUploaded, ChunkBytesUploaded, AtlasTextureWrites, AtlasUploadBatches, SideTableSlotsPrepared, UploadChunksAllocated, StagingWarmBytes, StagingOneShotBytes |
| event loop | Wakes, TimersFired, FramesDrawn |
| live gauges | ClipEntriesLive, ClipSlotsReach, PaintEntriesLive, PaintSlotsReach, SpatialNodesLive, FragmentsLive, PaintChunkBytes, ChunksResident, BoxesLive, AtlasEntriesLive, GlyphEntriesLive, ScratchLayers, ScratchBytes, VectorMaskTilesLive, VectorLayerBytesLive |
Counters that are easy to misread
| Counter | Meaning |
|---|---|
NodesVisited | nodes a traversal looked at, dirty or not. The only counter that notices a walk touching thousands of clean nodes to service one. |
BoxTreeBuilds | whole-document box-tree builds. One on a frame that changed one region means every box got a new identity. |
ObservationsTruncated | size or position deliveries still changing when the pass budget ran out; each costs an extra frame. |
TextBytesShaped | bytes that reached real shaping. Read it beside TextShaped. |
VectorLayerRasterUs | microseconds spent rasterising CPU layers, not a count. |
VectorFramesDropped | frames whose vector content had nowhere to go. Must stay zero. |
UploadChunksAllocated | staging chunks that had to grow. Recurring non-zero values mean GPU backlog or bursts. |
Test a counter of avoided work
A counter of avoided work reads zero when the stage is perfect, when the stage was deleted, and when
nobody wired the counter up. An assertion such as skipped <= n on it alone always passes.
assert_non_vacuous makes such a counter meaningful. It takes a scenario that must move the skip
counter, and a scenario where skipping would be wrong, which must leave the skip counter unchanged
and move the counter of work done:
use zgui_profile::Counter;
use zgui_profile::counter::non_vacuity::{Scenario, assert_non_vacuous};
assert_non_vacuous(
Counter::ChunksTranslated,
Scenario::new("scrolling a document already painted once", scroll_a_painted_document),
Scenario::new("the first paint of a fresh document", open_a_fresh_document),
);cargo xtask skips fails for any skip counter that has no such call in the workspace's tests.
Environment variables
| Variable | Effect |
|---|---|
ZGUI_LATENCY=<path> | write the latency trace to <path> |
ZGUI_LATENCY_ELEMENTS=1 | also write a latency mark per restyled element |
ZGUI_FULL_DAMAGE=1 | start every frame with the whole surface damaged |
ZGUI_INVARIANTS=1 | check that element, box and fragment levels agree, plus replay ownership and spatial dependencies; opt-in because it costs a lookup per distinct raster per replayed fragment |
ZGUI_STYLE_THREADS=<n> | width of the cascade worker pool; 0 or 1 for none (overrides the builder) |
ZGUI_LAYOUT_THREADS=<n> | width of the layout worker pool, at most 8; 0 or 1 for none |
ZGUI_LAYOUT_BATCHES=0 | keep layout batches off the pool |
ZGUI_PLATFORM=winit|wayland | choose the desktop backend on Linux |
ZGUI_PRESENT_PACING=notify | also request pre-present notification on the winit backend, to compare callback pacing |
ZGUI_BENCH_GPU=1 | draw the bench harness through this machine's GPU offscreen instead of the null renderer |
ZGUI_BENCH_FRAMES=1 | print per-frame counts in the thread-resize and vector benches |
ZGUI_CADENCE_OUT=<path> | where the cadence probes write their report |
ZGUI_CALIBRATE=1 | run the CPU-layer cost calibration tests in zgui-paint (calibrate_the_cost_model, calibrate_the_tile_cost_model) |