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, and FIFO v1 commit pacing. FIFO is available in both Vulkan and diagnostic builds; physical DRM/VRR and FIFO plane-promotion qualification remain outstanding.
• 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.

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, sharing, and clipboard

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.

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.

Known protocol gaps

The current compositor does not expose DRM lease v1 or the legacy wlr input-inhibitor protocol. The practical effects are:

• VR headsets that require DRM leasing are not yet supported.
• Old lock tools that only understand wlr input inhibition should be replaced with an ext-session-lock client.

Staging XDG dialog/toplevel-drag protocols and superseded legacy generations of xdg-foreign, tablet, input-method, and text-input are also not exposed. Modern versions of those capabilities are supported where listed above.

Note

General Plasma- and GNOME-private shell APIs are not implemented beyond the legacy decoration compatibility described above. This does not prevent standard Wayland applications from running, but desktop components that require compositor-specific private APIs need a protocol-compatible alternative.