Project 2: Simple Wayland Compositor with wlroots
Project 2: Simple Wayland Compositor with wlroots
Project Overview
| Attribute | Value |
|---|---|
| Difficulty | Advanced/Master (Level 5) |
| Time Estimate | 1+ month |
| Programming Language | C |
| Knowledge Area | Window Managers / Graphics Pipeline |
| Main Book | “The Wayland Book” by Drew DeVault |
| Coolness Level | Level 5: Pure Magic (Super Cool) |
| Business Potential | Open Core Infrastructure |
| Reference Implementation | tinywl (wlroots reference compositor) |
What you’ll build: A minimal but functional Wayland compositor using the wlroots library that can display client windows, handle keyboard/mouse input, and manage window focus.
Why it teaches compositors: wlroots abstracts the hard parts (DRM/KMS, libinput) while exposing the compositor logic. You’ll implement window stacking, damage tracking, and the compositor’s view of the Wayland protocol.
Learning Objectives
By completing this project, you will be able to:
- Explain compositor architecture - Describe the three roles of a Wayland compositor: protocol server, rendering pipeline, and policy engine
- Implement server-side protocol handling - Create surfaces, route input events, manage object lifecycles
- Understand DRM/KMS - Explain how compositors control display hardware directly
- Manage scene graphs - Use wlroots scene API to position and render surfaces
- Route input correctly - Implement focus management and input event delivery
- Handle multiple outputs - Support multi-monitor configurations with independent rendering
The Core Question You’re Answering
“What does it really mean to be a Wayland compositor, and how do the pieces fit together to create a functional windowing system?”
This project forces you to answer fundamental questions about display servers:
-
What is a compositor’s job? To negotiate protocol objects (surfaces, seats, outputs), route input events to the right clients, composite client buffers onto the screen, and maintain the windowing policy (focus, stacking, positioning)
-
How does the protocol become reality? By implementing the server side—when a client calls
wl_compositor.create_surface(), your code allocates a surface object and sends back a resource ID -
Where does rendering actually happen? Clients render to shared buffers (DMA-BUF or shared memory), your compositor just positions and blends them onto outputs
-
How do you manage state? The compositor is stateful—it tracks which windows exist, where they are, which has focus, what input devices are connected
-
What makes Wayland secure? Input isolation—only the focused window receives keyboard input, other windows can’t snoop
By building a compositor, you’ll discover:
-
Why wlroots exists: Direct DRM/KMS and libinput are complex—wlroots provides scene graphs, output management, and input handling so you focus on policy (how windows behave) not mechanism (how pixels appear)
-
Why Wayland is stateless from the client’s perspective: Clients render independently, the compositor just tells them when to draw—this enables security and smooth animation
-
Why the protocol is extensible: Base protocol (wl_compositor, wl_surface) is minimal; extensions (xdg-shell for windows, layer-shell for panels) add features without breaking compatibility
-
Why there’s no “Wayland window manager”: The compositor IS the window manager—you decide focus behavior, tiling vs floating, keybindings, everything
The deeper insight: A compositor is simultaneously a protocol server, a rendering pipeline, and a policy engine. It’s the Unix philosophy inverted—instead of small tools composed together, it’s one tool doing everything related to display.
Deep Theoretical Foundation
1. Compositor Architecture
A Wayland compositor has three distinct responsibilities:
COMPOSITOR RESPONSIBILITIES
═══════════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────────┐
│ WAYLAND COMPOSITOR │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │
│ │ PROTOCOL SERVER │ │ RENDERING │ │ POLICY ENGINE │ │
│ │ │ │ PIPELINE │ │ │ │
│ │ • Accept client │ │ │ │ • Focus management │ │
│ │ connections │ │ • Collect │ │ • Window placement │ │
│ │ • Implement │ │ buffers │ │ • Keybindings │ │
│ │ wl_compositor │ │ • Compose scene │ │ • Tiling/floating │ │
│ │ • Create │ │ • Send to GPU │ │ • Workspaces │ │
│ │ surfaces │ │ • Output to │ │ • Decorations │ │
│ │ • Route events │ │ display │ │ │ │
│ │ • Manage │ │ │ │ │ │
│ │ lifecycles │ │ │ │ │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
│
┌───────────┴───────────┐
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ wlroots handles │ │ You implement │
│ mechanism: │ │ policy: │
│ • DRM/KMS │ │ • What happens │
│ • libinput │ │ on click │
│ • Scene graph │ │ • Where windows │
│ • Buffer mgmt │ │ appear │
│ │ │ • Keyboard │
│ │ │ shortcuts │
└─────────────────┘ └─────────────────┘
2. The Rendering Pipeline
Understanding how frames are rendered is essential:
COMPOSITOR RENDERING PIPELINE (Frame-by-Frame)
═══════════════════════════════════════════════════════════════════════
PHASE 1: CLIENT RENDERING (Parallel, Independent)
─────────────────────────────────────────────────────────────────────
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Client A │ │ Client B │ │ Client C │
│ (Terminal) │ │ (Browser) │ │ (Editor) │
│ │ │ │ │ │
│ Render to │ │ Render to │ │ Render to │
│ wl_buffer │ │ wl_buffer │ │ wl_buffer │
│ │ │ │ │ │
│ attach() │ │ attach() │ │ attach() │
│ commit() │ │ commit() │ │ commit() │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
└───────────────────┼───────────────────┘
▼
PHASE 2: COMPOSITOR RECEIVES BUFFERS
─────────────────────────────────────────────────────────────────────
┌─────────────────────────────────┐
│ Wayland Compositor │
│ │
│ wl_surface A → buffer A │
│ wl_surface B → buffer B │
│ wl_surface C → buffer C │
│ │
│ Each surface has: │
│ - Position (x, y) │
│ - Z-order (stacking) │
│ - Damage region (what changed) │
└─────────────────────────────────┘
│
▼
PHASE 3: SCENE GRAPH CONSTRUCTION (wlroots)
─────────────────────────────────────────────────────────────────────
┌─────────────────────────────────────────┐
│ wlr_scene (Root) │
└─────────────────┬───────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ Background │ │ Window Layer │ │ Overlay Layer │
│ (Wallpaper) │ │ (Apps) │ │ (Panels) │
└───────────────┘ └───────┬───────┘ └───────────────┘
│
┌─────────────┼─────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│Surface A │ │Surface B │ │Surface C │
│ Z=100 │ │ Z=101 │ │ Z=102 │
│(10, 10) │ │(400,200) │ │(50, 500) │
└──────────┘ └──────────┘ └──────────┘
│
▼
PHASE 4: DAMAGE TRACKING & OPTIMIZATION
─────────────────────────────────────────────────────────────────────
Compositor analyzes what changed:
┌────────────────────────────────────────────────┐
│ Damage Regions: │
│ │
│ • Region 1: Terminal moved (10,10,100,50) │
│ • Region 2: Browser scrolled (400,200,800,600)│
│ • Editor unchanged → NO damage, skip │
└────────────────────────────────────────────────┘
│
▼
PHASE 5: GPU COMPOSITING (OpenGL/Vulkan)
─────────────────────────────────────────────────────────────────────
┌────────────────────────────────────────────────┐
│ GPU Render Pass: │
│ │
│ 1. Clear framebuffer (or use previous frame) │
│ │
│ 2. For each damaged region: │
│ for each surface (back to front): │
│ │
│ if DMA-BUF: Zero-copy texture bind │
│ if SHM: Upload pixels to GPU texture │
│ │
│ glDrawArrays(quad at surface position) │
│ │
│ 3. Render cursor on top │
└────────────────────────────────────────────────┘
│
▼
PHASE 6: DISPLAY OUTPUT (DRM/KMS Atomic Commit)
─────────────────────────────────────────────────────────────────────
┌────────────────────────────────────────────────┐
│ DRM Atomic Commit: │
│ │
│ ioctl(drm_fd, DRM_IOCTL_MODE_ATOMIC, ...) │
│ │
│ Kernel schedules buffer swap at VBLANK │
│ (No tearing!) │
└────────────────────────────────────────────────┘
│
▼
┌─────────────────┐
│ Physical Screen │
│ │
│ Pixels visible! │
└─────────────────┘
3. DRM/KMS Subsystem
Your compositor must control the display hardware:
DRM/KMS ARCHITECTURE
═══════════════════════════════════════════════════════════════════════
User Space (Your Compositor)
────────────────────────────────────────────────────────────────────
│
│ Open /dev/dri/card0
│
│ ioctl(fd, DRM_IOCTL_MODE_GETRESOURCES, ...)
│ ioctl(fd, DRM_IOCTL_MODE_ATOMIC, ...)
│
▼
═══════════════════════════════════════════════════════════════════════
Kernel Space (DRM Subsystem)
────────────────────────────────────────────────────────────────────
┌──────────────────────────────────────────────────────────────────┐
│ DRM Core │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Mode Setting (KMS) │ │
│ │ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌──────────┐ │ │
│ │ │ CRTC │───▶│ Encoder │───▶│Connector │ │ │
│ │ └─────────┘ └─────────┘ └──────────┘ │ │
│ │ │ │ │ │ │
│ │ Scanout engine Signal format Physical port │ │
│ │ (reads buffer) (HDMI/DP/VGA) (HDMI-A-1) │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────┐ │ │
│ │ │ Framebuffer │ │ │
│ │ │ - Points to GEM buffer object │ │ │
│ │ │ - Width, height, stride, format │ │ │
│ │ └──────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Atomic Mode Setting: │ │
│ │ - Set all properties in one ioctl │ │
│ │ - Either all changes apply or none │ │
│ │ - VBLANK synchronization │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ GEM (Graphics Execution Manager) │ │
│ │ │ │
│ │ Buffer objects for GPU memory allocation │ │
│ │ DMA-BUF for cross-process buffer sharing │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────┘
│
▼
═══════════════════════════════════════════════════════════════════════
Hardware
────────────────────────────────────────────────────────────────────
┌──────────────────────────────────────────────────────────────────┐
│ GPU │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ Display │ │ Display │ │ Video Memory (VRAM) │ │
│ │ Engine 1 │ │ Engine 2 │ │ │ │
│ │ (CRTC) │ │ (CRTC) │ │ Framebuffers stored here│ │
│ └──────┬──────┘ └──────┬──────┘ └─────────────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ HDMI Port │ │ DisplayPort │ │
│ └──────┬──────┘ └──────┬──────┘ │
└─────────┼────────────────┼───────────────────────────────────────┘
│ │
▼ ▼
┌─────────┐ ┌─────────┐
│ Monitor │ │ Monitor │
│ 1 │ │ 2 │
└─────────┘ └─────────┘
4. wlroots Architecture
wlroots provides building blocks for compositors:
WLROOTS COMPONENT ARCHITECTURE
═══════════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────────┐
│ Your Compositor Code │
│ │
│ main() → Setup wlroots → Connect signals → Event loop │
│ │
└───────────────────────────────┬─────────────────────────────────────┘
│
Uses wlroots components:
│
┌───────────────────────────────▼─────────────────────────────────────┐
│ wlroots Library │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────┐│
│ │ wlr_backend │ │ wlr_renderer │ │ wlr_scene ││
│ │ │ │ │ │ ││
│ │ • DRM backend │ │ • OpenGL │ │ • Scene graph ││
│ │ • Wayland │ │ • Vulkan │ │ • Damage tracking ││
│ │ nested │ │ • Pixman (SW) │ │ • Surface positioning ││
│ │ • X11 nested │ │ │ │ • Z-ordering ││
│ │ • Headless │ │ │ │ • Automatic output ││
│ │ │ │ │ │ rendering ││
│ └─────────────────┘ └─────────────────┘ └─────────────────────────┘│
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────┐│
│ │ wlr_output │ │ wlr_seat │ │ wlr_xdg_shell ││
│ │ │ │ │ │ ││
│ │ • Output layout │ │ • Keyboard │ │ • xdg_surface ││
│ │ • Mode setting │ │ • Pointer │ │ • xdg_toplevel ││
│ │ • Frame │ │ • Touch │ │ • xdg_popup ││
│ │ scheduling │ │ • Input routing │ │ • Configure events ││
│ │ • Hotplug │ │ • Focus mgmt │ │ ││
│ └─────────────────┘ └─────────────────┘ └─────────────────────────┘│
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────┐│
│ │wlr_layer_shell │ │ wlr_cursor │ │ wlr_compositor ││
│ │ │ │ │ │ ││
│ │ • Panel support │ │ • Cursor image │ │ • wl_compositor impl ││
│ │ • Overlays │ │ • Movement │ │ • wl_surface creation ││
│ │ • Backgrounds │ │ • Hardware │ │ • wl_subcompositor ││
│ │ • Lock screens │ │ cursor │ │ ││
│ └─────────────────┘ └─────────────────┘ └─────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────────────┘
Complete Project Specification
Functional Requirements
- Backend Initialization: Start DRM/KMS (or Wayland nested for development)
- Output Management: Handle monitor detection, mode setting, hotplug
- Protocol Implementation: Advertise wl_compositor, xdg_wm_base, wl_seat
- Surface Management: Create and track xdg_toplevel surfaces
- Rendering: Composite surfaces using wlr_scene
- Input Handling: Route keyboard and pointer events to focused surface
- Focus Management: Click-to-focus with visual indication
- Window Movement: Alt+drag to move windows
- Exit Handling: Ctrl+Shift+Escape to quit
Non-Functional Requirements
- Must run from a TTY (DRM backend) or nested (Wayland/X11 backend)
- Must handle client crashes gracefully
- Must not leak resources when clients disconnect
- Should maintain 60 FPS under normal conditions
Solution Architecture
High-Level Component Diagram
┌─────────────────────────────────────────────────────────────────────┐
│ my_compositor │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ server.c │ │
│ │ │ │
│ │ struct my_server { │ │
│ │ struct wl_display *display; │ │
│ │ struct wlr_backend *backend; │ │
│ │ struct wlr_renderer *renderer; │ │
│ │ struct wlr_scene *scene; │ │
│ │ struct wlr_scene_output_layout *scene_layout; │ │
│ │ │ │
│ │ struct wlr_xdg_shell *xdg_shell; │ │
│ │ struct wl_list views; // my_view list │ │
│ │ │ │
│ │ struct wlr_cursor *cursor; │ │
│ │ struct wlr_seat *seat; │ │
│ │ struct my_view *focused_view; │ │
│ │ │ │
│ │ struct wl_listener new_output; │ │
│ │ struct wl_listener new_xdg_surface; │ │
│ │ struct wl_listener cursor_motion; │ │
│ │ struct wl_listener cursor_button; │ │
│ │ struct wl_listener keyboard_key; │ │
│ │ }; │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │
│ │ output.c │ │ view.c │ │ input.c │ │
│ │ │ │ │ │ │ │
│ │ handle_new_ │ │ handle_new_ │ │ handle_cursor_ │ │
│ │ output() │ │ xdg_surface() │ │ motion() │ │
│ │ handle_output_ │ │ handle_map() │ │ handle_cursor_ │ │
│ │ frame() │ │ handle_unmap() │ │ button() │ │
│ │ handle_output_ │ │ handle_destroy()│ │ handle_keyboard_ │ │
│ │ destroy() │ │ focus_view() │ │ key() │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
View Structure (Window Representation)
struct my_view {
struct wl_list link; // server.views
struct my_server *server;
struct wlr_xdg_toplevel *xdg_toplevel;
struct wlr_scene_tree *scene_tree;
// Listeners
struct wl_listener map;
struct wl_listener unmap;
struct wl_listener destroy;
struct wl_listener request_move;
struct wl_listener request_resize;
// State
int x, y;
bool mapped;
};
Signal/Event Flow
CLIENT CREATES WINDOW
═══════════════════════════════════════════════════════════════════════
1. Client: xdg_wm_base.get_xdg_surface()
└─→ wlr_xdg_shell emits: events.new_surface
2. Your handler: handle_new_xdg_surface()
├─→ Allocate my_view
├─→ Create scene tree: wlr_scene_xdg_surface_create()
├─→ Connect listeners: map, unmap, destroy
└─→ Add to server.views list
3. Client: commits surface content
└─→ xdg_surface emits: events.map
4. Your handler: handle_view_map()
├─→ Set initial position
├─→ Focus the view
└─→ view.mapped = true
5. On each frame:
└─→ wlr_scene renders all mapped views
CLIENT CLOSES WINDOW
═══════════════════════════════════════════════════════════════════════
1. Client: xdg_toplevel.destroy() (or client disconnects)
└─→ xdg_surface emits: events.unmap
2. Your handler: handle_view_unmap()
├─→ view.mapped = false
└─→ If focused, focus another view
3. xdg_surface emits: events.destroy
4. Your handler: handle_view_destroy()
├─→ Remove from server.views
├─→ Disconnect listeners
└─→ Free my_view
Phased Implementation Guide
Phase 1: Minimal Compositor (Week 1)
Goal: Display a background color, handle output lifecycle
Steps:
- Create project with Makefile (link wlroots, wayland-server)
- Initialize wl_display, wlr_backend, wlr_renderer
- Create wlr_scene
- Handle new_output signal
- Create output frame handler
- Add socket and run event loop
Verification:
# From TTY (no existing Wayland/X11 session)
$ ./my_compositor
# Should show solid gray background
# Ctrl+C to exit
Key Code:
int main(void) {
struct wl_display *display = wl_display_create();
struct wlr_backend *backend = wlr_backend_autocreate(display, NULL);
struct wlr_renderer *renderer = wlr_renderer_autocreate(backend);
wlr_renderer_init_wl_display(renderer, display);
struct wlr_scene *scene = wlr_scene_create();
struct wlr_output_layout *output_layout = wlr_output_layout_create(display);
wlr_scene_attach_output_layout(scene, output_layout);
// Handle new outputs
server.new_output.notify = handle_new_output;
wl_signal_add(&backend->events.new_output, &server.new_output);
const char *socket = wl_display_add_socket_auto(display);
wlr_backend_start(backend);
wl_display_run(display);
return 0;
}
Phase 2: XDG Shell Support (Week 2)
Goal: Accept client windows, display them
Steps:
- Create wlr_xdg_shell
- Handle new_xdg_surface signal
- Create my_view structure
- Add to scene graph with wlr_scene_xdg_surface_create
- Handle map/unmap events
Verification:
$ ./my_compositor &
$ WAYLAND_DISPLAY=wayland-1 weston-terminal
# Terminal window should appear
Phase 3: Input Handling (Week 2-3)
Goal: Route keyboard and pointer events
Steps:
- Create wlr_seat
- Create wlr_cursor
- Handle keyboard input device
- Handle pointer motion
- Implement focus on click
- Send events to focused view
Key Concept: Input routing
void handle_cursor_button(struct wl_listener *listener, void *data) {
struct wlr_pointer_button_event *event = data;
if (event->state == WLR_BUTTON_PRESSED) {
// Find view under cursor
struct my_view *view = view_at(server, cursor->x, cursor->y);
if (view) {
focus_view(view);
}
}
// Forward to focused view
wlr_seat_pointer_notify_button(seat, event->time_msec,
event->button, event->state);
}
Phase 4: Window Management (Week 3-4)
Goal: Move, resize, focus windows
Steps:
- Implement Alt+drag to move
- Implement Alt+right-drag to resize
- Implement Alt+Tab focus cycling
- Add exit keybinding (Ctrl+Shift+Escape)
Grab Mode State Machine:
GRAB_NONE ──[Alt+Click]──► GRAB_MOVE
│ │
│ [Release]
│ │
◄─────────────────────────┘
GRAB_NONE ──[Alt+RightClick]──► GRAB_RESIZE
│ │
│ [Release]
│ │
◄──────────────────────────────┘
Phase 5: Polish (Week 4+)
Goal: Production-quality behavior
Steps:
- Handle client crashes gracefully
- Implement proper focus indication (border)
- Support multiple monitors
- Add configuration (background color, keybinds)
- Proper cleanup on exit
Testing Strategy
Manual Testing Matrix
| Test Case | Expected Result |
|---|---|
| Launch with no clients | Background displayed |
| Launch weston-terminal | Window appears, receives input |
| Click different windows | Focus changes correctly |
| Alt+drag window | Window moves with cursor |
| Close window | Window disappears, no crash |
| Kill client process | Compositor survives |
| Connect second monitor | Both outputs work |
| Disconnect monitor | Graceful handling |
| Ctrl+Shift+Esc | Compositor exits cleanly |
Debugging Techniques
# Enable wlroots debug output
WLR_DEBUG=1 ./my_compositor
# Use software renderer (if GPU issues)
WLR_RENDERER=pixman ./my_compositor
# Run nested in existing session
WLR_BACKENDS=wayland ./my_compositor
# or
WLR_BACKENDS=x11 ./my_compositor
# Client-side protocol debug
WAYLAND_DEBUG=1 weston-terminal
Common Pitfalls and Debugging
Problem: Compositor crashes on client connect
Cause: Not handling xdg_surface roles correctly
Fix: Check if (xdg_surface->role != WLR_XDG_SURFACE_ROLE_TOPLEVEL) return;
Problem: No cursor visible
Cause: Didn’t set up wlr_cursor or load cursor theme Fix:
struct wlr_xcursor_manager *cursor_mgr =
wlr_xcursor_manager_create(NULL, 24);
wlr_xcursor_manager_load(cursor_mgr, 1);
wlr_cursor_set_xcursor(cursor, cursor_mgr, "default");
Problem: Input not reaching clients
Cause: Not calling wlr_seat keyboard/pointer enter Fix: When focusing, send enter events:
wlr_seat_keyboard_notify_enter(seat, surface,
keyboard->keycodes, keyboard->num_keycodes, &keyboard->modifiers);
wlr_seat_pointer_notify_enter(seat, surface, sx, sy);
Problem: Windows don’t appear
Cause: Scene tree not connected to output layout
Fix: Ensure wlr_scene_attach_output_layout() is called
Extensions and Challenges
Challenge 1: Window Decorations
Add server-side decorations (title bar, close button).
Challenge 2: Tiling Layout
Implement automatic tiling like i3/Sway.
Challenge 3: Workspaces
Add virtual desktop support with workspace switching.
Challenge 4: Layer Shell Support
Add wlr_layer_shell for panels (integrate with P04).
Challenge 5: Screenshot Protocol
Implement screencopy protocol for screenshots.
Real-World Connections
Production Compositors Using wlroots
- Sway: Full-featured tiling compositor, ~30k lines
- Wayfire: 3D effects compositor
- Phoc: Mobile compositor for Phosh
- cage: Kiosk compositor (single app)
- hikari: Stacking compositor inspired by CWM
Career Applications
- Linux Desktop Development: GNOME/KDE hire compositor developers
- Embedded Systems: Automotive, industrial displays use custom compositors
- Gaming Platforms: Steam Deck uses Gamescope (wlroots-based)
- VR/AR: Display composition is fundamental
- Cloud Gaming: Remote display requires compositor knowledge
Resources
Essential Reading (Before Starting)
| Resource | Chapter/Section |
|---|---|
| “The Wayland Book” | Ch. 1-4 (client), Ch. 7-8 (server) |
| wlroots docs | Backend, renderer, scene API |
| tinywl source | Line-by-line study |
| Linux DRM docs | Mode Setting (KMS) |
Reference Implementations
| Source | Purpose |
|---|---|
| tinywl (~600 lines) | Minimal reference |
| Sway | Production quality |
| cage | Simple single-app |
Online Resources
- Drew DeVault’s blog: “Writing a Wayland Compositor” series
- https://gitlab.freedesktop.org/wlroots/wlroots
- freedesktop.org protocol specs
Self-Assessment Checklist
Before considering this project complete, verify you can:
- Explain what happens when a client creates an xdg_toplevel
- Draw the rendering pipeline from client buffer to screen
- Describe how input events reach the correct client
- Explain DRM/KMS at a high level (CRTC, encoder, connector)
- Modify your compositor to use a different background
- Add a new keybinding for any action
- Handle a new client connecting while running
- Debug why a client’s window doesn’t appear
- Support multiple monitors with different resolutions
- Gracefully handle client crashes
Completing this project gives you deep understanding of how Linux desktops actually work. You’ve implemented the core of what GNOME, KDE, and Sway provide. You can now understand any compositor’s source code and contribute to Linux desktop development.