Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

fix(cua-driver): Linux cursor overlay compositing, xrdp-family servers, and resting float (#2940)

Francesco Bonacci997d6d864332
diff --git a/libs/cua-driver/rust/crates/platform-linux/src/overlay.rs b/libs/cua-driver/rust/crates/platform-linux/src/overlay.rs
index 33fafa5f50..ab219f3b0e 100644
--- a/libs/cua-driver/rust/crates/platform-linux/src/overlay.rs
+++ b/libs/cua-driver/rust/crates/platform-linux/src/overlay.rs
@@ -5,9 +5,25 @@
//! from XComposite. The window covers the full display area.
//! - A background thread renders cursor-local tiles at ~60 Hz while animation
//! is active and uploads them with XPutImage + XShape clipping.
-//! - XShape clips both input and visible pixels. On bare X11, the visible shape
-//! quantizes the rendered alpha mask so translucent bloom pixels do not turn
-//! into an opaque black disk when no compositor is present.
+//! - XShape clips both input and visible pixels. On bare X11 the server never
+//! blends our alpha, so the tile is software-composited over a save-under
+//! copy of the real desktop backdrop and uploaded opaque; the visible shape
+//! stays the alpha≠0 runs, exactly as under a compositor. When the backdrop
+//! cannot be read the frame is deferred, and if that persists the shape falls
+//! back to quantizing the alpha mask for the session, which keeps the cursor
+//! visible at the cost of the translucent bloom.
+//! - Software compositing reads the root under each tile. Our own painted
+//! pixels would come back with it, so every painted rect is recorded with
+//! both the desktop that was under it and the pixels we put on top; a later
+//! read of that rect is only treated as desktop once it stops matching what
+//! we uploaded. Whenever that record cannot be trusted — a RandR change, a
+//! compositing manager arriving or leaving — the overlay blanks itself for a
+//! short grace so the windows underneath repaint before it reads again.
+//! - Known cost of compositing without a compositor: the alpha≠0 footprint is
+//! opaque on screen, so whatever ends up under a *resting* cursor cannot be
+//! observed (the server clips those pixels away from their owner) and stays
+//! as it was at the last paint until the cursor moves or fades. The cutoff
+//! path had the same limitation over the smaller alpha≥128 silhouette.
//! - Z-ordering: `XRaiseWindow` every 80ms to stay above normal windows.
//! - Wayland: when WAYLAND_DISPLAY is set but DISPLAY is also available (XWayland),
//! the X11 path is used. Pure Wayland support is a TODO.
@@ -19,6 +35,8 @@
//! What stays here is the X11 window plumbing: connection setup,
//! override-redirect visual, ShapeInput passthrough, and the XPutImage paint.
+#[cfg(target_os = "linux")]
+use std::collections::VecDeque;
use std::collections::{HashMap, HashSet};
use std::sync::{Mutex, OnceLock};
#[cfg(target_os = "linux")]
@@ -28,6 +46,11 @@ use std::time::{Duration, Instant};
use cursor_overlay::CursorAction;
#[cfg(target_os = "linux")]
const X11_EVENT_POLL_INTERVAL: Duration = Duration::from_millis(50);
+/// How often the `_NET_WM_CM_S{n}` owner is re-sampled. A compositing manager
+/// starting or stopping emits no event we subscribe to, and it decides whether
+/// the server blends our alpha, so the sample cannot be startup-only.
+#[cfg(target_os = "linux")]
+const X11_COMPOSITOR_POLL_INTERVAL: Duration = Duration::from_secs(1);
#[cfg(target_os = "linux")]
use cursor_overlay::ZOrderEnforcer;
@@ -566,6 +589,17 @@ impl RenderState {
|| self.core.spring.is_some()
|| self.core.click_t.is_some()
|| self.core.session_badge_needs_frame_tick()
+ // The resting float bob (`shared_float_motion`) is part of the
+ // cursor's visual identity, not a transient animation: it runs
+ // whenever the cursor is on screen and reduced motion is off, so
+ // a settled cursor must keep receiving frames or the bob freezes
+ // mid-swing on Linux while macOS keeps levitating. The term dies
+ // with `idle_alpha` once the idle fade completes, returning the
+ // parked-overlay fast path to the fully hidden cursor.
+ || (self.core.visible
+ && self.core.pos.0 >= -100.0
+ && self.core.idle_alpha >= 0.004
+ && self.core.visual.reduced_motion != cursor_overlay::ReducedMotion::On)
|| (self.core.motion.idle_hide_ms > 0.0
&& self.core.visible
&& self.core.pos.0 >= -100.0
@@ -974,6 +1008,49 @@ fn run_overlay_thread(cfg: CursorConfig, rx: std::sync::mpsc::Receiver<OverlayMs
colormap
};
+ // An ARGB visual is only worth having when a compositing manager will
+ // blend it; the compositor-less path renders pre-blended opaque pixels
+ // behind a shape mask and needs no alpha channel. It is also actively
+ // hazardous on servers that accept an ARGB32 window but cannot show it —
+ // xorgxrdp repaints shaped ARGB regions as solid black whenever its
+ // refresh re-renders them, and answers root reads inside them with black,
+ // which both blanks the cursor on screen and poisons every save-under
+ // comparison into compositing the shadow over black. Those servers are
+ // exactly the compositor-less ones, so the rule is simple: no compositor
+ // at startup, no ARGB. `software_only` pins the software-composited path
+ // for the session — a compositing manager appearing later blends the
+ // opaque shaped window correctly, whereas switching paths would hand this
+ // 24-bit window premultiplied translucent pixels it cannot represent.
+ let (visual_id, depth, colormap, software_only) =
+ if compositor_present || visual_id == screen.root_visual {
+ (visual_id, depth, colormap, false)
+ } else {
+ conn.free_colormap(colormap).ok();
+ tracing::debug!(
+ "X11 overlay: no compositor at startup; using the root visual \
+ with software compositing"
+ );
+ (
+ screen.root_visual,
+ screen.root_depth,
+ screen.default_colormap,
+ true,
+ )
+ };
+ // Belt and braces for servers whose root reads are unreliable even for
+ // the visual chosen above: `resolve_backdrop` stops treating a readback
+ // mismatch as proof of a repaint.
+ let readback_untrusted = !x11_visual_readback_reliable(
+ &conn,
+ root,
+ visual_id,
+ depth,
+ colormap,
+ scr_w as u16,
+ scr_h as u16,
+ )
+ .unwrap_or(false);
+
// Create the overlay window.
let win = conn.generate_id().unwrap();
let win_aux = CreateWindowAux::new()
@@ -1040,6 +1117,12 @@ fn run_overlay_thread(cfg: CursorConfig, rx: std::sync::mpsc::Receiver<OverlayMs
tracing::warn!("X11 overlay: cannot create graphics context: {e}");
return;
}
+ let paint_target = X11PaintTarget {
+ win,
+ root,
+ depth,
+ gc_id,
+ };
// Render at ~60 Hz only while pixels can change. Quiescent cursors use
// bounded channel waits so X11/RandR events are serviced without repainting;
@@ -1051,6 +1134,26 @@ fn run_overlay_thread(cfg: CursorConfig, rx: std::sync::mpsc::Receiver<OverlayMs
let mut frame_tick_needed = false;
let mut maintenance_deadline = last_tick + X11_EVENT_POLL_INTERVAL;
let mut last_pinned: Option<u64> = None;
+ let mut last_compositor_poll = last_tick;
+ // Constructed after the geometry query and the window map, so the cache can
+ // never be primed against a placeholder geometry. This window has painted
+ // nothing yet and its bounding shape is still empty, so its first root read
+ // sees no pixels of ours. (A previous overlay instance torn down moments
+ // earlier can still be on screen; that resolves itself as soon as the
+ // cursor vacates the rect and its owner repaints.)
+ let mut backdrop = X11BackdropCache::default();
+ // Startup probe result; a property of the server, not of the compositor,
+ // so it is never re-sampled when a compositing manager comes or goes.
+ backdrop.readback_untrusted = readback_untrusted;
+ if readback_untrusted {
+ tracing::warn!(
+ "X11 overlay: root reads cannot see this window's own pixels; \
+ save-unders will be served without readback confirmation"
+ );
+ }
+ // Arrivals resolve callers waiting for the destination frame to be visible,
+ // so they are held back across a deferred paint instead of firing early.
+ let mut pending_arrivals: Vec<CursorKey> = Vec::new();
let z_enforcer = X11ZOrderEnforcer { conn: &conn, win };
loop {
@@ -1091,9 +1194,16 @@ fn run_overlay_thread(cfg: CursorConfig, rx: std::sync::mpsc::Receiver<OverlayMs
tracing::warn!("X11 overlay geometry repair failed; disabling overlay: {e}");
break;
}
+ // Every saved backdrop describes the pre-resize screen. The repair
+ // above emptied our bounding shape, but that only queues Expose:
+ // the framebuffer still holds our last frame until the windows
+ // underneath repaint it, so stay blank for the resync grace instead
+ // of reading our own pixels back as desktop.
+ backdrop.resync(Instant::now());
#[cfg(test)]
X11_RANDR_REPAIR_COUNT.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
compositor_present = x11_compositor_present(&conn, screen_num);
+ last_compositor_poll = Instant::now();
tracing::debug!(
width = geometry.0,
height = geometry.1,
@@ -1105,6 +1215,27 @@ fn run_overlay_thread(cfg: CursorConfig, rx: std::sync::mpsc::Receiver<OverlayMs
None
};
+ // A compositing manager can start or stop without any RandR event, and
+ // it decides which pixel policy is correct: with one present the server
+ // blends our alpha and a root read no longer sees the windows below us.
+ // Poll the selection owner rather than let a stale sample pick the path.
+ let compositor_changed = if last_compositor_poll.elapsed() >= X11_COMPOSITOR_POLL_INTERVAL {
+ last_compositor_poll = Instant::now();
+ let present = x11_compositor_present(&conn, screen_num);
+ let changed = present != compositor_present;
+ if changed {
+ compositor_present = present;
+ // Same reasoning as the RandR repair: what we already painted is
+ // still on screen, so blank and let it be repainted before the
+ // next root read (and repaint now that the policy changed).
+ backdrop.resync(Instant::now());
+ tracing::debug!(compositor_present, "X11 overlay compositor state changed");
+ }
+ changed
+ } else {
+ false
+ };
+
let now = Instant::now();
let elapsed_dt = now.duration_since(last_tick).as_secs_f64();
last_tick = now;
@@ -1176,13 +1307,26 @@ fn run_overlay_thread(cfg: CursorConfig, rx: std::sync::mpsc::Receiver<OverlayMs
last_ztick.elapsed() >= z_order_interval,
) {
last_ztick = Instant::now();
+ // Deliberately does not invalidate the backdrop cache. Restacking
+ // *us* does not change what is beneath us, and invalidating here
+ // would force a fresh read inside our own silhouette every 80 ms.
+ // If a window did draw over us before we raised again, the next
+ // root read no longer matches the pixels we uploaded there, so
+ // `resolve_backdrop` drops the save-under for those pixels on its
+ // own rather than serving a backdrop that is no longer under us.
z_enforcer.reassert(pinned_wid);
}
// Render after a command, during an active animation/fade, and once
// more as the final active state settles. This leaves the X11 window in
// its completed/cleared state before the next blocking receive.
- if had_msg || screen_changed || hover_changed || frame_tick_needed || next_frame_tick_needed
+ let mut paint_deferred = false;
+ if had_msg
+ || screen_changed
+ || compositor_changed
+ || hover_changed
+ || frame_tick_needed
+ || next_frame_tick_needed
{
let tiles = {
let guard = RENDER.lock().unwrap();
@@ -1190,31 +1334,43 @@ fn run_overlay_thread(cfg: CursorConfig, rx: std::sync::mpsc::Receiver<OverlayMs
};
if let Some(tiles) = tiles {
- if let Err(e) = paint_x11_tiles(
+ match paint_x11_tiles(
&conn,
- win,
- depth,
- gc_id,
+ &paint_target,
&tiles,
- compositor_present,
+ // A `software_only` window is 24-bit: handing the
+ // compositor branch premultiplied translucent pixels would
+ // display them as opaque dark artifacts, so the downgrade
+ // pins the software-composited path for the session.
+ compositor_present && !software_only,
screen_changed,
+ &mut backdrop,
) {
- // A broken X11 connection cannot recover inside this
- // owner thread. Exit instead of spinning at frame cadence
- // and repeatedly allocating/rendering work nobody can see.
- tracing::warn!("X11 overlay paint failed; disabling overlay: {e}");
- break;
+ Ok(outcome) => paint_deferred = outcome == X11PaintOutcome::Deferred,
+ Err(e) => {
+ // A broken X11 connection cannot recover inside this
+ // owner thread. Exit instead of spinning at frame cadence
+ // and repeatedly allocating/rendering work nobody can see.
+ tracing::warn!("X11 overlay paint failed; disabling overlay: {e}");
+ break;
+ }
}
}
}
// Preserve the original ordering: callers waiting on arrival only
- // resume after the destination frame has reached the X11 window.
- for key in &arrived {
- arrival_fire(key);
+ // resume after the destination frame has reached the X11 window. A
+ // deferred paint has not reached it yet, so they wait for the retry.
+ pending_arrivals.extend(arrived);
+ if !paint_deferred {
+ for key in pending_arrivals.drain(..) {
+ arrival_fire(&key);
+ }
}
- frame_tick_needed = next_frame_tick_needed;
+ // A deferred frame is still owed to the window: keep ticking so it is
+ // retried instead of leaving a stale cursor until the next command.
+ frame_tick_needed = next_frame_tick_needed || paint_deferred;
maintenance_deadline = next_maintenance_deadline(
last_tick,
last_ztick,
@@ -1352,6 +1508,464 @@ struct X11PaintTile {
pixmap: tiny_skia::Pixmap,
}
+/// Loop-constant X11 handles the paint path needs. Bundled so the per-frame
+/// paint entry point keeps a reviewable argument list as the compositing
+/// inputs grow.
+#[cfg(target_os = "linux")]
+struct X11PaintTarget {
+ win: u32,
+ root: u32,
+ depth: u8,
+ gc_id: u32,
+}
+
+/// One rect of screen the overlay painted over: the desktop pixels that were
+/// under it, and the pixels we actually put on top of them. Both are row-major
+/// BGRX, `width * height * 4` bytes, exactly as XGetImage returns a ZPixmap
+/// from the root.
+///
+/// The pair is what makes readback decidable. A later root read of the same
+/// rect is still our own paint when it equals `uploaded`, in which case the
+/// true backdrop is `under`; once it differs, the window that owns those pixels
+/// has serviced its Expose and the live read is the truth again.
+#[cfg(target_os = "linux")]
+struct X11SavedBackdrop {
+ bounds: X11TileBounds,
+ under: Vec<u8>,
+ uploaded: Vec<u8>,
+}
+
+/// One painted frame: the root-space rects the overlay actually made visible,
+/// and the save-unders covering them.
+#[cfg(target_os = "linux")]
+struct X11BackdropFrame {
+ /// When a later frame superseded this one. `None` while the frame is the
+ /// one on screen, which can never be read back as backdrop.
+ vacated_at: Option<Instant>,
+ painted: Vec<x11rb::protocol::xproto::Rectangle>,
+ saved: Vec<X11SavedBackdrop>,
+}
+
+#[cfg(target_os = "linux")]
+impl X11BackdropFrame {
+ /// A vacated frame is dropped once its save-unders are old enough that
+ /// serving them would be worse than reading whatever is there now. Nothing
+ /// about correctness rides on the exact value: while the frame is retained,
+ /// `resolve_backdrop` still prefers the live read for every pixel its owner
+ /// has repainted.
+ fn expired(&self, now: Instant) -> bool {
+ match self.vacated_at {
+ None => self.painted.is_empty(),
+ Some(vacated) => now.duration_since(vacated) > X11_BACKDROP_RETENTION,
+ }
+ }
+}
+
+/// Save-unders for compositor-less software blending. Without a compositing
+/// manager the server never blends our alpha, so we blend against the real
+/// backdrop ourselves. XGetImage on the root returns our own painted pixels
+/// wherever the overlay is currently shaped in, so those pixels are served from
+/// here instead and everything else keeps the live read.
+#[cfg(target_os = "linux")]
+#[derive(Default)]
+struct X11BackdropCache {
+ /// Newest frame at the front.
+ frames: VecDeque<X11BackdropFrame>,
+ /// Set while the overlay must stay blank so the windows it uncovered can
+ /// service their Expose before the next root read.
+ resync_until: Option<Instant>,
+ /// Whether the blanking shape for the current resync has been sent.
+ resync_blanked: bool,
+ slow_reads: u8,
+ unbacked_frames: u8,
+ disabled: bool,
+ /// Set when the startup probe found that a root `GetImage` inside the
+ /// overlay's own shaped-in footprint does not return the pixels we
+ /// uploaded (xorgxrdp answers black there for a 32-bit ARGB child on a
+ /// 24-bit root). On such a server the readback comparison in
+ /// `resolve_backdrop` can never confirm our paint survived, so mismatches
+ /// inside a save-under serve the saved backdrop instead of adopting the
+ /// unreadable live pixels — compositing each frame over those drives a
+ /// translucent shadow geometrically to black.
+ readback_untrusted: bool,
+}
+
+/// After the cache is dropped wholesale — a display change, a compositing
+/// manager appearing or leaving — nothing is left to tell our own pixels apart
+/// from the desktop, so the overlay blanks itself for this long and lets the
+/// windows underneath repaint before it reads the root again. Emptying the
+/// bounding shape only queues Expose; the framebuffer still physically holds
+/// our last frame until the owning clients answer it.
+#[cfg(target_os = "linux")]
+const X11_BACKDROP_RESYNC_GRACE: Duration = Duration::from_millis(200);
+/// How long a vacated frame's save-under stays available. Long is safe:
+/// `resolve_backdrop` only uses it for pixels that still hold our own paint.
+#[cfg(target_os = "linux")]
+const X11_BACKDROP_RETENTION: Duration = Duration::from_secs(2);
+/// Memory ceiling on retained frames, ~2.3 MB per cursor at the largest badged
+/// tile. This is what actually bounds the history during continuous motion:
+/// 32 frames is roughly half a second at the 60 Hz frame budget.
+#[cfg(target_os = "linux")]
+const X11_BACKDROP_MAX_FRAMES: usize = 32;
+/// A frame's whole root read (one round trip, all tiles) must fit well inside
+/// the 16 ms frame budget.
+#[cfg(target_os = "linux")]
+const X11_BACKDROP_READ_BUDGET: Duration = Duration::from_millis(8);
+/// Consecutive over-budget frames that latch software compositing off.
+#[cfg(target_os = "linux")]
+const X11_BACKDROP_SLOW_READ_LIMIT: u8 = 3;
+/// Consecutive frames the overlay may hold still waiting for a usable backdrop
+/// before compositing is latched off for the session. Three frames is ~50 ms of
+/// frozen cursor, which is cheaper than either painting a tile we cannot
+/// account for or losing translucency to a single transient X11 error.
+#[cfg(target_os = "linux")]
+const X11_BACKDROP_UNBACKED_FRAME_LIMIT: u8 = 3;
+
+/// Software compositing is compositor-less only, and only until a slow server
+/// latches it off. Split out so the hard constraint — a compositing manager
+/// changes nothing about this path — is locked by a test.
+#[cfg(target_os = "linux")]
+fn backdrop_compositing_enabled(compositor_present: bool, cache: &X11BackdropCache) -> bool {
+ !compositor_present && cache.enabled()
+}
+
+/// Intersect a root-space rect with a tile, returning tile-local
+/// `(x0, y0, x1, y1)` half-open bounds, or `None` when they do not overlap.
+#[cfg(target_os = "linux")]
+fn clip_to_tile(
+ bounds: X11TileBounds,
+ x: i32,
+ y: i32,
+ width: i32,
+ height: i32,
+) -> Option<(usize, usize, usize, usize)> {
+ let bx = i32::from(bounds.x);
+ let by = i32::from(bounds.y);
+ let x0 = x.max(bx);
+ let y0 = y.max(by);
+ let x1 = (x + width).min(bx + i32::from(bounds.width));
+ let y1 = (y + height).min(by + i32::from(bounds.height));
+ if x1 <= x0 || y1 <= y0 {
+ return None;
+ }
+ Some((
+ (x0 - bx) as usize,
+ (y0 - by) as usize,
+ (x1 - bx) as usize,
+ (y1 - by) as usize,
+ ))
+}
+
+/// Tile-local half-open bounding box of a shape, or `None` when it is empty.
+#[cfg(target_os = "linux")]
+fn shape_bounding_box(
+ shape: &[x11rb::protocol::xproto::Rectangle],
+) -> Option<(usize, usize, usize, usize)> {
+ let mut bbox: Option<(usize, usize, usize, usize)> = None;
+ for rect in shape {
+ if rect.width == 0 || rect.height == 0 {
+ continue;
+ }
+ let x0 = rect.x.max(0) as usize;
+ let y0 = rect.y.max(0) as usize;
+ let x1 = x0 + usize::from(rect.width);
+ let y1 = y0 + usize::from(rect.height);
+ bbox = Some(match bbox {
+ None => (x0, y0, x1, y1),
+ Some((bx0, by0, bx1, by1)) => (bx0.min(x0), by0.min(y0), bx1.max(x1), by1.max(y1)),
+ });
+ }
+ bbox
+}
+
+/// Copy the `(x0, y0, x1, y1)` sub-rect out of a tile-sized BGRX buffer. Only
+/// the painted bounding box is ever consulted later, so save-unders store that
+/// instead of the whole tile.
+#[cfg(target_os = "linux")]
+fn crop_tile_pixels(
+ pixels: &[u8],
+ tile_width: usize,
+ (x0, y0, x1, y1): (usize, usize, usize, usize),
+) -> Vec<u8> {
+ let mut out = Vec::with_capacity((x1 - x0) * (y1 - y0) * 4);
+ for row in y0..y1 {
+ let start = (row * tile_width + x0) * 4;
+ out.extend_from_slice(&pixels[start..start + (x1 - x0) * 4]);
+ }
+ out
+}
+
+#[cfg(target_os = "linux")]
+impl X11BackdropCache {
+ fn enabled(&self) -> bool {
+ !self.disabled
+ }
+
+ fn disable(&mut self, reason: &'static str) {
+ if self.disabled {
+ return;
+ }
+ self.disabled = true;
+ self.frames.clear();
+ self.resync_until = None;
+ tracing::warn!(
+ reason,
+ "X11 overlay: falling back to the alpha-cutoff cursor shape for this session"
+ );
+ }
+
+ /// Latch compositing off after repeated over-budget root reads. A loaded VM
+ /// must not pay an unbounded XGetImage round trip every frame forever; the
+ /// overlay falls back to the alpha-cutoff path for the rest of the session.
+ fn note_read_duration(&mut self, elapsed: Duration) {
+ if self.disabled {
+ return;
+ }
+ if elapsed <= X11_BACKDROP_READ_BUDGET {
+ self.slow_reads = 0;
+ return;
+ }
+ self.slow_reads = self.slow_reads.saturating_add(1);
+ if self.slow_reads >= X11_BACKDROP_SLOW_READ_LIMIT {
+ self.disable("root backdrop reads exceed the frame budget");
+ }
+ }
+
+ /// Record a frame the overlay could not composite. The frame is not painted
+ /// at all — painting the cutoff tile instead would make pixels visible that
+ /// no save-under can explain, and every later frame overlapping them would
+ /// fail for the same reason, latching the cutoff look in silently. Returns
+ /// `true` once the failures have persisted long enough that compositing is
+ /// latched off and the caller should paint the cutoff tile after all.
+ fn note_unbacked_frame(&mut self) -> bool {
+ if self.disabled {
+ // Already latched off — most likely by the slow-read budget during
+ // this very frame. Nothing is owed to the cache; paint the cutoff
+ // tile now instead of holding a frame back for nothing.
+ return true;
+ }
+ self.unbacked_frames = self.unbacked_frames.saturating_add(1);
+ if self.unbacked_frames < X11_BACKDROP_UNBACKED_FRAME_LIMIT {
+ return false;
+ }
+ self.disable("the root backdrop could not be read for several frames");
+ true
+ }
+
+ fn note_composited_frame(&mut self) {
+ self.unbacked_frames = 0;
+ }
+
+ /// Drop every save-under without blanking. Only correct where nothing of
+ /// ours is on screen to be read back — the compositing-manager path, which
+ /// never paints an opaque tile in the first place.
+ fn invalidate(&mut self) {
+ self.frames.clear();
+ }
+
+ /// Drop every save-under and blank the overlay for the resync grace. Used
+ /// when the screen the save-unders describe stops being the screen we are
+ /// painting on: a RandR geometry change, or a compositing manager arriving
+ /// or leaving.
+ fn resync(&mut self, now: Instant) {
+ self.frames.clear();
+ self.resync_until = Some(now + X11_BACKDROP_RESYNC_GRACE);
+ self.resync_blanked = false;
+ }
+
+ /// Whether painting is still suppressed. Clears the state once the grace
+ /// has elapsed so the next frame reads a root nobody has our pixels on.
+ fn resyncing(&mut self, now: Instant) -> bool {
+ match self.resync_until {
+ Some(deadline) if now < deadline => true,
+ Some(_) => {
+ self.resync_until = None;
+ self.resync_blanked = false;
+ false
+ }
+ None => false,
+ }
+ }
+
+ /// Whether the caller still has to blank the bounding shape for this
+ /// resync. Answering `true` once per resync keeps the wait from re-sending
+ /// a shape the server already has.
+ fn take_resync_blanking(&mut self) -> bool {
+ if self.resync_blanked {
+ return false;
+ }
+ self.resync_blanked = true;
+ true
+ }
+
+ /// Retire frames that are too old to be worth keeping and cap memory. The
+ /// on-screen frame is pinned while it has painted rects: those pixels are
+ /// what the server is displaying right now.
+ fn prune(&mut self, now: Instant) {
+ while self.frames.len() > X11_BACKDROP_MAX_FRAMES {
+ self.frames.pop_back();
+ }
+ while let Some(frame) = self.frames.back() {
+ if !frame.expired(now) {
+ break;
+ }
+ self.frames.pop_back();
+ }
+ }
+
+ fn record_frame(
+ &mut self,
+ at: Instant,
+ painted: Vec<x11rb::protocol::xproto::Rectangle>,
+ saved: Vec<X11SavedBackdrop>,
+ ) {
+ // The frame that was on screen is only vacated now, not when it was
+ // painted: a cursor that rested for a minute still leaves its pixels
+ // behind for the owning client to repaint after it finally moves.
+ if let Some(previous) = self.frames.front_mut() {
+ previous.vacated_at.get_or_insert(at);
+ }
+ self.frames.push_front(X11BackdropFrame {
+ vacated_at: None,
+ painted,
+ saved,
+ });
+ self.prune(at);
+ }
+
+ /// Build the true backdrop for `bounds` out of a live root read plus the
+ /// save-unders.
+ ///
+ /// A pixel the overlay painted is only served from a save-under while the
+ /// live read still matches the pixels we uploaded there; as soon as the
+ /// owning window repaints, the live read wins again. That check is what
+ /// keeps a cursor ghost from being blended in and re-saved frame after
+ /// frame, and it needs no assumption about how fast a client answers
+ /// Expose.
+ ///
+ /// Returns `None` when a painted pixel has no save-under at all, so callers
+ /// fail closed instead of compositing against pixels that may be our own.
+ fn resolve_backdrop(
+ &self,
+ now: Instant,
+ bounds: X11TileBounds,
+ fresh: &[u8],
+ ) -> Option<Vec<u8>> {
+ if self.disabled {
+ return None;
+ }
+ let width = usize::from(bounds.width);
+ let height = usize::from(bounds.height);
+ let pixels = width.checked_mul(height)?;
+ if pixels == 0 || fresh.len() != pixels * 4 {
+ return None;
+ }
+
+ let mut out = fresh.to_vec();
+ // `decided` is the running answer for the whole tile; `pending` is the
+ // mask of pixels the frame in hand painted and still owes an answer
+ // for. Newest frame first, so the most recent paint over a pixel is the
+ // one its live value is compared against.
+ let mut decided = vec![false; pixels];
+ let mut pending = vec![false; pixels];
+ for frame in &self.frames {
+ if frame.expired(now) {
+ continue;
+ }
+ let mut painted: Option<(usize, usize, usize, usize)> = None;
+ for rect in &frame.painted {
+ let Some(clip) = clip_to_tile(
+ bounds,
+ i32::from(rect.x),
+ i32::from(rect.y),
+ i32::from(rect.width),
+ i32::from(rect.height),
+ ) else {
+ continue;
+ };
+ let (x0, y0, x1, y1) = clip;
+ for row in y0..y1 {
+ pending[row * width + x0..row * width + x1].fill(true);
+ }
+ painted = Some(match painted {
+ None => clip,
+ Some((px0, py0, px1, py1)) => {
+ (px0.min(x0), py0.min(y0), px1.max(x1), py1.max(y1))
+ }
+ });
+ }
+ let Some((bx0, by0, bx1, by1)) = painted else {
+ continue;
+ };
+
+ for saved in &frame.saved {
+ let Some((x0, y0, x1, y1)) = clip_to_tile(
+ bounds,
+ i32::from(saved.bounds.x),
+ i32::from(saved.bounds.y),
+ i32::from(saved.bounds.width),
+ i32::from(saved.bounds.height),
+ ) else {
+ continue;
+ };
+ let saved_width = usize::from(saved.bounds.width);
+ let expected = saved_width * usize::from(saved.bounds.height) * 4;
+ if saved.under.len() != expected || saved.uploaded.len() != expected {
+ continue;
+ }
+ let dx = i32::from(bounds.x) - i32::from(saved.bounds.x);
+ let dy = i32::from(bounds.y) - i32::from(saved.bounds.y);
+ for row in y0..y1 {
+ let saved_row = (row as i32 + dy) as usize;
+ for col in x0..x1 {
+ let index = row * width + col;
+ if decided[index] || !pending[index] {
+ continue;
+ }
+ let saved_col = (col as i32 + dx) as usize;
+ let src = (saved_row * saved_width + saved_col) * 4;
+ let dst = index * 4;
+ // Compare colour only: the fourth byte is an unused pad
+ // in the root read and a forced 255 in what we upload.
+ // On a server whose root reads cannot see our own
+ // window (`readback_untrusted`) the comparison carries
+ // no information — the live pixel is unreadable, not
+ // repainted — so the save-under is served regardless.
+ // The cost is that a genuine repaint under the cursor
+ // goes unnoticed until the save-under expires.
+ if self.readback_untrusted
+ || fresh[dst..dst + 3] == saved.uploaded[src..src + 3]
+ {
+ out[dst..dst + 4].copy_from_slice(&saved.under[src..src + 4]);
+ }
+ decided[index] = true;
+ }
+ }
+ }
+
+ // Clear this frame's mask, and fail closed on any pixel it painted
+ // that no save-under covers: trusting the live read there would
+ // blend our own cursor in as if it were desktop. Every painted rect
+ // of a composited frame lies inside one of its save-unders, so this
+ // only trips on a frame recorded without one.
+ let mut unbacked = false;
+ for row in by0..by1 {
+ for col in bx0..bx1 {
+ let index = row * width + col;
+ if pending[index] {
+ unbacked |= !decided[index];
+ pending[index] = false;
+ }
+ }
+ }
+ if unbacked {
+ return None;
+ }
+ }
+ Some(out)
+ }
+}
+
#[cfg(target_os = "linux")]
fn cursor_tile_bounds(
core: &RenderStateCore,
@@ -1407,7 +2021,9 @@ fn render_x11_tiles(map: &RenderMap) -> Vec<X11PaintTile> {
let mut pixmap = tiny_skia::Pixmap::new(bounds.width.into(), bounds.height.into())?;
// Paint every cursor into every intersecting tile. tiny-skia clips
// automatically, so overlapping cursor tiles carry the same
- // composite pixels regardless of upload order.
+ // composite pixels regardless of upload order — and identical
+ // backdrops, because every root read for a frame is issued before
+ // any upload.
for rs in map.cursors.values() {
cursor_overlay::paint_cursor(
&mut pixmap,
@@ -1430,80 +2046,516 @@ fn render_x11_tiles(map: &RenderMap) -> Vec<X11PaintTile> {
#[cfg(target_os = "linux")]
const NONCOMPOSITED_ALPHA_CUTOFF: u8 = 128;
+/// Read the true desktop pixels under every tile of one frame.
+///
+/// All cookies are issued before any reply is collected, so the whole frame
+/// costs one round trip regardless of tile count. Callers must invoke this
+/// before the first `put_image` of the frame: that ordering is what lets
+/// overlapping tiles read the same pre-frame screen instead of each other's
+/// freshly uploaded pixels.
+///
+/// A failed or unexpected read fails the whole frame. Compositing some tiles
+/// and not others would upload two different pixel policies into one bounding
+/// shape, so the frame is deferred (or, eventually, compositing is latched off)
+/// as a unit.
#[cfg(target_os = "linux")]
-fn paint_x11_tiles(
+fn read_root_backdrops(
conn: &impl x11rb::connection::Connection,
- win: u32,
- depth: u8,
- gc_id: u32,
+ root: u32,
tiles: &[X11PaintTile],
- compositor_present: bool,
- checked_requests: bool,
-) -> anyhow::Result<()> {
- use x11rb::protocol::shape::{ConnectionExt as ShapeConnectionExt, SK, SO};
+ backdrop: &mut X11BackdropCache,
+) -> Option<Vec<Vec<u8>>> {
use x11rb::protocol::xproto::{ConnectionExt as XprotoConnectionExt, ImageFormat};
- let mut payloads = Vec::with_capacity(tiles.len());
- let mut visible_shape = Vec::new();
- for tile in tiles {
- let (bgra, mut tile_shape) = bgra_and_visible_shape(&tile.pixmap, compositor_present);
- for rect in &mut tile_shape {
- rect.x = rect.x.saturating_add(tile.bounds.x);
- rect.y = rect.y.saturating_add(tile.bounds.y);
- }
- visible_shape.extend(tile_shape);
- payloads.push((tile.bounds, bgra));
- }
+ // Tiles are pre-clamped to the screen by `cursor_tile_bounds`, so the rect
+ // is in bounds by construction; a stale-geometry race after RandR simply
+ // errors out into the deferral below.
+ let cookies: Vec<_> = tiles
+ .iter()
+ .map(|tile| {
+ let bounds = tile.bounds;
+ conn.get_image(
+ ImageFormat::Z_PIXMAP,
+ root,
+ bounds.x,
+ bounds.y,
+ bounds.width,
+ bounds.height,
+ !0u32,
+ )
+ .ok()
+ })
+ .collect();
- for (bounds, bgra) in payloads {
- let cookie = conn.put_image(
+ let started = Instant::now();
+ let reads: Option<Vec<Vec<u8>>> = cookies
+ .into_iter()
+ .zip(tiles)
+ .map(|(cookie, tile)| {
+ let reply = cookie?.reply().ok()?;
+ let expected = usize::from(tile.bounds.width) * usize::from(tile.bounds.height) * 4;
+ // Same BGRX/4-byte assumption the screen capture path decodes with;
+ // anything else is a read failure, not a format to guess at. It is
+ // also what makes the readback comparison in `resolve_backdrop`
+ // meaningful: an 8-bit-per-channel root returns exactly the bytes
+ // we uploaded.
+ if !matches!(reply.depth, 24 | 32) || reply.data.len() != expected {
+ return None;
+ }
+ Some(reply.data)
+ })
+ .collect();
+ backdrop.note_read_duration(started.elapsed());
+ reads
+}
+
+/// Whether this server can genuinely display a window of the given visual and
+/// fold it into root `GetImage` reads. Both halves of the compositor-less
+/// overlay ride on that: PutImage must reach the screen and *stay* there
+/// (xorgxrdp repaints a 32-bit ARGB child as solid black on its 24-bit root
+/// whenever the region is refreshed), and `resolve_backdrop` decides "still
+/// our paint" versus "someone repainted over us" by comparing a later root
+/// read against the uploaded bytes — a comparison that misfires on every
+/// pixel when the read returns black instead.
+///
+/// Probed once per candidate visual at startup with a throwaway window that
+/// mirrors the real overlay as closely as possible — full-screen,
+/// override-redirect, bounding-shaped down to a 4×1 strip at the origin —
+/// because the failure is not visible to a simpler probe: xorgxrdp serves a
+/// small unshaped ARGB window's pixels back faithfully and only blacks out
+/// shaped regions of a large one when its refresh re-renders them. Map,
+/// shape, upload the strip, read it back off the root twice (immediately,
+/// and again after the server has had time to reprocess the damage),
+/// destroy. The round trip through `get_image` orders the reply after the
+/// map and upload on this connection, so no separate sync is needed. Errors
+/// report as unreliable: a server that cannot service this exchange cannot
+/// service the per-frame paint either.
+#[cfg(target_os = "linux")]
+fn x11_visual_readback_reliable(
+ conn: &impl x11rb::connection::Connection,
+ root: u32,
+ visual_id: u32,
+ depth: u8,
+ colormap: u32,
+ scr_w: u16,
+ scr_h: u16,
+) -> anyhow::Result<bool> {
+ use x11rb::protocol::shape::{ConnectionExt as ShapeConnectionExt, SK, SO};
+ use x11rb::protocol::xproto::{
+ ClipOrdering, ConnectionExt as XprotoConnectionExt, CreateGCAux, CreateWindowAux,
+ EventMask, ImageFormat, Rectangle, WindowClass,
+ };
+
+ const PROBE_WIDTH: u16 = 4;
+ // Distinctive opaque colours a desktop corner is unlikely to hold.
+ let uploaded: Vec<u8> = (0..u32::from(PROBE_WIDTH))
+ .flat_map(|i| {
+ let i = i as u8;
+ [
+ 0x35_u8.wrapping_add(i.wrapping_mul(7)),
+ 0x8C_u8.wrapping_sub(i.wrapping_mul(11)),
+ 0x5A_u8.wrapping_add(i.wrapping_mul(23)),
+ 0xFF,
+ ]
+ })
+ .collect();
+
+ let win = conn.generate_id()?;
+ conn.create_window(
+ depth,
+ win,
+ root,
+ 0,
+ 0,
+ scr_w.max(PROBE_WIDTH),
+ scr_h.max(1),
+ 0,
+ WindowClass::INPUT_OUTPUT,
+ visual_id,
+ &CreateWindowAux::new()
+ .background_pixel(0)
+ .border_pixel(0)
+ .colormap(colormap)
+ .override_redirect(1u32)
+ .event_mask(EventMask::NO_EVENT),
+ )?;
+ let probe = (|| -> anyhow::Result<bool> {
+ let gc = conn.generate_id()?;
+ conn.create_gc(gc, win, &CreateGCAux::new())?;
+ // Shape before mapping so only the probe strip ever shows, exactly as
+ // the real overlay exposes only its painted runs.
+ conn.shape_rectangles(
+ SO::SET,
+ SK::BOUNDING,
+ ClipOrdering::UNSORTED,
+ win,
+ 0,
+ 0,
+ &[Rectangle {
+ x: 0,
+ y: 0,
+ width: PROBE_WIDTH,
+ height: 1,
+ }],
+ )?;
+ conn.shape_rectangles(SO::SET, SK::INPUT, ClipOrdering::UNSORTED, win, 0, 0, &[])?;
+ conn.map_window(win)?;
+ conn.put_image(
ImageFormat::Z_PIXMAP,
win,
- gc_id,
- bounds.width,
- bounds.height,
- bounds.x,
- bounds.y,
+ gc,
+ PROBE_WIDTH,
+ 1,
+ 0,
+ 0,
0,
depth,
- &bgra,
+ &uploaded,
)?;
- if checked_requests {
- cookie.check()?;
+ // Two reads: the first is ordered right behind the upload on this
+ // connection and catches servers that never see the pixels at all;
+ // the second runs after a pause long enough for a deferred-refresh
+ // server to reprocess the damage. xorgxrdp passes the first read —
+ // the bytes are still in its shadow framebuffer — and only blacks
+ // the region out when its update timer re-renders it from the window
+ // tree, so an immediate-only probe would wrongly bless the visual.
+ let matches_upload = |reply: &x11rb::protocol::xproto::GetImageReply| {
+ // Colour only: the fourth byte is an unused pad in the root read.
+ matches!(reply.depth, 24 | 32)
+ && reply.data.len() == uploaded.len()
+ && uploaded
+ .chunks_exact(4)
+ .zip(reply.data.chunks_exact(4))
+ .all(|(ours, live)| ours[..3] == live[..3])
+ };
+ for pause in [None, Some(Duration::from_millis(80))] {
+ if let Some(pause) = pause {
+ std::thread::sleep(pause);
+ }
+ let reply = conn
+ .get_image(ImageFormat::Z_PIXMAP, root, 0, 0, PROBE_WIDTH, 1, !0u32)?
+ .reply()?;
+ if !matches_upload(&reply) {
+ conn.free_gc(gc)?;
+ return Ok(false);
+ }
}
- }
+ conn.free_gc(gc)?;
+ Ok(true)
+ })();
+ // Destroy on every exit so a failed probe cannot leave a stray mapped
+ // window at the origin.
+ conn.destroy_window(win).ok();
+ conn.flush().ok();
+ probe
+}
- // Keep the previous (or fail-closed empty) shape while uploading pixels,
- // then expose only the freshly rendered alpha runs. This ordering prevents
- // stale/zero-filled backing pixels from becoming visible during repair.
- let shape_cookie = conn.shape_rectangles(
+/// A composited tile: its bounds, the opaque pixels to upload, the tile-local
+/// visible shape, and the backdrop they were blended over.
+#[cfg(target_os = "linux")]
+type X11CompositedTile = (
+ X11TileBounds,
+ Vec<u8>,
+ Vec<x11rb::protocol::xproto::Rectangle>,
+ Vec<u8>,
+);
+
+/// Compose every tile of a frame, or none of it.
+#[cfg(target_os = "linux")]
+fn composite_x11_tiles(
+ now: Instant,
+ tiles: &[X11PaintTile],
+ fresh: &[Vec<u8>],
+ backdrop: &X11BackdropCache,
+) -> Option<Vec<X11CompositedTile>> {
+ tiles
+ .iter()
+ .zip(fresh)
+ .map(|(tile, fresh)| {
+ let under = backdrop.resolve_backdrop(now, tile.bounds, fresh)?;
+ let (bgra, shape) = composited_bgra_and_visible_shape(&tile.pixmap, &under)?;
+ Some((tile.bounds, bgra, shape, under))
+ })
+ .collect()
+}
+
+/// Hide every overlay pixel. Used while a resync waits for the windows we
+/// uncovered to repaint: the wait is only useful if we are not painting.
+#[cfg(target_os = "linux")]
+fn blank_x11_overlay_shape(
+ conn: &impl x11rb::connection::Connection,
+ win: u32,
+ checked_requests: bool,
+) -> anyhow::Result<()> {
+ use x11rb::protocol::shape::{ConnectionExt as ShapeConnectionExt, SK, SO};
+ use x11rb::protocol::xproto::ClipOrdering;
+
+ let cookie = conn.shape_rectangles(
SO::SET,
SK::BOUNDING,
- x11rb::protocol::xproto::ClipOrdering::UNSORTED,
+ ClipOrdering::UNSORTED,
win,
0,
0,
- &visible_shape,
+ &[],
)?;
if checked_requests {
- shape_cookie.check()?;
+ cookie.check()?;
}
-
conn.flush()?;
Ok(())
}
+/// Whether the rendered frame reached the X11 window. `Deferred` means the
+/// overlay deliberately left the previous frame on screen because it could not
+/// account for the pixels this one would cover; the caller must retry on the
+/// next frame tick rather than treating the state as settled.
#[cfg(target_os = "linux")]
-fn bgra_and_visible_shape(
- pm: &tiny_skia::Pixmap,
- compositor_present: bool,
-) -> (Vec<u8>, Vec<x11rb::protocol::xproto::Rectangle>) {
- use x11rb::protocol::xproto::Rectangle;
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+enum X11PaintOutcome {
+ Painted,
+ Deferred,
+}
- let width = pm.width() as usize;
- let height = pm.height() as usize;
- let src = pm.data();
- let mut bgra = Vec::with_capacity(src.len());
+#[cfg(target_os = "linux")]
+fn paint_x11_tiles(
+ conn: &impl x11rb::connection::Connection,
+ target: &X11PaintTarget,
+ tiles: &[X11PaintTile],
+ compositor_present: bool,
+ checked_requests: bool,
+ backdrop: &mut X11BackdropCache,
+) -> anyhow::Result<X11PaintOutcome> {
+ use x11rb::protocol::shape::{ConnectionExt as ShapeConnectionExt, SK, SO};
+ use x11rb::protocol::xproto::{ConnectionExt as XprotoConnectionExt, ImageFormat};
+
+ // Phase A — decide, then read every root rect before any pixel is uploaded.
+ // Under a compositing manager no root read is issued, no record is written
+ // and the cache stays empty: that path is exactly what it was before.
+ let now = Instant::now();
+ let compositing_available = backdrop_compositing_enabled(compositor_present, backdrop);
+ if compositing_available {
+ // Retire stale save-unders before they can be consumed, not after.
+ backdrop.prune(now);
+ } else {
+ backdrop.invalidate();
+ }
+
+ let mut payloads = Vec::with_capacity(tiles.len());
+ let mut visible_shape = Vec::new();
+ let mut saved = Vec::new();
+ let mut composited = false;
+
+ // Phase B — assemble the true backdrop per tile and blend, or hold the
+ // previous frame until we can.
+ if compositing_available && !tiles.is_empty() {
+ if backdrop.resyncing(now) {
+ // Nothing left describes what is under us. Stay invisible until the
+ // windows we uncovered have answered their Expose; painting now
+ // would recontaminate the region we are waiting on and bake our own
+ // cursor into the first save-under.
+ if backdrop.take_resync_blanking() {
+ blank_x11_overlay_shape(conn, target.win, checked_requests)?;
+ }
+ return Ok(X11PaintOutcome::Deferred);
+ }
+
+ match read_root_backdrops(conn, target.root, tiles, backdrop)
+ .and_then(|fresh| composite_x11_tiles(now, tiles, &fresh, backdrop))
+ {
+ Some(frame) => {
+ composited = true;
+ backdrop.note_composited_frame();
+ for (bounds, bgra, mut tile_shape, under) in frame {
+ // Only the painted bounding box is ever consulted again, so
+ // that is all the frame keeps.
+ if let Some(bbox) = shape_bounding_box(&tile_shape) {
+ let width = usize::from(bounds.width);
+ saved.push(X11SavedBackdrop {
+ bounds: X11TileBounds {
+ x: bounds.x.saturating_add(bbox.0 as i16),
+ y: bounds.y.saturating_add(bbox.1 as i16),
+ width: (bbox.2 - bbox.0) as u16,
+ height: (bbox.3 - bbox.1) as u16,
+ },
+ under: crop_tile_pixels(&under, width, bbox),
+ uploaded: crop_tile_pixels(&bgra, width, bbox),
+ });
+ }
+ for rect in &mut tile_shape {
+ rect.x = rect.x.saturating_add(bounds.x);
+ rect.y = rect.y.saturating_add(bounds.y);
+ }
+ visible_shape.extend(tile_shape);
+ payloads.push((bounds, bgra));
+ }
+ }
+ // Hold the previous frame rather than paint pixels no save-under
+ // can explain: doing that once guarantees the next frame fails the
+ // same way, which is how a single transient X11 error would
+ // otherwise latch the cutoff look in for the session. Once the
+ // failures persist, compositing is latched off deliberately and
+ // this frame paints the cutoff tile after all.
+ None if !backdrop.note_unbacked_frame() => {
+ return Ok(X11PaintOutcome::Deferred);
+ }
+ None => {}
+ }
+ }
+
+ if !composited {
+ for tile in tiles {
+ let (bgra, mut tile_shape) = bgra_and_visible_shape(&tile.pixmap, compositor_present);
+ for rect in &mut tile_shape {
+ rect.x = rect.x.saturating_add(tile.bounds.x);
+ rect.y = rect.y.saturating_add(tile.bounds.y);
+ }
+ visible_shape.extend(tile_shape);
+ payloads.push((tile.bounds, bgra));
+ }
+ }
+
+ // Phase C — expose the new shape, then upload into it. The order matters
+ // and is the reverse of what it once was: output to a window is CLIPPED to
+ // its current bounding shape, so uploading first silently discards every
+ // pixel of the frame's frontier — the runs the new shape adds over the old
+ // one — and enlarging the shape afterwards exposes the window's zero
+ // backing there instead. On an ARGB window zero is transparent and the
+ // loss was invisible, but it left the frontier unreadable to the
+ // save-under readback (adopting black as backdrop, which composites the
+ // shadow into a hard black ring), and on a 24-bit window zero shows as
+ // literal black. Shaping first means the frontier briefly exposes zero
+ // backing server-side, but both requests travel in one batch ahead of a
+ // single flush, so no frame with the bare frontier is ever presented.
+ let shape_cookie = conn.shape_rectangles(
+ SO::SET,
+ SK::BOUNDING,
+ x11rb::protocol::xproto::ClipOrdering::UNSORTED,
+ target.win,
+ 0,
+ 0,
+ &visible_shape,
+ )?;
+ if checked_requests {
+ shape_cookie.check()?;
+ }
+
+ // Phase D — upload. A composited buffer covers the whole tile rect; pixels
+ // outside the shape are the backdrop copied back and are never displayed.
+ for (bounds, bgra) in payloads {
+ let cookie = conn.put_image(
+ ImageFormat::Z_PIXMAP,
+ target.win,
+ target.gc_id,
+ bounds.width,
+ bounds.height,
+ bounds.x,
+ bounds.y,
+ 0,
+ target.depth,
+ &bgra,
+ )?;
+ if checked_requests {
+ cookie.check()?;
+ }
+ }
+
+ conn.flush()?;
+
+ // Phase E — record what actually landed, after the flush succeeded. The
+ // rects are exactly what we SET, so the contamination record is truthful. A
+ // clearing paint (no tiles) records an empty frame, which vacates the frame
+ // that was on screen without discarding its save-unders: the trail it left
+ // is still there until its owners repaint it.
+ if compositing_available && backdrop.enabled() && (composited || tiles.is_empty()) {
+ backdrop.record_frame(Instant::now(), visible_shape, saved);
+ }
+ Ok(X11PaintOutcome::Painted)
+}
+
+/// Software-composite a premultiplied cursor tile over the real backdrop under
+/// it. Without a compositing manager the server never blends our alpha, so we
+/// blend here and upload opaque pixels: translucent bloom and antialiased edges
+/// survive instead of being quantized to XShape's one bit of visibility. The
+/// visible region is still the α≠0 runs, exactly as on the compositing path —
+/// at the shape boundary α≈0, so the blended pixel is the backdrop and the
+/// 1-bit edge is invisible.
+///
+/// `backdrop` is a tile-sized row-major BGRX buffer as XGetImage returns it for
+/// the root. Returns `None` when it does not match the tile so callers fail
+/// closed onto the alpha-cutoff path rather than uploading a guess.
+#[cfg(target_os = "linux")]
+fn composited_bgra_and_visible_shape(
+ pm: &tiny_skia::Pixmap,
+ backdrop: &[u8],
+) -> Option<(Vec<u8>, Vec<x11rb::protocol::xproto::Rectangle>)> {
+ use x11rb::protocol::xproto::Rectangle;
+
+ let width = pm.width() as usize;
+ let height = pm.height() as usize;
+ let src = pm.data();
+ if backdrop.len() != src.len() || backdrop.len() != width * height * 4 {
+ return None;
+ }
+
+ let mut bgra = Vec::with_capacity(src.len());
+ let mut rectangles = Vec::new();
+
+ for y in 0..height {
+ let mut run_start = None;
+ for x in 0..width {
+ let offset = (y * width + x) * 4;
+ let pixel = &src[offset..offset + 4];
+ let under = &backdrop[offset..offset + 4];
+ let alpha = pixel[3];
+ let inverse = 255 - u32::from(alpha);
+ // Premultiplied source over an opaque backdrop; the result is
+ // opaque, so alpha carries no information the server has to blend.
+ let over = |source: u8, back: u8| {
+ source.saturating_add(((u32::from(back) * inverse + 127) / 255) as u8)
+ };
+ bgra.extend_from_slice(&[
+ over(pixel[2], under[0]),
+ over(pixel[1], under[1]),
+ over(pixel[0], under[2]),
+ 255,
+ ]);
+
+ if alpha != 0 {
+ run_start.get_or_insert(x);
+ } else if let Some(start) = run_start.take() {
+ rectangles.push(Rectangle {
+ x: start as i16,
+ y: y as i16,
+ width: (x - start) as u16,
+ height: 1,
+ });
+ }
+ }
+ if let Some(start) = run_start {
+ rectangles.push(Rectangle {
+ x: start as i16,
+ y: y as i16,
+ width: (width - start) as u16,
+ height: 1,
+ });
+ }
+ }
+
+ Some((bgra, rectangles))
+}
+
+#[cfg(target_os = "linux")]
+fn bgra_and_visible_shape(
+ pm: &tiny_skia::Pixmap,
+ compositor_present: bool,
+) -> (Vec<u8>, Vec<x11rb::protocol::xproto::Rectangle>) {
+ use x11rb::protocol::xproto::Rectangle;
+
+ let width = pm.width() as usize;
+ let height = pm.height() as usize;
+ let src = pm.data();
+ let mut bgra = Vec::with_capacity(src.len());
let mut rectangles = Vec::new();
for y in 0..height {
@@ -2277,23 +3329,45 @@ mod tests {
assert!(!render_map_needs_z_order_tick(&map));
}
+ // The idle-park contract now applies to reduced-motion sessions: with the
+ // float bob active (the default), a visible cursor keeps ticking so it
+ // levitates at rest, and only a hidden or reduced-motion cursor parks.
#[test]
fn resting_visible_cursor_only_requires_cheap_z_order_ticks() {
let mut map = default_render_map();
let cursor = map.cursors.get_mut("default").unwrap();
cursor.core.pos = (100.0, 100.0);
cursor.core.motion.idle_hide_ms = 0.0;
+ cursor.core.visual.reduced_motion = cursor_overlay::ReducedMotion::On;
assert!(!render_map_needs_frame_tick(&map));
assert!(render_map_needs_z_order_tick(&map));
}
+ #[test]
+ fn resting_visible_cursor_keeps_ticking_for_the_float_bob() {
+ let mut map = default_render_map();
+ let cursor = map.cursors.get_mut("default").unwrap();
+ cursor.core.pos = (100.0, 100.0);
+ cursor.core.motion.idle_hide_ms = 0.0;
+
+ // Default reduced_motion (auto) floats, so frames keep flowing while
+ // the cursor is visible…
+ assert!(render_map_needs_frame_tick(&map));
+
+ // …and stop once the idle fade has fully hidden it.
+ let cursor = map.cursors.get_mut("default").unwrap();
+ cursor.core.idle_alpha = 0.0;
+ assert!(!render_map_needs_frame_tick(&map));
+ }
+
#[test]
fn disabling_settled_cursor_clears_once_then_parks() {
let mut map = default_render_map();
let cursor = map.cursors.get_mut("default").unwrap();
cursor.core.pos = (100.0, 100.0);
cursor.core.motion.idle_hide_ms = 0.0;
+ cursor.core.visual.reduced_motion = cursor_overlay::ReducedMotion::On;
let (_tx, rx) = std::sync::mpsc::channel();
assert!(!render_map_needs_frame_tick(&map));
@@ -2340,6 +3414,7 @@ mod tests {
// before sending MoveTo; mirror that valid on-screen starting state.
cursor.core.pos = (100.0, 100.0);
cursor.core.motion.idle_hide_ms = 500.0;
+ cursor.core.visual.reduced_motion = cursor_overlay::ReducedMotion::On;
cursor.apply_command(OverlayCommand::MoveTo {
x: 250.0,
y: 150.0,
@@ -2511,6 +3586,7 @@ mod tests {
let cursor = map.cursors.get_mut("default").unwrap();
cursor.core.pos = (100.0, 100.0);
cursor.core.motion.idle_hide_ms = 500.0;
+ cursor.core.visual.reduced_motion = cursor_overlay::ReducedMotion::On;
// Cheap 80 ms z-order heartbeats advance the idle clock without
// requesting expensive frame paints during the opaque delay.
@@ -2553,6 +3629,7 @@ mod tests {
let mut map = default_render_map();
let cursor = map.cursors.get_mut("default").unwrap();
cursor.core.motion.idle_hide_ms = 0.0;
+ cursor.core.visual.reduced_motion = cursor_overlay::ReducedMotion::On;
cursor.apply_command(OverlayCommand::ClickPulse { x: 20.0, y: 30.0 });
assert!(cursor.needs_frame_tick());
@@ -2697,6 +3774,8 @@ mod tests {
);
}
+ /// Golden for the documented fallback: whenever the real backdrop cannot be
+ /// read (or a compositor is present), tiles still paint exactly like this.
#[test]
fn compositorless_shape_drops_bloom_and_unpremultiplies_visible_pixels() {
let mut pixmap = tiny_skia::Pixmap::new(4, 1).unwrap();
@@ -2716,6 +3795,738 @@ mod tests {
(1, 0, 3)
);
}
+
+ // ── Save-unders / software compositing ───────────────────────────────
+
+ /// 4×1 premultiplied cursor strip with alphas 0 / 64 / 180 / 255.
+ fn composite_test_pixmap() -> tiny_skia::Pixmap {
+ let mut pixmap = tiny_skia::Pixmap::new(4, 1).unwrap();
+ pixmap.data_mut().copy_from_slice(&[
+ 0, 0, 0, 0, // transparent
+ 32, 16, 8, 64, // faint bloom
+ 180, 90, 45, 180, // translucent body
+ 200, 100, 50, 255, // opaque core
+ ]);
+ pixmap
+ }
+
+ /// Matching BGRX root read: four distinct opaque desktop pixels.
+ fn composite_test_backdrop() -> Vec<u8> {
+ vec![
+ 10, 20, 30, 255, //
+ 40, 50, 60, 255, //
+ 70, 80, 90, 255, //
+ 100, 110, 120, 255,
+ ]
+ }
+
+ fn tile_bounds(x: i16, y: i16, width: u16, height: u16) -> X11TileBounds {
+ X11TileBounds {
+ x,
+ y,
+ width,
+ height,
+ }
+ }
+
+ fn painted_rect(x: i16, y: i16, width: u16, height: u16) -> x11rb::protocol::xproto::Rectangle {
+ x11rb::protocol::xproto::Rectangle {
+ x,
+ y,
+ width,
+ height,
+ }
+ }
+
+ #[test]
+ fn composited_tile_blends_translucent_pixels_over_the_backdrop() {
+ let pixmap = composite_test_pixmap();
+ let backdrop = composite_test_backdrop();
+
+ let (bgra, _) = composited_bgra_and_visible_shape(&pixmap, &backdrop).unwrap();
+
+ assert_eq!(&bgra[0..4], &[10, 20, 30, 255]);
+ assert_eq!(&bgra[4..8], &[38, 53, 77, 255]);
+ assert_eq!(&bgra[8..12], &[66, 114, 206, 255]);
+ assert_eq!(&bgra[12..16], &[50, 100, 200, 255]);
+ // Every uploaded pixel is opaque: the server has nothing left to blend.
+ assert!(bgra.chunks_exact(4).all(|pixel| pixel[3] == 255));
+ }
+
+ #[test]
+ fn composited_tile_reproduces_the_backdrop_where_the_cursor_is_transparent() {
+ let pixmap = composite_test_pixmap();
+ let backdrop = composite_test_backdrop();
+
+ let (bgra, _) = composited_bgra_and_visible_shape(&pixmap, &backdrop).unwrap();
+
+ assert_eq!(&bgra[0..3], &backdrop[0..3]);
+ }
+
+ #[test]
+ fn composited_tile_output_depends_on_the_backdrop() {
+ let pixmap = composite_test_pixmap();
+
+ let (over_white, _) = composited_bgra_and_visible_shape(&pixmap, &[0xFF; 16]).unwrap();
+ let (over_black, _) = composited_bgra_and_visible_shape(&pixmap, &[0x00; 16]).unwrap();
+
+ assert_ne!(&over_white[4..8], &over_black[4..8]);
+ assert_ne!(&over_white[8..12], &over_black[8..12]);
+ // The opaque core hides whatever is beneath it.
+ assert_eq!(&over_white[12..16], &over_black[12..16]);
+ }
+
+ #[test]
+ fn composited_tile_keeps_the_bloom_the_cutoff_path_drops() {
+ let pixmap = composite_test_pixmap();
+ let backdrop = composite_test_backdrop();
+
+ let (_, cutoff_shape) = bgra_and_visible_shape(&pixmap, false);
+ let (bgra, shape) = composited_bgra_and_visible_shape(&pixmap, &backdrop).unwrap();
+
+ // The alpha=64 bloom pixel sits at x=1: the cutoff path shapes it away.
+ assert!(cutoff_shape.iter().all(|rect| rect.x > 1));
+ assert!(shape
+ .iter()
+ .any(|rect| rect.x <= 1 && i32::from(rect.x) + i32::from(rect.width) > 1));
+ // ...and its colour lands strictly between the backdrop and the
+ // unpremultiplied source instead of being forced to either end.
+ let unpremultiplied = [8u32 * 255 / 64, 16 * 255 / 64, 32 * 255 / 64];
+ for (channel, source) in unpremultiplied.iter().enumerate() {
+ let out = u32::from(bgra[4 + channel]);
+ let back = u32::from(backdrop[4 + channel]);
+ assert!(
+ out > back.min(*source) && out < back.max(*source),
+ "channel {channel}: {out} is not between {back} and {source}"
+ );
+ }
+ }
+
+ #[test]
+ fn composited_tile_shape_matches_the_compositing_path() {
+ let pixmap = composite_test_pixmap();
+ let backdrop = composite_test_backdrop();
+
+ let (_, compositing_shape) = bgra_and_visible_shape(&pixmap, true);
+ let (_, composited_shape) = composited_bgra_and_visible_shape(&pixmap, &backdrop).unwrap();
+
+ let as_tuples = |rects: Vec<x11rb::protocol::xproto::Rectangle>| {
+ rects
+ .into_iter()
+ .map(|rect| (rect.x, rect.y, rect.width, rect.height))
+ .collect::<Vec<_>>()
+ };
+ assert_eq!(as_tuples(compositing_shape), as_tuples(composited_shape));
+ }
+
+ #[test]
+ fn composited_tile_rejects_a_mismatched_backdrop() {
+ let pixmap = composite_test_pixmap();
+
+ assert!(composited_bgra_and_visible_shape(&pixmap, &[0u8; 12]).is_none());
+ assert!(composited_bgra_and_visible_shape(&pixmap, &[0u8; 20]).is_none());
+ }
+
+ /// A save-under as the paint path records one: the desktop that was under
+ /// the rect, and the pixels the overlay put on top of it.
+ fn saved_backdrop(
+ bounds: X11TileBounds,
+ under: Vec<u8>,
+ uploaded: Vec<u8>,
+ ) -> X11SavedBackdrop {
+ X11SavedBackdrop {
+ bounds,
+ under,
+ uploaded,
+ }
+ }
+
+ #[test]
+ fn saved_backdrop_serves_pixels_the_overlay_painted_last_frame() {
+ let tile = tile_bounds(0, 0, 4, 1);
+ let desktop: Vec<u8> = (0u8..16).collect();
+ let mut cache = X11BackdropCache::default();
+ let now = Instant::now();
+ cache.record_frame(
+ now,
+ vec![painted_rect(0, 0, 2, 1)],
+ vec![saved_backdrop(tile, desktop.clone(), vec![0xAA; 16])],
+ );
+
+ // 0xAA is what the overlay uploaded, so a root read that still returns
+ // it is our own paint rather than desktop.
+ let out = cache.resolve_backdrop(now, tile, &[0xAA; 16]).unwrap();
+
+ assert_eq!(&out[0..8], &desktop[0..8]);
+ assert_eq!(&out[8..16], &[0xAA; 8]);
+ }
+
+ #[test]
+ fn a_repainted_pixel_is_read_live_even_inside_the_painted_rect() {
+ let tile = tile_bounds(0, 0, 4, 1);
+ let mut cache = X11BackdropCache::default();
+ let now = Instant::now();
+ cache.record_frame(
+ now,
+ vec![painted_rect(0, 0, 2, 1)],
+ vec![saved_backdrop(tile, vec![0x11; 16], vec![0xAA; 16])],
+ );
+
+ // The owner answered its Expose: the first pixel no longer holds what
+ // we uploaded, so the live read is the truth and the stale save-under
+ // must not be served.
+ let mut live = vec![0xAAu8; 16];
+ live[0..4].copy_from_slice(&[0x77, 0x77, 0x77, 0xFF]);
+ let out = cache.resolve_backdrop(now, tile, &live).unwrap();
+
+ assert_eq!(&out[0..4], &[0x77, 0x77, 0x77, 0xFF]);
+ assert_eq!(&out[4..8], &[0x11; 4]);
+ }
+
+ /// The halo regression: on a server whose root reads return black inside
+ /// our own footprint (xorgxrdp + ARGB32 overlay), the mismatch must serve
+ /// the save-under, not adopt the unreadable black — compositing each frame
+ /// over the last otherwise drives a translucent shadow to solid black.
+ #[test]
+ fn untrusted_readback_serves_the_save_under_on_mismatch() {
+ let tile = tile_bounds(0, 0, 4, 1);
+ let mut cache = X11BackdropCache::default();
+ cache.readback_untrusted = true;
+ let now = Instant::now();
+ cache.record_frame(
+ now,
+ vec![painted_rect(0, 0, 2, 1)],
+ vec![saved_backdrop(tile, vec![0x11; 16], vec![0xAA; 16])],
+ );
+
+ // Live read is black where we painted — unreadable, not repainted.
+ let mut live = vec![0xAAu8; 16];
+ live[0..8].fill(0x00);
+ let out = cache.resolve_backdrop(now, tile, &live).unwrap();
+
+ // Both painted pixels come from the save-under; the unpainted rest of
+ // the tile keeps the live read.
+ assert_eq!(&out[0..8], &[0x11; 8]);
+ assert_eq!(&out[8..16], &[0xAA; 8]);
+ }
+
+ #[test]
+ fn readback_comparison_ignores_the_unused_fourth_byte() {
+ let tile = tile_bounds(0, 0, 4, 1);
+ let mut cache = X11BackdropCache::default();
+ let now = Instant::now();
+ // The overlay uploads alpha=255; a depth-24 root read pads with zero.
+ let uploaded: Vec<u8> = (0..4).flat_map(|_| [0x20, 0x30, 0x40, 0xFF]).collect();
+ let live: Vec<u8> = (0..4).flat_map(|_| [0x20, 0x30, 0x40, 0x00]).collect();
+ cache.record_frame(
+ now,
+ vec![painted_rect(0, 0, 4, 1)],
+ vec![saved_backdrop(tile, vec![0x11; 16], uploaded)],
+ );
+
+ assert_eq!(
+ cache.resolve_backdrop(now, tile, &live).unwrap(),
+ vec![0x11; 16]
+ );
+ }
+
+ #[test]
+ fn moving_cursor_reads_only_newly_exposed_pixels_from_the_root() {
+ let first = tile_bounds(0, 0, 4, 1);
+ let second = tile_bounds(2, 0, 4, 1);
+ let mut cache = X11BackdropCache::default();
+ let now = Instant::now();
+
+ // Frame 1: empty cache, the whole tile is read live.
+ let desktop: Vec<u8> = (1u8..17).collect();
+ assert_eq!(
+ cache.resolve_backdrop(now, first, &desktop).unwrap(),
+ desktop
+ );
+ cache.record_frame(
+ now,
+ vec![painted_rect(1, 0, 2, 1)],
+ vec![saved_backdrop(first, desktop.clone(), vec![0xAA; 16])],
+ );
+
+ // Frame 2: the shifted tile. 0xAA marks everything the root read would
+ // hand back, including our own frame-1 pixels.
+ let out = cache.resolve_backdrop(now, second, &[0xAA; 16]).unwrap();
+
+ // x=2 was inside frame 1's shape and still holds our pixels → served
+ // from the save-under.
+ assert_eq!(&out[0..4], &desktop[8..12]);
+ // x=3 was inside frame 1's tile but outside its shape → read live.
+ assert_eq!(&out[4..8], &[0xAA; 4]);
+ // x=4,5 are the newly exposed band → read live.
+ assert_eq!(&out[8..16], &[0xAA; 8]);
+ }
+
+ #[test]
+ fn badge_expansion_reads_the_new_side_strips_from_the_root() {
+ let narrow = tile_bounds(136, 0, 128, 1);
+ let widened = tile_bounds(96, 0, 208, 1);
+ let mut cache = X11BackdropCache::default();
+ let now = Instant::now();
+ cache.record_frame(
+ now,
+ vec![painted_rect(136, 0, 128, 1)],
+ vec![saved_backdrop(
+ narrow,
+ vec![0x33; 128 * 4],
+ vec![0xAA; 128 * 4],
+ )],
+ );
+
+ let out = cache
+ .resolve_backdrop(now, widened, &vec![0xAA; 208 * 4])
+ .unwrap();
+
+ assert_eq!(&out[0..40 * 4], &vec![0xAA; 40 * 4][..]);
+ assert_eq!(&out[40 * 4..168 * 4], &vec![0x33; 128 * 4][..]);
+ assert_eq!(&out[168 * 4..208 * 4], &vec![0xAA; 40 * 4][..]);
+ }
+
+ #[test]
+ fn resolving_fails_when_a_painted_pixel_has_no_saved_backdrop() {
+ let tile = tile_bounds(0, 0, 4, 1);
+ let mut cache = X11BackdropCache::default();
+ let now = Instant::now();
+ cache.record_frame(now, vec![painted_rect(0, 0, 2, 1)], Vec::new());
+
+ assert!(cache.resolve_backdrop(now, tile, &[0xAA; 16]).is_none());
+ }
+
+ #[test]
+ fn a_frame_is_vacated_when_it_is_superseded_not_when_it_was_painted() {
+ let tile = tile_bounds(0, 0, 4, 1);
+ let elsewhere = tile_bounds(8, 0, 4, 1);
+ let start = Instant::now();
+ let mut cache = X11BackdropCache::default();
+ cache.record_frame(
+ start,
+ vec![painted_rect(0, 0, 2, 1)],
+ vec![saved_backdrop(tile, vec![0x11; 16], vec![0xAA; 16])],
+ );
+
+ // The cursor rests for five seconds, then moves. The old frame's pixels
+ // were vacated just now, so the window under them has not repainted yet
+ // and the save-under has to survive the next few frames.
+ let moved = start + Duration::from_secs(5);
+ for step in 0..3 {
+ cache.record_frame(
+ moved + Duration::from_millis(16 * step),
+ vec![painted_rect(8, 0, 2, 1)],
+ vec![saved_backdrop(elsewhere, vec![0x22; 16], vec![0xAA; 16])],
+ );
+ }
+
+ let out = cache
+ .resolve_backdrop(moved + Duration::from_millis(48), tile, &[0xAA; 16])
+ .unwrap();
+ assert_eq!(&out[0..8], &[0x11; 8]);
+ }
+
+ #[test]
+ fn a_long_vacated_frame_stops_being_consulted_without_waiting_for_a_prune() {
+ let tile = tile_bounds(0, 0, 4, 1);
+ let elsewhere = tile_bounds(8, 0, 4, 1);
+ let start = Instant::now();
+ let mut cache = X11BackdropCache::default();
+ cache.record_frame(
+ start,
+ vec![painted_rect(0, 0, 2, 1)],
+ vec![saved_backdrop(tile, vec![0x11; 16], vec![0xAA; 16])],
+ );
+ cache.record_frame(
+ start + Duration::from_millis(16),
+ vec![painted_rect(8, 0, 2, 1)],
+ vec![saved_backdrop(elsewhere, vec![0x22; 16], vec![0xAA; 16])],
+ );
+
+ // Nothing painted for a long while, so nothing pruned either: expiry is
+ // applied where the save-unders are consumed.
+ let later = start + X11_BACKDROP_RETENTION + Duration::from_secs(1);
+ assert_eq!(
+ cache.resolve_backdrop(later, tile, &[0xAA; 16]).unwrap(),
+ vec![0xAA; 16]
+ );
+ }
+
+ #[test]
+ fn pruning_keeps_the_frame_that_is_still_on_screen() {
+ let start = Instant::now();
+ let mut visible = X11BackdropCache::default();
+ visible.record_frame(
+ start,
+ vec![painted_rect(0, 0, 2, 1)],
+ vec![saved_backdrop(
+ tile_bounds(0, 0, 4, 1),
+ vec![0x11; 16],
+ vec![0xAA; 16],
+ )],
+ );
+ visible.prune(start + Duration::from_secs(10));
+ assert_eq!(visible.frames.len(), 1);
+
+ let mut cleared = X11BackdropCache::default();
+ cleared.record_frame(start, Vec::new(), Vec::new());
+ cleared.prune(start + Duration::from_secs(10));
+ assert!(cleared.frames.is_empty());
+ }
+
+ #[test]
+ fn a_clearing_paint_vacates_the_frame_it_replaces_without_dropping_it() {
+ let tile = tile_bounds(0, 0, 4, 1);
+ let start = Instant::now();
+ let mut cache = X11BackdropCache::default();
+ cache.record_frame(
+ start,
+ vec![painted_rect(0, 0, 2, 1)],
+ vec![saved_backdrop(tile, vec![0x11; 16], vec![0xAA; 16])],
+ );
+ // The cursor faded out: the tile is cleared, but the trail it leaves is
+ // still on screen until its owner repaints it.
+ cache.record_frame(start + Duration::from_millis(16), Vec::new(), Vec::new());
+
+ let out = cache
+ .resolve_backdrop(start + Duration::from_millis(32), tile, &[0xAA; 16])
+ .unwrap();
+ assert_eq!(&out[0..8], &[0x11; 8]);
+ }
+
+ #[test]
+ fn retained_frames_are_capped() {
+ let start = Instant::now();
+ let mut cache = X11BackdropCache::default();
+ for step in 0..(X11_BACKDROP_MAX_FRAMES + 8) {
+ cache.record_frame(
+ start + Duration::from_millis(16 * step as u64),
+ vec![painted_rect(0, 0, 2, 1)],
+ vec![saved_backdrop(
+ tile_bounds(0, 0, 4, 1),
+ vec![0x11; 16],
+ vec![0xAA; 16],
+ )],
+ );
+ }
+
+ assert_eq!(cache.frames.len(), X11_BACKDROP_MAX_FRAMES);
+ }
+
+ #[test]
+ fn invalidate_drops_every_saved_backdrop() {
+ let tile = tile_bounds(0, 0, 4, 1);
+ let mut cache = X11BackdropCache::default();
+ let now = Instant::now();
+ cache.record_frame(
+ now,
+ vec![painted_rect(0, 0, 4, 1)],
+ vec![saved_backdrop(tile, vec![0x11; 16], vec![0xAA; 16])],
+ );
+
+ cache.invalidate();
+
+ assert_eq!(
+ cache.resolve_backdrop(now, tile, &[0xAA; 16]).unwrap(),
+ vec![0xAA; 16]
+ );
+ }
+
+ #[test]
+ fn a_resync_blanks_once_and_suppresses_painting_for_the_grace() {
+ let tile = tile_bounds(0, 0, 4, 1);
+ let start = Instant::now();
+ let mut cache = X11BackdropCache::default();
+ cache.record_frame(
+ start,
+ vec![painted_rect(0, 0, 4, 1)],
+ vec![saved_backdrop(tile, vec![0x11; 16], vec![0xAA; 16])],
+ );
+
+ cache.resync(start);
+
+ // The save-unders are gone and painting is suppressed, so no root read
+ // can happen while our own pixels are still on screen.
+ assert!(cache.frames.is_empty());
+ assert!(cache.resyncing(start));
+ assert!(cache.take_resync_blanking());
+ assert!(!cache.take_resync_blanking());
+ assert!(cache.resyncing(start + X11_BACKDROP_RESYNC_GRACE - Duration::from_millis(1)));
+ assert!(!cache.resyncing(start + X11_BACKDROP_RESYNC_GRACE));
+ // The next resync blanks again.
+ cache.resync(start + X11_BACKDROP_RESYNC_GRACE);
+ assert!(cache.take_resync_blanking());
+ }
+
+ #[test]
+ fn a_transient_backdrop_failure_defers_frames_before_latching_compositing_off() {
+ let mut cache = X11BackdropCache::default();
+
+ for _ in 1..X11_BACKDROP_UNBACKED_FRAME_LIMIT {
+ assert!(!cache.note_unbacked_frame());
+ assert!(cache.enabled());
+ }
+ // A frame that composites clears the streak, so a one-off X11 error
+ // cannot cost the session its translucency.
+ cache.note_composited_frame();
+ for _ in 1..X11_BACKDROP_UNBACKED_FRAME_LIMIT {
+ assert!(!cache.note_unbacked_frame());
+ }
+ assert!(cache.enabled());
+
+ assert!(cache.note_unbacked_frame());
+ assert!(!cache.enabled());
+ }
+
+ #[test]
+ fn slow_backdrop_reads_latch_compositing_off() {
+ let over_budget = X11_BACKDROP_READ_BUDGET + Duration::from_millis(1);
+ let mut cache = X11BackdropCache::default();
+
+ cache.note_read_duration(over_budget);
+ cache.note_read_duration(over_budget);
+ assert!(cache.enabled());
+
+ // A fast frame clears the streak.
+ cache.note_read_duration(Duration::from_millis(1));
+ cache.note_read_duration(over_budget);
+ cache.note_read_duration(over_budget);
+ assert!(cache.enabled());
+
+ cache.note_read_duration(over_budget);
+ assert!(!cache.enabled());
+ assert!(cache
+ .resolve_backdrop(Instant::now(), tile_bounds(0, 0, 4, 1), &[0xAA; 16])
+ .is_none());
+ }
+
+ #[test]
+ fn backdrop_compositing_is_disabled_under_a_compositor() {
+ let fresh = X11BackdropCache::default();
+ let latched_off = X11BackdropCache {
+ disabled: true,
+ ..X11BackdropCache::default()
+ };
+
+ assert!(!backdrop_compositing_enabled(true, &fresh));
+ assert!(!backdrop_compositing_enabled(true, &latched_off));
+ assert!(!backdrop_compositing_enabled(false, &latched_off));
+ assert!(backdrop_compositing_enabled(false, &fresh));
+ }
+
+ #[test]
+ fn a_save_under_keeps_only_the_painted_bounding_box() {
+ let shape = vec![painted_rect(2, 1, 3, 1), painted_rect(1, 2, 2, 2)];
+
+ let bbox = shape_bounding_box(&shape).unwrap();
+
+ assert_eq!(bbox, (1, 1, 5, 4));
+ assert!(shape_bounding_box(&[]).is_none());
+ }
+
+ #[test]
+ fn cropping_a_tile_buffer_keeps_row_order() {
+ // 3×3 tile, one distinct byte quad per pixel.
+ let tile: Vec<u8> = (0u8..9)
+ .flat_map(|index| [index, index, index, 255])
+ .collect();
+
+ let cropped = crop_tile_pixels(&tile, 3, (1, 1, 3, 3));
+
+ assert_eq!(
+ cropped,
+ vec![4, 4, 4, 255, 5, 5, 5, 255, 7, 7, 7, 255, 8, 8, 8, 255]
+ );
+ }
+
+ // ── Framebuffer model ────────────────────────────────────────────────
+ //
+ // The save-under logic is only correct against a real screen, where our own
+ // paint is physically present in the pixels a root read returns. These
+ // tests model that screen: paint writes the overlay's pixels into it, reads
+ // come back out of it, and the windows underneath answer their Expose after
+ // a configurable delay. The invariant every frame asserts is the one the
+ // whole design exists for — the backdrop we composite over is the real
+ // desktop, never our own previous frame.
+
+ /// 8×1 premultiplied cursor strip: transparent edges, a translucent bloom
+ /// and an opaque core, i.e. every alpha class the shape has to handle.
+ fn strip_cursor_pixmap() -> tiny_skia::Pixmap {
+ let mut pixmap = tiny_skia::Pixmap::new(8, 1).unwrap();
+ let alphas = [0u8, 40, 120, 255, 255, 120, 40, 0];
+ let data = pixmap.data_mut();
+ for (index, alpha) in alphas.into_iter().enumerate() {
+ let scale = |value: u32| ((value * u32::from(alpha)) / 255) as u8;
+ data[index * 4..index * 4 + 4].copy_from_slice(&[
+ scale(200),
+ scale(120),
+ scale(60),
+ alpha,
+ ]);
+ }
+ pixmap
+ }
+
+ struct ScreenModel {
+ /// What the windows underneath would draw: the answer every composited
+ /// backdrop has to reproduce.
+ desktop: Vec<u8>,
+ /// What a root read actually returns, including our own paint.
+ screen: Vec<u8>,
+ painted_at: Vec<Option<usize>>,
+ /// Frames a vacated pixel takes to be repainted by its owner; `None`
+ /// models a client that never answers its Expose at all.
+ repaint_delay: Option<usize>,
+ }
+
+ impl ScreenModel {
+ fn new(width: usize, repaint_delay: Option<usize>) -> Self {
+ let desktop: Vec<u8> = (0..width)
+ .flat_map(|x| [x as u8, (x * 3) as u8, (x * 7) as u8, 0])
+ .collect();
+ Self {
+ screen: desktop.clone(),
+ painted_at: vec![None; width],
+ desktop,
+ repaint_delay,
+ }
+ }
+
+ fn read(&self, x: usize, width: usize) -> Vec<u8> {
+ self.screen[x * 4..(x + width) * 4].to_vec()
+ }
+
+ fn desktop_slice(&self, x: usize, width: usize) -> Vec<u8> {
+ self.desktop[x * 4..(x + width) * 4].to_vec()
+ }
+
+ /// Redraw part of the desktop. Pixels the overlay is currently covering
+ /// keep our paint: the server clips their owner away from them.
+ fn redraw_desktop(&mut self, range: std::ops::Range<usize>, tint: u8) {
+ for pixel in range {
+ let at = pixel * 4;
+ self.desktop[at..at + 4].copy_from_slice(&[tint, tint / 2, tint / 3, 0]);
+ if self.painted_at[pixel].is_none() {
+ self.screen[at..at + 4].copy_from_slice(&self.desktop[at..at + 4]);
+ }
+ }
+ }
+
+ fn paint(
+ &mut self,
+ frame: usize,
+ x: usize,
+ bgra: &[u8],
+ shape: &[x11rb::protocol::xproto::Rectangle],
+ ) {
+ for rect in shape {
+ for col in usize::from(rect.x as u16)..usize::from(rect.x as u16 + rect.width) {
+ let at = (x + col) * 4;
+ // The server keeps our colour bytes; a depth-24 root read
+ // pads the fourth byte with zero rather than our 255.
+ self.screen[at..at + 3].copy_from_slice(&bgra[col * 4..col * 4 + 3]);
+ self.screen[at + 3] = 0;
+ self.painted_at[x + col] = Some(frame);
+ }
+ }
+
+ let Some(delay) = self.repaint_delay else {
+ return;
+ };
+ for pixel in 0..self.painted_at.len() {
+ let Some(at_frame) = self.painted_at[pixel] else {
+ continue;
+ };
+ if at_frame < frame && frame - at_frame > delay {
+ let at = pixel * 4;
+ self.screen[at..at + 4].copy_from_slice(&self.desktop[at..at + 4]);
+ self.painted_at[pixel] = None;
+ }
+ }
+ }
+ }
+
+ /// Drive the real cache and the real compositing helper across `path`,
+ /// asserting on every frame that the backdrop resolves to the true desktop.
+ fn run_screen_model(model: &mut ScreenModel, path: &[usize], redraw: Option<(usize, u8)>) {
+ let pixmap = strip_cursor_pixmap();
+ let start = Instant::now();
+ let mut cache = X11BackdropCache::default();
+
+ for (frame, &x) in path.iter().enumerate() {
+ if let Some((at_frame, tint)) = redraw {
+ if frame == at_frame {
+ model.redraw_desktop(0..6, tint);
+ }
+ }
+ let now = start + Duration::from_millis(16 * frame as u64);
+ let bounds = tile_bounds(x as i16, 0, 8, 1);
+
+ let fresh = model.read(x, 8);
+ let under = cache
+ .resolve_backdrop(now, bounds, &fresh)
+ .unwrap_or_else(|| panic!("frame {frame}: no backdrop"));
+ assert_eq!(
+ under,
+ model.desktop_slice(x, 8),
+ "frame {frame} composited over something other than the desktop"
+ );
+
+ let (bgra, mut shape) = composited_bgra_and_visible_shape(&pixmap, &under).unwrap();
+ model.paint(frame, x, &bgra, &shape);
+
+ let saved: Vec<X11SavedBackdrop> = shape_bounding_box(&shape)
+ .map(|bbox| X11SavedBackdrop {
+ bounds: tile_bounds(
+ (x + bbox.0) as i16,
+ 0,
+ (bbox.2 - bbox.0) as u16,
+ (bbox.3 - bbox.1) as u16,
+ ),
+ under: crop_tile_pixels(&under, 8, bbox),
+ uploaded: crop_tile_pixels(&bgra, 8, bbox),
+ })
+ .into_iter()
+ .collect();
+ for rect in &mut shape {
+ rect.x = rect.x.saturating_add(x as i16);
+ }
+ cache.record_frame(now, shape, saved);
+ }
+ }
+
+ /// One pass right and back again, so every frame's tile overlaps the trail
+ /// the previous frames left behind.
+ fn sweep_path(limit: usize) -> Vec<usize> {
+ (0..=limit).chain((0..limit).rev()).collect()
+ }
+
+ #[test]
+ fn a_moving_cursor_never_composites_over_its_own_previous_frame() {
+ for delay in [Some(0), Some(1), Some(5)] {
+ let mut model = ScreenModel::new(64, delay);
+ run_screen_model(&mut model, &sweep_path(12), None);
+ }
+ }
+
+ #[test]
+ fn a_client_that_never_answers_expose_still_gets_a_clean_backdrop() {
+ // The 200 ms-style timing guess is exactly what this case used to
+ // break: nothing under the trail is ever repainted, so every vacated
+ // pixel still holds our own paint when it is read back.
+ let mut model = ScreenModel::new(64, None);
+ run_screen_model(&mut model, &sweep_path(12), None);
+ }
+
+ #[test]
+ fn a_backdrop_that_changed_while_uncovered_is_picked_up_again() {
+ // The trail is repainted quickly and then its owner draws something
+ // else there. Returning over it must show the new content, not the
+ // save-under captured on the way out.
+ let mut model = ScreenModel::new(64, Some(1));
+ run_screen_model(&mut model, &sweep_path(12), Some((13, 0x5A)));
+ }
}
#[cfg(not(target_os = "linux"))]
diff --git a/libs/cua-driver/scripts/_install-local-rust.sh b/libs/cua-driver/scripts/_install-local-rust.sh
index 4893a8bda0..f59ec78afc 100755
--- a/libs/cua-driver/scripts/_install-local-rust.sh
+++ b/libs/cua-driver/scripts/_install-local-rust.sh
@@ -501,12 +501,24 @@ INSTALLED_BIN="$BIN_DIR/cua-driver-local"
# so the next invocation picks up this build. Best-effort, never
# fails the install. Survivors (rare on Unix — `pkill` reaches all
# user-owned procs without elevation) get a yellow hint.
+#
+# NOTE: do not use `pkill -x cua-driver-local`. `-x` compares against the
+# kernel's truncated process name — 15 chars on Linux (`comm`) — and
+# `cua-driver-local` is 16, so on Linux it silently matched nothing and
+# every pre-swap daemon survived the install. Match argv[0] instead, and
+# anchor it: an unanchored `-f` pattern also matches the launcher shells
+# whose script *text* contains the daemon path, killing the surrounding
+# session rather than the daemon.
if [ "$OS" = "Darwin" ]; then
launchctl unload "$HOME/Library/LaunchAgents/com.trycua.cua-driver-local.plist" 2>/dev/null || true
elif [ "$OS" = "Linux" ] && command -v systemctl >/dev/null 2>&1; then
systemctl --user stop cua-driver-local.service >/dev/null 2>&1 || true
fi
-pkill -x cua-driver-local >/dev/null 2>&1 || true
+for _daemon_bin in "$INSTALLED_BIN" "$BIN_TARGET"; do
+ [ -n "$_daemon_bin" ] || continue
+ pkill -f "^${_daemon_bin}([[:space:]]|\$)" >/dev/null 2>&1 || true
+done
+unset _daemon_bin
# Agent skill pack symlinks: NOT auto-created. Run
# `cua-driver skills install --local` to symlink agent dirs to the
diff --git a/libs/cua-driver/scripts/uninstall-local.sh b/libs/cua-driver/scripts/uninstall-local.sh
index c152ce9279..2a0258fe3f 100755
--- a/libs/cua-driver/scripts/uninstall-local.sh
+++ b/libs/cua-driver/scripts/uninstall-local.sh
@@ -94,7 +94,15 @@ elif [[ "$OS" == "Linux" && -f "$SYSTEMD_UNIT" ]]; then
rm -f "$SYSTEMD_UNIT"
log "removed systemd user unit $SYSTEMD_UNIT"
fi
-pkill -x cua-driver-local >/dev/null 2>&1 || true
+# See the note in _install-local-rust.sh: `pkill -x cua-driver-local` never
+# matches on Linux, because `-x` compares against the 15-char truncated
+# `comm` and the name is 16. Match argv[0], anchored so the launcher shells
+# that merely mention the path in their script text are left alone.
+for _daemon_bin in "$CLI_LINK" "$HOME_DIR/packages/current/cua-driver-local"; do
+ [ -n "$_daemon_bin" ] || continue
+ pkill -f "^${_daemon_bin}([[:space:]]|\$)" >/dev/null 2>&1 || true
+done
+unset _daemon_bin
# Revoke only the local bundle's TCC rows, while LaunchServices can resolve it.
if [[ "$OS" == "Darwin" && "$RESET_TCC" == "1" ]] && command -v tccutil >/dev/null 2>&1; then