UI retention and drawing
Understand how the UI engine retains layout and how the render pass draws before you change either.
Read this page before you change the layout engine, UiRenderPass, or the
text system. It explains how every UI stage reuses its result while its inputs
repeat, how one draw covers the whole UI, and how text is drawn from outlines.
To build an interface with the module, follow
Build a user interface. Its depth order and limits are in the
UI reference.
Add a UI feature
When you add a UI feature, follow the existing route:
- build or update a primitive
- let layout evaluate geometry, clipping, and retained identity
- let
UiRenderPassconsume the render data
That path keeps UI code testable and avoids coupling application widgets directly to renderer resource ownership.
Retention and invalidation
Unchanged UI must cost nothing beyond the draw calls themselves, so every stage retains its result and reuses it while its inputs repeat. The contract is one chain of revisions:
- The retained tree advances a revision whenever an element is added, removed,
or changed through
update_container,update_text,update_curve, and the other update methods. The engine compares the element before and after each edit, so an edit that writes the values it already has changes nothing, and re-declaring the same element path on a later frame doesn't count either. Engine::evaluatereuses the retained layout while the tree revision and the viewport size repeat. Input routing and task polling still run every frame.Engine::renderreturns a reference to the render retained by the engine. It keeps the sameRender::revisionwhile the tree, its layout, and the viewport are unchanged, so clone it only when the revision moved.Engine::renderalso reports damage:Render::damagereturns the previous revision and the layout-unit rectangles whose pixels differ from it, built from the same per-node revisions. A consumer holding pixels for that base revision redraws only inside those rectangles. Anyone else redraws everything. A viewport change reports no base, meaning everything changed.UiRenderPasskeeps a persistent transparent UI layer. Each frame it clears and redraws only the damaged pixel regions (plus every visible backdrop blur, which samples the scene rendered that frame), then composites the scene under the layer. Primitives, uploads, and glyph residency are rebuilt only for the elements touching that damage, and only when the adopted render revision, the viewport extent, the glyph generation, or the damaged regions change. A frame with no damage records only the composite.
Drawing
UiRenderPass draws the whole UI with one shader pair and no vertex or index
buffers. Every rectangle layer, glyph, image, backdrop blur, and curve piece is
one 80-byte primitive in a storage buffer, written in painter order: by depth,
then by element, across all element types. The vertex shader pulls six vertices
from each primitive, and the fragment shader branches on the primitive's kind.
A primitive is constant across its quad, so each branch is coherent, and a plain
square fill skips the corner, stroke, and mask math entirely.
A frame is one draw per damaged region. Only a backdrop blur adds draws, because it reads the layer drawn below it: the primitives before it are drawn, its compute passes run, and its own quad starts the next draw. Damaged regions are cleared by the same shaders with blending turned off, in the same pass. When the damage covers the viewport, the attachment's clear does it instead.
Curves
Curves are evaluated on the GPU. The CPU doesn't flatten, clip, or cache them:
it converts each segment to a cubic in pixels, picks how many pieces to draw it
in, and writes that many copies of the control points. The vertex shader cuts
piece k out of the cubic, fits the quadratic closest to it, and bounds it
with a box along its chord. The fragment shader finds the closest point on that
quadratic in closed form and shades by the exact distance. A line or a quadratic
is exact, and a cubic stays within 0.05 pixels.
The piece count grows with how far the curve bends and with zoom, so a straight line is one piece at any length and a typical node-graph wire is six to eight.
Each pixel is shaded by exactly one piece of a segment, the one whose part of the curve it's closest to, so translucent strokes have no seams. Path ends and corners are round. Where two segments meet smoothly, neither draws a cap. At a corner, the segment that starts there rounds it, and a translucent stroke is blended twice where that cap overlaps the previous segment.
A curve's clip is tested per pixel because its quads aren't axis aligned. Every other element is still trimmed on the CPU.
Text rendering
Text is drawn from glyph outlines on the GPU with the Slug algorithm by Eric Lengyel. The text system reads each glyph's quadratic curves from the font once, in em units that don't depend on a font size. The render pass packs them into two storage buffers: the curves, and bands that list the curves crossing each horizontal and vertical slice of the glyph. Every visible glyph becomes one primitive, drawn in painter order in the same draw as rectangles, curves, and images, and the fragment shader computes each pixel's exact coverage from the few curves in its bands.
Measurement and placement use the same size-independent advances, so layout and drawing never disagree.
The glyph buffers hold a few thousand glyphs. When they fill up, they're emptied to hold only the glyphs of the current frame. This advances the glyph generation, which invalidates prepared frames automatically. Glyphs that still don't fit are skipped and reported once in the log.
Switch to the glyph atlas renderer
The previous renderer is still in the engine. It rasterizes each character on the CPU once per whole pixel size, packs the coverage into one atlas texture, and draws pixel-aligned quads that sample it. Use it to compare output or performance, or on hardware where per-pixel curve evaluation costs too much.
To switch, set UI_TEXT_MODE in crates/byte-engine/src/ui/render_pass.rs to
UiTextMode::Atlas and rebuild. Both renderers emit primitives for the same
shader and share the draw list, clipping, and damage rules, so nothing else
changes. The atlas is the first element of the image texture array.