display_utils

Display plumbing shared by the WebSocket and WebRTC transports.

Covers X11 RandR display management (resolution modes, extended-desktop logical monitors, framebuffer sizing), per-desktop-environment DPI application, Wayland output-id mapping, pixelflux CaptureSettings population, and cursor payload/cache-handle helpers.

Every RandR operation runs natively on a retained python-xlib connection; the xrandr/cvt/gtf subprocess each one degrades to when the native call fails lives in display_utils_xrandr. Blocking X work runs on executor threads (asyncio.to_thread) under _x11_lock so the event loop never waits on the X server. A helper drops the cached connection on any failure other than an X protocol error: an XError leaves the connection healthy, while a broken connection also frees this session's RandR modes. RandR request failures arrive through the connection's asynchronous error handler -- printed, never raised -- so every mutation reads its result back before claiming success.

An extended desktop is laid out one of two ways, decided by what the server offers (apply_extended_layout). Where it has pluggable outputs -- spare RandR outputs carrying a Connected property, each with a CRTC of its own, which the Xvfb the images build provides -- every display is a real output: a secondary is plugged in, given its exact mode and a position, and unplugged when its client leaves, so window managers and toolkits meet what hardware would show them and need no knowledge of the framebuffer (_sync_apply_output_layout). A layout that both adds a display and moves the primary publishes the move first (output_layout_stage). Anywhere else the server has one CRTC covering the framebuffer and each display is a RandR 1.5 logical monitor over it, which consumers that build their screens from CRTCs do not follow; that layout, the window-manager restart it needs and the subprocess fallbacks are display_utils_xrandr, which this module imports only at the point it falls back.

DPI handling here is X11-only by design: on the Wayland backend a DPI is an output scale on the session compositor (applied in-process through wlr-output-management), never Xft resources — XWayland runs in the compositor's logical space and is scaled with it, so Xft resources merged there would scale applications twice.