feat: global spring animation system (#134)

* feat(config): add animations and animations.slowdown keys

* test(vulkan): cover content clipping when the window rect differs from content

* feat(core): spring velocity, value-type motion with slowdown, retarget keeps velocity

* perf(core): keep the Seq of an unchanged scene and drop it in outputs

* feat(core): one creation and one stop path for animations, off lands instantly

* perf(core): advance only the flipped output's springs and keep the pulse value between its flips

* fix(core): use value-type motions in Monitor.settled after rebase on main

* feat(core): camera transitions for binds, click focus and discrete swipes

* test(core): build the swipe rig's timer mock before core runs

* feat(core): per-window rect transitions with a cached shown layout

* docs: describe animations and their cost

* test(core): guard zero allocations in animate

* test: tighten SameAs, headless and config tests; fix animation doc claims

* fix(core): give an animating screen a fresh scene Seq and keep its fallback timer

An animating screen skips the Scene.SameAs Seq reuse, so the first frame
after an action is flipped instead of waiting for the fallback timer. A
flip of one output keeps the fallback timer while another still animates.
Chained workspace keys keep their spring velocity (recorded in the
snapshot), and rect motions of windows out of the layout are dropped.
screen.stopRects joins the clearing sites; settled/isSettled are renamed.

* test(core): cover fresh Seq, fallback timer, chained velocity and transitions

Adds tests for the animating Seq, the fallback timer under another
output's flips, velocity carry-over, click and discrete-swipe transitions,
a following swipe and framed switches. Folds the pulse transition test
into the slide table, merges the moved-workspace tests, strengthens the
overview test, and removes two duplicates.

* feat(vulkan): export multi-plane DCC render targets

probeModifiers keeps modifiers with 1 to 4 memory planes and records the
counts; exportTarget reads every plane layout and gives each plane its own
file. ExportTargets gains a singlePlane argument (ports.Renderer) that
drops multi-plane modifiers, and logs the chosen modifier and plane count.

* feat(drm): retry single-plane images before linear and close every plane

showImages tries driver images, then single-plane driver images, then
linear. exportImages closes every plane file of every buffer and rejects
buffers with more planes than a framebuffer holds.

* fix(drm): skip the single-plane retry when driver images had one plane

Record the plane count of the last exported images; a refused one-plane
driver image goes straight to linear. TestExportTargetsPlanes now reads
each multi-plane target back, checks plane offsets and skips without a
multi-plane modifier. Clamp the plane count once in exportTarget and log
the exported target at Debug.

* perf(core): presize scene windows and separators, pin publish and moving-window draw allocations

* perf(core): guard publish, overview and partial-redraw allocations, reuse damage scratch

* fix(core): stop the placeholder's animations when the last output is unplugged

The last output's screen stays as a placeholder and kept its rect, camera and
workspace springs, so the fallback timer kept waking core for a screen nothing
draws. Also adds session lock and output unplug mid rect motion tests.

* test(core): animations-on variants of the border and old animations-off tests

Border scene invariants with animations on (weak invariants mid-transition, full
ones once settled), On variants that land every spring on a mock clock for the
workspace, drag, state, unplug, free float and workspace-size tests, and an unmap
mid rect motion test.

* test(core): review fixes for the animations-on variants

Restore the default animations setting of the sized-workspace tests, make the on
variants fail when no spring ever ran, extend the last-output unplug test with a
workspace switch spring and a replug, and share one mock clock between the swipe
and landing rigs.

* perf(vulkan): redraw only the changed rects when a scene's windows move

A scene with a new Seq redrew the whole output. The target now holds the
scene it was drawn from; sceneDelta (zero allocations) gives the union of
the old and new rects of each changed window plus the separators present
in only one scene, and everything else differing forces a full redraw.
The headless frame log gains the redrawn pixel count.

* test(vulkan): pin the sceneDelta-seeded partial redraw at zero allocations

TestRenderSteadyStateAllocations replicates Render's partial sequence for a
new scene Seq with one of two windows moved, asserts the redraw is partial
and that building and clipping its draws allocates nothing.

* fix(vulkan): copy the held scene's slices and split full redraws at the floats start

Output adapters reuse their scene slices in place (DRM overlay frames,
capture), so a target holding them by reference compared a mutated old
scene. hold now copies Windows, Separators, Layers, DropHints and
CaptureIndicators into per-target buffers (no allocation once warm).

sceneDelta also redraws everything when the first window that opens the
floats changes, since the tile lines and the Dim veil are painted there.
Tests cover reused slices, fractional scale, a rotated output, scene and
window Dim, and the Scene field count.

* fix(core): chain rect, camera and switch motions from their exact state at the action time

snapshot(now) samples a copy of every running motion at now for value and
speed, and rectShot keeps the settled rect plus the float offsets, so a
retarget no longer starts from the rounded rect or the last frame's speed.
publish(ctx) wraps publishFrame(ctx, only); c.stepping is gone.

* refactor(core): read the clock once per action, test untouched motions of unmoved windows

* feat(scene): add SceneWindow.Fade, drawn by the vulkan walk and never scanned out

A window's Fade (0 opaque, 1 invisible) scales its body fill, its own
border lines, its dim and every content draw by 1-Fade, premultiplied
(solids re-encoded on HDR outputs like solidDraw); a window at Fade 1
draws nothing but still opens the floats. The DRM scanout refuses a
fading or zoomed fullscreen window (window_fade) and the overlay plane a
fading candidate. sceneDelta covers Fade by struct equality (the draw
extent stays inside Rect); a leaving entry appearing or disappearing
changes the list and redraws everything.

* feat(core): fade, dim and scale rect motions, leaving entries and the appear helper

rectMotion gains fade and dim offsets (sprung to the settled Fade, 0 or
1 for a leaving window, and Dim), a scale flag and, for leaving windows,
the last settled placement. refreshShown applies them to the shown
layout: Fade, an added Dim and a Zoom (settled Preview or 1 times the
drawn/settled width) that publish emits as the scene's Preview while the
settled Preview keeps telling input and popups a card from a window.

A leaving motion keeps drawing a window that closed or hid: refreshShown
appends its last placement, Hidden and Leaving, to both the settled and
the shown layout in ID order, so publish's index alignment holds; input,
focus, popups and configures ignore it (Hidden), the scene shows it
(Hidden false, Fade, Preview). It goes once its springs settle, when the
layout shows the window again, or with stopRects. A leaving float keeps
its own border lines.

c.appear(sc, id, now) fades a window in from invisible and grows it from
90 % of its settled rect; c.leave(sc, p, now) does the reverse. Both are
no-ops with animations off. animate stays allocation-free with fade, dim
and scale components; publish budgets are unchanged (36, overview 70).

* fix(scene): carry an animating window's content scale as Zoom, apart from Preview

publish copied the derived zoom into SceneWindow.Preview, which the
vulkan walk reads as "overview card" (opensFloats): an appearing or
leaving float stopped opening the floats, so the veil went missing and
popped back and the tile lines were painted over the fading float.

SceneWindow.Zoom (15 fields) is the content scale of a window whose frame
animates; the walk uses it over Preview for content only, opensFloats
keeps reading Preview. DRM scanout and the overlay plane refuse Zoom > 0
like Preview. sceneDelta covers it by struct equality (the zoomed content
stays inside Rect). Walk test: a zoomed float with scene.Dim and
separators paints the veil and the tile lines under it exactly as
unzoomed; a Preview card still does not.

* fix(core): order leaving tiles under the floats, reuse the settled buffer, clamp dim, snap the zoom on a re-flow

- A leaving tile is inserted before the first window that opens the
  floats, a leaving float appended; both layouts get the same index, so
  a closing tile never flashes over a float (TestLeavingPaintOrder).
- withLeaving builds the settled layout with its leaving entries into a
  reused screen buffer: TestPublishLeavingAllocations pins 28 allocs per
  frame (two leaving + four moving windows per screen), budget 36.
- Dim offsets are clamped into 0..1 on the shown placement and publish
  never emits a negative Dim.
- A re-flow that retargets a running rect motion clears its scale: the
  content snaps to the settled size (the aspect may change), the fade
  goes on (TestRetargetClearsScaleKeepsFade).
- floatDim counts leaving floats, scaled by 1-Fade, so the veil fades
  with the last float instead of dropping at once.
- A leaving window's content settles at the 90 % zoom through show;
  its placement's Preview stays 0.

* feat(core): slide a dropped tile and re-flow its neighbours on drag release

* test(core): follow the bind order on drop, guard the drop's own spring, check every configure, animate the cross-output drop

* feat(core): animate a workspace moved to another monitor

* fix(core): keep the destination of a moved workspace off the switch slide, cover named pulls and mixed geometry

* feat(core): animate a window's open and re-flow its neighbours

A mapped tiled or floating toplevel that shows on the current workspace fades
in and grows from 90 % of its settled rect; the tiles its column displaces
slide from where they were. The map handling is wrapped with snapshot and
transition, the client is configured once, to the final size. Fullscreen,
below floats, stash peeks, a session lock, the overview and animations off
stay instant. Tests that read the scene right after a map get an animations-off
variant and an on variant that settles.

* fix(core): follow a float's first commit in its entrance, drop it only for a fullscreen that applied

A float maps with no size (it commits after the map), so its entrance was laid
out from the default rect and broke the aspect once WindowResized moved the
settled rect. WindowResized now scales the running entrance's offsets and
springs by the settled size ratio, keeping progress and speed. A fullscreen
request that was ignored (grace after the map) no longer drops the entrance.
The headless collector stops in a cleanup.

* feat(core): animate the overview open, close and navigation

Rect motions now run in the overview: toggling it, moving its selection or
clicking a card slides every card drawn before and after from its shown
rect, content scaled through the derived Zoom (clamped to 1, emitted as 1
for a card at its size). Cards the other rows bring in fade in. The click
path hit-tests the shown layout while the cards move.

* fix(core): review of the overview animation: faded cards, carried fades, min-ratio zoom, filtered snapshots

Cards with Fade >= 0.5 take no click, a running fade carries over an
overview state change, a scale motion's zoom follows the smaller of the
width and height ratios, input snapshots only for events that can step the
overview, a map with the overview open is not an overview action, and the
no-camera-slide check is restored as an internal test.

* feat(core): animate the stash show, hide and navigation

toggle-stash-visible makes the windows it brings on screen appear and
the ones it hides leave (fade and 90 % scale, from their last settled
placement); a navigation that brings a window to a margin or sends a
peek off does the same. The peek veil goes through the dim component,
as an offset from the configured Stash.Dim.

* fix(core): chain stash leave and appear from what was drawn, order leaving entries deterministically

A hide during an entrance or a slide starts from the drawn rect, fade and
veil with their speeds; a show during a hide continues the leaving motion
instead of restarting at 90 %. withLeaving replaces the entries the layout
still lists first, then inserts the absent ones in ID order.

* feat(core): a four-finger swipe down shows or hides the stash

* docs: describe the four-finger swipe down on the stash

* feat(core): animate a window's close with a leaving entry, drawn from its last content

An unmap is wrapped with snapshot/transition so the neighbours re-flow, and
a window that was drawn as a tile or an ordinary float (animations on, no
session lock, overview closed, not fullscreen) leaves from its last settled
placement: fade 0→1 and scale 1→0.9 (leave). Lock, animations off, an
overview toggle, a workspace change and an unplug drop it via stopRects.

The empty content wayland emits right after WindowUnmapped would strip the
renderer of the buffer before the scene listing the leaving window arrives.
Outputs now keep their contents in a surfaces.Table: an empty content of a
window the current scene draws keeps the previous one with Acquire zeroed
(the first draw waited on it, wayland closes it on release); the entry goes
once an accepted scene no longer lists the window. The renderer reuses its
existing dmabuf import or shm copy: no vkCmdCopyImage, no extra pass.

Tests: core lifecycle (tiled, float, mid-motion, off, exceptions, lock);
TestUnmapMidRectMotion gains an on variant; surfaces table unit tests
(kept/pruned/Acquire nil/zero allocs); drm and headless Run intake.

* fix(core): a closed window leaves from where it was drawn, ordered by the two-pass rule

unmapWindow hands leaveFrom the snapshot's rectShot of the closed window,
so one closed mid-motion (its entrance, a slide) exits from its drawn rect
and fade with their speeds instead of jumping to its settled rect. Absent
leaving tiles take withLeaving's two-pass order (C6); a tile closed while
the stash hides is drawn before the leaving stash floats, the same on every
publish. configures.prune forgets a destroyed window once it left the
scene: no configure reaches it during or after the fade (tested).

* fix(drm): never put a closed window's kept buffer on a plane; forget its configures

GO-001: wayland releases a closed window's buffer once the output reports
its empty content as seen, so the client may already draw into it while
the leaving entry is composed. The first leaving scene carries Fade 0 and
Zoom 0, so the plane paths need the output's own knowledge: Output.kept
(surfaces.Table.Kept) is passed to scanoutCandidate and overlayCandidate,
which refuse a kept window with reason "leaving". shownBy and headless
flipInfo skip kept IDs (GO-005): nothing is presented to the client.

GO-002: configures.keep held the destroyed window's last configure; xdg
reuses window IDs, so a remap during the fade would withhold the new
toplevel's unchanged tile configure. unmapWindow forgets the ID's sent and
answer state up front. The remap chains the entrance over the leaving
motion (appearFrom), lists the window once and configures it.

GO-003: the kept content's Children are copied with their Acquire fences
zeroed (one allocation per unmap); the package doc states the invariant
(composed only; window capture ends before the leaving scene).

Tests: drm overlay + single leaving tile composed with reason leaving,
direct scanout of a lone leaving fullscreen window refused, shownBy skips
kept; headless flipInfo skips kept; surfaces children copy; core remap
during the fade; leaving dropped by a real lock, unplug, overview toggle
and workspace switch (GO-004).

* docs(core): say an unmapped toplevel keeps its ID when it maps again

* docs: describe the animations, rect redraws and compressed render targets

* perf(core): make the frame fallback timer once and reset it per frame

armFrame built a time.Timer and two closures on every animation frame
(about 4 allocations). Core keeps one ports.Timer, made on the first arm
and Stop+Reset afterwards; frameC is nil while it is not armed. Mock
clocks in tests accept Reset; the multi-output timer test counts resets
instead of comparing channels.

* test(core): measure publish allocations on the flip path and the opening overview

The frame budget drops to 32 (timer no longer allocated) and is measured
on both step paths (fallback timer and a page flip while another screen
animates), with fade, dim and scale motions running. The overview test
toggles through snapshot/transition so its cards' motions are in flight
(70). The leaving budget is its measured value, 24.

* perf(vulkan): compare separator lists index by index before counting

sceneDelta counted every separator in both lists (O(S²) per frame). Equal
lists are one slices.Equal; same-length lists (core emits them in layout
order) only count the pairs that differ by index; the full multiset count
remains for lists of different lengths. Same damage as before. The alloc
test runs with 80 lines, and with a dropped line.

* test(core): benchmark refreshShown with 26 rect motions on 24 windows

Records the per-frame cost of matching motions to the layout (about 5 µs,
33 allocations, all from the layout rebuild) before any change to it.

* test(core): deterministic mid-swipe overview test, shared transition helpers, quitting headless scripts

TestOverviewOpenedMidSwipeDropsIt receives the lift's own scene and then
settles on the stepped clock instead of polling real time. settledOf,
settleShown, configuresOf and drainConfigures live in one file
(settledPlacement was a copy of settledOf). The headless click-focus
variants end their script with the quit bind, so the run stops at ~2.6 s
instead of the 5 s timeout.

* perf(core): settle pixel springs once they stay within half a pixel

A rect, view or workspace spring ran to its 1e-4 epsilon although the
drawn rect is rounded to whole logical pixels: its tail redrew nothing
but still submitted a frame. A spring with Snap settles as soon as the
critically damped solution is bounded within Snap of its target
(|x|(1+1/e) + |v|/(βe) < Snap), so the last frame drawn already equals
the settled one: no jump, exact settle, chaining unchanged. Rect and view
springs snap at 0.5 logical px; the workspace slide at 0.5 px of the
output height; fades and veils (levelSpring) keep the fine epsilon.
Headless V6: empty-delta frames 11.2k -> 9.5-9.9k; per motion 100 px at
165 Hz: 54 -> 47 frames.

* perf(core): drop the veil at once when a float closes or hides

The veil under a leaving float faded with it, which changed Scene.Dim on
every frame of the fade and forced a full redraw of the output for about
300 ms, where the float's own fade redraws only its rect. floatDim now
ignores leaving floats: the veil goes when the float starts to leave.
Deliberate spec change (C0 pinned the fading veil): the veil vanishing at
once is acceptable visually and restores partial redraws during float
close and stash hide. publish keeps a leaving window's configure only
when its workspace still holds it (a hidden stash window), as the comment
always said; a closed one stays forgotten.

* fix(core): a window closed while its stash hide fades keeps that fade

unmapWindow dropped the window's rect motion before starting a fresh exit;
when the motion was already a leaving one (a stash hide still fading) the
fade restarted. It is kept and runs on from where it was, drawn from the
content the renderer kept.

* refactor(core): remove the appear, leave and Monitor.overviewAt wrappers

Only tests called them; they call appearAt, leaveFrom and overviewIn
directly.

* docs: content zooms only on open, close and overview cards; present-state perf numbers

Transitions: moves and resizes clip or pad the content, never scale it;
the veil under a closing float goes at once; pixel springs settle at half
a pixel; the frame timer is reset, not rebuilt. Redraw bullet: separator
comparison and the pinned publish budgets (32 / 24 / 70).

* test(core): drop an unused index in the refreshShown benchmark

* perf(core): build per-frame layouts in reused owner buffers

publish rebuilt every screen's layout from fresh slices each frame
(Monitor.Layout, Workspace.Layout, the column, row and stash rects, the
overview rows and zoom tiles): 33 allocs per refreshShown, 32 per
published frame.

Add layoutInto(dst) to Monitor and Workspace and use it only on the
per-frame owner paths (refreshShown into screen.layoutBuf, publish's real
layouts and state() into Core.realBuf). Layout() keeps returning a fresh
slice for every other caller, so retained layouts (snapshots, captures,
drag, transitions) never alias a buffer; Scenes copy placements and never
alias one either. Per-workspace scratch (column, row, tile and zoom
buffers) and the slide's neighbor buffer back the helpers, which are dead
once the placements are built; no cache, nothing to invalidate.

BenchmarkRefreshShown: 33 -> 0 allocs/op, 4.7 -> 3.3 us/op.
Pinned budgets: publish 32 -> 6, leaving 24 -> 4, overview 70 -> 18.
Tests: reused-buffer results equal fresh ones, retained Layout() results
survive later layouts, sent scenes are never mutated (run under -race).

* test(core): pin the layout buffer reuse contracts

Review follow-ups for the layout buffers:
- an empty settledLayout stays nil, so shownLayout falls back to the live
  layout until the next publish;
- the overview phase of the sent-scenes test also checks each scene against
  a fresh Layout() taken before the step (IDs, hidden, and rects once
  settled), so the overview's real layouts sharing a screen buffer fail it;
- layoutInto must build in the caller's buffer, and a result kept across the
  calls that use the workspace scratch stays unchanged;
- the layout variants assert they hold the feature they are named for (the
  stash variant had put its window on a hidden workspace);
- maps.Keys replaces the hand-written key iterator.

* fix(drm): offer the primary plane's XRGB modifiers for output images

The renderer chose its own render-target modifier and KMS refused it:
on RDNA2 RADV exports pipe-aligned DCC (0x...56bb03, 2 planes) while
amdgpu lists only non-pipe-aligned DCC (0x...563b03), so ADDFB2 returned
EINVAL because no plane advertises that format and modifier, then the
single-plane fallback was used. Pass the plane's IN_FORMATS modifiers for
the image format in SDR as in HDR, so the renderer picks the best common
one first time; document that DCC is not scanned out on this hardware.

* refactor(drm): share the image format and stop re-exporting refused linear images

Add Output.imageFormat for setupImages and exportImages. When KMS refuses
images that were already linear, return that error instead of exporting
the identical linear images again for the later kinds. Document that a
plane without IN_FORMATS gets linear images first, and pin both with tests.

* feat(core): hide the shown stash on a four-finger swipe up

* docs: describe the four-finger swipe up hiding the stash

* feat(config): turn animations off by default and mark them experimental

* test(vulkan): benchmark a full compose into each exported target modifier

* perf(vulkan): never export targets with the AMD DCC retile modifier

RADV renders a DCC_RETILE image into pipe-aligned DCC and runs a compute pass to rewrite the displayable copy: an extra full-surface GPU pass per frame. Drop those modifiers from the probed target list; plain DCC stays.

* feat(core): keep three-finger swipes still when animations are off

* perf(vulkan): hide the root only under a child's opaque region

A child that is not wholly opaque but whose opaque region stops a pixel
short of its edges (Firefox's page) no longer leaves the shm root below it
drawn in full: the root draws the strips around the region only.

* feat(config): replace animations.slowdown with animations.speed and make normal faster

* test(core): sync no-scene and command checks on a flip barrier instead of timeouts

* refactor(core): always snapshot overview keys and scrolls and release unplugged shots

* perf(vulkan): bound the strips a root quad splits into around opaque covers

* refactor(vulkan): dup exported target planes with dupFile

* docs(drm): align compressed render target notes with the plane-accepted modifiers

* fix(vulkan): draw a kept shm window from its GPU copy when its pool is closed

commit

b6be3a859652ca727179546a3cd662d5355b97b5

author

bnema · 17d ago · 2026-10-05 10:04 UTC

committer

GitHub · 17d ago · 2026-10-05 10:04 UTC

parent

ae51138

signature

GPG UnverifiedB5690EEEBB952194 The key is unknown

refs

tag: v0.4.0