Module frontend 

Headless Smithay compositor, protocol handlers, and input routing. Headless Smithay compositor that stands in for a real display server so ordinary Wayland clients have somewhere to render — their composited output is exactly what the capture pipeline reads back and H.264-encodes. There is no monitor, KMS, or libinput in this process, so everything a desktop session normally receives from hardware — an output to map windows onto, a seat to deliver input to, a clipboard to share — this frontend has to synthesize itself.

This module owns AppState, the single context threaded through every Smithay protocol handler, and implements those handlers: wl_compositor commit handling with the window map/configure/focus state machine, seat/keyboard/pointer/touch routing through FocusTarget, clipboard and primary-selection bridging to Python, and the xdg-shell / layer-shell / xdg-activation / decoration / fractional-scale / dmabuf wiring. It also resolves cursor images to PNG for the Python callback and provides the serial and monotonic-time helpers the input path stamps onto events.

Structs

AppState

Central context threaded through every Smithay handler; owns the Wayland globals, the GBM/EGL (or pixman) renderer state, and the capture/encode pipeline state.

ClientState

Per-client data attached to every Wayland client connection; holds the compositor’s per-client surface state.

OutputCopySession

One ext-image-copy-capture session: an external client capturing one of this compositor’s outputs. A requested frame parks in pending until the render loop has content for it, so delivery happens at most once per composited frame and an unchanged screen holds the frame instead of duplicating it.

OutputNode

One virtual output and everything sized to it: the Smithay Output + its advertised global, its layout position, the damage tracker, render targets, and the (at most one) capture bound to it. id is the Python-facing display key; id 0 is the primary HEADLESS-1 output, which is never destroyed.

PendingHostLayout

A host-capture layout request in flight for one display: the epoch of the apply it rode on, the size the capture was configured for, and the geometry readers parked behind it, answered once the host has decided so they report the size actually captured (the realized-geometry barrier).

PfVirtualKeyboard

In-house zwp_virtual_keyboard_v1 implementation. Smithay’s manager swaps the client-visible seat keymap to the virtual keyboard’s keymap on every VK event and never restores it, leaving every client holding a foreign keymap (and killing the compositor’s overlay keycodes) after any VK use. Here VK key events are TRANSLATED instead: each keycode resolves to its level-0 keysym under the VK client’s own uploaded keymap, maps onto the seat keymap (overlay-binding on demand, batched at keymap upload), and injects through the seat’s regular input path — the seat keymap identity never changes and modifier/pressed-key state stays coherent with server-side injection. VK modifiers requests are ignored: applying a foreign modifier mask would corrupt the seat’s own tracked state, and the supported VK client (selkies’ wayland_typer) binds every keysym at level 0 and never sends them.

WindowMeta

Per-window bookkeeping carried in the window’s user-data map: a stable numeric id the Python side addresses the window by, the display id of the output it is placed on, and whether that output has been chosen yet.

WlCapture

One capture pipeline bound to one output (display id): its settings, encoder set, frame pools, delivery thread, and per-stream bookkeeping. Exactly one capture may run per output; all fields mirror the pipeline strategy documented on AppState, instantiated per display.

Enums

FocusTarget

Input-event target for Smithay’s seat handlers. Smithay requires a concrete type as the “target” of a keyboard / pointer / touch event; FocusTarget bridges that to the concrete Wayland surface behind a window, popup, or layer surface.

GpuEncoder

The one hardware H.264 encoder session backing a capture. Only a single GPU backend is ever live for a given capture, and VA-API and NVENC expose entirely different session types, so this enum is what lets the render and delivery code pass around “the hardware encoder” without caring which vendor path actually produced the frames.

Constants

PARKED_LOGICAL_SIZE

The logical size a parked screen is held at. A nested session lays its desktop out across every screen it has, including one waiting here: at the size of a real screen it would double the session’s coordinate space, sending anything a client centres on the desktop (X11 applications place themselves) onto the screen nobody is watching. Small enough not to move that centre, large enough to lay out on; place_window_on_output configures the real size the moment the screen is given an output.

PARKED_POS

Where a parked window is mapped: clear of every output, so it is composited into none of them. Layout offsets are non-negative — the union layout Selkies computes re-anchors at the origin — so far negative coordinates can never collide with a real output.

Functions

cursor_icon_to_str

Map a Smithay CursorIcon to its CSS cursor-name string, used both for themed-cursor lookup and for the name handed to the Python cursor callback; unknown icons fall back to "default".

next_serial

Hand out the next unique, monotonically increasing Wayland event serial.

output_capture_constraints

Buffer constraints for capturing output: its current mode’s size, the shm formats both render paths can serve, and — with a GLES renderer — the renderer’s dmabuf render formats so a client buffer can be blitted to on the GPU.

output_content_covers

Whether a client on this display has COMMITTED content spanning the whole output. Under forced fullscreen a window answers its configure at the output’s logical size, so one still carrying its pre-configure size reads as not covering and holds the display’s frames.

wayland_time

Millisecond timestamp for pointer / keyboard / touch events.

wayland_utime

Microsecond timestamp for relative-pointer motion.

window_meta

The window’s meta, inserted at new_toplevel; windows created before that (none in practice) read as id 0 / primary output.

window_output_id

The display id of the output this window is placed on (primary when untagged).

windows_on_output

Every window placed on display_id and actually composited there. Keyed off the window’s own output tag rather than the Space’s output map, which only catches up on the next Space::refresh; a parked window carries the tag but is mapped clear of every output.

Type Aliases

ScreenshotRequest

A queued computer-use screenshot as (display id, reply); the reply carries the encoded image or the reason it could not be produced.