@desklink/host 0.3.0 → 0.4.0

package/engine/native/agent_overlay_x11.c

@@ -1,40 +1,82 @@
-// The X server draws cursors outside GetImage(root). No overlay window can
-// expose black pixels, intercept input, or poison agent frame diffs.
+// The agent cue is a click-through override-redirect window that follows the
+// pointer, so it stays visible over windows that set their own cursor and never
+// replaces the person's cursor. With a compositing manager it uses an ARGB
+// visual; without one, a 1-bit shape. It appears in GetImage(root), so each
+// state is reported on stdout before it is drawn and the engine restores the
+// covered pixels in X11 capture (desklink_indicator_covered below).
 #include <X11/Xlib.h>
-#include <X11/Xcursor/Xcursor.h>
+#include <X11/Xutil.h>
+#include <X11/Xresource.h>
+#include <X11/extensions/shape.h>
 #include <math.h>
 #include <fcntl.h>
 #include <stdio.h>
+#include <stdlib.h>
 #include <string.h>
 #include <time.h>
 #include <unistd.h>
+#include "agent_indicator.h"
+
+// The same coverage test the helper draws with, for the engine's capture mask.
+int desklink_indicator_covered(double x, double y, double opacity, double click, double typed, unsigned threshold, double reveal) {
+    return hypot(x,y)<reveal && (indicator_pixel(x,y,opacity,click,typed)>>24) >= threshold;
+}
 
 static double now(void) { struct timespec t; clock_gettime(CLOCK_MONOTONIC, &t); return t.tv_sec + t.tv_nsec/1e9; }
 
