Wayland and XWayland Compatibility

Aqueous is a wlroots 0.20 compositor with native Wayland clients and optional embedded XWayland. Its shell and tooling interfaces are protocols rather than hard-coded dependencies on a particular desktop shell.

Application and rendering protocols

Aqueous exposes the Wayland core compositor, subcompositor, shared-memory, seat, output, and data-device interfaces together with:

XDG shell, activation, decoration, foreign relationships, viewporter, fractional scale, single-pixel buffers, cursor shapes, alpha modifiers, and explicit content type.
Linux DMA-BUF and explicit DRM synchronization where the renderer/backend support them.
Presentation timing, tearing control, FIFO v1 commit pacing, and commit-timing-v1 per-commit deadlines. Both renderer paths are implemented; physical DRM/VRR, scanout, and plane-promotion timing qualification remains outstanding.
XDG dialogs, toplevel dragging, toplevel icons, and client-provided toplevel tags/descriptions. Dragging uses the integrated per-seat drag-and-drop path; external-policy mode hides that global. Tags can be used in window rules.
Color representation and color-management-v1, including parametric image descriptions and the supported Windows HDR descriptions in the Vulkan effects build.
xdg-system-bell-v1 version 1 for configurable visual feedback and custom sound effects. It is available in Vulkan and Pixman builds, including security-context clients and external-policy mode. See System bell for configuration and request handling.

The default client-buffer policy advertises exact fractional output scale. integer-ceil is an opt-in global or per-window compatibility path for toolkits that produce softer output at fractional device coordinates.

For native HDR games using Proton-CachyOS, follow the Steam HDR setup, including enabling HDR on the output and setting the game’s launch options.

Desktop shells and portals

Standard shell and desktop components can use:

wlr layer shell for panels, launchers, notifications, and wallpapers.
ext-workspace-v1 for per-output workspace lists and activation.
ext and wlr foreign-toplevel protocols for task lists and window discovery.
The Aqueous window-info protocol for layouts, content type, detailed states, scene snapshots, decoration negotiation, and overlay diagnostics.
wlr output management, output power, gamma control, and XDG output.
ext idle notification, idle inhibit, and ext session lock.
XDG desktop portals through the packaged wlr/GTK portal configuration.
ext-background-effect-v1 for exact client-requested blur regions in Vulkan effects builds, including compatible DMS/Quickshell clients.
The versioned Aqueous shell protocol and persistent AQUEOUS_SOCKET IPC for state and typed runtime actions. See Shell integration.

Layer-shell exclusive zones feed directly into each output’s usable area. Session-lock surfaces are handled outside ordinary window policy and Auto HDR.

Client and server decorations

Aqueous implements xdg-decoration mode negotiation. With [layout].force_ssd = true, a client that creates an xdg-decoration object is configured for server-side decoration even when it requests client-side mode. Repeated client requests receive a configure response even when policy keeps the same effective mode.

The legacy org_kde_kwin_server_decoration_manager is also available for GTK and older Qt clients. Its display-wide default follows force_ssd.

Applications that do not create the protocol object—or that paint a custom toolbar/title bar into their normal content—are not removable by compositor policy. Use an application setting or a typed [[application]] launch profile for those clients. See Rounded corners and decorations for configuration and diagnostics.

Capture clients can use wlr screencopy and export-DMA-BUF, plus the newer ext image-copy-capture protocol and output/toplevel capture-source protocols. Clipboard tools are supported through core selection, primary selection, and both ext and wlr data-control managers.

Overlay-plane candidates fall back to normal composition while capture or a software cursor requires it, ensuring capture tools see the expected content.

The packaged xdg-desktop-portal-aqueous backend handles ScreenCast and Screenshot with a shell-native source chooser; GTK handles remaining portal interfaces. See portal setup and troubleshooting.

Input protocols

Aqueous supports relative pointer, pointer constraints, pointer gestures, tablet v2, text input v3, input method v2 and its popup surfaces, virtual pointer, virtual keyboard, XWayland keyboard grabs, and compositor-side idle notification. Holding the configured untrap_pointer binding temporarily releases a client pointer constraint and restores it when the key is released.

Physical tablets support per-output absolute pen mapping through input.toml tablet rules, with independent mouse input. Drawing clients need tablet-v2 support; this does not add mouse emulation for applications without native tablet support. Physical HUION/Wacom calibration and XWayland drawing-application compatibility still require device testing.

keyboard-shortcuts-inhibit-v1 lets eligible focused clients inhibit normal compositor bindings. Built-in virtual-terminal switching remains reserved. pointer-warp-v1 supports client cursor repositioning after checks on focus, client ownership, a recent pointer-enter serial, coordinates, grabs, and constraints.

XWayland

When built with -Dxwayland=true, Aqueous starts and manages XWayland itself. Rules match X11 WM_CLASS through class, and aqueousctl reports the X11 backend and identity. Aqueous integrates X11 focus, transient relationships, fullscreen, maximize/minimize, floating geometry, and validated _NET_WM_MOVERESIZE interactions.

The compositor can project XWayland through legacy or native-resolution scaling. Native mode keeps embedded XWayland on the renderer-selected GPU and uses per-output projection suitable for mixed-scale setups. Use -no-xwayland to disable XWayland for one session.

GPU selection and multi-GPU systems

At startup Aqueous resolves the DRM device used for scanout/rendering and exports compatible client-selection variables when appropriate. This keeps clients and the Vulkan renderer on the same device in hybrid-GPU setups. The Vulkan effects build requires the renderer and the pinned wlroots render hook to expose the required integration.

DRM leasing

drm-lease-v1 is implemented for non-desktop DRM connectors, including the connector class used by VR headsets. Aqueous reserves these outside desktop output handling and revokes leases on lock/session changes. Availability depends on the backend and hardware; security-context clients are restricted.

Protocol and headless tests pass, but physical DRM/VR qualification remains outstanding. Protocol support alone is not a claim that a headset has been tested.

Aqueous extension protocols

Screen warming provides exclusive per-output adjustments and commit/restoration status for eligible SDR Vulkan outputs.
Input activity supplies authorized category-only keyboard/mouse press notifications to Pearl.
Capture color metadata describes the destination encoding of supported isolated window captures.

Known protocol gaps

ext-transient-seat-v1 remains unavailable, so clients cannot create temporary independent seats through that protocol. The legacy wlr input-inhibitor protocol is also unavailable; use an ext-session-lock client for screen locking. Superseded generations of xdg-foreign, tablet, input-method, and text-input remain omitted in favor of their supported modern interfaces.

The source protocol inventory tracks implementation and qualification limits. Registry availability can vary with build, renderer, backend, and client policy.