zgui
Architecture

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.

RuleReason
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 calls shift_composed before the next draw. See Shifting a composed scrollport.
  • composed_survives_configure: asked after every configure. 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,
}
Outcomeretires_damage()wants_another_frame()
Presentedyesno
Recoveredyesyes
Skipped(Unconfigured)noyes
Skipped(Unacquired)noyes
Skipped(Timeout)yesyes
Skipped(Outdated)yesyes
Skipped(Validation)yesyes
Skipped(Occluded)yesno
Skipped(DeviceUnavailable)nono
Skipped(Undamaged)yesno

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: one VectorPass per PlannedPass, in order, or an empty plan. Composites name passes by index, so dropping one would draw every later composite from the wrong pass. VectorPlan::resourcing starts a plan that keeps the alignment.
  • plan() runs once per frame and holds the per-frame bookkeeping. clear_targets and prepare run once per round, and again for each damage rectangle, so they must not age caches or reset statistics.
  • clear_targets is mandatory. Without it, a rasterisation that fails silently leaves the previous frame's paths in a reused scratch, which composite as wrong pixels.
  • prepare runs 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 clamped flag 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::region is where the pass composites on the surface; VectorPass::raster_region is its bin.
  • Capacity. Capacity::DEFAULT is 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

CrateTypeFor
zgui-render-vector-velloVelloRasterDevices that run compute shaders over writable storage textures. The reference implementation.
zgui-render-vector-coverageCoverageRasterDevices 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 = 4 in coverage.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 devicePer window
Device, queue, adapter, compiled pipelines, on-disk pipeline cache, the Vello rendererSurface 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::open reads them, so a device without dual-source blending draws text with ordinary coverage, and so on.
  • Graphics made with with_gpu never 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 return GpuUnavailable instead. Gpu::is_adopted() and SharedGraphics::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 from DeviceLoss::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):

KindDrawsBlend
QuadRounded, bordered rectangles.premultiplied over
ShadowBox shadows, outer and inset.premultiplied over
DecorationUnderline, overline and strikethrough.premultiplied over
MonoSpriteSingle-channel coverage tiles: glyphs, atlas masks, path glyph cells.premultiplied over
SubpixelSpritePer-channel coverage tiles, on an opaque destination.dual source, no alpha write
ColorSpriteFull-colour tiles: images, colour emoji, CPU vector layers.premultiplied over
MarksDisc, MarksBox, MarksPolyline, MarksGlyphOne payload kind of a mark, painted directly.premultiplied over
MarksDiscCoverage … MarksGlyphCoverageThe same kinds, writing coverage into a union bin.add; polylines take the max
MarksCompositeA union mark, painted through its bin.premultiplied over
VectorCompositeA rasterised vector pass.premultiplied over
CompositeAn isolated group target into the target beneath.premultiplied over
ExternalA texture the renderer did not draw.premultiplied over
DamageClearOne damage rectangle, cleared by drawing over it.replace
BlurDownsample, BlurAxisThe steps of a blur.replace
Blit, BlitUndoSrgbThe 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;
  • finish unmaps before submission, and recall starts 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 boundaryReason
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

  1. 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 for plan_uncut_passes first. It then calls plan(), clears and prepares round 0, before the frame's encoder exists.
  2. r.plan. The mark bins come from Scene::mark_plan(), or are planned again with Scene::plan_marks when the frame was widened. MarksScratch is sized to the plan's pages.
  3. 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:

  1. The coverage pipelines write into the bin: polylines first (keeping the largest coverage of their segments), then discs, boxes and glyphs adding to it.
  2. MarksComposite paints 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:

  1. the composed target outlives the frame, and every pass on it uses PassLoad::Keep;
  2. the scissor stops every draw of the frame, including the clear, from writing outside the rectangle;
  3. 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):

