Protocol Support

Sweets implements a range of Wayland protocols for activation, cross-client window relationships, pointer control, and input methods. This page covers each one and how Sweets handles it.

XDG Activation

Sweets implements xdg-activation-v1. Launchers, portals, notifications, and applications can request activation for a mapped XDG toplevel.

If the surface belongs to a managed window and the session is unlocked, Sweets switches to that window's workspace and focuses it. Requests for unmapped, unmanaged, or non-XDG surfaces are ignored.

XDG Foreign

Sweets implements xdg-foreign v1 and v2. Applications and portals can export a toplevel from one client and import it from another. This lets helper windows, dialogs, and embedded flows establish parent/child relationships across processes.

# smoke test
wayland-info | rg 'zxdg_(exporter|importer)_v[12]'

Relative Pointer and Pointer Constraints

Sweets implements relative-pointer-v1 and pointer-constraints-v1. Games, virtual machines, remote desktop clients, and 3D tools can request relative pointer events and lock or confine the pointer while their surface has focus.

Sweets activates constraints for the pointer-focused root surface on seat0.

• Locked pointers keep the compositor cursor stationary while relative motion continues to the client.
• Confined pointers clamp cursor motion to the client's constraint region.

Compositor-owned move/resize grabs do not send relative pointer motion.

Text Input and Input Methods

Sweets implements text-input-v3 and input-method-v2, the pair used by frameworks such as Fcitx5 and IBus for preedit text, candidate windows, and surrounding-text updates.

Normal XDG windows and keyboard-interactive layer-shell surfaces can receive text-input focus. One input method can bind to seat0. IME keyboard grabs work after compositor keybindings, and popup surfaces are placed near the client's cursor rectangle. Session lock clears IME focus so lock surfaces receive raw keyboard input.

# smoke test
fcitx5 -d
WAYLAND_DISPLAY=$WAYLAND_DISPLAY foot

Then focus a text field and switch to an input method with preedit UI.

Virtual Keyboards

Sweets implements virtual-keyboard-v1, so on-screen keyboards, accessibility tools, and some input-method setups can inject keyboard events into seat0.

Virtual keyboards use the same routing as physical ones: compositor keybindings first, then shortcut inhibition and IME policy, then focused-client delivery. Session lock takes priority.

# smoke test
wayland-info | rg zwp_virtual_keyboard_manager_v1

For an interactive test, use an on-screen keyboard such as wvkbd.

Virtual Pointers

Sweets implements virtual-pointer-v1, so remote-control, accessibility, and automation tools can inject motion, buttons, and scroll into seat0.

Virtual pointers use the normal cursor path. Output activation, focus-follows-mouse, pointer constraints, interactive move/resize, and click focus all behave as with physical pointers.

# smoke test
wayland-info | rg zwlr_virtual_pointer_manager_v1

Presentation Time

Sweets implements wp_presentation_time. Clients receive accurate presentation feedback: the exact time a frame hit the screen, the refresh cycle, and whether it used zero copy or hardware clocks. Media players and games use this for frame pacing and A/V sync.

There is nothing to configure. The scene graph emits feedback for every surface it presents, tracking each output's real refresh.

# smoke test
wayland-info | rg wp_presentation

Foreign Toplevel Listing

Sweets publishes the list of open windows so taskbars, docks, and switchers can show and act on them. It implements both the older zwlr_foreign_toplevel_management_v1 and the modern ext-foreign-toplevel-list side by side.

Each XDG toplevel appears as a handle on both, created on map and removed on unmap, with title and app-id kept in sync.

• The zwlr manager also carries state — focused, fullscreen, maximized, per-output — and accepts activate, close, fullscreen, and maximize requests.
• ext-foreign-toplevel-list is listing-only by design, mirroring just title and app-id.

# smoke test
wayland-info | rg 'foreign_toplevel'

Toplevel Icon

Sweets implements xdg-toplevel-icon-v1. A client can give an individual window its own icon — a themed name or pixel buffers — overriding the default derived from app-id. This helps when one app shows several windows wanting distinct icons.

Sweets draws no title bars, so it does not paint the icon. It records the per-window icon name and exposes it through the IPC windows query as icon="<name>", so an IPC-driven bar can render it.

Buffer-only icons are accepted but not surfaced, since text IPC cannot carry raw pixels. The compositor advertises preferred icon sizes from 16 to 64 px.

# smoke test
wayland-info | rg xdg_toplevel_icon_manager_v1

Server-Side Decorations

Sweets draws window borders itself, so it asks clients not to draw title bars. It implements both xdg-decoration and KDE's obsolete org_kde_kwin_server_decoration, for clients that only speak the old one.

Both default to server-side. For xdg-decoration Sweets forces server-side mode on every toplevel and re-asserts it if a client renegotiates. For KDE server-decoration it advertises a server-side default mode, the signal those clients read to drop their own decorations.

# smoke test
wayland-info | rg 'decoration'

Single-Pixel Buffer

Sweets implements single-pixel-buffer-v1. Clients can create a 1×1 solid-color buffer without allocating shared memory. Portals and some toolkits use this for cheap solid fills and placeholder surfaces. Nothing to configure.

# smoke test
wayland-info | rg wp_single_pixel_buffer_manager_v1

Alpha Modifier

