Wayland drag lattice: the window visibly wiggles/steps while dragging — smoother than Windows is the bar

[dfattal]

Observation on the Linux dev box (native Wayland, GNOME 50, 3840x2160 panel at 200 %) with the DisplayXR browser (browser-pvt #167) and the demos: the phase-snapped drag is 3D-stable (no shimmer) but the window itself moves jerkily — it wiggles/steps while being dragged, noticeably worse than the same drag on Windows, which is smooth.

Mechanism (per docs/specs/runtime/wayland-window-geometry.md §8 and the session memory): Windows snaps each step before the window moves (app-owned drag, per-step snap_window_rect, sub-lattice precision). Wayland cannot position its own window, so the GNOME extension corrects each compositor-applied move after mutter places it (position-changed → move_frame to the nearest table entry), and the table is a grid at kLatticeCell = 3 logical px (6 device px at 200 %). Two candidate causes, not yet separated:

1. Quantization: the window only lands on the 3-px table grid, so a slow drag advances in visible steps.
2. Correct-after-apply: if the raw position is painted for even one frame before move_frame lands (the spec claims the correction precedes the paint — worth measuring with DISPLAYXR_DEBUG=1's per-frame audit), the window oscillates between raw and corrected positions.

Asks: measure which it is (frame audit: how many frames paint off-table; whether corrections alternate sign); if (1), a finer table (cell 1–2 px where the lens allows, or interpolating along the drag vector) — the lattice period on this panel is what bounds it; if (2), a mutter-side hook (the Meta.ExternalConstraint path once mutter makes new_rect writable — upstream request drafted) or predicting the next position from pointer velocity so the correction is applied to the upcoming move. Windows is the reference for feel. Not a regression — filed from the 2026-09-26 panel session.

[dfattal]

Findings

The wiggle comes from a table that was coarser than the lens. It is not the correction landing after the raw position was painted.

Setup. All numbers below come from a private headless GNOME Shell 50.1 running the v8 extension (not the panel):

• The drag is a real xdg_toplevel.move grab, driven by pointer injection through org.gnome.Mutter.RemoteDesktop.
• Slow straight drags, horizontal, vertical and 20°, about 1 logical px per event.
• The table comes from displayxr-common's own probe, over a best-phase snap of the vendor weaver's shape (best phase within ±2 device px).
• Distances are in device px.

Cause 2 (correct-after-apply): not present.

• 0 of ~1,000 audited frames were painted off-table, at 200 % and at 150 %.
• The correction lands inside the same move_resize that emitted position-changed, before the next paint.
• The corrections change sign as the pointer crosses the midpoint between two table entries. That is geometry, not a raw/corrected flicker in time.

Cause 1 (quantization): the dominant cause, with a part that can be fixed.

• A 3 px probe keeps one entry per cell. It leaves out 18 % (200 %) to 31 % (150 %) of the reachable phase-correct positions.
• Each move was therefore pulled to an entry up to 6.3 px away where 4.5 would do.
• Along a straight drag, the chosen entry switches between neighbours on either side of the drag line: a sideways wiggle of up to 6 px at 200 %.

scale	table	correction rms / max	across-track max
200 %	3 px (today)	3.8 / 6.3	6.0
200 %	dense (fix)	3.1 / 4.5	4.0
150 %	3 px (today)	3.1 / 5.4	4.7
150 %	dense (fix)	2.5 / 4.5	4.5
Windows app-owned (same snap)	—	1.9 / 2.8	2.0

The two 200 % rows from the grab reproduce an offline model to within 0.1 px. That model also predicts the ~13k-entry tables and the "largest correction 3 logical px" seen in the hardware drag summaries.

What stays. Mutter places windows at whole logical px, so at 200 % only every other device px per axis is reachable. Any table at the same phase precision is therefore about 1.6× coarser than Windows. Closing that gap would mean accepting a looser phase, which is the display processor's decision.

Other causes checked.

• Coverage misses happen only on drags that start off-panel, before the mid-drag table arrives (20–46 % of moves in the hardware logs).
• Extension merges keep the drag's start.
• No re-anchor or jump was found.

Fix.

• fix(linux_window): dense Wayland drag-lattice table — probe every logical px (runtime#1748) displayxr-common#65 builds a dense table on the grid-snap path: every logical px is probed and every reachable answer kept. The display processor does no extra work at a non-unit scale. The table stays ~13k entries, and the probe's own CPU stays ~10 ms. The per-point fallback keeps 3 px. No extension change is needed.
• docs(wayland): §8.7 drag smoothness — measured causes and the dense table (#1748) #1749 records this in the spec (§8.7).
• The browser's own Linux drag-lattice port needs the same probe pitch.

[dfattal]

Selection rule on top of the dense table — measured (PR #1751)

The dense table (DisplayXR/displayxr-common#65) is as dense as the reachable positions allow. What remains is which equally phase-correct entry each move lands on. #1751 (extension v9) replaces plain nearest with a direction-aware choice:

• Cost: along² + 9 · across² in device px, so a sideways error counts 3× a lead or lag along the drag.
• Drag axis: estimated from mutter's raw positions. It survives a reversal and follows a turn.
• Lead/lag cap: 6 device px.
• Fallback: plain nearest before 4 px of travel, or when no entry is within the cap.
• Invariant: every landing is still a table entry.

Setup (rebuilt from the previous one):

• A private headless GNOME Shell 50.1 on its own display and session bus.
• A real xdg_toplevel.move grab, driven through that instance's org.gnome.Mutter.RemoteDesktop.
• The table is Upstream Monado cherry-pick (macOS) #65's probe over a best-phase snap: best phase within ±2 device px, period 2.76, slant 0.287. The client answers DragLatticeNeeded.
• Device px. Each cell is "Upstream Monado cherry-pick (macOS) #65 alone → Upstream Monado cherry-pick (macOS) #65 + selection".

scale	drag	correction rms / max	sideways max	sideways rms	along-drag lead/lag max	sideways sign flips /100 px	sideways travel /100 px	largest sideways jump
200 %	horizontal	3.1/4.5 → 3.9/6.3	4.0 → 4.0	2.56 → 1.64	4.0 → 6.0	10.3 → 4.4	73 → 31	8.0 → 4.0
200 %	vertical	3.1/4.5 → 3.5/6.0	4.0 → 2.0	2.02 → 1.46	4.0 → 6.0	6.4 → 5.1	45 → 22	6.0 → 4.0
200 %	diagonal 20°	3.3/4.5 → 3.5/6.0	4.4 → 3.8	2.07 → 1.50	4.4 → 5.6	9.2 → 6.6	52 → 31	6.2 → 6.2
200 %	diagonal 45°	3.3/4.5 → 3.5/6.0	4.4 → 3.8	1.94 → 1.77	4.4 → 5.6	6.6 → 7.5	34 → 35	5.9 → 5.9
200 %	reversing	3.2/4.5 → 3.6/6.3	4.0 → 4.0	2.56 → 1.62	4.0 → 6.0	9.5 → 4.4	73 → 32	8.0 → 4.0
150 %	horizontal	2.6/4.5 → 3.6/6.2	4.5 → 1.5	1.87 → 0.99	3.0 → 6.0	10.0 → 5.4	58 → 22	7.5 → 3.0
150 %	vertical	2.6/4.7 → 3.5/6.2	4.5 → 3.0	1.84 → 1.21	3.0 → 6.0	6.8 → 4.0	46 → 24	6.0 → 4.5
150 %	diagonal 20°	2.5/4.5 → 3.0/5.4	4.2 → 1.9	1.76 → 0.88	3.8 → 5.3	17.0 → 9.6	72 → 26	8.1 → 3.5
150 %	diagonal 45°	2.5/3.4 → 3.2/5.4	3.2 → 2.1	1.64 → 1.33	3.2 → 5.3	11.2 → 10.2	51 → 34	5.3 → 4.2
150 %	reversing	2.6/4.5 → 3.3/6.2	4.5 → 1.5	1.87 → 1.00	3.0 → 6.0	8.9 → 5.4	62 → 26	7.5 → 3.0
Windows reference (model: same snap, every device px reachable)	h / v / 20° / 45°	1.9/2.8	2.0 / 2.0 / 2.6 / 2.8	1.31–1.41	2.0–2.8	8–20	45–81	4.0–4.8

Verdict: it clearly helps, but it does not reach the Windows maximum everywhere.

• Sideways rms: down 30–50 %. At 150 % it is now below the Windows reference (0.9–1.3). At 200 % it is 1.5–1.8, against 1.3–1.4 for Windows.
• Sideways travel and flips: roughly halved on straight drags.
• Largest single sideways jump: 8 → 4 px on straight drags.
• Sideways max: now 1.5–2.1 px at 150 % on horizontal, 20° and reversing drags. At 200 % it still reaches 4 px, at spots where the table has no closer entry within the 6 px lag cap. The offline sweep says a 2 px maximum everywhere at 200 % would need ~8 px of lag, which shows as along-drag steps of up to 16 px.
• What stays: 45° at 200 % barely changes. That, and the 200 % maximum, is the reachability floor this issue already describes.
• Cost: a lead or lag along the drag of ≤ 6 px (up from ≤ 4.5), and a larger correction.
• Hysteresis: tried in the offline model, no measurable gain on top of the anisotropic metric, so it is not included.

Also checked, with a real grab:

• A drag from rest: sideways max over the first 20 px is 4.0 → 2.0 at 200 % and 3.0 → 1.5 at 150 %. The rule stays plain nearest for the first 4 px.
• Edge tiling to the left half, and the top-edge maximize, still work at both scales.
• No frame inside the table's coverage was painted off it.

Offline model: it reproduces the headless numbers to within ~0.1 px and shows the same gain at 100/125/175 %, over two other lens shapes, and at 2× pointer speed.

DISPLAYXR_LATTICE_NEAREST=1 in the shell's environment restores the old rule for a panel A/B.

[dfattal]

Spike: move-synchronised re-weave (draft #1752)

Idea. During a compositor move, the stage shows each frame only at the position it was woven for, so no lattice is needed.

Mechanism:

• mutter keeps the move grab and moves the MetaWindow as usual.
• The extension (v9) places only the window's actor, in the stage's before-update, at the position the buffer it is about to paint was woven for.
• The runtime (DXR_WL_MOVE_SYNC=1) tags every commit with a 1x1 synchronised subsurface at (x mod 256, y mod 256) of the woven position. The tag lands atomically with the buffer.

Feasibility: is there a same-paint hook?

Not directly, but an equivalent works.

What GJS lacks:

• A per-commit identifier.
• damaged fires inside the commit's apply, before the subsurface state is synced.
• meta_window_actor_freeze() is not a usable hold on Wayland: it also stops the texture and subsurface sync until thaw.

What works:

• The subsurface tag plus before-update positioning gives an exact binding.
• before-update runs after the frame's input and commits and before layout and paint.

Numbers

Setup:

• Private headless GNOME Shell 50.1.
• Real title-bar move grabs through org.gnome.Mutter.RemoteDesktop.
• cube_handle_vk_linux on sim_display only.

Audit:

• The runtime stamps each frame's present origin into its pixels.
• The extension reads the stamp back after every stage paint (~1,000 paints per run).
• "Off-origin" means the frame is painted at a device origin other than the one it was woven for.
• The phase column uses the sim_display period (5 device px) as the lens model.

scale	mode	off-origin (phase-wrong)	lag slow p50/p90	lag fast p50/p90	judder slow/fast	window still on
200 %	lattice (§8)	84 % (6.7 %)	2 / 4	0 / 0 *	4.9 / 11.2	70 % of paints
200 %	re-weave after move	91 % (75 %)	0 / 0	0 / 0	2.0 / 8.5	0 %
200 %	move sync	0 % (0 %)	14 / 16	140 / 180	3.2 / 28	51 %
150 %	lattice (§8)	88 % (8.6 %)	1.5 / 4.5	0 / 0 *	3.4 / 18.8	72 %
150 %	re-weave after move	92 % (76 %)	0 / 0	0 / 0	1.5 / 9.4	0 %
150 %	move sync	0 % (0 %)	9 / 12	90 / 120	2.9 / 18.2	51 %

Notes on the table:

• Distances are device px.
• Slow = 250 px/s and fast = 2,500 px/s (at 200 %).
• Judder is the RMS residual from constant-velocity motion.
• * The fast drags outran the lattice's coverage, so they moved uncorrected.

Move sync, other behaviours:

• No oscillation. One direction flip on a reversal drag.
• No sideways deviation on a straight drag.
• All 0 off-origin frames: from rest, release mid-motion, and a 40 ms slow frame every 15 frames.
• Edge tiling survives. Top edge maximises, left edge tiles.
• App SIGSTOPped for 670 ms mid-drag.
  • The fallback fires: after 100 ms and 6 frames the window follows the pointer with stale frames (28 % of that drag).
  • It re-syncs with one hop of ≤ 108 px.
• A 400 ms app-thread stall is absorbed by the runtime's repaint thread, which keeps weaving at the new origin.

Costs:

1. Lag. About 3.4 frames (50–56 ms) behind the pointer at every speed. The chain is: move → published geometry → next weave → FIFO-barriered commit → paint.
2. Cadence. The window advances only when a new-origin frame lands. In this harness that is ~30/s for every mode: re-weave gets the same 30/s of new origins but paints stale ones at 60 Hz. So the window stands still on half the paints.
   • A runtime that re-weaves on every refresh during a move would lift this to the refresh rate.
   • DXR_WEAVE_REPAINT_FORCE=1 hung the app in the headless harness, so this is not tested.

Found on the way:

• An app that keeps deriving lattice tables stalls its frame loop for ~90 ms per sim_display grid probe: 10–18 % of motion time in the lattice runs.
• Move sync must therefore also turn the app's lattice off. The snapshot now carries move_sync, so displayxr-common can key off it.

Recommendation

Move sync is the only mode of the three with no off-origin frames, so it is the only one that is exact for any lens (not only when it is phase-equivalent under the lattice). It needs no lattice probe, and it allows every logical position at any scale.

Its costs are lag and, until the runtime re-weaves every refresh during a move, a cadence of about half the refresh rate. Two options follow:

• Keep the lattice as the default. Take move sync to the panel for an eyeball comparison.
• If the lag reads as acceptable, the next steps are:
  • a re-weave-per-refresh policy while moving, to reach 60 Hz;
  • displayxr-common skipping the table when move_sync is set.

The details and harness are in #1752 (spec §9, scripts/linux/move_sync_spike/).