GG-UI — Rendering

From Snapshot to Pixels

UI update (on jobs)                                   Encoder
───────────────────                                   ───────
Update        re-run what changed
UpdateBindings
UpdateLayout
Paint         nodes → primitives, glyphs → atlas      read latest snapshot
Publish       snapshot + primitives + atlas edits ──► upload changed ranges
                                                      one draw per window, after the scene

• Published, not shared. Encoder reads a published snapshot and never touches rows the UI update is writing: the same contract as the published sim frame.
• Only what changed. An idle document paints nothing, publishes nothing, and uploads nothing.
• The GPU does the per-pixel work. Rounded corners, borders, and clipping are evaluated in the fragment shader from a few numbers per primitive. No CPU tessellation, no scissor changes between draws.

The UI Primitive

Every UI draw is one primitive type: an instanced quad. Screen UI writes primitives on the CPU; world UI and sprites will write the same structure from compute, which is why the format is fixed.

48 bytes (UIPrimitive, Paint.h).

A line or a triangle uses the rect for points rather than a box: a line runs from (X, Y) to (Width, Height), Parameter wide, with round ends and one pixel of anti-aliasing; a triangle has corners (X, Y), (Width, Height), and a third in Parameter and the first UV pair. Triangles aren't anti-aliased. An arc is part of a ring in the rect's inscribed circle: U0 is where it starts and U1 how far it reaches, in 65535ths of a turn clockwise from the top, and Parameter the ring's thickness (0 fills to the centre, a pie); its edges are anti-aliased across radius and angle. Radial progress fills and shape arcs are arcs.

• Draw order is a separate list. Primitives are in slots; a list says which slot is drawn when, back to front, blended in linear light. No depth buffer, no CPU sorting.
• Document space, not pixels. The vertex shader applies the surface's transform, so the same primitives serve any surface.
• No vertex buffers. The vertex shader builds each quad from the vertex index and reads the primitive through Buffer Device Address.

The UI Pass

UIPass (renderer) draws a document as one instanced draw. ui.vert.slang builds each quad; ui.frag.slang evaluates clip, rounded box, border, texture, and colour. Per window, per frame in flight, there is a primitive buffer (by slot, overlays after), an order buffer, and a clip buffer.

• The main window's document is drawn after the scene. Something else can be drawn between its nodes and its overlay (UIPass::Part). Every other window with a document is cleared and shows it.
• Blending is in linear light with an sRGB target. Coverage text gets a small gamma correction so thin strokes don't look light.

Not yet: a closed window's buffers are kept until shutdown.

The Engine Texture Table

TextureTable (renderer): the engine's bindless sampled-image table, with the UI as its first user. Materials will use the same table.

• One descriptor array of 4,096 sampled images, partially bound, updated between frames. Four samplers (linear and nearest, clamped and repeating).
• A texture is an index. Indices are recycled after the frames in flight have drained.
• Entry 0 is a white pixel, so a solid primitive is an image primitive with nothing special about it.
• TextureTable::Update writes a rect in place: glyph pages are uploaded by changed rect.
• Textures need host image copy, which the engine already requires.

Text

GGUIText is its own library: TextEngine puts FreeType and HarfBuzz behind the core's text interfaces. It needs no engine and no GPU, so it builds in every configuration and its tests run headless.

