GPUI Fast: Retained Mode for GPUI
How gpui-fast makes GPUI render faster by only redrawing what changed
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:
- request_layout: Render views and request layout
- prepaint: Compute layout and place elements
- 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!rustThe 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:
- Tracks dependencies: Remembers what data each view reads (entities, globals, scroll state)
- Checks for changes: If nothing the view depends on changed, and it’s still in the same position → reuse output from previous frame
- Splices when needed: If parent view unchanged but child view changed → only rebuild child view and “splice” it into old output
- Keeps layout nodes: Layout nodes, text measurements are preserved across frames to avoid recomputation
Comparison: Immediate vs Retained#
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 rebuildtextDependency 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#
| Path | When | What happens |
|---|---|---|
| Reused | Nothing it depends on changed, still in same position | Layout from kept nodes, prepaint/paint ranges copied from previous frame |
| Spliced | Only nested view changed | Copied from previous frame in stretches, with changed nested views rebuilt in gaps |
| Built at retained layout | Moved or inherited style changed | Rendered again at layout nodes it kept |
| Prebuilt | Nested view already built for splice | Parent view takes already-built nested view instead of building it twice |
| Built | Anything else | Rendered, laid out, prepainted and painted as upstream does |
Real-World Performance#
In benchmark with 60 panel views (each panel 64 labels):
| Panels notified/frame | Upstream GPUI | gpui-fast | Reduction |
|---|---|---|---|
| None (animation) | 3.31 ms | 0.19 ms | -94% |
| 1 panel | 6.72 ms | 0.71 ms | -89% |
| 6 panels | 7.27 ms | 1.46 ms | -80% |
| All 60 | 10.33 ms | 7.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:
- 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.
- Public API stays unchanged: Code written for upstream GPUI compiles and runs unchanged. No opt-in needed, nothing new to learn.
- 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" }tomlScrolling 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.