-static unsigned pixel(double distance, double radius, double opacity) {
-    double edge = fmax(0, 1 - fabs(distance-radius)/2.5);
-    unsigned alpha = (unsigned)(fmin(1, edge * opacity) * 255);
-    return (alpha << 24) | 0x4c9ed0;
+static double desktop_scale(Display *d) {
+    double scale=1;
+    const char *resources=XResourceManagerString(d);
+    if(!resources) return scale;
+    XrmInitialize(); XrmDatabase db=XrmGetStringDatabase(resources);
+    XrmValue value; char *type;
+    if(db && XrmGetResource(db,"Xft.dpi","Xft.Dpi",&type,&value) && value.addr) {
+        double dpi=strtod(value.addr,NULL);
+        if(isfinite(dpi) && dpi>=96 && dpi<=384)scale=dpi/96;
+    }
+    if(db)XrmDestroyDatabase(db);
+    return scale;
 }
 
 int desklink_agent_overlay_main(const char *display_name) {
     Display *d = XOpenDisplay(display_name);
     if (!d) return 2;
-    Window root = DefaultRootWindow(d);
-    unsigned best_w=64,best_h=64;
-    XQueryBestCursor(d,root,64,64,&best_w,&best_h);
-    unsigned size = best_w < best_h ? best_w : best_h;
-    if (size < 32) { XCloseDisplay(d); return 2; }
-    if (size > 96) size = 96;
-    XcursorImage *image = XcursorImageCreate(size,size);
-    if (!image) { XCloseDisplay(d); return 2; }
-    image->version = XCURSOR_IMAGE_VERSION;
-    Cursor previous = None;
+    int event_base, error_base, screen=DefaultScreen(d);
+    if (!XShapeQueryExtension(d,&event_base,&error_base)) { XCloseDisplay(d); return 2; }
+    Window root = RootWindow(d,screen);
+    double scale=desktop_scale(d);
+    // The arrow reaches 36 logical px from the cue's center.
+    int size=(int)ceil(80*scale);
+    char selection[32]; snprintf(selection,sizeof(selection),"_NET_WM_CM_S%d",screen);
+    XVisualInfo argb;
+    int alpha = XGetSelectionOwner(d,XInternAtom(d,selection,False))!=None
+        && XMatchVisualInfo(d,screen,32,TrueColor,&argb);
+    XSetWindowAttributes attrs={0};
+    attrs.override_redirect=True;
+    attrs.background_pixmap=None;
+    attrs.border_pixel=0;
+    unsigned long mask=CWOverrideRedirect|CWBackPixmap|CWBorderPixel;
+    Visual *visual=DefaultVisual(d,screen); int depth=DefaultDepth(d,screen);
+    if(alpha) {
+        visual=argb.visual; depth=32;
+        attrs.colormap=XCreateColormap(d,root,visual,AllocNone); mask|=CWColormap;
+    } else if(depth<24) { XCloseDisplay(d); return 2; }
+    Window window=XCreateWindow(d,root,0,0,size,size,0,depth,InputOutput,visual,mask,&attrs);
+    XStoreName(d,window,"Desklink agent");
+    XShapeCombineRectangles(d,window,ShapeInput,0,0,NULL,0,ShapeSet,Unsorted);
+    XSelectInput(d,window,ExposureMask);
+    XSelectInput(d,root,SubstructureNotifyMask);
+    GC gc=XCreateGC(d,window,0,NULL);
+    uint32_t *pixels=calloc((size_t)size*size,4);
+    int row=(size+7)/8;
+    char *bits=calloc((size_t)row*size,1);
+    XImage *image=pixels?XCreateImage(d,visual,depth,ZPixmap,0,(char *)pixels,size,size,32,0):NULL;
+    if(!image || !bits || image->bits_per_pixel!=32) { XCloseDisplay(d); return 2; }
     int stdin_flags = fcntl(STDIN_FILENO, F_GETFL);
     fcntl(STDIN_FILENO, F_SETFL, stdin_flags | O_NONBLOCK);
     puts("READY"); fflush(stdout);
-    double target_x=0,target_y=0,cursor_x=0,cursor_y=0,click=0,typed=0,ending=0;
-    int active=0;
+    double target_x=0,target_y=0,cue_x=0,cue_y=0,click=0,typed=0,ending=0,started=0;
+    int active=0,mapped=0,redraw=0,was_animating=0,last_x=-100000,last_y=-100000;
     char pending[128]; size_t used=0;
     for (;;) {
         char bytes[128]; ssize_t n = read(STDIN_FILENO, bytes, sizeof(bytes));
@@ -44,11 +86,12 @@ int desklink_agent_overlay_main(const char *display_name) {
                 pending[used]=0; char kind=0; double px=0,py=0;
                 if (sscanf(pending,"%c %lf %lf",&kind,&px,&py)>=1) {
                     if (kind=='S') ending=now();
-                    else if (kind=='M'||kind=='C'||kind=='T') {
+                    else if ((kind=='M'||kind=='C'||kind=='T') && (active || (px>=0 && py>=0))) {
                         if (px>=0 && py>=0) {
                             target_x=px; target_y=py;
-                            if (!active) { cursor_x=px; cursor_y=py; }
+                            if (!active) { cue_x=px; cue_y=py; }
                         }
+                        if (!active) started=now();
                         active=1;
                         if (kind=='C') click=now();
                         if (kind=='T') typed=now();
@@ -57,47 +100,135 @@ int desklink_agent_overlay_main(const char *display_name) {
                 used=0;
             } else if (used < sizeof(pending)-1) pending[used++]=bytes[i];
         }
+        while (XPending(d)) {
+            XEvent event; XNextEvent(d,&event);
+            if (event.type==Expose && event.xexpose.window==window) redraw=1;
+            // Stay above windows and menus mapped or restacked after us.
+            if (mapped && ((event.type==MapNotify && event.xmap.window!=window)
+                || (event.type==ConfigureNotify && event.xconfigure.window!=window))) XRaiseWindow(d,window);
+        }
         double t=now();
-        if (ending && t-ending>0.55) break;
+        if (ending && (!active || t-ending>0.55)) break;
         if (active) {
-            cursor_x += (target_x-cursor_x)*0.24;
-            cursor_y += (target_y-cursor_y)*0.24;
-            int radius=(int)size/2-3;
-            image->xhot = (unsigned)fmax(0,fmin(size-1,(double)size/2+target_x-cursor_x));
-            image->yhot = (unsigned)fmax(0,fmin(size-1,(double)size/2+target_y-cursor_y));
-            for (unsigned y=0;y<size;y++) for (unsigned x=0;x<size;x++) {
-                double distance=hypot(x-(double)size/2,y-(double)size/2);
-                double opacity=ending ? fmax(0,1-(t-ending)/0.55) : 1;
-                unsigned color=pixel(distance,12,0.72*opacity);
-                if (distance>=16 && distance<=radius) {
-                    unsigned outer=pixel(distance,20,0.20*opacity);
-                    if ((outer>>24)>(color>>24)) color=outer;
+            cue_x += (target_x-cue_x)*0.24;
+            cue_y += (target_y-cue_y)*0.24;
+            double opacity=ending ? fmax(0,1-(t-ending)/0.55) : fmin(1,(t-started)/0.18);
+            double c=click?(t-click)/0.55:-1, k=typed?(t-typed)/0.4:-1;
+            int animating = opacity<1 || (c>=0 && c<1) || (k>=0 && k<1);
+            // One more frame once an animation ends, so the rest state is exact.
+            if (!animating && was_animating) redraw=1;
+            was_animating=animating;
+            int x=(int)lround(cue_x), y=(int)lround(cue_y);
+            if (animating || redraw || x!=last_x || y!=last_y) {
+                // A 1-bit shape cannot fade: reveal outward from the tip and
+                // retract inward, so coverage only grows while appearing and a
+                // still cue never uncovers stale pixels.
+                double unit=scale, reveal=alpha?99:40*opacity*(2-opacity);
+                memset(bits,0,(size_t)row*size);
+                for (int py=0;py<size;py++) for (int px=0;px<size;px++) {
+                    double lx=(px-size/2.0)/unit, ly=(py-size/2.0)/unit;
+                    uint32_t color=hypot(lx,ly)<reveal?indicator_pixel(lx,ly,alpha?opacity:1,c,k):0;
+                    unsigned a=color>>24;
+                    if (alpha) { pixels[py*size+px]=color; continue; }
+                    if (a<128) { pixels[py*size+px]=0; continue; }
+                    bits[py*row+px/8]|=(char)(1<<(px%8));
+                    // Un-premultiply: the shaped path paints opaque pixels.
+                    pixels[py*size+px]=((((color>>16)&255)*255/a)<<16)|((((color>>8)&255)*255/a)<<8)|((color&255)*255/a);
                 }
-                if (click && t-click<0.5) {
-                    double progress=(t-click)/0.5;
-                    unsigned ripple=pixel(distance,12+(radius-14)*progress,0.6*(1-progress)*opacity);
-                    if ((ripple>>24)>(color>>24)) color=ripple;
+                // Announce first: capture reads this pipe after each grab, so
+                // every state a grab can see is already announced.
+                printf("P %d %d %d %.6f %.4f %.4f %.4f %u %.4f\n",x-size/2,y-size/2,size,unit,alpha?opacity:1,c,k,alpha?1u:128u,reveal);
+                // No reader means the engine is gone: leave at once rather
+                // than animate unmasked into whatever captures next.
+                if (fflush(stdout)) break;
+                if (!alpha) {
+                    Pixmap shape=XCreateBitmapFromData(d,window,bits,size,size);
+                    XShapeCombineMask(d,window,ShapeBounding,0,0,shape,ShapeSet);
+                    XFreePixmap(d,shape);
                 }
-                if (typed && t-typed<0.35) {
-                    double progress=(t-typed)/0.35;
-                    if (distance<5+progress*12) {
-                        unsigned pulse=(unsigned)(0.22*(1-progress)*opacity*255);
-                        if (pulse>(color>>24)) color=(pulse<<24)|0x5baed8;
-                    }
-                }
-                image->pixels[y*size+x]=color;
-            }
-            Cursor next=XcursorImageLoadCursor(d,image);
-            if (next!=None) {
-                XDefineCursor(d,root,next); XFlush(d);
-                if (previous!=None) XFreeCursor(d,previous);
-                previous=next;
+                if (x!=last_x || y!=last_y) XMoveWindow(d,window,x-size/2,y-size/2);
+                if (!mapped) { XMapRaised(d,window); mapped=1; }
+                XPutImage(d,window,gc,image,0,0,0,0,size,size);
+                // Wait until the server has drawn it, so at most the newest
+                // announced state is not on screen yet.
+                XSync(d,False);
+                last_x=x; last_y=y; redraw=0;
             }
         }
         usleep(16000);
     }
-    XUndefineCursor(d,root); XFlush(d);
-    if (previous!=None) XFreeCursor(d,previous);
-    XcursorImageDestroy(image); XCloseDisplay(d);
+    XDestroyWindow(d,window);
+    XDestroyImage(image); free(bits);
+    XFreeGC(d,gc); XCloseDisplay(d);
+    return 0;
+}
+
+// Point cues are independent of the real cursor. A shaped override-redirect
+// window works without a compositor; an empty input shape passes every event
+// through and mapping it never asks for keyboard focus. It intentionally appears
+// in GetImage(root), so the local person and the video observer share the cue.
+
+int desklink_point_overlay_main(const char *display_name) {
+    Display *d = XOpenDisplay(display_name);
+    if (!d) return 2;
+    int event_base, error_base;
+    if (!XShapeQueryExtension(d, &event_base, &error_base)) { XCloseDisplay(d); return 2; }
+    int screen = DefaultScreen(d), width = DisplayWidth(d, screen), height = DisplayHeight(d, screen);
+    Window root = RootWindow(d, screen);
+    XSetWindowAttributes attrs = {0};
+    attrs.override_redirect = True;
+    attrs.background_pixel = 0x4c9ed0;
+    Window window = XCreateWindow(d, root, 0, 0, width, height, 0,
+        CopyFromParent, InputOutput, CopyFromParent, CWOverrideRedirect | CWBackPixel, &attrs);
+    XStoreName(d, window, "Desklink point");
+    XShapeCombineRectangles(d, window, ShapeInput, 0, 0, NULL, 0, ShapeSet, Unsorted);
+    Pixmap mask = XCreatePixmap(d, root, width, height, 1);
+    GC shape = XCreateGC(d, mask, 0, NULL), ink = XCreateGC(d, window, 0, NULL);
+    XFontStruct *font = XLoadQueryFont(d, "fixed");
+    if (font) XSetFont(d, ink, font->fid);
+    XSetLineAttributes(d, shape, 4, LineSolid, CapRound, JoinRound);
+    fcntl(STDIN_FILENO, F_SETFL, fcntl(STDIN_FILENO, F_GETFL) | O_NONBLOCK);
+    puts("READY"); fflush(stdout);
+    char pending[512]; size_t used = 0;
+    double deadline = 0;
+    for (;;) {
+        char bytes[512]; ssize_t n = read(STDIN_FILENO, bytes, sizeof(bytes));
+        if (n == 0) break;
+        for (ssize_t i = 0; i < n; i++) {
+            if (bytes[i] != '\n') { if (used < sizeof(pending)-1) pending[used++] = bytes[i]; continue; }
+            pending[used] = 0; used = 0;
+            double px, py; unsigned timeout; int offset = 0;
+            if (sscanf(pending, "P %lf %lf %u %n", &px, &py, &timeout, &offset) != 3 || !offset) continue;
+            const char *label = pending + offset;
+            int x = (int)px, y = (int)py, len = (int)strlen(label);
+            int badge_w = font ? XTextWidth(font, label, len) + 16 : len * 6 + 16;
+            if (badge_w > width) badge_w = width;
+            int badge_x = x + 30, badge_y = y - 14;
+            if (badge_x + badge_w > width) badge_x = width - badge_w;
+            if (badge_y < 0) badge_y = 0;
+            if (badge_y + 28 > height) badge_y = height - 28;
+            XUnmapWindow(d, window);
+            XSetForeground(d, shape, 0); XFillRectangle(d, mask, shape, 0, 0, width, height);
+            XSetForeground(d, shape, 1);
+            XDrawArc(d, mask, shape, x-18, y-18, 36, 36, 0, 360*64);
+            XFillArc(d, mask, shape, x-3, y-3, 6, 6, 0, 360*64);
+            if (len) XFillRectangle(d, mask, shape, badge_x, badge_y, badge_w, 28);
+            XShapeCombineMask(d, window, ShapeBounding, 0, 0, mask, ShapeSet);
+            XMapRaised(d, window);
+            XClearWindow(d, window);
+            if (len) {
+                XSetForeground(d, ink, 0x123047);
+                XFillRectangle(d, window, ink, badge_x, badge_y, badge_w, 28);
+                XSetForeground(d, ink, 0xffffff);
+                XDrawString(d, window, ink, badge_x+8, badge_y+18, label, len);
+            }
+            XSync(d, False);
+            deadline = now() + timeout/1000.0;
+        }
+        if (deadline && now() >= deadline) { XUnmapWindow(d, window); XFlush(d); deadline = 0; }
+        usleep(5000);
+    }
+    XDestroyWindow(d, window); XFreeGC(d, shape); XFreeGC(d, ink);
+    XFreePixmap(d, mask); if (font) XFreeFont(d, font); XCloseDisplay(d);
     return 0;
 }

package/engine/src/capture.rs

@@ -13,7 +13,7 @@ use pw::spa;
 use pw::spa::pod::{serialize::PodSerializer, Pod};
 use std::io::Cursor;
 use std::os::fd::OwnedFd;
-use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
 use std::sync::{mpsc, Arc, Mutex};
 use std::thread::JoinHandle;
 use std::time::{Duration, Instant};
@@ -55,6 +55,7 @@ pub struct Capture {
     quit: pw::channel::Sender<()>,
     thread: Option<JoinHandle<()>>,
     pub source: SelectedSource,
+    cursor_positions: Arc<AtomicBool>,
     geometry: Arc<Mutex<Option<StreamGeometry>>>,
     frames: Arc<AtomicU64>,
     dropped: Arc<AtomicU64>,
@@ -63,6 +64,9 @@ pub struct Capture {
 }
 
 impl Capture {
+    pub fn cursor_positions(&self) -> bool {
+        self.cursor_positions.load(Ordering::Relaxed)
+    }
     pub fn geometry(&self) -> Option<StreamGeometry> {
         self.geometry.lock().ok().and_then(|g| g.clone())
     }
@@ -193,16 +197,29 @@ fn buffer_pod(buffer: &mut Vec<u8>) -> Result<()> {
 }
 
 /// Start capturing `session`'s node, delivering I420 frames to `sink`.
+#[allow(clippy::too_many_arguments)]
 pub fn start(
     session: PortalSession,
     encoded_width: usize,
     encoded_height: usize,
     max_fps: u32,
+    cursor_sink: Option<crate::cursor::CursorSink>,
     sink: FrameSink,
     indicator_position: Option<Arc<Mutex<Option<(i64, i64)>>>>,
     on_stop: Box<dyn Fn(String) + Send>,
 ) -> Result<Capture> {
-    let PortalSession { fd, source, .. } = session;
+    let PortalSession {
+        fd,
+        source,
+        cursor_mode,
+        ..
+    } = session;
+    let cursor_positions = Arc::new(AtomicBool::new(false));
+    let cursor_sink = if cursor_mode == "metadata" {
+        cursor_sink
+    } else {
+        None
+    };
     let geometry = Arc::new(Mutex::new(None));
     let frames = Arc::new(AtomicU64::new(0));
     let dropped = Arc::new(AtomicU64::new(0));
@@ -210,7 +227,9 @@ pub fn start(
     let (ready_tx, ready_rx) = mpsc::channel::<Result<(), String>>();
 
     let node_id = source.node_id;
+    let source_size = (source.width.max(1) as usize, source.height.max(1) as usize);
     let thread = {
+        let cursor_positions = cursor_positions.clone();
         let geometry = geometry.clone();
         let frames = frames.clone();
         let dropped = dropped.clone();
@@ -221,9 +240,12 @@ pub fn start(
                 let result = run_loop(
                     fd,
                     node_id,
+                    source_size,
                     encoded_width,
                     encoded_height,
                     max_fps,
+                    cursor_sink,
+                    cursor_positions,
                     sink,
                     indicator_position,
                     on_stop,
@@ -250,6 +272,7 @@ pub fn start(
         quit,
         thread: Some(thread),
         source,
+        cursor_positions,
         geometry,
         frames,
         dropped,
@@ -268,9 +291,12 @@ pub fn start(
 fn run_loop(
     fd: OwnedFd,
     node_id: u32,
+    source_size: (usize, usize),
     encoded_width: usize,
     encoded_height: usize,
     max_fps: u32,
+    cursor_sink: Option<crate::cursor::CursorSink>,
+    cursor_positions: Arc<AtomicBool>,
     sink: FrameSink,
     indicator_position: Option<Arc<Mutex<Option<(i64, i64)>>>>,
     on_stop: Box<dyn Fn(String) + Send>,
@@ -302,6 +328,8 @@ fn run_loop(
     let stream = pw::stream::StreamBox::new(&core, "desklink-capture", props)
         .context("pw_stream_new failed")?;
 
+    let wants_cursor_meta = cursor_sink.is_some();
+    let mut cursor = cursor_sink.map(crate::cursor::Reporter::new);
     let mut state = StreamState {
         box_w: encoded_width,
         box_h: encoded_height,
@@ -367,6 +395,31 @@ fn run_loop(
             let Some(mut buffer) = stream.dequeue_buffer() else {
                 return;
             };
+            if let Some(cursor) = cursor.as_mut() {
+                if let Some(meta) = buffer.find_meta::<spa::buffer::meta::MetaCursor>() {
+                    cursor_positions.store(true, Ordering::Relaxed);
+                    // The wrapper's size check bounds the bitmap header;
+                    // never follow an unchecked bitmap offset.
+                    let bitmap = buffer
+                        .find_meta::<CursorWithBitmap>()
+                        .filter(|m| {
+                            m.cursor.bitmap_offset as usize
+                                == std::mem::size_of::<spa::sys::spa_meta_cursor>()
+                        })
+                        .map(|m| &m.bitmap);
+                    if state.logical_w == 0 || state.logical_h == 0 {
+                        return;
+                    }
+                    let mut position = *meta.as_raw();
+                    position.position.x = (i64::from(position.position.x) * source_size.0 as i64)
+                        .div_euclid(state.logical_w as i64)
+                        as i32;
+                    position.position.y = (i64::from(position.position.y) * source_size.1 as i64)
+                        .div_euclid(state.logical_h as i64)
+                        as i32;
+                    cursor.update_spa(&position, bitmap, source_size.0, source_size.1);
+                }
+            }
             let Some(format) = state.format else { return };
             let datas = buffer.datas_mut();
             if datas.is_empty() {
@@ -463,10 +516,15 @@ fn run_loop(
     format_pod(&mut format_buf, max_fps)?;
     let mut buffer_buf = Vec::new();
     buffer_pod(&mut buffer_buf)?;
-    let mut params = [
+    let mut cursor_buf = Vec::new();
+    cursor_pod(&mut cursor_buf)?;
+    let mut params = vec![
         Pod::from_bytes(&format_buf).context("invalid EnumFormat pod")?,
         Pod::from_bytes(&buffer_buf).context("invalid Buffers pod")?,
     ];
+    if wants_cursor_meta {
+        params.push(Pod::from_bytes(&cursor_buf).context("invalid Cursor Meta pod")?);
+    }
 
     stream
         .connect(
@@ -483,7 +541,8 @@ fn run_loop(
 
 // The portal composites layer-shell into its pixels. Keep the last clean
 // backing for the helper's bounded circle and edge strips before diff/encode;
-// the center stays live so a click marker at the caret remains observable.
+// the center (4 logical px, which the cue leaves clear) stays live so a
+// click marker at the caret remains observable.
 struct IndicatorMask {
     position: Arc<Mutex<Option<(i64, i64)>>>,
     clean: Option<Vec<u8>>,
@@ -533,6 +592,7 @@ impl IndicatorMask {
                     )
                 });
             let radius = (150 * width / source_w).max(55) as i64;
+            let hole = (4 * width / source_w) as i64;
             let edge = (20 * width / source_w)
                 .max(8)
                 .min(width / 2)
@@ -572,7 +632,7 @@ impl IndicatorMask {
                         };
                         (col as i64 - cx).pow(2) + (row as i64 - cy).pow(2) <= radius * radius
                     });
-                    if (distance <= radius * radius || along) && distance > 16 {
+                    if (distance <= radius * radius || along) && distance > hole * hole {
                         let at = start + col * 4;
                         raw[at..at + 4].copy_from_slice(&clean[at..at + 4]);
                     }
@@ -658,6 +718,7 @@ mod tests {
                 origin_x: 0,
                 origin_y: 0,
             },
+            cursor_positions: Arc::new(AtomicBool::new(false)),
             geometry: Arc::new(Mutex::new(None)),
             frames: Arc::new(AtomicU64::new(0)),
             dropped: Arc::new(AtomicU64::new(0)),
@@ -678,3 +739,33 @@ mod tests {
             .expect("capture stopped and joined");
     }
 }
+
+fn cursor_pod(buffer: &mut Vec<u8>) -> Result<()> {
+    use spa::pod::{object, property, Value};
+    let obj = object!(
+        spa::utils::SpaTypes::ObjectParamMeta,
+        spa::param::ParamType::Meta,
+        property!(
+            RawKey(spa::sys::SPA_PARAM_META_type),
+            Id,
+            RawKey(spa::sys::SPA_META_Cursor)
+        ),
+        property!(
+            RawKey(spa::sys::SPA_PARAM_META_size),
+            Int,
+            (std::mem::size_of::<CursorWithBitmap>() + 256 * 256 * 4) as i32
+        )
+    );
+    PodSerializer::serialize(Cursor::new(buffer), &Value::Object(obj))
+        .map(|_| ())
+        .map_err(|e| anyhow::anyhow!("failed to build Cursor Meta pod: {e}"))
+}
+
+#[repr(C)]
+struct CursorWithBitmap {
+    cursor: spa::sys::spa_meta_cursor,
+    bitmap: spa::sys::spa_meta_bitmap,
+}
+impl spa::buffer::meta::Metadata for CursorWithBitmap {
+    const META_TYPE: u32 = spa::sys::SPA_META_Cursor;
+}

package/engine/src/capture_win.rs

@@ -0,0 +1,23 @@
+//! Windows desktop capture is deferred; encoded sources never call this adapter.
+use crate::convert::I420;
+use crate::portal::PortalSession;
+use anyhow::{bail, Result};
+
+pub type FrameSink = Box<dyn Fn(I420, u64, Pixels) + Send + 'static>;
+pub type Pixels<'a> = &'a mut dyn FnMut() -> Option<Vec<u8>>;
+pub struct Capture;
+
+pub fn unavailable_reason() -> &'static str {
+    "Windows display capture is not implemented in this build."
+}
+
+pub fn start(
+    _session: PortalSession,
+    _width: usize,
+    _height: usize,
+    _fps: u32,
+    _sink: FrameSink,
+    _status: Box<dyn Fn(bool, String) + Send>,
+) -> Result<Capture> {
+    bail!("{}", unavailable_reason())
+}