wlroots/docs/architecture.md

# Architecture

This document describes the high-level design of wlroots. wlroots is modular:
each module can be used mostly independently from the rest of wlroots. For
instance, some wlroots-based compositors only use its backends, some only use
its protocol implementations.

## Backends

Backends are responsible for exposing input devices and output devices.
wlroots provides DRM and libinput backends to directly drive physical
devices, Wayland and X11 backends to run nested inside another compositor,
and a headless backend. A special "multi" backend is used to combine together
multiple backends, for instance DRM and libinput. Compositors can also
implement their own custom backends if they have special needs.

Input devices such as pointers, keyboards, touch screens, tablets, switches
are supported. They emit input events (e.g. a keyboard key is pressed) which
compositors can handle and forward to Wayland clients.

Output devices are tasked with presenting buffers to the user. They also
provide feedback, for instance presentation timestamps. Some backends support
more advanced functionality, such as displaying multiple buffers (e.g. for the
cursor image) or basic 2D transformations (e.g. rotation, clipping, scaling).

## Renderers

Renderers provide utilities to import buffers submitted by Wayland clients,
and a basic 2D drawing API suitable for simple compositors. wlroots provides
renderer implementations based on OpenGL ES 2, Vulkan and Pixman. Just like
backends, compositors can implement their own renderers, or use the graphics
APIs directly.

To draw an image onto a buffer, compositors will first need to create a
texture, representing a source of pixels the renderer can sample from. This can
be done either by uploading pixels from CPU memory, or by importing already
existing GPU memory via DMA-BUFs. Compositors can then create a render pass
and submit drawing operations. Once they are done drawing, compositors can
submit the rendered buffer to an output.

## Protocol implementations

A number of Wayland interface implementations are provided.

### Plumbing protocols

wlroots ships unopinionated implementations of core plumbing interfaces, for
instance:

- `wl_compositor` and `wl_surface`
- `wl_seat` and all input-related interfaces
- Buffer factories such as `wl_shm` and linux-dmabuf
- Additional protocols such as viewporter and presentation-time

### Shells

Shells give a meaning to surfaces. There are many kinds of surfaces:
application windows, tooltips, right-click menus, desktop panels, wallpapers,
lock screens, on-screen keyboards, and so on. Each of these use-cases is
fulfilled with a shell. wlroots supports xdg-shell for regular windows and
popups, Xwayland for interoperability with X11 applications, layer-shell for
desktop UI elements, and more.

### Other protocols

Many other protocol implementations are included, for instance:

- xdg-activation for raising application windows
- idle-inhibit for preventing the screen from blanking when the user is
  watching a video
- ext-idle-notify for notifying when the user is idle

## Helpers

wlroots provides additional helpers which can make it easier for compositors to
tie everything together:

- `wlr_output_layout` organises output devices in the physical space
- `wlr_cursor` stores the current position and image of the cursor
- `wlr_scene` provides a declarative way to display surfaces

## tinywl

tinywl is a minimal wlroots compositor. It implements basic stacking window
management and only supports xdg-shell. It's extensively commented and is a
good learning resource for developers new to wlroots.