The renderer
The Renderer and VectorRaster contracts, the wgpu backend, frame planning, partial redraw, presentation, atlases, and how each visual feature is drawn.
The renderer takes a finished display list and a damage set and puts pixels on a screen.
zgui-render defines the contract, and zgui-render-wgpu is the backend zgui ships. The renderer
makes no drawing decisions of its own: batches, draw order, vector passes and mark bins are all
planned in the display list (see Paint and the scene), and the
renderer executes that plan.
The Renderer trait
crates/zgui-render/src/renderer.rs defines eight required methods and ten with defaults:
pub trait Renderer {
fn capabilities(&self) -> RenderCapabilities;
fn configure(&mut self, target: RenderTarget);
fn target(&self) -> Option<RenderTarget>;
fn draw(&mut self, scene: &Scene, damage: &DamageSet) -> FrameOutcome;
fn register_external(&mut self, texture: ExternalTexture) -> TextureHandle;
fn release_external(&mut self, handle: TextureHandle);
fn memory(&self) -> MemoryReport;
fn texture_sink(&mut self) -> &mut dyn TextureSink;
fn shifts_composed_pixels(&self) -> bool { false }
fn composed_survives_configure(&self) -> bool { false }
fn shift_composed(&mut self, shift: ScrollShift) { }
fn vector_status(&self) -> VectorStatus { VectorStatus::default() }
fn target_pool(&self) -> TargetPoolReport { TargetPoolReport::EMPTY }
fn release_cached_targets(&mut self) -> u64 { 0 }
fn release_idle_resources(&mut self) -> u64 { self.release_cached_targets() }
fn acquire_block(&self) -> Duration { Duration::ZERO }
fn as_any_mut(&mut self) -> Option<&mut dyn Any> { None }
fn as_any(&self) -> Option<&dyn Any> { None }
}zgui-render names no graphics API and implements none of its traits. Every default is the correct
answer for a renderer that does not support the feature, so a minimal implementation stays correct.
| Rule | Reason |
|---|---|
| Compose into a target that persists between frames. | draw may assume everything outside the damage still holds the previous frame's pixels. A renderer that draws into a fresh surface each frame must treat every frame as full damage. |
| Execute the display list's plan; do not derive another. | Batches, draw order, vector passes, mark bins and the damage cull are decided in the scene, so tests can assert them without a device. A renderer or VectorRaster that culls against damage again becomes a second owner of the same decision. |
| Report capabilities before the frame is built. | They change what the display list contains, not only how it is drawn. |
| Retire damage when work is submitted. | FrameOutcome::retires_damage() decides, and the answer is not "when presented". |
Hand out texture_sink() per call. | Atlas textures do not survive a device loss, so a borrow kept across frames outlives what it names. |
| Report a pool if you keep one. | A window's budget asserts that every registered cache is empty after it is told to release its contents. |
Forward as_any/as_any_mut from a wrapper. | Backend companion crates, such as the embedding host, reach the concrete renderer through them. |
Two optional capabilities change what the runtime sends:
shifts_composed_pixels: when this is true, the runtime narrows a scroll frame's damage to the exposed band and callsshift_composedbefore the nextdraw. See Shifting a composed scrollport.composed_survives_configure: asked after everyconfigure. When it is true and the scale and opacity did not change, the runtime damages only the bands a larger surface exposes. Otherwise the next frame is full damage. See The persistent target.
What a frame reports
draw returns a FrameOutcome, not a Result, because most reasons a frame does not reach the
screen are normal events in a window's life.
pub enum FrameOutcome { Presented(FrameStats), Skipped(SkipReason), Recovered }
#[non_exhaustive]
pub enum SkipReason {
Unconfigured, Timeout, Unacquired, Occluded, Outdated, Validation, DeviceUnavailable, Undamaged,
}| Outcome | retires_damage() | wants_another_frame() |
|---|---|---|
Presented | yes | no |
Recovered | yes | yes |
Skipped(Unconfigured) | no | yes |
Skipped(Unacquired) | no | yes |
Skipped(Timeout) | yes | yes |
Skipped(Outdated) | yes | yes |
Skipped(Validation) | yes | yes |
Skipped(Occluded) | yes | no |
Skipped(DeviceUnavailable) | no | no |
Skipped(Undamaged) | yes | no |
Three outcomes keep their damage because nothing was recorded: the surface was not configured, the
device could not be rebuilt, or (Unacquired) a renderer that draws straight into a buffer the
display scans out had no buffer to draw into. Timeout is the same refusal after the frame was
composed, so the persistent target already holds the new pixels and the damage is retired.
Three outcomes must not request another frame:
Occluded: redrawing a hidden window would make it run at full rate.Undamaged: another frame would produce the same pixels.DeviceUnavailable: a device that could not be rebuilt will not be rebuilt by asking again.
Tests in crates/zgui-render/src/outcome.rs hold these rules.
Render targets and capabilities
pub struct RenderTarget {
pub size: Size<i32, Device>,
pub scale: Scale<Css, Device>,
pub opaque: bool,
}
pub struct RenderCapabilities {
pub subpixel_text: bool,
pub vector_compute: bool,
pub mutable_texture_formats: bool,
pub custom_shaders: bool,
pub max_texture_size: i32,
}RenderTarget::translucent() clears opaque. A window opened with App::with_transparent(true) is
composed into a translucent target: each pixel is a premultiplied colour, a pixel nothing paints has
zero alpha, and text uses greyscale (single-channel) antialiasing. Per-channel text writes three
coverage values and no alpha, which is meaningless over a destination that is not opaque.
RenderCapabilities::MINIMAL is the least capable device zgui supports: no per-channel text, no
compute, no format views, no application shaders, and max_texture_size: 4096.
Vector rasterisers
Rectangles, sprites and lines are drawn by fixed pipelines. Paint lowers most vector content to
quads, marks, atlas masks or CPU-rasterised sprites (see
Vector routes). Only what is left becomes
VectorItems, planned into vector passes, and a
VectorRaster draws those passes.
pub trait VectorRaster: 'static {
fn backend(&self) -> VectorBackend { VectorBackend::Other }
fn plan(&mut self, passes: &ScenePassPlan) -> VectorPlan;
fn clear_targets(&mut self, plan: &VectorPlan, round: usize);
fn prepare(&mut self, frame: &mut VectorFrame<'_>) -> Result<(), VectorError>;
fn memory(&self) -> MemoryReport;
fn release_idle_resources(&mut self) -> u64 { 0 }
}A rasteriser writes each pass into a scratch texture, and the renderer composites the scratch back with one ordinary draw at the pass's position in the batch stream. The renderer has no depth buffer, stencil or order-independent scheme. Submission order is z-order, so inserting the composite at the right index is enough.
The rules, from crates/zgui-render/src/vector/raster.rs:
- The scratch holds straight (un-premultiplied) colour. The composite premultiplies as it reads.
plan()is index-aligned with its input: oneVectorPassperPlannedPass, in order, or an empty plan. Composites name passes by index, so dropping one would draw every later composite from the wrong pass.VectorPlan::resourcingstarts a plan that keeps the alignment.plan()runs once per frame and holds the per-frame bookkeeping.clear_targetsandpreparerun once per round, and again for each damage rectangle, so they must not age caches or reset statistics.clear_targetsis mandatory. Without it, a rasterisation that fails silently leaves the previous frame's paths in a reused scratch, which composite as wrong pixels.prepareruns before the commands that composite its round are recorded, because an implementation may submit work of its own.- Residual clips are part of the contract. A composite applies one clip, so the part of an item's clip chain below its pass's clip is applied inside the scratch.
- A pass whose
clampedflag is set (cut to the damage, or with ink past the surface edge) must be clipped to its region, because the next pass's bin starts where the region ends. - An empty plan means do nothing. An empty pass over a full-size surface is not free.
Packing passes into scratch and rounds
Both rasterisers use the zgui_render::Layering helper (crates/zgui-render/src/vector/pack/mod.rs):
- Bins. Each pass gets a bin of its own size on a shelf of a scratch layer. Two passes never
share a texel, whatever they cover on the surface, so a stack of passes over one point costs the
same as the same passes side by side.
VectorPass::regionis where the pass composites on the surface;VectorPass::raster_regionis its bin. - Capacity.
Capacity::DEFAULTis eight layers of 2048 × 2048 per round (at most 128 MiB of RGBA8). A pass larger than a layer widens the layer, so every pass fits. - Rounds. A frame that needs more is cut into rounds: contiguous runs of the plan, in order. The renderer submits what it has recorded, rasterises the next round into the same layers, and continues. Paint order does not change, and no pass is dropped.
- Sizing. The scratch grows at once to what a frame needs, rounded up to 256-pixel size classes.
It shrinks only after
Decay::GRACE(two seconds) of needing less, so a fling does not reallocate on every quiet frame.
VectorFramesDropped counts frames where a round still failed to rasterise. It should stay at zero.
Vello and coverage rasterisers
| Crate | Type | For |
|---|---|---|
zgui-render-vector-vello | VelloRaster | Devices that run compute shaders over writable storage textures. The reference implementation. |
zgui-render-vector-coverage | CoverageRaster | Devices that cannot. A visible downgrade. |
zgui_render_vector_vello::for_device reads gpu.capabilities().vector_compute (what the device
supports, not what the adapter advertised) and returns one or the other. If VelloRaster::new fails
on a compute device, it logs one warning and uses the coverage raster. One Vello renderer is shared
per device; scratch textures and caches are per window.
VelloRaster keeps an encoding cache (raster/cached.rs). An item's encoding is keyed by
content: the identity of its shared path allocation, its paints, its fill rule and stroke style, and
its brush transform. Placement, pass, clip and item identity are not part of the key, so a scrolled,
moved, refitted or duplicated drawing reuses its encoding. The cache holds the Arc, so a freed
path address cannot be reused by another path, and drops the least recently drawn entries past
64 MiB. VectorEncodeHits and VectorEncodeMisses count lookups.
The coverage raster's limitations, from its crate documentation:
- No blend or compose modes. Everything composites source-over.
- Multisampled coverage. Sixteen samples per pixel (
GRID: i32 = 4incoverage.wgsl), so an edge has seventeen levels. Interiors are exact. - Cost scales with area times outline complexity. Fine for icons, slow for a map.
- Gradients are filled flat in the ramp's mean colour. Image paints are not drawn.
The general rasteriser is built lazily, on the first frame whose plan is not empty. Building it
takes hundreds of milliseconds and a large fixed allocation, so a document whose shapes all take
another route never builds it. Renderer::vector_status() reports the configured backend and whether
it has been built; VectorBackendBuilt counts builds.
A renderer with no rasteriser factory attached still plans vector passes, but nothing writes the
scratch, so each general vector item draws as an empty rectangle. zgui::app() calls
zgui_render_vector_vello::attach for you (crates/zgui/src/app/graphics.rs). Call it yourself
when you build a WgpuRenderer directly.
The wgpu backend
zgui-render-wgpu is the shipped implementation. Builder opens a device and returns a
WgpuRenderer. It is a builder because the surface must be created from the same instance as the
device, and an adapter is only known to be usable once a device was created from it and a surface
configured under a validation error scope.
use zgui_geom::{Scale, Size};
use zgui_render::{GpuUnavailable, RenderTarget};
use zgui_render_wgpu::{Builder, WgpuRenderer};
fn offscreen() -> Result<WgpuRenderer, GpuUnavailable> {
let target = RenderTarget::new(Size::new(256, 256), Scale::new(1.0));
let mut renderer = Builder::new().offscreen(target, wgpu::TextureFormat::Bgra8Unorm, false)?;
// Install the lazy factory for the general vector rasteriser.
zgui_render_vector_vello::attach(&mut renderer, target.size);
Ok(renderer)
}GpuUnavailable is a typed error, not a fallback, and names every adapter that was tried. A window
that opens and never paints is worse than a clear failure.
Sharing a device across windows
The standard renderer factory owns one SharedGraphics. The first window selects and opens a
device. Later windows get renderers on that device when its adapter can present to their surfaces.
A surface the primary adapter cannot present to gets a fallback device, shared by compatible windows.
| Shared per device | Per window |
|---|---|
| Device, queue, adapter, compiled pipelines, on-disk pipeline cache, the Vello renderer | Surface and swap chain, composed target, primitive arenas, remap and side-table buffers, group pool, scroll scratch, mark pages, atlas textures |
The atlas stays per window because atlas keys are created by a window's content cache; sharing it would let one window's eviction blank another's glyphs. The factory is lazy: constructing the application enumerates no adapters, and closing the last window on a fallback device releases it.
Adopting a host-opened device
An application embedded in a host that already owns the graphics device, such as a game engine, can draw on that device instead of opening its own:
use zgui_render_wgpu::{Gpu, SharedGraphics};
let gpu = Gpu::from_existing(instance, adapter, device, queue); // the host's wgpu objects
let graphics = SharedGraphics::with_gpu(gpu);
// Then, per window: graphics.renderer_for_surface(target, surface, pacing, None)zgui::app() opens its own device. To draw on a host's device, install a
renderer factory with App::with_renderer that hands out renderers from these
graphics, and call zgui_render_vector_vello::attach on each.
- Capabilities are read from the host's device and adapter the same way
Gpu::openreads them, so a device without dual-source blending draws text with ordinary coverage, and so on. - Graphics made with
with_gpunever open a device. Wherever one would be opened (the first surface on a lost device, a surface the adapter cannot present to, the replacement after a loss), they returnGpuUnavailableinstead.Gpu::is_adopted()andSharedGraphics::is_adopted()report this. - Device loss is reported by the host. wgpu keeps one device-lost callback per device and the
host already owns it, so zgui installs none. The host calls
gpu.loss().report(reason, message), or calls the closure fromDeviceLoss::observer()inside its own callback. Until then, renderers on the device do not see the loss. - Recovery. After recovering, the host hands over the new device with
graphics.adopt(new_gpu). Each renderer moves to it the next time it recovers. Adopting the device that is already primary changes nothing.
Presenting into supplied textures
SharedGraphics::renderer_supplied(target, textures) builds a renderer that presents into textures
the caller created on the shared device (via SharedGraphics::open_gpu) instead of into a swap
chain. The experimental console backend uses it to draw into scanout buffers; Vulkan extensions the
textures need are declared once with SharedGraphics::with_extensions. When no supplied buffer is
free, the renderer reports Skipped(Unacquired) and keeps its damage. Such a renderer cannot recover
from a device loss, because its textures belong to the old device; its owner builds a new one.
Colour encoding
Compositing, blending and filtering all happen on premultiplied, gamma-encoded values in every
target. The composed target's format is the surface format with any *Srgb suffix removed, and a
debug build asserts it. An *Srgb attachment would decode before each blend and encode after it:
rgba(128, 128, 128, 0.5) over white would then read back 225 instead of the 191 CSS specifies.
pub enum SrgbTier { Native, ViewFormatTwin, UndoInBlit }When the surface offers only an encoded format and the device cannot view a texture under a second
format, the final copy (BlitUndoSrgb) cancels the encoding instead. It is the only shader that
converts between encodings, which is safe because that copy is a pure copy.
Pipelines
A pipeline is keyed by kind and by the format of the attachment it draws into. There are 23
built-in kinds (crates/zgui-render-wgpu/src/pipeline/kind.rs):
| Kind | Draws | Blend |
|---|---|---|
Quad | Rounded, bordered rectangles. | premultiplied over |
Shadow | Box shadows, outer and inset. | premultiplied over |
Decoration | Underline, overline and strikethrough. | premultiplied over |
MonoSprite | Single-channel coverage tiles: glyphs, atlas masks, path glyph cells. | premultiplied over |
SubpixelSprite | Per-channel coverage tiles, on an opaque destination. | dual source, no alpha write |
ColorSprite | Full-colour tiles: images, colour emoji, CPU vector layers. | premultiplied over |
MarksDisc, MarksBox, MarksPolyline, MarksGlyph | One payload kind of a mark, painted directly. | premultiplied over |
MarksDiscCoverage … MarksGlyphCoverage | The same kinds, writing coverage into a union bin. | add; polylines take the max |
MarksComposite | A union mark, painted through its bin. | premultiplied over |
VectorComposite | A rasterised vector pass. | premultiplied over |
Composite | An isolated group target into the target beneath. | premultiplied over |
External | A texture the renderer did not draw. | premultiplied over |
DamageClear | One damage rectangle, cleared by drawing over it. | replace |
BlurDownsample, BlurAxis | The steps of a blur. | replace |
Blit, BlitUndoSrgb | The copy from the composed target to the surface. | replace |
Copies, clears and filter passes replace rather than blend, so their result never depends on what the attachment held.
SubpixelSprite is the only kind that needs a device feature (dual-source blending) and the only
one refused for an isolated target's format. Without the feature, text is emitted as single-channel
coverage.
The WGSL sources live once in zgui-wgsl and are concatenated per module, so a clip evaluated by a
quad, a glyph and an application effect runs the same code. They are parsed when zgui-render-wgpu
is built, and a launch loads the parsed form. Every built-in pipeline is created at renderer
construction over PipelineKind::ALL, so the driver's first compilation does not land in a frame.
Application shader effects are registered per device and built
lazily for the formats that use them. draw syncs newly declared effects before planning, and a
device rebuild registers them again.
GPU tables and buffers
Side tables
Clips, paints and coordinate systems are addressed by index from every instance, so they travel in
storage buffers (crates/zgui-render-wgpu/src/bind/tables.rs): GpuClip, GpuPaint (with gradient
stops in a separate table) and GpuSpatial (one 4×4 matrix per slot). Globals are per target,
read through a dynamic offset; one buffer rewritten per frame would give every pass the last mapping
written.
The renderer keeps CPU copies of the tables. The scene's clip and paint tables publish a bounded
change journal, and a TableVersion asks what changed since the frame it last prepared, so an
unchanged scene flattens zero slots and uploads zero side-table bytes. Changed slots are copied
as contiguous ranges. The renderer falls back to a full copy when it missed the journal, when
gradient stops moved, when at least half the table changed, or when more than sixteen ranges would
be needed. SideTableSlotsPrepared counts the CPU work.
Application shader parameters use a separate fixed-stride uniform buffer. Equal parameter blocks share one slot, and a draw selects its block with a dynamic offset.
Instance arenas
The seven instanced kinds (quads, shaded rectangles, shadows, decorations and the three sprite
kinds) and mark payloads live in persistent GPU arenas, keyed by the paint chunk's revision. A
new encoding uploads once. A replay at the same position uploads nothing, and a moved replay
uploads nothing either: the scene records the chunk's offset (Scene::chunk_offsets) and the shader
adds it at draw time. Content that cannot be resident (unresolved sprites, captures) goes into a
transient range.
Arenas reuse freed ranges before growing their tail, grow to at least twice their size, and keep each lane's bytes when they grow. A freed range is reused only after the GPU has completed the submission that last read it.
Upload belts
Uploads go through a reusable UploadBelt (buffer/upload.rs) rather than Queue::write_buffer,
which can allocate and map a staging buffer per call:
- chunks are at least 256 KiB and grow to the next power of two for larger requests;
finishunmaps before submission, andrecallstarts asynchronous re-mapping after it;- a frame reuses only chunks whose mapping completed, and never waits for one;
- one free chunk stays warm; others unused for 120 frames are released.
Atlas uploads use a second belt with the same policy and one submission per batch.
UploadChunksAllocated is non-zero when the belt grew; a recurring count means GPU backlog or
repeated bursts.
Planning a frame
The scene's batches say which draw calls a frame makes and in what order. The renderer adds render passes around them. A render pass ends at:
| Render pass boundary | Reason |
|---|---|
| A new damage rectangle. | The batch stream is replayed once per rectangle, under its own scissor. |
| A group start or end. | Content is redirected into a pooled target, then composited back. |
A backdrop-filter. | EncoderOp::Capture copies what is beneath, because a shader cannot read its own attachment. |
| Each blur or filter step. | Each step reads one target and writes another. |
| A new vector round. | Recorded work is submitted before the rasteriser writes the shared layers again. |
All of these split points need the command encoder, which a live render pass holds borrowed. So the
frame is planned before any pass opens (crates/zgui-render-wgpu/src/frame/), as a value that
tests can read:
pub enum Segment { Encoder(EncoderOp), Pass(PlannedPass), Round(usize) }
pub struct PlannedPass {
pub target: TargetRef,
pub load: PassLoad,
pub scissor: Rect<i32, Device>,
pub globals: u32,
pub draws: Range<usize>,
}Each damage rectangle replays the whole batch stream; it is not culled again. Which primitives
survive was decided when the display list was built. FrameStats::draw_calls therefore grows with
the number of rectangles, which is why MAX_DAMAGE is six and not larger.
Vector work inside a frame
r.vectors. If the renderer widened this frame to full damage but the scene's passes were cut to the damage, it asks the scene forplan_uncut_passesfirst. It then callsplan(), clears and prepares round 0, before the frame's encoder exists.r.plan. The mark bins come fromScene::mark_plan(), or are planned again withScene::plan_markswhen the frame was widened.MarksScratchis sized to the plan's pages.r.record. For each later round, the renderer submits what it has recorded, prepares that round, and continues recording into a fresh encoder.
Drawing marks
A mark whose shapes are apart is painted directly, with one draw per payload kind it holds. A union mark is drawn through its planned bin on a single-channel coverage page:
- The coverage pipelines write into the bin: polylines first (keeping the largest coverage of their segments), then discs, boxes and glyphs adding to it.
MarksCompositepaints the item's paint through the summed coverage.
Pages are the size of the surface, so a bin is never split. Items on the shared spare page each write their coverage just before their own composite.
Partial redraw
Damage becomes scissor rectangles in one place, crates/zgui-render-wgpu/src/frame/damage.rs. A
full set becomes the whole used area; otherwise each rectangle is intersected with it and empty ones
are dropped. The rectangles are pairwise disjoint, so no pixel is redrawn twice. When damage touches
a backdrop-filter, the scissor grows to the backdrop's whole source region, so the filter reads
this frame's pixels and not its own output from the last frame.
A render pass clears its whole attachment or none of it, so a damage rectangle is cleared by
drawing over it: DamageClear writes transparent with no blending under the rectangle's scissor.
Pixels outside the damage stay valid because:
- the composed target outlives the frame, and every pass on it uses
PassLoad::Keep; - the scissor stops every draw of the frame, including the clear, from writing outside the rectangle;
- the copy to the surface covers the whole target, so untouched pixels reach the screen again.
A pooled group target is different. It uses PassLoad::Discard on the first write of each lease
and discards the whole target, so a blur fades to transparent at the edge of what the group
painted and never reads what a previous lease left behind. A group that received no draw is not
composited.
The renderer widens damage to the whole surface once, at the top of draw, when
full_damage_next is set: by a reallocated target, a change of scale or opacity, a device rebuild,
or an acquisition result that says the compositor changed the surface. A frame with empty damage, no
pending shift and nothing owed to the surface returns Skipped(Undamaged) before acquiring
anything.
The persistent target
Each frame is composed into a texture the renderer keeps, and then the whole texture is copied onto
the surface (crates/zgui-render-wgpu/src/target/scene_texture.rs). Both halves are required. An
acquired surface texture starts uninitialised, so partial redraw needs a target that outlives the
frame, and copying all of it keeps the undamaged pixels from coming out black.
The target is allocated in 256-pixel size classes (SIZE_CLASS). During an interactive resize,
growing costs a few allocations and shrinking costs none; SceneTexture::used is the part the
surface occupies.
A size change alone keeps the composed picture when the target still fits. In that case
composed_survives_configure() is true, and the runtime damages only the right and bottom bands the
new extent exposes, plus whatever layout moved. A change of scale or opacity, or a reallocated
target, makes the next frame full.
Shifting a composed scrollport
The runtime calls shift_composed with a ScrollShift only after it has checked that the shift is
safe: the port moved rigidly by whole device pixels, nothing else draws over it, and it is opaque.
The port is measured where it stands on the device (the scroll container's padding box minus its
scrollbar gutter), not in the container's own coordinates. See
Scrolling for the conditions the runtime checks.
The copy is recorded, not performed immediately, and runs in the frame's own encoder before any damage is redrawn. Source and destination usually overlap, so it goes through a scratch texture that is allocated on first use and released by the idle trim. The bands the move exposes are added to the damage and redrawn by the ordinary partial-redraw path.
Present
The present mode follows the surface's pacing (crates/zgui-render-wgpu/src/gpu/surface.rs; see
the platform layer for PresentPacing):
PresentPacing | Mode | Who paces |
|---|---|---|
Display | Fifo | Surface acquisition blocks until the display frees an image. |
Platform | Mailbox, else Immediate, else Fifo | Compositor frame callbacks (for example native Wayland). Mailbox and Immediate keep acquisition non-blocking; Fifo works but can add a second wait. |
FRAME_LATENCY is 2: one image being composited and one being drawn (wgpu-hal turns this into three
swap-chain images). acquire_block() reports how long the last acquisition waited. On a
display-paced surface, the runtime uses it to start later frames closer to the next refresh, keeping
a margin of one sixth of the refresh interval, clamped to 500 µs–2 ms. On a platform-paced surface,
acquisition does not wait, so the hold converges to zero. Every field of
wgpu::SurfaceConfiguration is set explicitly.
The order inside draw (crates/zgui-render-wgpu/src/renderer/draw.rs):
- Configure the surface if needed, recover a lost device, widen damage, and return
Undamagedif there is nothing to do. - Prepare side tables and stage effect parameters (
r.tables), rasterise round 0 of the vector plan (r.vectors), and plan the frame (r.plan). - Create the encoder (
r.encoder), apply a pending scroll shift (r.shift), upload buffers (r.buffers), and record every pass (r.record), submitting between vector rounds. - Rebuild the swap chain if owed. The rebuild waits for the device to go idle, and the frame's CPU work has just given it time to.
- Acquire a surface texture (
acq.in), blit the composed target onto it (a four-vertex strip, onetextureLoadper fragment), submit once (sub.out), and present (pres.out).
Surface acquisition
Acquisition has seven answers (crates/zgui-render-wgpu/src/target/acquire.rs):
| Answer | Presents | Reconfigure | Recreate surface | Full damage next |
|---|---|---|---|---|
Success | yes | |||
Suboptimal | yes | yes | ||
Timeout | ||||
Occluded | ||||
Outdated | yes | yes | ||
Lost | yes | yes | yes | |
Validation |
- Suboptimal. The texture is presented and the surface reconfigured afterwards, so the user does not lose a frame.
- Outdated. Not retried in the same frame, because the recorded work was sized for the old surface.
- Validation. A run of these answers escalates to a device loss. The next frame rebuilds the adapter, device, presentation, pipelines, composed target, buffers and atlas textures. Paint records stay on the CPU and are re-noted, so the next drawn frame makes them resident again in one pass. The vector rasteriser is dropped and rebuilt lazily.
- Timeout. The window is marked starved. Animation, caret and frame-callback deadlines stop, so a blocking acquisition cannot stall the input thread repeatedly. zgui probes after 1 second, doubling up to 16 seconds. Input, focus gain, resize, a scale change or becoming visible clears the state. Timers keep running.
ZGUI_SURFACE_FAULT=<answer>[,n] injects any of the seven answers for testing.
Atlases
An atlas is a large texture holding many small rasters, so a page of text binds one texture instead
of one per glyph. zgui-atlas holds the whole policy (placement, lifetime, eviction) and has no GPU
dependency.
One ContentCache per window holds one atlas for glyphs, vector masks, path glyph cells,
images and CPU vector layers, so they share one memory budget. It has four pools:
TextureKind | Format | Holds | Sampled |
|---|---|---|---|
Mono | R8Unorm | Glyph coverage, atlas vector masks, path glyph cells. | nearest |
Subpixel | Rgba8Unorm | Per-channel glyph coverage. | nearest |
Color | Rgba8Unorm | Colour glyphs and emoji, premultiplied. | nearest |
Image | Rgba8Unorm | Decoded images and CPU vector layers, premultiplied. | linear, mipmapped |
Formats are fixed rather than following the surface: no channel swizzle on upload, and one byte per coverage texel keeps text uploads small. Glyph pools use nearest sampling because a glyph is rasterised at its drawn size; the image pool filters because images are stretched.
AtlasKey::new(handle, kind) is opaque. A glyph's handle hashes face, glyph id, size and subpixel
phase; other caches create handles in their own namespace.
Allocation and eviction
Each pool packs tiles with etagere::BucketedAtlasAllocator, one allocator per texture, trying the
newest texture first. A tile larger than max_texture_size is AtlasError::TooLarge. No room is
AtlasError::OutOfSpace, which eviction can fix.
pub struct AtlasLimits {
pub texture_size: i32, // default 1024
pub max_texture_size: i32, // default 4096; a window uses the device's limit
pub max_textures_per_pool: u32, // default 16
pub soft_bytes: Option<u64>, // default None; a window sets ATLAS_SOFT_BYTES = 64 MiB
}An image variant with a long edge above 512 pixels, or a CPU vector layer above 1024, gets a standalone texture with a full mip chain in the same pool.
soft_bytes is a level the atlas returns below between frames, not a ceiling: everything one frame
draws is in use and may exceed it. Eviction is by generation. Atlas::begin_frame starts a new
generation, every lookup stamps its entry, and evict_to_soft_limit frees the oldest unreferenced
generations until resident bytes drop below the level. It stops when a step frees nothing, so a
frame whose working set exceeds the limit keeps it. A paint record's replay holds reference counts
on its tiles, so a replayed chunk keeps its texels without looking them up again.
The upload path
Uploads are deferred. get_or_insert allocates, calls build() only on a miss, checks the byte
count, and queues the write. Nothing reaches the device until flush_uploads.
pub trait TextureSink {
fn create_texture(&mut self, texture: TextureId, size: Size<i32, Device>,
format: TextureFormat) -> Result<(), SinkError>;
fn create_texture_with_mips(/* … */) -> Result<(), SinkError>; // defaulted
fn begin_uploads(&mut self) -> Result<(), SinkError> { Ok(()) }
fn write_texture(&mut self, texture: TextureId, bounds: Rect<i32, Device>,
format: TextureFormat, bytes: &[u8]) -> Result<(), SinkError>;
fn write_texture_mip(/* … */) -> Result<(), SinkError>; // defaulted
fn finish_uploads(&mut self) {}
fn destroy_texture(&mut self, texture: TextureId);
}A sink may rely on the call order: create before write, writes inside the created size,
create_texture once per id, nothing written after destroy. MemorySink implements the trait over
a Vec<u8> for unit tests. The device side is AtlasTextures
(crates/zgui-render-wgpu/src/atlas_backend/sink.rs), reached through Renderer::texture_sink().
Tiles are allocated while the emit walk runs and uploaded in one batch afterwards: the frame calls
ContentCache::flush(renderer.texture_sink()) between emitting and drawing
(crates/zgui-runtime/src/window/frame.rs). Drawing before the flush samples texels that were never
written, which on most devices shows stale texture contents rather than a blank glyph.
How each feature is drawn
| Feature | Mechanism |
|---|---|
| Solid fill | One Quad. PaintRef carries the paint family beside the index, so a solid fill never reads gradient stops. |
| Edges and antialiasing | Each quad measures one device pixel in its own space with derivatives and spreads its edge over that length. Edges stay one device pixel wide at every zoom, including the inner half of rounded edges and inner border corners. |
| Rounded and superellipse corners | A signed distance function over two semi-axes per corner (so border-radius: 80px / 20px works) and the --zgui-corner-shape exponent. Exponent 2 takes the exact ellipse path. The same exponent reaches quads, shadows, clips and outlines. |
| Border | Same instance as the fill. An inner distance against the box shrunk by each side's width selects the border colour. |
| Dashed and dotted border | Laid out clockwise around the whole perimeter, sized by border width. Corner arc lengths use Ramanujan's quarter-ellipse perimeter and the eccentric anomaly, so dashes do not stretch at corners. |
| Gradient | Evaluated per fragment (gradient_position, sample_ramp). Stops are converted to the ramp's interpolation space and premultiplied on the CPU; decode_stop converts back, so a ramp to transparent does not darken midway. |
| Outer shadow | One Shadow, analytic: a closed-form erf integral horizontally, four samples vertically. Shadow::BLUR_EXTENT = 3.0 standard deviations. |
| Inset shadow | The complement of the same integral, clipped to the padding box. The hole is the padding box offset by the shadow's offset and shrunk by its spread, with concentric corners; a large spread closes it. |
| Application paint or coverage shader | One ShadedQuad, batched by shader and parameter block. The framework supplies transform, clip and blend. Without custom_shaders, the built-in fallback is emitted instead. |
| Application filter | A custom step in a group's filter chain. Its declared reach grows damage and bounds the source region. |
| Text | One sprite per glyph, ordered as one run. SubpixelSprite or MonoSprite, as paint chooses. Coverage is contrast-enhanced and gamma-corrected, more strongly for light text on dark. |
| Decorations | One Decoration with style Solid, Wavy, Dashed, Dotted or Double. |
| Image | A ColorSprite with elliptical corner radii and a grayscale flag. |
| Recognised vector shapes | Analytic Quads, or Marks drawn from a payload (drawing marks). |
| CPU vector layer | A ColorSprite from the image pool, or one per 512-pixel tile of a large layer. |
| Path glyphs | A mark whose glyph words read Mono atlas cells, sixteen sub-pixel phases per outline. |
| General vector item | Rasterised into a scratch bin, then drawn with VectorComposite. |
| Opacity group | Folded into each primitive's paint when no two primitives of the subtree overlap; otherwise a pooled target composited with the group's alpha. |
| Filter chain | Chain::of folds consecutive per-pixel functions into one colour matrix. Blur breaks the fold; split() hands the trailing matrix to the composite. |
| Blur | A 2:1 downsample, then two separable Gaussian passes. Past BlurParams::MAX_TAPS = 16.0, taps spread out rather than truncating. Extents are explicit, so a moving blur does not shift its sampling lattice. |
| Drop-shadow filter | A blurred copy composited with COMPOSITE_TINT (flat colour times alpha) at the offset. |
backdrop-filter | EncoderOp::Capture copies the region beneath into a pooled target; the chain runs; the result composites back. |
| Clipping | Every pipeline calls one clip_coverage. The chain's intersection rectangle is a hard edge (no bleed outside a scrollport); at most two rounded tests run inline. More, or more than one mask, gets a group target (ClipTable::needs_group_target). |
| Transform | Each instance carries a SpatialId; to_clip_position applies that slot's matrix. Shapes are evaluated in the primitive's space, clips in device space. |
| Isolated targets | GroupPool, Rgba16Float, 256 MiB budget, no depth limit. At the limit, the pool drops to half resolution rather than skipping isolation. A step the pool cannot serve is skipped and counted. |
Custom renderers
An application replaces the renderer with a factory:
pub type RendererFactory =
Box<dyn FnMut(&Arc<dyn Surface>, RenderTarget) -> Result<Box<dyn Renderer>, AppError>>;The runtime calls it once per opened surface, and again for recreated surfaces after a platform
resume. Keep device-level state outside the returned renderer, as SharedGraphics does.
use zgui::prelude::*;
use zgui::render::{RenderTarget, Renderer};
fn main() -> Result<(), zgui::Error> {
zgui::app()
.with_renderer(Box::new(|_surface, target: RenderTarget| {
// The factory's return type forces the coercion, so write it out.
let renderer: Box<dyn Renderer> = Box::new(MyRenderer::new(target));
Ok(renderer)
}))
.run(|| view! { Dashboard() })
}Two existing implementations are useful references. CaptureRenderer in zgui-testkit-scene
records the display list as stable text and draws nothing. NullRenderer in
crates/zgui-bench/src/draw.rs accepts every frame, so a benchmark measures only the CPU. A
texture_sink that accepts every write and stores nothing is enough for a renderer that draws
nowhere.
memory() reports by component, because fixed cost and per-frame cost are budgeted differently:
pub struct MemoryReport { pub fixed: u64, pub targets: u64, pub scratch: u64, pub atlases: u64, pub buffers: u64 }WgpuRenderer reports the composed target and group pool as targets, the mark pages as
scratch, the atlas textures as atlases, and arenas, side tables and upload belts (by allocated
capacity) as buffers. The vector rasteriser adds its own report component by component.
release_idle_resources is called by the runtime's idle maintenance, two seconds after the last
normal frame (see the frame). WgpuRenderer releases unused group
targets, the scroll scratch, completed upload chunks, persistent arenas, retained remap and table
buffers, and the vector rasteriser's reproducible scratch. The composed target and fixed state stay.
Common mistakes
| Mistake | Consequence |
|---|---|
| Returning a damage-keeping skip for the wrong reason | Unconfigured, Unacquired and DeviceUnavailable keep damage; every other skip retires it. |
| Culling against damage | The display list already did. A primitive that reaches draw reaches the damage. |
Calling batches() on an unfinished scene | It panics with "batches() needs a finished scene; call finish() first". The runtime always finishes the scene; a hand-built test scene may not. |
| Ignoring group markers | push_group never culls, so markers are always a matched pair. Half a pair leaves a target open or composites one that never began. |
| Composing straight into the surface | Legal, but every frame must then be full damage. |
Pooling targets and leaving target_pool() defaulted | The budget check catches it. |
| Drawing an external quad against another texture | A quad naming an unregistered texture is counted as undrawn, never drawn with whatever is bound. |
Measured costs
The present path itself is cheap. Across 2 705 frames on the maintainer's machine (RTX 3080 Ti,
Vulkan, Hyprland, 1080×720; docs/perf/present.md, Measurement A):
| Stage | p50 | p90 | p99 | max |
|---|---|---|---|---|
get_current_texture | 0.028 ms | 0.101 | 12.802 | 30.808 |
blit and queue.submit | 0.175 ms | 0.323 | 0.558 | 1.811 |
present | 0.103 ms | 0.181 | 0.271 | 1.003 |
| whole present path | 0.327 ms | 0.629 | 13.003 | 31.337 |
All 64 acquisitions over 2 ms came from the one run with desired_maximum_frame_latency = 1. Nothing
waits on a fence inside a frame; device.poll is called only by pixel readback.
wgpu::Surface::configure is a full GPU idle wait (2.4 ms on counter, 8.0 ms on styled). It
scales with in-flight work, not window size, which is why the rebuild is deferred to just before
acquisition and skipped when the extent did not change.
| Cost | Grows with |
|---|---|
| Draw calls | Batches × damage rectangles. |
damage_px | Area of the damage rectangles clipped to the surface. |
bytes_uploaded | Atlas misses, new or transient primitive bytes, mark payloads, changed remaps and side-table ranges. Replays upload nothing, moved or not. |
| Vector passes | The general vector plan; rounds only when the passes exceed one scratch capacity. |
| Mark bins | Union marks that reach the damage (MarksUnionBins). |
| Pool memory | What the document nests, not what it draws. |
Next
Paint and the scene
How fragments become a display list, how vector content is routed, and how passes are planned.
The platform layer
The platform contract and the native Wayland, winit, headless and console backends.
Caches
Every cache in the pipeline, what invalidates it, and what a miss costs.
Vector and canvas
Drawing icons, documents and canvas scenes from an application.
Paint and the scene
How paint turns the fragment tree into a display list: primitives, clips, draw order, the stacking walk, damage culling, replay, vector routes, vector passes and batching.
The platform layer
The platform contract in zgui-platform, and the native Wayland, winit, headless and experimental console backends that implement it.