diff options
| -rw-r--r-- | docs/architecture.md | 86 |
1 files changed, 86 insertions, 0 deletions
diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 00000000..7ab9212b --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,86 @@ +# 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. |