zgui
Performance

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 methodReturns
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:

QuestionCounterHealthy answer
Did one change restyle more than it should?ElementsRestyledthe elements you changed
Is a stage walking the whole document?NodesVisitedclose to the number of dirty nodes
Was the box tree rebuilt?BoxesRebuilt, BoxTreeBuildszero for a colour, class or hover; whole builds almost never
Did layout run?LayoutsHeld against NodesRelaidOutheld, for a frame that moved no box
Did layout start from the root?LayoutReachedRootrarely: a resize, a scale change, the first frame
Are intrinsic sizes measured again?SizesHeld against SizesMeasuredmostly held once settled
Is text being reshaped?TextShaped, TextBytesShaped, TextRebrokenshaping only for strings that changed
Are glyphs rasterised again?GlyphsRasterised against GlyphsPlacedzero on a repaint of unchanged text
Is paint replayed?ChunksTranslated against ChunksReencodedtranslated, for anything that only moved
Is culling working?PrimitivesCulled against PrimitivesEmittedmost primitives culled on a small change
Are ancestors forcing offscreen targets?GroupTargetsone per genuinely isolated subtree
Is the hit index rebuilt?HitIndexRebuildszero while scrolling
Do size observers settle?ObservationPasses, ObservationsTruncatedtruncated stays zero
Which vector routes ran?VectorRoute*analytic, marks, path glyphs or layers for stable content
Is the event loop spinning?Wakesone 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 --release

The 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 prefixStage
loop.wake, evt.in, wait.in, wait.outthe event loop
f.*frame stages: f.begin, f.restyle, f.boxes, f.layout, f.fragments, f.observe, f.paint, f.end, and others
b.whywhy 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.outpresentation

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:

MeaningWhen violated
time banda recorded baseline plus a tolerancefails cargo xtask perf
count banda ceiling with no tolerancefails cargo xtask perf
budgetwhat the design was meant to cost; it never moves with the measurementreported 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:

ToleranceValueApplies to
INTERACTION_TOLERANCE40 %microsecond interactions
STARTUP_TOLERANCE25 %millisecond measurements
IDLE_TURN_TOLERANCE100 %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:

  1. stores the run under docs/perf/runs/<unix-seconds>.tsv, whatever the result;
  2. regenerates docs/performance.md from it;
  3. 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

ScenarioDocumentExercises
idle833 rows of six elements (about 5 000 nodes); 600 turns at 60 Hz with nothing touchedthe decision not to draw
hover-storma 1 000-row table; 240 pointer crossings at 120 Hza two-element style change staying proportional to two
scrolla virtualised list of 10 000 rows; 600 ticks, a wheel notch every 40translation frames against recycle frames
cold-startthe shipped gallery (s13, 1 851 boxes), measured onceeverything, with no cache to hit yet
kitchen-sinkthe same gallery; 32 repeats per interaction and 240 untouched turnsresize, click, keystroke, Tab, smooth-scroll tick, an animating window
thread-resizea chat-like document of 250 wrapped messagesa text-heavy resize, and a paced drag of one size change per millisecond at 75 Hz
app-shell12 tooltip triggers, 48 rows of component-library controls, a dock with a 5 000-line virtualised logtooltips, a dock drag, a window resize

Some scenario rules exist to keep the numbers honest:

  • idle does not use the gallery, because the gallery has a running progress animation and is supposed to draw every refresh.
  • hover-storm fails if no element was restyled, because a pointer aimed at empty space would pass every band.
  • scroll classifies a frame as a translation by boxes_rebuilt == 0 and then asserts other counters (restyles, relayouts, hit-index rebuilds), so the classification and the claim never share a number.
  • kitchen-sink runs 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

MeasurementUnitBandLimitBudget
idle.framesframesceiling00
idle.turnµs1.0 +100 %2.0—
hover.crossingµs190 +40 %266500
hover.primitives_emittedprimsceiling200200
scroll.translationµs44 +40 %61.61 000
scroll.recycleµs560 +40 %7841 500
scroll.translation.restyleselementsceiling00
scroll.translation.relayoutsnodesceiling00
scroll.translation.hit_rebuildsrebuildsceiling00
cold.first_framems112 +25 %140250
kitchen.resizems8.2 +25 %10.25—
kitchen.clickµs10.8 +40 %15.12—
kitchen.keystrokeµs291 +40 %407.4—
kitchen.untouched_turnµs22 +40 %30.8—
kitchen.glide_tickµs610 +40 %854—
kitchen.tab_traversalµs381 +40 %533.4—
thread.resizems13.2 +25 %16.58
thread.resize_p95ms15 +25 %18.75—
thread.rebreaks_per_stepparagraphsceilingthe paragraph count—
thread.reshapes_per_stepparagraphsceiling00
thread.relayouts_per_stepnodesceilingtwice the box count—
thread.hit_rebuilds_per_steprebuildsceiling2—
thread.drag.layoutslayoutsceilingelapsed time over the refresh interval—
shell.tooltip_crossingµs1 250 +40 %1 7504 000
shell.tooltip_tree_buildsbuildsceiling00
shell.tooltip_hit_rebuildsrebuildsceiling5—
shell.drag_stepµs300 +40 %4208 333
shell.drag_restyledelementsceiling8—
shell.drag_hit_rebuildsrebuildsceiling0—
shell.drag_observation_passespassesceiling2—
shell.drag_primitives_emittedprimsceiling1 000—
shell.resize_stepµs2 000 +40 %2 800—
shell.resize_truncateddeliveriesceiling00
reshape.paragraphs_forgotten (every scenario)paragraphsceiling0—
reshape.boxes_marked_all_dirty (every scenario)boxesceiling0—

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:

