zgui
Architecture

Architecture overview

The stages of the zgui pipeline, what one frame does, the design principles behind them, how the crates are layered, and a map of the architecture pages.

This section describes how zgui works inside. You do not need it to write an application, but it explains rules the guide states without justifying them: why a component runs once, why a signal write settles at the end of the frame, and why changing a colour costs less than changing a width.

The pipeline

zgui is retained. It keeps the document, the computed styles, the box tree, the shaped paragraphs, the per-fragment paint recordings and the rendered pixels between frames. Each stage receives a description of what became invalid and rebuilds only that.

Components and signalszgui-view · zgui-view-macro · zgui-elements · zgui-reactive
The documentzgui-dom
The cascadezgui-style · zgui-css
The box tree and layoutzgui-layout (Cephal) · zgui-text · zgui-text-parley
Paintzgui-paint
The rendererzgui-render · zgui-render-wgpu

The renderer contract, a GPU implementation, and a vector rasteriser.

A surfacezgui-platform · zgui-platform-wayland · zgui-platform-winit · zgui-platform-headless
The one-way architecture of zgui

Data flows one way. Each stage reads the output of the stage above it and never calls back into it: the paint crate does not depend on the style engine, and the renderer knows nothing about elements.

Three external engines do the heaviest work. Styles are computed by Stylo, text is shaped with Parley, and layout runs on Cephal, a retained, incremental layout engine published on crates.io.

One frame

zgui-runtime runs the pipeline. A frame has these phases, in order:

Accept work. Dispatch queued platform events, fire due timers, advance scrolling and gestures, reconfigure the surface, and sample running animations. Hit testing for an event uses the previous frame's fragments. Between two queued events, reactive work is settled so the second event sees the document changes made by the first.

Settle reactive work. Listeners, timers and completed tasks write signals. A write marks observers but does not run them. The frame then flushes the reactive graph, runs the script-engine checkpoint, and applies queued view commands. Effects change the document through the same Dom seam a view is built with.

Restyle. The style engine visits only elements that owe a restyle and turns each change into work for later stages. A colour change becomes repaint damage. A width change becomes relayout.

Layout. Patch the changed parts of the box tree, then run Cephal over the boxes its scheduler queued. Paragraphs are shaped or re-broken only when their content, style or available width changed. Geometry observations are delivered next; they can trigger at most two more flush-restyle-layout passes. Hit targets under a stationary pointer are updated and the caret is planned.

Paint. Walk the fragments in stacking order. Unchanged fragments replay their recordings; changed ones are recorded again. Everything is culled against the damage rectangles.

Draw. The renderer receives the display list and the damage set and composes into a target it keeps between frames. Pixels outside the damage keep their previous values.

Publish and schedule. Publish the accessibility update, recycle frame-local document data, apply the renderer's pacing information, and call the frame probe with the final window state.

After the frame, the loop parks and uses no CPU until something requests another frame:

  • a queued platform event (input, resize, a surface change);
  • a wake from another thread, such as a finished task;
  • the earliest deadline: an animation, a timer, a held gesture, a paced resize, a caret blink, a held presentation or a renderer retry.

Requests are coalesced, so many requests before the next frame starts cost one frame. Reactive work woken during a frame's flush is settled in that same flush (it polls up to three rounds) instead of scheduling a new frame. The frame covers each phase in detail.

Design principles

Invalidation as obligations

Each node records what it owes: restyle, relayout, repaint, and the subtree variant of each. Each stage clears the obligations it services as it walks, so no stage has to ask globally whether anything changed. Invalidation lists the bits and the propagation rules.

Stage outputs as values

The display list contains no renderer. Elements that cascade to the same result share one computed style. A fragment tree is plain data. Anything that crosses a stage boundary can be printed, compared and asserted on without a device or a window. This is why most of zgui's tests run headless and why testing an application is practical.

Cost proportional to the change

A signal write invalidates only its observers. A restyle visits only elements that owe one. Paint emits only primitives the damage reaches. No stage walks the whole tree every frame.

Wide changes, such as a window resize or a theme switch, still reach many nodes. zgui exposes counters and headless probes so you can measure the cost; the cost model has the numbers.

Windows

The application owns one reactive scope. Each window below it has its own document and its own frame pipeline.

  • Signals and application-level contexts are shared across windows.
  • Node handles and window-local contexts are tied to one document and cannot be used in another.
  • Windows are created and destroyed on an event-loop turn that has a platform context.
  • The default graphics setup shares the device and compiled pipelines between windows where the adapter allows it. Window-sized targets, buffers and atlases are per window.

See Windows for the API and The frame for the lifecycle.

Crates by layer