PresentPacingModeWho paces
DisplayFifoSurface acquisition blocks until the display frees an image.
PlatformMailbox, else Immediate, else FifoCompositor 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):

  1. Configure the surface if needed, recover a lost device, widen damage, and return Undamaged if there is nothing to do.
  2. Prepare side tables and stage effect parameters (r.tables), rasterise round 0 of the vector plan (r.vectors), and plan the frame (r.plan).
  3. 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.
  4. 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.
  5. Acquire a surface texture (acq.in), blit the composed target onto it (a four-vertex strip, one textureLoad per fragment), submit once (sub.out), and present (pres.out).

Surface acquisition

Acquisition has seven answers (crates/zgui-render-wgpu/src/target/acquire.rs):

AnswerPresentsReconfigureRecreate surfaceFull damage next
Successyes
Suboptimalyesyes
Timeout
Occluded
Outdatedyesyes
Lostyesyesyes
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:

TextureKindFormatHoldsSampled
MonoR8UnormGlyph coverage, atlas vector masks, path glyph cells.nearest
SubpixelRgba8UnormPer-channel glyph coverage.nearest
ColorRgba8UnormColour glyphs and emoji, premultiplied.nearest
ImageRgba8UnormDecoded 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

FeatureMechanism
Solid fillOne Quad. PaintRef carries the paint family beside the index, so a solid fill never reads gradient stops.
Edges and antialiasingEach 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 cornersA 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.
BorderSame instance as the fill. An inner distance against the box shrunk by each side's width selects the border colour.
Dashed and dotted borderLaid 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.
GradientEvaluated 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 shadowOne Shadow, analytic: a closed-form erf integral horizontally, four samples vertically. Shadow::BLUR_EXTENT = 3.0 standard deviations.
Inset shadowThe 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 shaderOne 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 filterA custom step in a group's filter chain. Its declared reach grows damage and bounds the source region.
TextOne 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.
DecorationsOne Decoration with style Solid, Wavy, Dashed, Dotted or Double.
ImageA ColorSprite with elliptical corner radii and a grayscale flag.
Recognised vector shapesAnalytic Quads, or Marks drawn from a payload (drawing marks).
CPU vector layerA ColorSprite from the image pool, or one per 512-pixel tile of a large layer.
Path glyphsA mark whose glyph words read Mono atlas cells, sixteen sub-pixel phases per outline.
General vector itemRasterised into a scratch bin, then drawn with VectorComposite.
Opacity groupFolded into each primitive's paint when no two primitives of the subtree overlap; otherwise a pooled target composited with the group's alpha.
Filter chainChain::of folds consecutive per-pixel functions into one colour matrix. Blur breaks the fold; split() hands the trailing matrix to the composite.
BlurA 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 filterA blurred copy composited with COMPOSITE_TINT (flat colour times alpha) at the offset.
backdrop-filterEncoderOp::Capture copies the region beneath into a pooled target; the chain runs; the result composites back.
ClippingEvery 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).
TransformEach 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 targetsGroupPool, 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

MistakeConsequence
Returning a damage-keeping skip for the wrong reasonUnconfigured, Unacquired and DeviceUnavailable keep damage; every other skip retires it.
Culling against damageThe display list already did. A primitive that reaches draw reaches the damage.
Calling batches() on an unfinished sceneIt 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 markerspush_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 surfaceLegal, but every frame must then be full damage.
Pooling targets and leaving target_pool() defaultedThe budget check catches it.
Drawing an external quad against another textureA 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):

Stagep50p90p99max
get_current_texture0.028 ms0.10112.80230.808
blit and queue.submit0.175 ms0.3230.5581.811
present0.103 ms0.1810.2711.003
whole present path0.327 ms0.62913.00331.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.

CostGrows with
Draw callsBatches × damage rectangles.
damage_pxArea of the damage rectangles clipped to the surface.
bytes_uploadedAtlas misses, new or transient primitive bytes, mark payloads, changed remaps and side-table ranges. Replays upload nothing, moved or not.
Vector passesThe general vector plan; rounds only when the passes exceed one scratch capacity.
Mark binsUnion marks that reach the damage (MarksUnionBins).
Pool memoryWhat the document nests, not what it draws.

Next

On this page