• Shaping happens once. Measuring shapes the text, breaks lines, and caches the result as a run. Paint draws from the same run. Runs are shared between nodes with the same text, font, size, and width, and are reference counted.
• Fallback: spaces, punctuation, digits, and combining marks stay in the font of the text before them, so a mark is never split from its letter. Line height and baseline are the style font's. The engine adds Noto Sans Hebrew and Noto Sans Arabic.
• Atlas: glyphs are rendered hinted at the pixel size they are shown at, on first use, into 1024 × 1024 one-byte pages, and sit on whole pixels. A glyph primitive names an atlas page, not a texture; the pass fills in the texture index as it uploads, which keeps the core and the text library free of the renderer.
• Scale: hinted glyphs differ by pixel size, so a UI scale change re-shapes text.
• Fonts are chosen by style class: the default UI font, heading, and mono come from the engine's font directory (Manrope, Space Grotesk, JetBrains Mono).
• Determinism: text metrics enter fixed-point layout at one boundary and are converted there. The fonts are pinned in the build, so the same text gives the same metrics everywhere.
• Rich text (TextRequest::Spans): parts of a paragraph in their own font and size, with padding before and after (a key cap), and inline boxes (an image: one U+FFFC, as wide as its aspect at its line's height). The paragraph is shaped and broken into lines as one; a line is as tall as the tallest font on it. A glyph says which span it is in (GlyphQuad::Span), and GlyphSource::Pieces gives each span's rect on each line, for its background and image. Spans are part of the run's identity, so differently styled text is another run.
• TextEngine::Inspect lists a run's glyphs as drawn; Stats::FallbackGlyphs counts fallback glyphs.

Not yet: the full Unicode line-breaking algorithm (Thai and other scripts without spaces need a dictionary); vertical text; a font for ideographs (they draw as the missing glyph); signed-distance text for world space (the primitive kind is reserved); kerning between runs of different fonts.

Images

ui.Image(handle, props);
ui.Image("ui/coin.png", props);     // looked up when built; a missing file warns once with file and line
ui.Viewport(target, props);         // a render target sized by layout

• An image is an ImageID. The core describes one through an ImageSource (texture, region, pixel size) and never sees files or GPU objects. The source has a revision; documents re-read their images only when it moves.
• Size: unset, an image is its pixel size at 100 %, scaled with the UI. With one axis set, the other keeps the aspect ratio. Its bottom sits on the text baseline.
• Fit (Contain, Cover, Fill, None) places it in a box of another shape, also within an atlas region. Props add a tint, corner radius, and an accessible name (none: decorative).
• Render targets: ui.Image(target) shows it at its own resolution. ui.Viewport(target) takes the size layout gives it: after layout each viewport's pixel size is published (UIContext::Viewports) and the owner resizes to it. Until it does, the old image is stretched.
• UIImages (renderer) is the engine's source: files (PNG, BMP) loaded on first use from the image roots, images from pixels, regions, and targets. Files are RGBA8 sRGB.

ui.Embed(id) is an area something else draws: the document draws nothing there and publishes where it is (GGSnapshot::Embeds, clipped, in UI units). The pointer over it isn't the document's, whatever is under it, unless a popup is over it or the document holds the pointer from a press.

Not yet: the scene shown live in a document outside the editor (the renderer draws straight to the swapchain there, so there is no scene target); images chosen by a binding; removing an atlas doesn't remove its regions.

if (auto canvas = ui.Canvas({ .Width = GGSize::Grow(), .Height = GGSize::Grow() }, [=](GGCanvas& draw)
{
    draw.Line({ 0, 0 }, { draw.Width(), draw.Height() }, { .Width = 2.0f, .Color = axisX });
}))
{
    ui.OnDrag([](const PointerEvent& e) { ... });   // handlers and children inside it, as for a box
}

The Engine Host

UIHost owns the documents the engine shows, one per window, and runs them. Threading is described at the top of UIHost.h.

• The update (re-run, bindings, layout, paint, publish) runs once per display frame, started by Encoder at the start of its frame. The snapshot drawn is the one built for that frame, so UI adds no frame of latency. A heavy update lengthens the render frame, never the sim's.
• Unrelated documents update in parallel on jobs. Related ones (a popup and its owner, a tool and the document it inspects, a dock space's windows) update serially.
• UpdateAll returns on time. A document that overruns the budget keeps updating on its job and is drawn from its last snapshot until it finishes.
• Input arrives on Sentinel, which decides from the last published snapshot whether the UI takes it and queues what it takes. Neither thread waits on the other.
• Bindings read the published sim frame through a reader the host supplies. The default reads EngineStats.
• Headless builds have the core and no host.

Testing

The reference rasterizer samples the atlas and images the way the GPU's sampler does, so text and images are part of the pixel comparison. --ui-test mounts a check document; RequestUICapture reads it back.

Performance

Decisions

Open Questions

• Whether paint is split by subtree when a document is large.
• Rounded clips (a scrolling box with rounded corners).
• Sub-pixel positioning for hinted glyphs: a few horizontal offsets per glyph cost atlas space and give evener spacing.
• Atlas eviction when a document uses many sizes.