layersurface

Layersurface is a concept from the Wayland protocol extension known as layer-shell. It allows clients to request placement of a surface on a specific region of the screen, typically for UI elements such as panels, docks, notifications, or background widgets. The interface is implemented by Wayland compositors and is supported by many desktop environments and compositor projects.

How it works in practice: a client first binds to the wl_layer_shell_v1 global provided by the compositor, then creates a wl_layer_surface_v1 for the surface it wants to place on the screen. The client configures several properties that govern how the surface is laid out and how it behaves. The layer value determines the stacking order: background, bottom, top, or overlay, with overlay typically drawn above other layers. The anchor properties (top, bottom, left, right) specify which edges of the output the surface should be attached to. Margins provide offset from those edges in pixels. The exclusive zone indicates how many pixels of the screen the surface reserves for itself, preventing other surfaces from occupying that space. A keyboard interactivity flag indicates whether the surface should receive keyboard input, which is useful for panels or overlays that need keyboard shortcuts.

The compositor uses these hints to position and size the surface and to manage interaction with other surfaces. Layer surfaces are commonly used for panels, taskbars, notifications, and other persistent UI elements that should remain in a fixed position relative to the screen edges. Implementations exist in wlroots-based compositors (such as Sway), Weston, KDE Plasma on Wayland, and others that support the layer-shell protocol.