Retained views make a frame cheap when views did not change. Scrolling defeats them: everything inside a scroll container moves, and a retained view is only drawn again where it was drawn before, so every view in the scrolled content is built again on every scrolled frame. Scroll layers handle that case the way UIKit, Flutter and Chrome do. A scroll container's content is rasterized once into cached tiles, and a frame in which only the scroll offset changed draws those tiles at the new offset instead of building the content again.
The design is in
superpowers/specs/2026-09-30-scroll-layers-design.md.
This page covers how the pieces fit together, when a container falls back to
drawing as it does without layers, and how to verify and measure layers.
- Linux, on the wgpu renderer; macOS, on the Metal renderer; and Windows, on
the Direct3D 11 renderer. Everywhere else layers are compiled out
(
fast::layers::COMPILED), and nothing changes. - Scrolling
divs (overflow_x_scroll/overflow_y_scroll), whether their content is a child view or plain elements in the same view. uniform_listandlist(fast::layers::lists), unless flipped vertically. A list's layer holds the rows its viewport shows and two viewports of rows on each side, each row kept apart:- A frame that only scrolled the list renders only the rows the scroll brought into the overscan, the rows whose hover changes and the rows that show again after leaving the viewport. Every other row it keeps: it is not rendered, laid out, prepainted or painted, and its hitboxes, listeners, element states and dispatch nodes are carried from the last frame, its hitboxes moved by the scroll since the row was painted.
- The frame hit tests the pointer between prepaint and paint, and hover styles are painted by that. Which rows to render again for their hover is decided as the rows prepaint, so the hit test is foretold: the last frame's hitboxes, the rows' moved to where they show now. Only the rows whose hover changes are rendered again, not the whole layer.
- A list without a layer drops the element states of a row it no longer shows (a nested scroll offset, say). A row leaving the viewport is neither rendered nor keeps its element states that frame, and is rendered afresh before it shows again.
- The layer's content is one part per row (
LayerContent), and it has no tiles: a composited frame replays into the frame the paint operations of the rows that reach the viewport, moved by the scroll (fast::layers::paint::replays). That costs the frame what painting the rows it shows costs, without rendering, laying out or prepainting them again, and leaves nothing to rasterize, keep within a tile budget or bake a background into. Rows past the overscan are dropped a batch at a time. - The first frame painting a list's layer paints the whole overscan. A
frame painting it afresh after that, for a change of its content, paints
only the rows the list shows, as the list does without a layer. A frame
that keeps the rows renders no more than three quarters of a viewport of
rows, those it shows that the layer lacks first: the rest of that budget
grows the overscan, three quarters of it on the side the list scrolls
toward (
fast::layers::lists::RENDER_PER_FRAME_VIEWPORTS). A view holding the list that is notified now and then, as a chat transcript is when it reaches its end, does not rebuild five viewports of rows each time, and a scroll faster than the overscan grows renders the rows it shows, not five viewports of rows around them. - A view holding a
listthat asks only whether the list is scrolled to its end (ListState::is_scrolled_to_end) as it renders, as a chat transcript does to show a "back to bottom" button, is taken to have read only that: a scroll that leaves the answer as it was does not change what the view renders, and the layer is composited. Reading the list's offset itself (logical_scroll_top,scroll_px_offset_for_scrollbar, ...) as it renders keeps the list off its layer.ListState::scroll_to_endon a list already at its end, as a view keeping its list there calls on every render, changes nothing. Nor doesScrollHandle::scroll_to_bottomon a handle already at its bottom (fast::layers::scroll_to_bottom). - A scrollbar dragging a
list(ListState::set_offset_from_scrollbar) scrolls it as a wheel does: the offset it sets is taken for a scroll, not for a change of the list, and the view holding the list, which the scrollbar notifies, draws it from its layer.
- While accessibility is active, a
div's layer keeps the accessibility nodes its content added as it was painted, and a composited frame adds them again moved by the scroll since, as it does the content's hitboxes. Content holding synthetic nodes with bounds of their own (a11y_synthetic_children) is painted again instead, as nothing says the code placing them moves them with their element. Virtual lists draw without their layer while accessibility is active: the layer holds rows the list does not show, whose nodes a list without a layer leaves out of the tree. GPUI_SCROLL_LAYERS=0turns layers off for a process.Window::set_scroll_layersdoes the same for one window in tests.
While a wheel scrolls under a still pointer, hover is held still
(fast::layers::hover_freeze): for 100 ms after a wheel event, as long as the
pointer stays where the event was, nothing is hovered. Otherwise every frame of
the scroll hovers another row, rendering the row it leaves and the row it
enters again, and an animation a hover starts (a card fading in) keeps the
list off its layer. When the wheel stops the window is drawn again and hover
follows the pointer; a pointer that moves ends it at once. The crate's own
tests, which scroll under a still pointer to test hover as rows move, turn it
off (Window::set_hover_freeze).
A container gets a layer once it has scrolled on two consecutive frames. On
each frame it then takes one of three paths (fast::layers::policy::decide):
- Composite. Only the scroll offset changed: no view in the content was
notified or read anything that changed, and no hover changed. The content is
not prepainted or painted. Its hitboxes are carried over, translated. Its
listeners, cursor styles and dispatch subtree are carried over too
(
fast::layers::reuse). The tiles that cover the viewport go into the scene as polychrome sprites with reserved texture ids. - Repaint. The content changed, or the scroll reached the edge of what was
painted. The content is painted into the layer's own scene over the viewport
plus two viewports of overscan on each scrolled side (
fast::layers::paint::OVERSCAN_VIEWPORTS). Each tile is hashed, and the renderer rasterizes again only the tiles whose hash changed (fast::layers::tiles), and only once a frame shows them: a dirty tile in the overscan waits, so a list whose rows keep arriving at the edge of its overscan does not rasterize the tiles there on every frame. - Bypass. The frame is drawn exactly as it would be without layers. This
happens when a layer cannot guarantee identical pixels or current window
coordinates, for example:
- the background under the viewport is not one opaque solid quad (a list's rows are replayed over whatever is under them instead);
- the content has deferred or anchored elements, a focused input, or
surfaces, or something in it (an element, or a view drawn in it) asked
for an animation frame this frame or the last. Whether it still does is
only known by painting it into the layer again, which costs a repaint
for nothing while it does: the layer is dropped but not demoted, and
painted again 8 frames later, then twice as long after each attempt
that finds the content as it was, up to 256 frames
(
fast::layers::policy::RETRY_AFTER_INELIGIBLE_FRAMES). The focus leaving an input in the content ends the wait at once; - the view holding the container asked for an animation frame from outside the content (a scrollbar fading beside a list, a pulsing button): it renders again on every frame the animation runs, and rendering the content again with it costs more than drawing it without the layer. The layer is dropped but not demoted, and painted again as soon as the animation stops. An animation in a view around the one holding the container leaves the layer composited;
- the scroll moved past everything the layer holds since the last frame, as a scrollbar's thumb dragged fast does: the layer is dropped, and is not promoted again while the scroll moves by a viewport or more a frame;
- the content changes on at least eight of the last sixteen frames, or the layer's estimated work exceeds drawing directly (demotion, below).
The view holding the container is notified by the container's wheel
listener, and a frame is taken for a scroll only while that view was
notified no more often than the wheel scrolled what it holds. Other wheel
listeners react to the same scroll: GPUI Kit's scrollbar notifies the view
again when the offset moved since it last saw it, to show itself. A
notification of a view sent while a wheel event is dispatched, when the event
scrolled a container that view painted, counts as one for the scroll as long
as nothing else changed while the event was dispatched: no entity was
updated or written and no global changed (fast::layers::wheel). A wheel
listener that updates an entity and notifies changed the content, and the
layer is painted again. What this assumes is that state outside entities
that a listener changes in reaction to a scroll, and notifies the view for,
does not change what the view renders inside the scrolled content: the
scrollbar beside it is drawn afresh, the content is not. State that does
belongs in an entity the listener updates.
The demotion policy also tracks rebuilding work over the last 32 completed
layer frames (fast::layers::work), in units of drawing the visible content
directly. Virtual lists count the rows they rendered, by their height against
that of the rows shown (or of the viewport, if taller) and by their paint
operations against those of the rows shown; other scroll containers count painted primitives relative to
those visible in the viewport. Scroll extensions, hover changes and input
rebuilds count too. Painting content afresh costs about twice what drawing it
directly does (its tiles are hashed and its records rebuilt besides), and a
repaint's work is counted at REPAINT_COST times. The initial cache build is
excluded, and a quarter of each frame's budget is reserved for cache
bookkeeping and tile rendering. A layer whose estimated work reaches direct
drawing's budget falls back even if updates occur on fewer than half the
frames, and one whose last six frames cost more than drawing directly, their upkeep
included, half of them each costing more, falls back at once, without waiting
for the 32-frame average. Two content refreshes that each rebuild more than two
visible regions within 120 frames of each other also trigger fallback: broad
updates must not keep causing latency spikes. Refreshes further apart than
that are paid back by the frames composited between them. One isolated update
and the initial cache build are not enough to trigger either guard.
A list's layer is not demoted: replayed, painting its rows afresh costs what drawing them without it does, and every frame between two changes is composited for the cost of replaying the rows shown.
Demotion releases cached rows and resets the fixed-size work history. The first cooldown requires 60 stable frames; repeated demotions double that wait, up to 1920 frames, so periodic refreshes do not keep rebuilding and discarding the cache. An update during cooldown asks for 60 more stable frames from it, so a view notified every few seconds gets its layer back between notifications. A repaint for a change that left every row it painted as the layer held it does not count as a changed frame. After 1920 quiet frames the backoff resets. This is a work estimate, not a measurement of GPU time, and does not depend on the monitor's refresh rate.
Paths are never rasterized into tiles: the path shaders antialias with
screen-space derivatives (dpdx/dfdx/ddx), taken within the 2×2 pixel
quads the GPU shades together, so a tile composited at an odd translation can
come out one level apart on a path's edge pixels. Instead the content is split
(fast::layers::overlay): its paths, and everything drawn after a path or
after such a primitive that overlaps it, are the layer's overlay, kept out
of the tiles and drawn over them in the frame, in drawing order, wherever the
layer is composited. On every pixel the primitives drawing it are then drawn
in the same order as without a layer, and the paths are rasterized where they
show. A list's layer, which replays its rows, draws their paths in order with
the rest and has no overlay. A table in a rounded frame, whose corner notches are paths under the
frame's border, composites with only the paths and the border drawn each
frame.
A virtual list's layer keeps what each row read apart from what the list read
besides (fast::layers::lists). While a row renders, is laid out, prepainted
and painted, the entities it reads are logged under it; the record keeps only
what the rest of the list read. A frame that finds a row's reads changed, or a
view drawn in it notified, still composites: it renders that row again, alone,
as it does a row whose hover changed. A row the list only measured, without
prepainting it, is not the layer's, and nothing it read is kept.
What the list and its rows write while the list is built — a row noting in a
model the rows read that it was drawn — is part of building the list, not a
change of the rows the layer keeps. So is what a row writes while it is laid
out, prepainted or painted, as a chart in it fills its own path cache: the
row is not rendered again for it. A row reading what another row writes as
it is drawn, as rows sharing one cache do, is. What the view holding the list writes in
its render, as a sidebar writing the items its rows show into a model they
read on every render, is judged with that render, by what the view read: the
rows the layer holds are not all rendered again for it.
When the view holding a list renders again for something the layer cannot
tell apart (a notification, a change of what it read itself), it may hand the
list a different row renderer. The frame still composites: the list renders
the rows it shows again, and every other row the layer holds is marked suspect
and rendered again before it shows. A list whose item count changed is
painted afresh instead, as its rows moved to other indices.
Rows keep their layout nodes: each row the layer holds keeps the keys its
layout claimed (and only its own, though a list lays out every row it shows
before it prepaints the first), and a row's nodes outlive it for 240 frames
after it leaves, so scrolling back over it reuses them and the measurements
they carry instead of shaping its text again. That holds for the nodes of a
view in the row too, which a row that moved lays out again as the list
prepaints it, outside the row's own layout: chat-drag, dragging a
transcript's scrollbar back over rows it showed moments before, lays none of
them out afresh.
- Scroll offsets are snapped to device pixels wherever layers are compiled,
with or without a layer, so both paths put content on the same grid. Glyph
origins are quantized so that a whole-pixel shift moves them by exactly that
shift (
fast::glyphs::quantize_origin). On screen the result is unchanged. - Tiles are cleared with the baked background, so subpixel text blends exactly as it does on screen.
- Metal's gradient dither is seeded from the position within the quad, not on screen, so a gradient gets the same noise in a tile as in the window.
- Before any input other than the wheel reaches a layer that has moved since
it was painted, the layer is repainted (
fast::layers::input). Listeners, element state and anything handed to application code therefore hold current window coordinates. A list's rows are painted over many frames, at as many offsets: any row painted at another offset than the one shown counts as moved. - A list's rows are painted in a region reaching far above and below the viewport instead of inside the list's own clip, so that no edge of what a row was painted in clips it once it has moved; the viewport clips it where it is composited, as the list's clip does without a layer.
cargo test -p gpui --features test-support --lib fast::tests::layersincludes the layer oracle (fast/tests/layers_oracle.rs). It runs random histories of wheel scrolls (including fractional deltas at scale 1.25), hovers, clicks, keys and content changes through a window with layers and a window without. Every frame it compares the expanded scenes, hit tests and the positions listeners observe.cargo test -p gpui_wgpucompares rasterized and composited tiles with direct drawing, byte for byte, on a surfaceless device.cargo test -p gpui_apple fast::layersdoes the same on macOS with a headless Metal renderer (crates/gpui_apple/src/fast/layers/), which draws tiles as the wgpu renderer does.cargo test -p gpui_windows --features test-support fast::layersdoes the same for the Direct3D 11 renderer (gpui_windows/src/fast/layers/), on a hardware device or WARP, on Windows.cargo run -p gpui_perf --release -- --headless --verifyalso runs the scroll scenarios with layers on and off.
The gpui_perf headless scroll scenarios dispatch real wheel events with the
pointer over the content. Linux, release build, retained views on, 300 frames:
| Scenario | Layers off | Layers on |
|---|---|---|
scroll-child-view |
0.619 ms, 8.83M instructions | 0.066 ms, 0.88M instructions |
scroll-same-view |
0.578 ms, 8.59M instructions | 0.232 ms, 3.19M instructions |
scroll-uniform-list |
0.397 ms, 5.36M instructions | 0.137 ms, 1.62M instructions |
scroll-list |
0.377 ms, 5.11M instructions | 0.147 ms, 1.70M instructions |
The chat scenarios, macOS (Apple silicon), release build, retained views on, 300 frames:
| Scenario | Layers off | Layers on |
|---|---|---|
chat-scroll |
0.250 ms, 3.58M instructions | 0.090 ms, 1.22M instructions |
chat-scroll-no-button |
0.249 ms, 3.56M instructions | 0.093 ms, 1.21M instructions |
chat-scroll scrolls a transcript of 160 messages, each body a view of its
own holding paragraphs, code blocks and tables, away from its end and back,
while the view holding it follows the end, asks whether the list is at its
end and fades a "back to bottom" button in and out. Before the list's layer
told a read of only that from a read of its offset, and painted only the rows
shown when the view was notified, the layer was composited on none of these
frames (0.262 ms, 3.60M instructions), and chat-scroll-no-button on 80 % of them (0.137 ms, 1.81M).
Every scenario composited its layer on all scrolled frames. In the list scenarios the pointer stays over the rows, 40 px of wheel a frame over rows about 48 px tall: most frames render one row entering the overscan and two whose hover changed, and, scrolling back, one row showing again after it left the viewport. Drawn without a layer, each frame renders about 20.
GPUI Kit's Button story, measured before the overscan was raised to two
viewports, at 145 Hz, with one wheel event per frame, over two 12-second runs
of each (a later run against main, same setup: 27-28 % and 1.53-1.57 ms on
main, 18-19 % and 0.92-0.93 ms with layers):
| Process CPU | Main-thread draw per frame | |
|---|---|---|
| Layers off | 23–41 % (mostly 26–33 %) | 1.26–2.38 ms (mostly 1.5–1.9) |
| Layers on | 17–30 % (mostly 18–22 %) | 0.83–1.73 ms (mostly 0.9–1.1) |
With layers on, 89 % of frames were composited. The rest were repaints as the scroll crossed the overscan.
Most of what remains in the Button story is GPUI Kit, not the scrolled content.
GPUI Kit writes window-wide state during render (sync_focused_input_registry,
GlobalState, SelectionStateRegistry), which rebuilds the ancestor views on
every scrolled frame.
Refresh workloads can be measured with the same release build using
GPUI_PERF_STREAM_MS, the showcase workspace's quote interval in milliseconds
(default 16), and switching only GPUI_SCROLL_LAYERS. For example:
GPUI_PERF_STREAM_MS=133 cargo run -p gpui_perf --release -- --auto --only WorkspaceScroll --retention on --frames 600
GPUI_PERF_STREAM_MS=133 GPUI_SCROLL_LAYERS=0 cargo run -p gpui_perf --release -- --auto --only WorkspaceScroll --retention on --frames 600