MeasurementValueBand limitResult
idle.turn0.07 µs2.0ok
hover.crossing195.5 µs266ok
hover.primitives_emitted41.6200ok
scroll.translation48.0 µs61.6ok
cold.first_frame182.4 ms140over
kitchen.resize8.63 ms10.25ok
kitchen.click27.8 µs15.12over
kitchen.keystroke591.7 µs407.4over
kitchen.untouched_turn57.5 µs30.8over
kitchen.glide_tick857.4 µs854over
kitchen.tab_traversal381.0 µs533.4ok

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.

GateWhat it checks
skipsevery counter of avoided work names the counter of work done and has a non-vacuity test
budgeta cache over its soft limit comes back under it without thrashing, and no replay uses an evicted raster (details)
cadencean animation and the overscroll spring each get one frame per refresh at 60, 75 and 240 Hz
wall-clockthe absolute-duration ceilings in zgui, zgui-layout and zgui-platform-wayland, in release
resizethe resize slope (µs per box over four document sizes) as a ratio of a whole-document change in the same run
workloadsthe reference workloads against their same-run ratios
hits, a11y-geomhit testing and accessibility rectangles in a live window match a window that recomputed everything
verifythe display list and geometry of a live window match one rebuilt from nothing, at every document size
perf, tailsthe scenarios against their bands, and that every published time carries its distribution
growthevery 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.

InteractionCeilingMeasured on the development machine
a click3 ms0.058 ms, over a 136-box document with 28 lines of text
a hover on and off3 ms0.066 ms
a resize step8 ms0.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.

WorkloadDocumentVariedGate
gallery scriptthe shipped gallery, 42 stepsfour document sizesverify
static-slope10 000 control elements1 250 → 10 000 controlsworkloads
list-slopea virtualised list of 100 000 rows12 500 → 100 000 rows; scrollport 200 → 1 600 pxworkloads
resize-slopefour documents, 135 → 1 031 boxesdocument sizeresize
unvirtualised-probethe same rows with every one mounted2 500 → 20 000 rowsnone
glide-splitthe same rows in sections1 250 → 10 000 rowsnone
CriterionRatio ofAllowedMeasured
STATIC-localitya one-control update ÷ the same property changed on every control≤ 0.090.0679–0.0702
STATIC-restyle-localityelements restyled per control≤ 0.0010.0000
STATIC-visit-localitynodes visited per control≤ 1.101.0000
LIST-virtualisation-wheela wheel over 100 000 rows ÷ over 12 500≤ 1.050.9991–1.0123
LIST-virtualisation-touchpadthe same, touchpad≤ 1.050.9970–1.0042
LIST-damage-wheelshare of the surface one glide frame damaged≤ 0.970.9460
LIST-damage-touchpadthe same, during a held gesture≤ 0.550.4830
LIST-full-framesscroll frames that damaged the whole surface≤ 00
LIST-rebuilds-wheelfragments rebuilt per glide frame≤ 127.52
LIST-rebuilds-touchpadthe same, during a held gesture≤ 127.06
LIST-glideone glide frame ÷ a full repaint of the same rows0.92 ± 12 %0.9037–0.9193
RESIZEa resize ÷ a whole-document content change0.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.

ArgumentsMeasures
--bin zgui-bench -- vector <scenario|all> [variant]vector drawing cost per route, with the vector counters per stretch
--bin zgui-bench -- passes s13 1the vector pass plan across a scroll
--bin label-churn [count]one frame relabelling 30 axis labels: the fixed cost of short paragraphs
--bin unvirtualised-probeglide cost per box with every row mounted (about ten minutes)
--bin glide-splithow 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:

ScenarioVariants
scatter-panmask-512, mask-2k, markers-200, 10k, 100k, waves, series-100k, series-1m, waves-view, triangles-10k, series-path-100k, line-5m, series-zoom
icons-scrollicons, gallery
svg-staticgrid, huge
map-panmap

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 scroll

The 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 all

Gallery 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

GroupMeaningConsequence
BackendNeutralindependent of what draws the resultsafe to assert under a stub renderer
RendererSpecificincremented by the GPU rendererreads zero under a renderer that submits nothing
Skip { done }counts work not done, and names the counter of the work done insteadnever assert on it alone
Livea gauge, set each frame to how many of something exist nowread 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

