Skip to content

Wayland Essentials (Quick Primer)

For both roles: Warmwind's OS runs on Wayland (via Sway). This page gives you enough Wayland literacy to discuss their architecture intelligently. The Linux Platform role needs the deep dive; the Backend role just needs this primer.

The 60-Second Mental Model

graph LR
    APP["App<br/>(renders pixels)"] -->|"wl_surface + dma-buf fd"| COMP["Compositor<br/>(Sway)"]
    COMP -->|"DRM/KMS"| DISPLAY["Display"]
    KB["Keyboard"] -->|"libinput"| COMP
    COMP -->|"wl_keyboard events"| APP

X11: Server draws for clients. WM is separate. Any client can spy on any other.

Wayland: Compositor IS the server IS the WM. Clients draw their own buffers. Clients are isolated -- can't see each other's pixels or input.

Key Concepts

Concept What it means
wl_surface A rectangle of pixels. No role until assigned (toplevel, popup, etc.)
wl_buffer Pixel data (SHM or GPU dma-buf). Client-allocated.
xdg_toplevel A window. Compositor tells it what size to be (configure/ack).
wl_seat A user's input devices (keyboard + pointer + touch).
Compositor The single program that owns the display, routes input, composites.

The Unix philosophy connection

Wayland's design is deeply Unix: everything is a file descriptor. Buffers are fds (shared via SCM_RIGHTS). The compositor socket is a fd. Even keyboard keymaps are sent as fds to mmap. If you understand fd passing, you understand Wayland's superpower.

Why Warmwind Chose Wayland

  1. Per-surface capture: Each app renders to its own buffer. The compositor (Sway) knows each window's content separately. WayVNC can capture individual surfaces or the whole output.

  2. Security: AI agents run in containers. Wayland's isolation prevents one agent from reading another's screen (unlike X11 where any client can XGetImage the root window).

  3. No legacy: A purpose-built OS doesn't need X11 compatibility. Starting clean on Wayland avoids 40 years of accumulated complexity.

The Protocol in 30 Seconds

  • Transport: Unix domain socket ($XDG_RUNTIME_DIR/wayland-0)
  • Message format: Object ID + size/opcode + arguments (32-bit aligned)
  • Model: Fully async. No request/reply. Events pushed by compositor.
  • Buffers: Shared via file descriptor passing (SCM_RIGHTS)
  • Sync: configure → client renders → ack_configure → commit

Glossary

dma-buf
Linux kernel mechanism for sharing GPU memory between processes via file descriptors. Enables zero-copy buffer sharing between client and compositor.
DRM/KMS
Direct Rendering Manager / Kernel Mode Setting. The kernel subsystem that controls GPUs and displays. The compositor uses it to put pixels on screen.
wlroots
C library providing modular building blocks for Wayland compositors. Used by Sway, Hyprland, and others. ~60K lines of code that handle DRM, libinput, rendering, and protocol implementations.
xdg-shell
The standard Wayland protocol for application windows. Defines how windows are created, sized, maximized, fullscreened, and closed.