Every crate declares its layer in a # L<n> — … comment at the top of its manifest's dependency list. A crate may depend on crates in its own layer or a lower one, never a higher one. cargo xtask ledger layers checks this against the real manifests.

LayerCratesRole
L0 foundationzgui-geom, zgui-color, zgui-arena, zgui-interned, zgui-bits, zgui-profileCoordinate spaces, colour, stable-address storage, interned names, invalidation bits, counters. No policy.
L1 contractszgui-vocab, zgui-css, zgui-scene, zgui-render, zgui-atlas, zgui-platform, zgui-reactive, zgui-image, zgui-wgslTraits and value types the other crates agree on.
L2 backendszgui-render-wgpu, zgui-render-vector-vello, zgui-render-vector-coverage, zgui-platform-wayland, zgui-platform-winit, zgui-platform-headless, zgui-tokioImplementations of L1 contracts against real libraries.
L3 documentzgui-domThe node arena. Safe to read from many threads while the cascade runs.
L4 engineszgui-style, zgui-layout, zgui-text, zgui-text-style, zgui-text-parley, zgui-paint, zgui-svg, zgui-canvasThe stages that turn a document into a display list.
L5 systemszgui-input, zgui-scroll, zgui-a11y, zgui-anim, zgui-editBehaviour over a laid-out document: hit testing and dispatch, scrolling, accessibility, animation, text editing.
L6 frontendzgui-view, zgui-view-dom, zgui-view-macro, zgui-elements, zgui-custom, zgui-shader-macroHow an interface is described: views, macros, the element vocabulary, custom elements.
L7 runtime and toolingzgui-runtime, zgui, zgui-shader, zgui-wgpu, zgui-testkit-scene, zgui-testkit-view, zgui-conformanceThe frame pipeline, the umbrella crate, shader and external-texture integration, test instruments.
L8 productzgui-ui, zgui-ui-primitives, zgui-ui-tokens, zgui-ui-icons, zgui-devtools, zgui-bench, zgui-examplesThe component library, the inspector, the benchmark harness, example applications. They use only the public API.

Applications depend on zgui (cargo add zgui), which re-exports what an application needs. An application that only describes an interface never names another crate.

The experimental Linux console backend (zgui-console, zgui-platform-drm, zgui-drm, zgui-seat, zgui-evdev, zgui-libinput, zgui-xkb) follows the same layering but is not published to crates.io. The crate map describes every crate.

Seams

A seam is a trait that separates two parts of the system. These are the ones you are most likely to implement or replace:

SeamCrateWhat plugs in
Rendererzgui-renderA device that puts a display list on a screen.
VectorRasterzgui-renderA path rasteriser whose output the renderer composites.
Surface, AppHandler, Clock, Waker, Clipboardzgui-platformA windowing system, or none (headless).
Dom, ViewHost, EventSinkzgui-viewThe node tree, the engine that laid it out, and where handler commands go.
SheetLoader, ReplacedContent, LinkResolver, PresentationalHintszgui-domBehaviour a document language supplies that the document core cannot define.
FontSource, FontMetricsSource, ParagraphShaper, GlyphRasterzgui-textA font engine, or a fixed-metrics stand-in for tests.
MeasureContentzgui-layoutMeasurement for content layout cannot size itself.
CustomElementzgui-customA retained widget that measures, places its children and paints its own primitives.
HostBindingzgui-runtimeEvent, frame and shutdown hooks for an embedded script engine.
FrameProbezgui-runtimeA reader of the window state after each frame.

Most seams have two implementations in the repository. HostBinding is the exception: zgui ships only the no-op binding.

Pages in this section

The first three pages cover what every stage shares. The rest follow the pipeline from top to bottom.

PageCovers
The frameThe frame loop step by step, the reactive flush, observation delivery, parking, wakes, timers and animation pacing.
The documentThe zgui-dom node arena, the Dom and ViewHost seams, mutation batches, and the document-language seams.
Invalidation and damageThe dirty bits, how they propagate and are cleared, how style changes become obligations, and how damage rectangles merge.
Reactive internalsSignal storage, subscriptions, the flush, cross-thread wakes, owners and task cancellation.
The style engineHow zgui drives Stylo: selector matching, style sharing, the restyle pass and animations.
The layout engineThe box tree, Cephal, parallel layout, fragments, the hit index and paint order.
The text engineFonts, shaping and line breaking, glyph rasterisation, and the text caches.
Paint and the sceneHow fragments become a display list: primitives, clips, culling, replay, batching and vector routes.
The rendererThe Renderer and VectorRaster contracts, the wgpu backend, partial redraw, presentation and atlases.
The platform layerThe platform contract and its backends, frame pacing, scale, clipboard, accessibility and IME.
The crate mapEvery crate, its layer, the dependency checks, and how a release is made.

Next

On this page