blog.dopana

Back

Have you ever wondered why the Zed code editor feels so smooth? It’s thanks to GPUI - the UI framework developed by the Zed team. But GPUI has a problem: it operates in “immediate mode” - meaning every frame, it redraws the entire interface even when only a tiny number has changed.

Imagine you’re editing a spreadsheet with thousands of cells. Change just one cell, and GPUI would redraw the entire spreadsheet from scratch. That’s wasteful!

The Problem: Immediate Mode#

GPUI follows a 3-step process for each frame:

  1. request_layout: Render views and request layout
  2. prepaint: Compute layout and place elements
  3. paint: Convert elements into scene for GPU rendering

The problem is: GPUI repeats all 3 steps every frame, even when almost nothing changed. The cost of a frame is close to the cost of the entire window, not the cost of what actually changed.

// Example: table with 60 panels, each panel has 64 labels
// Change 1 label = redraw 3840 labels!
rust

The Solution: Retained Mode#

gpui-fast is an experimental project by Longbridge that solves this problem with Retained Mode - only redrawing what changed since the last frame.

How It Works#

Instead of redrawing the entire element tree, gpui-fast:

  1. Tracks dependencies: Remembers what data each view reads (entities, globals, scroll state)
  2. Checks for changes: If nothing the view depends on changed, and it’s still in the same position → reuse output from previous frame
  3. Splices when needed: If parent view unchanged but child view changed → only rebuild child view and “splice” it into old output
  4. Keeps layout nodes: Layout nodes, text measurements are preserved across frames to avoid recomputation

Comparison: Immediate vs Retained#

Retained Mode gpui-fastImmediate Mode GPUINo changeChangedFrame startsRender all viewsBuild new element treeLayout entire treePrepaint everythingPaint everythingGPU renderFrame startsCheck dependenciesReuse old outputRebuild only changed partsSplice into old outputGPU render

Technical Details#

Identity: Finding Elements Between Frames#

gpui-fast doesn’t keep a parallel UI tree. It uses GlobalElementId - the path from root to view - to identify each view:

View reached during frame
    ↓
Its GlobalElementId
    ↓
RetainedSubtree from previous frame
    ↓
Check dependencies and position
    ↓
Decide: reuse, splice, or rebuild
text

Dependency Tracking#

While a view runs, gpui-fast records:

  • Entities it accessed
  • Globals it read (with generation stamps)
  • Versioned state: ScrollHandle, ListState with version bump on change
  • Ambient input: Mouse position, modifier keys

This allows gpui-fast to know exactly which views need rebuilding when data changes.

5 Paths When Rendering a View#

PathWhenWhat happens
ReusedNothing it depends on changed, still in same positionLayout from kept nodes, prepaint/paint ranges copied from previous frame
SplicedOnly nested view changedCopied from previous frame in stretches, with changed nested views rebuilt in gaps
Built at retained layoutMoved or inherited style changedRendered again at layout nodes it kept
PrebuiltNested view already built for spliceParent view takes already-built nested view instead of building it twice
BuiltAnything elseRendered, laid out, prepainted and painted as upstream does

Real-World Performance#

In benchmark with 60 panel views (each panel 64 labels):

Panels notified/frameUpstream GPUIgpui-fastReduction
None (animation)3.31 ms0.19 ms-94%
1 panel6.72 ms0.71 ms-89%
6 panels7.27 ms1.46 ms-80%
All 6010.33 ms7.38 ms-29%

In real application (gpui_perf showcase):

  • Spinner animating: 5.91ms → 0.73ms (-88%)
  • Scrolling sidebar: 5.95ms → 0.79ms (-87%)
  • Scrolling data table: 3.07ms → 0.54ms (-82%)
  • Streaming quotes: 5.06ms → 1.35ms (-73%)

Why This Architecture?#

gpui-fast follows 3 important constraints:

  1. Frame from scratch is the spec: A retained frame is correct if and only if it matches the frame upstream GPUI would have drawn from scratch. This can be tested mechanically.
  2. Public API stays unchanged: Code written for upstream GPUI compiles and runs unchanged. No opt-in needed, nothing new to learn.
  3. Upstream code stays upstream: gpui-fast logic lives in fast/ directories. Upstream files get only small hooks.

This allows gpui-fast to merge upstream changes easily and each piece can be proposed upstream separately.

How to Use#

gpui-fast is an experimental project. The public API is upstream’s, so code written for upstream GPUI compiles here unchanged.

One thing to know: state that a view’s render reads that gpui-fast cannot observe (like Rc<RefCell<..>> outside an entity, the time) needs a cx.notify() when it changes.

# Cargo.toml
[dependencies]
gpui = { git = "https://github.com/longbridge/gpui-fast" }
toml

Scrolling with GPU Tiles#

Scrolling is a special case - everything in a scroll container moves so no view is drawn where it was. gpui-fast handles this by keeping scrolled content as cached GPU tiles and compositing at the new offset.

References#