Module host 

Host-capture mode: capture/inject as a client of an external compositor. Host-capture mode: pixelflux as a CLIENT of an external Wayland compositor (e.g. labwc running WLR_BACKENDS=headless), inverting the nested topology.

The host compositor owns the session — one seat, one selection, one screen model — and pixelflux captures and injects as a privileged-protocol client: frames via ext_image_copy_capture_v1 where the host offers it (wlroots 0.19+, KWin 6.2+, cosmic) and zwlr_screencopy_v1 (v3 copy_with_damage) everywhere else — both damage-gated, so idle screens cost nothing (PIXELFLUX_HOST_CAPTURE=zwlr forces the fallback); keyboard via a persistent zwp_virtual_keyboard_v1 device carrying selkies’ own keymap text, pointer via zwlr_virtual_pointer_v1. Zero-copy is preserved by allocating the capture buffers from pixelflux’s OWN GBM device (render node — no privileges): the compositor blits straight into the dmabufs the encoder imports, so no CPU ever touches a frame. A host that cannot import our dmabufs (other GPU, software renderer) and any run without a GPU degrade to wl_shm buffers feeding the CPU encode pool.

Every host wl_output maps to one selkies display id, in registry order: a control thread on the primary connection owns wlr-output-management and applies the whole layout (per-output custom modes plus row positions) as one atomic configuration, while each output gets its own capture connection and thread. Input proxies are called from the calloop thread directly (wayland-client proxies are thread-safe); pointer coordinates arrive in the same union-layout space selkies uses, so the virtual-pointer extent is the layout’s bounding box. All capture-side waits poll a wake pipe next to the Wayland socket, so a resize or teardown lands immediately even while the thread is parked in a copy_with_damage wait on a static screen.

Structs

HostCpuFrame

Borrow-by-Arc view of a software frame still sitting in its shm mapping.

HostFrame

A frame the compositor finished blitting, ready for the encoder.

HostSession

The calloop-side session: input proxies plus one capture handle per output.

Constants

LAYOUT_DEADLINE

Bound for one layout application on the control thread: a host that has not answered by then counts as having kept its own mode, which the session then follows, the way a refusal is handled.