AreaCounters
styleElementsRestyled, ElementsRecascaded, ElementsTraversed, SelectorMatches, CustomSubtreesSkipped, CustomMapsRefreshed, NodesVisited, DirtyWalkSteps
box tree and layoutBoxesRebuilt, BoxTreeBuilds, BoxesMarkedAllDirty, NodesRelaidOut, NodesChanged, LayoutReachedRoot, LayoutsHeld, SizesHeld, SizesMeasured, GuttersExamined, LayoutBatchesDistributed, ObservationPasses, ObservationsTruncated
textTextShaped, TextBytesShaped, TextRebroken, ParagraphsForgotten, ParagraphsEvicted, BoxesReshaped
fragments and hit testingFragmentsDiffed, FragmentsRebuilt, BoxesShifted, HitEntriesUpdated, HitEntriesMovedInPlace, HitEntriesReinserted, HitIndexRebuilds, HitRetests, PointerMovesCoalesced
accessibilityA11yProjected, A11yRemeasured
animationTierBTransitions, TierCPlacements, PlaceWritesWithoutReemit, PlaceWritesWithReemit, OrderBandEscapes
paintRepaints, StylesLowered, StylesLoweredFromCache, GroupTargets, ChunksReencoded, ChunksTranslated, ChunksIncomplete, ChunksRetainedUnvisited, ChunksEvicted, FragmentsRetired, PrimitivesEmitted, PrimitivesCulled, BoundsTreeInserts, SpritesFixedUp, SpritesResolvedAtPush, PaintsReanchored
glyphs and imagesGlyphsPlaced, GlyphsRasterised, RebuiltAfterEviction, AtlasTilesEvicted, ImageInsertFailed, EncodedImageBytes, RecordTilesRetained, RecordTilesReleased
vector routingVectorRouteAnalytic, VectorRouteMarks, VectorRoutePathGlyphs, VectorRouteMask, VectorRouteLayer, VectorRouteGeneral, VectorTierChanges, VectorReplaysMoved, VelloPasses, VectorClipLayers, VectorFramesDropped
marks and seriesMarksUnionBins, MarksPayloadBytes, MarksUncached, SeriesPayloadsBuilt, SeriesBuildsAsync, SeriesDrawsProvisional, SeriesChunksDrawn, SeriesChunksCulled
masks and path glyphsVectorMaskMisses, VectorMaskBudgetOverflow, PathGlyphTilesRasterised
CPU layersVectorLayersRasterised, VectorLayerRasterUs, VectorLayerBytesUploaded, VectorLayersProvisional, VectorLayersDeferred, VectorLayersDemoted, VectorLayersEvicted, VectorLayerFallbacks, VectorLayerTilesRasterised, VectorLayerTilesDeferred, VectorLayerTilesReused
general vector rasteriserVectorBackendBuilt, VelloRenders, VectorEncodeHits, VectorEncodeMisses
renderer and uploadsDrawCalls, DamagePx, BytesUploaded, ChunkBytesUploaded, AtlasTextureWrites, AtlasUploadBatches, SideTableSlotsPrepared, UploadChunksAllocated, StagingWarmBytes, StagingOneShotBytes
event loopWakes, TimersFired, FramesDrawn
live gaugesClipEntriesLive, ClipSlotsReach, PaintEntriesLive, PaintSlotsReach, SpatialNodesLive, FragmentsLive, PaintChunkBytes, ChunksResident, BoxesLive, AtlasEntriesLive, GlyphEntriesLive, ScratchLayers, ScratchBytes, VectorMaskTilesLive, VectorLayerBytesLive

Counters that are easy to misread

CounterMeaning
NodesVisitednodes a traversal looked at, dirty or not. The only counter that notices a walk touching thousands of clean nodes to service one.
BoxTreeBuildswhole-document box-tree builds. One on a frame that changed one region means every box got a new identity.
ObservationsTruncatedsize or position deliveries still changing when the pass budget ran out; each costs an extra frame.
TextBytesShapedbytes that reached real shaping. Read it beside TextShaped.
VectorLayerRasterUsmicroseconds spent rasterising CPU layers, not a count.
VectorFramesDroppedframes whose vector content had nowhere to go. Must stay zero.
UploadChunksAllocatedstaging 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

VariableEffect
ZGUI_LATENCY=<path>write the latency trace to <path>
ZGUI_LATENCY_ELEMENTS=1also write a latency mark per restyled element
ZGUI_FULL_DAMAGE=1start every frame with the whole surface damaged
ZGUI_INVARIANTS=1check 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=0keep layout batches off the pool
ZGUI_PLATFORM=winit|waylandchoose the desktop backend on Linux
ZGUI_PRESENT_PACING=notifyalso request pre-present notification on the winit backend, to compare callback pacing
ZGUI_BENCH_GPU=1draw the bench harness through this machine's GPU offscreen instead of the null renderer
ZGUI_BENCH_FRAMES=1print per-frame counts in the thread-resize and vector benches
ZGUI_CADENCE_OUT=<path>where the cadence probes write their report
ZGUI_CALIBRATE=1run the CPU-layer cost calibration tests in zgui-paint (calibrate_the_cost_model, calibrate_the_tile_cost_model)

Next

On this page