Sweets implements the staging alpha-modifier-v1 protocol and advertises wp_alpha_modifier_v1 version 1. A client can commit a constant opacity for one of its own surfaces without reattaching its buffer. The value is double-buffered with the rest of wl_surface state and is independent for roots, subsurfaces, popups, cursors, drag icons, input-method surfaces, and lock surfaces.

Client pixel alpha, this per-surface multiplier, and any Sweets appearance-rule opacity multiply exactly once. A value below one removes that surface's opaque region, damages its visible geometry on commit, and prevents a fullscreen tree containing it from entering direct primary-plane scanout. Static state does not produce continuous redraws. Display and isolated-window capture preserve the resulting alpha.

Destroying the modifier restores the unspecified/unit multiplier on the next surface commit. Duplicate construction and requests made after destroying the associated surface are protocol errors scoped to the offending client. Security-context clients can use the protocol because it is self-surface presentation state, not an observation or administration capability.

# smoke test
wayland-info | rg wp_alpha_modifier_v1

Background Effect

Sweets implements staging ext-background-effect-v1 and advertises ext_background_effect_manager_v1 version 1 with only the blur capability. One effect object belongs to one wl_surface; its optional region is copied from the supplied wl_region, double-buffered, and applied on that surface's next commit. Exact rectangular, disjoint, and subtractive shapes are retained. Unset and explicitly empty regions remain distinct but both draw no protocol effect.

The protocol is admitted for ordinary managed XDG roots and subsurfaces, XDG popups, and normal layer-shell roots, subsurfaces, and popups. Cursor, drag-icon, input-method, unmanaged X11, and secure-lock surfaces remain outside the rendered effect policy. Restricted security-context clients do not see the global because backdrop effects can sample pixels owned by other clients.

The global sweets.blur master and mode control rendering. Managed blur = false is a subtree veto; a non-empty client region otherwise has exact shape precedence over compositor-forced geometry. Committed requests survive a disabled master and become active after a valid enabling reload. Duplicate effect construction is a protocol error for only the offending client, while over-complex well-formed regions are safely ignored with a bounded diagnostic. optimized mode samples one shared output-local background/bottom-layer cache; scene mode samples the exact pixels already rendered below each effect. Either mode disables direct primary-plane scanout only while an effect is active; an otherwise eligible hardware cursor remains independent and sharp above the effect. Output capture preserves the visible result, while isolated window capture intentionally keeps transparent pixels instead of importing a desktop backdrop.

# smoke test and inspect the advertised blur capability
wayland-info | rg ext_background_effect_manager_v1

Pointer Gestures

Sweets implements pointer-gestures-v1. Multi-finger touchpad gestures — swipe, pinch, and hold — are forwarded to the application under the pointer, so native clients get browser swipe-back, GTK pinch-zoom, and similar.

Sweets relays every gesture begin, update, and end from the seat cursor straight to the pointer-focused client. It does not bind gestures to compositor actions, so nothing is intercepted.

Gesture events only originate from a physical multi-finger touchpad via libinput, though the global is always advertised.

# smoke test
wayland-info | rg zwp_pointer_gestures_v1

Explicit Synchronization

Sweets implements linux-drm-syncobj-v1. Instead of implicit, driver-guessed fences, clients hand the compositor explicit acquire/release timeline points, so the GPU knows exactly when a buffer is ready and free to reuse. This removes a class of flicker and stutter, most visibly on NVIDIA.

The protocol is advertised only when the renderer and backend support DRM synchronization timelines and a DRM device is available — in practice, DRM/KMS on a capable GPU. Without that support the global is not exposed and clients fall back to implicit sync.

Turn it off with the explicit_sync setting. Keep it on for NVIDIA. This controls the client protocol global; compositor-internal renderer-to-KMS fences may remain active when the global is disabled.

# smoke test (DRM/KMS session)
wayland-info | rg wp_linux_drm_syncobj_manager_v1

Tearing Control

Sweets implements tearing-control-v1. A client, typically a game, can hint that a surface should be presented immediately rather than waiting for vsync — trading a possible seam for lower latency.

The hint is honored only when all of these hold:

• The global allow_tearing switch is on.
• The requesting window is fullscreen and driving the output.
• The backend accepts a tearing page-flip for that frame.

A fullscreen surface tagged a game through content-type-v1 counts as requesting tearing too, so games that never speak tearing-control-v1 still get the low-latency path. Any other frame falls back to a normal vsynced flip. After a rejected tearing flip succeeds through that fallback, Sweets backs off further async tests for the same fullscreen surface until its eligibility or the output configuration changes. Tearing requires the DRM/KMS backend.

# smoke test
wayland-info | rg wp_tearing_control_manager_v1

Content Type

Sweets implements content-type-v1. A client can tag a surface as photo, video, or game so the compositor can adjust presentation.

A fullscreen surface tagged game is treated as wanting low latency. With allow_tearing on, it triggers a tearing page-flip even without an explicit tearing-control-v1 hint. Other content types are advertised but do not currently change presentation.

# smoke test
wayland-info | rg wp_content_type_manager_v1

Keyboard Shortcut Inhibition

Sweets implements keyboard-shortcuts-inhibit-v1. Virtual machines, remote desktop clients, and some games can ask Sweets to pass shortcuts through while their surface has focus.

Sweets honors inhibitors for the focused surface on seat0. While active, it skips compositor keybindings and forwards key events to the client. Session lock still takes priority.