Project 1: Bare-Metal Wayland Client

Project 1: Bare-Metal Wayland Client

Project Overview

Attribute Value
Difficulty Intermediate (Level 3)
Time Estimate 1-2 weeks
Programming Language C
Knowledge Area Graphics / Window Systems
Main Book “The Wayland Book” by Drew DeVault
Coolness Level Level 4: Hardcore Tech Flex
Business Potential Resume Gold

What you’ll build: A Wayland client from scratch that displays a colored window using only libwayland-client and shared memory—no toolkits, no helpers.

Why it teaches Wayland: Forces you to understand the entire client lifecycle: connecting to the compositor, negotiating protocols via wl_registry, creating surfaces, attaching buffers, and handling the frame callback loop.

Learning Objectives

By completing this project, you will be able to:

  1. Explain the Wayland protocol model - Describe how Wayland’s asynchronous, object-oriented protocol differs from X11’s request/reply model
  2. Implement a Wayland client from scratch - Write C code that connects to a compositor, negotiates interfaces, and displays pixels
  3. Manage shared memory buffers - Use POSIX shared memory (memfd_create, mmap) for zero-copy buffer sharing
  4. Handle the xdg-shell lifecycle - Implement the configure/ack/commit cycle correctly
  5. Debug Wayland applications - Use WAYLAND_DEBUG=1 to trace protocol messages
  6. Compare client-side vs server-side rendering - Understand why Wayland puts rendering responsibility on clients

The Core Question You’re Answering

“How does a graphical application actually display pixels on screen in a modern Linux desktop, and what is the conversation between my program and the compositor?”

Before you write any code, sit with this question. Most developers think “GTK draws my window” or “X11 shows my pixels,” but they can’t explain what that actually means at the protocol level.

The deeper question beneath this:

“Why does Wayland exist? What was so broken about X11 that the entire Linux graphics stack was redesigned from scratch?”

By building a bare-metal Wayland client, you’ll discover that:

  • Wayland is asynchronous: You request things and get callbacks, not immediate responses
  • Wayland is stateless on the compositor side: The compositor doesn’t store your window contents—you do
  • Wayland is about buffer passing: You render pixels in shared memory; the compositor just displays them
  • Wayland is object-oriented: Everything is an object (surface, buffer, seat) with interfaces and events

This project answers the fundamental question: “What is the minimal conversation needed between an application and a display server to show a window?”

Deep Theoretical Foundation

1. Display Server Architecture: X11 vs Wayland

Understanding why Wayland exists requires understanding what was wrong with X11:

X11 Architecture (Complex 3-Layer Stack):
════════════════════════════════════════════════════════════════════════════

┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│   Application   │         │   Application   │         │   Application   │
│   (Client)      │         │   (Client)      │         │   (Client)      │
└────────┬────────┘         └────────┬────────┘         └────────┬────────┘
         │                           │                           │
         │  X11 Protocol (Network)   │                           │
         │  - Draw requests          │                           │
         │  - Event messages         │                           │
         └───────────────────────────┼───────────────────────────┘
                                     │
                          ┌──────────▼──────────────────────────┐
                          │       X Server                       │
                          │  - Manages resources                 │
                          │  - Executes draw commands            │
                          │  - Routes input events               │
                          │  - Handles network protocol          │
                          │  - Stores window contents            │
                          └──────────┬──────────────────────────┘
                                     │ Rendered frames
                                     │
                          ┌──────────▼──────────────────────────┐
                          │   Compositor (Separate Process)      │
                          │  - Reads from X server               │
                          │  - Applies effects                   │
                          │  - Composites to framebuffer         │
                          └──────────┬──────────────────────────┘
                                     │
                          ┌──────────▼──────────────────────────┐
                          │   GPU / Display Hardware             │
                          └──────────────────────────────────────┘

Problems with X11:
  • Extensive IPC (client → X server → compositor)
  • X server as middleman adds latency
  • Security: any client can spy on other windows
  • X server stores window contents (memory overhead)
  • Network protocol overhead even for local apps


Wayland Architecture (Direct, Simple 2-Layer):
════════════════════════════════════════════════════════════════════════════

┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│   Application   │         │   Application   │         │   Application   │
│   (Client)      │         │   (Client)      │         │   (Client)      │
│                 │         │                 │         │                 │
│  ┌───────────┐  │         │  ┌───────────┐  │         │  ┌───────────┐  │
│  │ Renders   │  │         │  │ Renders   │  │         │  │ Renders   │  │
│  │ Own Window│  │         │  │ Own Window│  │         │  │ Own Window│  │
│  │ to Buffer │  │         │  │ to Buffer │  │         │  │ to Buffer │  │
│  └─────┬─────┘  │         │  └─────┬─────┘  │         │  └─────┬─────┘  │
└────────┼────────┘         └────────┼────────┘         └────────┼────────┘
         │                           │                           │
         │ Wayland Protocol          │                           │
         │ - Share buffer FD         │                           │
         │ - Input events            │                           │
         │ - Surface config          │                           │
         └───────────────────────────┼───────────────────────────┘
                                     │
                  ┌──────────────────▼──────────────────────────┐
                  │    Wayland Compositor (All-in-One)          │
                  │                                             │
                  │  Display Server + Window Manager + Effects  │
                  │                                             │
                  │  • Receives client buffers (zero-copy)      │
                  │  • Manages window positions & focus         │
                  │  • Routes input to correct client           │
                  │  • Composites buffers to screen             │
                  │  • Controls DRM/KMS (display hardware)      │
                  │  • Enforces security isolation              │
                  └──────────────────┬──────────────────────────┘
                                     │ Direct GPU access
                                     │
                  ┌──────────────────▼──────────────────────────┐
                  │       GPU / Display Hardware                │
                  └─────────────────────────────────────────────┘

Benefits of Wayland:
  ✓ Clients render directly → no middleman
  ✓ Zero-copy buffer sharing → better performance
  ✓ Security by design → input isolation
  ✓ Compositor has full control → smooth animations
  ✓ Simpler protocol → easier to implement
  ✓ No network overhead for local apps

2. The Wayland Object Model

Wayland uses an object-oriented protocol where everything is an object with:

  • A unique ID within the connection
  • An interface (like a class)
  • Requests (methods you call on the object)
  • Events (callbacks the object fires)
WAYLAND OBJECT HIERARCHY
═════════════════════════════════════════════════════════════════

wl_display (ID=1, always exists)
    │
    ├── wl_registry (ID=2, requested from display)
    │       │
    │       ├── wl_compositor (global, bind to create surfaces)
    │       │       │
    │       │       └── wl_surface (created from compositor)
    │       │               │
    │       │               └── xdg_surface (role assignment)
    │       │                       │
    │       │                       └── xdg_toplevel (window behavior)
    │       │
    │       ├── wl_shm (global, shared memory management)
    │       │       │
    │       │       └── wl_shm_pool (created from shm)
    │       │               │
    │       │               └── wl_buffer (created from pool)
    │       │
    │       ├── xdg_wm_base (global, xdg-shell entry point)
    │       │
    │       ├── wl_seat (global, input device group)
    │       │       │
    │       │       ├── wl_keyboard
    │       │       ├── wl_pointer
    │       │       └── wl_touch
    │       │
    │       └── wl_output (global, each monitor)
    │
    └── wl_callback (one-shot callback objects)

3. Shared Memory and Zero-Copy Rendering

Wayland achieves high performance through zero-copy buffer sharing:

SHARED MEMORY BUFFER FLOW
═════════════════════════════════════════════════════════════════

Client Process                        Compositor Process
┌─────────────────────────────┐       ┌─────────────────────────┐
│                             │       │                         │
│ 1. Create shared memory:    │       │                         │
│    fd = memfd_create()      │       │                         │
│    ftruncate(fd, size)      │       │                         │
│                             │       │                         │
│ 2. Map into client memory:  │       │                         │
│    data = mmap(fd)          │       │                         │
│    ┌─────────────────┐      │       │                         │
│    │ Shared Memory   │◄─────┼───────┼───────────────────┐     │
│    │ (Client's View) │      │       │                   │     │
│    │ pixels[0..n]    │      │       │                   │     │
│    └─────────────────┘      │       │                   │     │
│            │                │       │                   │     │
│ 3. Create wl_shm_pool:      │       │                   │     │
│    pool = wl_shm_create_pool│       │                   │     │
│    (shm, fd, size)          │──────>│ Compositor maps   │     │
│                             │       │ the same fd       │     │
│                             │       │ ┌─────────────────┐     │
│                             │       │ │ Shared Memory   │     │
│                             │       │ │ (Compositor's   │     │
│                             │       │ │  View) - SAME   │     │
│                             │       │ │  PHYSICAL MEM   │     │
│                             │       │ └─────────────────┘     │
│ 4. Create buffer:           │       │                         │
│    buffer = pool.create_buf │       │                         │
│                             │       │                         │
│ 5. Paint pixels:            │       │                         │
│    for (i=0; i<n; i++)      │       │                         │
│      pixels[i] = 0xFFRRGGBB │       │                         │
│                             │       │                         │
│ 6. Attach and commit:       │       │                         │
│    wl_surface_attach(buf)   │──────>│ 7. Compositor reads     │
│    wl_surface_commit()      │       │    directly from        │
│                             │       │    shared memory!       │
│                             │       │                         │
│                             │       │    NO COPY NEEDED       │
│                             │       │                         │
└─────────────────────────────┘       └─────────────────────────┘

Key Insight: The file descriptor (fd) is passed over the Unix socket
using SCM_RIGHTS. Both processes map the same underlying memory.
The compositor never copies pixel data—it reads directly from your buffer.

4. The Configure/Ack/Commit Cycle

One of the most confusing aspects of xdg-shell is the configure cycle:

XDG-SHELL CONFIGURE CYCLE
═════════════════════════════════════════════════════════════════

Why This Exists:
  - Compositor suggests window size/state
  - Client must acknowledge before committing content
  - Prevents race conditions (client draws at wrong size)
  - Ensures synchronized state between compositor and client

The Flow:

Client                              Compositor
  │                                     │
  │ xdg_surface.get_toplevel()          │
  │────────────────────────────────────>│
  │                                     │
  │ wl_surface.commit() [initial]       │
  │────────────────────────────────────>│
  │                                     │ "Client wants a window"
  │                                     │
  │     xdg_toplevel.configure(w,h,s)   │ "Try this size/state"
  │<────────────────────────────────────│
  │     xdg_surface.configure(serial)   │ "Configuration complete"
  │<────────────────────────────────────│
  │                                     │
  │ xdg_surface.ack_configure(serial)   │ "I understand"
  │────────────────────────────────────>│
  │                                     │
  │ [Create buffer at suggested size]   │
  │ [Paint content to buffer]           │
  │                                     │
  │ wl_surface.attach(buffer)           │
  │────────────────────────────────────>│
  │ wl_surface.commit()                 │
  │────────────────────────────────────>│
  │                                     │
  │                                     │ Window appears on screen!

Critical Rules:
  ✗ DO NOT commit content before receiving configure
  ✗ DO NOT commit without acking first
  ✗ DO NOT ignore the suggested size (you can, but it's rude)
  ✓ DO ack even if you use a different size
  ✓ DO handle multiple configures (only ack the last one)

Complete Project Specification

Functional Requirements

  1. Connection: Connect to the default Wayland display ($WAYLAND_DISPLAY or wayland-0)
  2. Protocol Negotiation: Bind to required globals: wl_compositor, wl_shm, xdg_wm_base
  3. Surface Creation: Create a wl_surface with an xdg_toplevel role
  4. Buffer Management: Create and manage shared memory buffers
  5. Rendering: Fill the window with a solid color (configurable)
  6. Event Handling: Handle configure events and window resize
  7. Cleanup: Properly destroy all resources on exit

Non-Functional Requirements

  • Must compile with only -lwayland-client (plus generated protocol code)
  • Must not use any toolkit (GTK, Qt, SDL)
  • Must handle Ctrl+C gracefully
  • Must not leak memory or file descriptors

Expected Behavior

When running, the program should:

  1. Display diagnostic output showing protocol negotiation
  2. Show a solid-colored window that can be resized
  3. Respond to window close events
  4. Clean up properly on exit

Solution Architecture

High-Level Design

┌─────────────────────────────────────────────────────────────────┐
│                        main()                                   │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ 1. Initialize state structure                              │  │
│  │ 2. Connect to Wayland display                              │  │
│  │ 3. Get registry, bind globals                              │  │
│  │ 4. Create surface hierarchy                                │  │
│  │ 5. Enter event loop                                        │  │
│  │ 6. Cleanup on exit                                         │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              │
           ┌──────────────────┼──────────────────┐
           ▼                  ▼                  ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│  Registry       │ │  Surface        │ │  Buffer         │
│  Handling       │ │  Management     │ │  Management     │
│                 │ │                 │ │                 │
│ - Enumerate     │ │ - Create        │ │ - Create pool   │
│   globals       │ │   wl_surface    │ │ - Create buffer │
│ - Bind to       │ │ - Create        │ │ - Paint pixels  │
│   interfaces    │ │   xdg_surface   │ │ - Attach/commit │
│ - Handle        │ │ - Handle        │ │ - Handle resize │
│   removal       │ │   configure     │ │ - Handle release│
└─────────────────┘ └─────────────────┘ └─────────────────┘

State Structure Design

struct client_state {
    // Display connection
    struct wl_display *display;
    struct wl_registry *registry;

    // Bound globals
    struct wl_compositor *compositor;
    struct wl_shm *shm;
    struct xdg_wm_base *xdg_wm_base;

    // Surface objects
    struct wl_surface *surface;
    struct xdg_surface *xdg_surface;
    struct xdg_toplevel *xdg_toplevel;

    // Buffer state
    struct wl_buffer *buffer;
    void *buffer_data;
    size_t buffer_size;

    // Window state
    int32_t width;
    int32_t height;
    uint32_t last_configure_serial;
    bool configured;
    bool running;

    // Appearance
    uint32_t color;  // XRGB format
};

Listener Architecture

Each Wayland object that sends events needs a listener:

LISTENER CALLBACKS
═════════════════════════════════════════════════════════════════

wl_registry_listener:
  ├── global()       → Called for each available global
  └── global_remove() → Called when global is removed

xdg_wm_base_listener:
  └── ping()         → Compositor liveness check, must pong

xdg_surface_listener:
  └── configure()    → Surface configuration with serial

xdg_toplevel_listener:
  ├── configure()    → Size/state suggestion
  └── close()        → User requested close

wl_buffer_listener:
  └── release()      → Buffer can be reused/destroyed

Phased Implementation Guide

Phase 1: Connection and Registry (Day 1)

Goal: Connect to Wayland and enumerate available globals

Steps:

  1. Create basic project structure with Makefile
  2. Include necessary headers
  3. Implement wl_display_connect()
  4. Get registry and add listener
  5. Print all available globals

Verification:

$ ./wayland_client
Connected to Wayland display
Global: wl_compositor v6
Global: wl_shm v1
Global: xdg_wm_base v5
...

Key Code Pattern:

static void registry_global(void *data, struct wl_registry *registry,
                           uint32_t name, const char *interface,
                           uint32_t version) {
    printf("Global: %s v%u\n", interface, version);

    if (strcmp(interface, wl_compositor_interface.name) == 0) {
        state->compositor = wl_registry_bind(registry, name,
            &wl_compositor_interface, 4);
    }
    // ... bind other globals
}

Phase 2: Surface Creation (Day 2-3)

Goal: Create a surface with xdg-shell role

Steps:

  1. Bind to wl_compositor, wl_shm, xdg_wm_base
  2. Create wl_surface from compositor
  3. Implement xdg_wm_base ping handler
  4. Create xdg_surface and xdg_toplevel
  5. Set window title
  6. Initial commit to trigger configure

Verification:

$ WAYLAND_DEBUG=1 ./wayland_client 2>&1 | grep xdg
[...] xdg_wm_base@6.get_xdg_surface(...)
[...] xdg_surface@7.get_toplevel(...)
[...] -> xdg_toplevel@8.configure(800, 600, ...)
[...] -> xdg_surface@7.configure(1234)

Phase 3: Buffer Management (Day 3-4)

Goal: Create shared memory buffer and paint pixels

Steps:

  1. Implement create_shm_file() using memfd_create()
  2. Calculate buffer size (width * height * 4)
  3. Create wl_shm_pool
  4. Create wl_buffer from pool
  5. Paint solid color to buffer
  6. Implement buffer release handler

Key Functions:

static int create_shm_file(size_t size);
static struct wl_buffer* create_buffer(struct client_state *state);
static void paint_buffer(struct client_state *state, uint32_t color);

Phase 4: Configure Handling (Day 4-5)

Goal: Properly handle the configure/ack/commit cycle

Steps:

  1. Store configure serial
  2. Acknowledge configure
  3. Create buffer at configured size
  4. Paint and attach buffer
  5. Commit surface

Critical Pattern:

static void xdg_surface_configure(void *data,
                                   struct xdg_surface *xdg_surface,
                                   uint32_t serial) {
    struct client_state *state = data;

    xdg_surface_ack_configure(xdg_surface, serial);

    if (state->buffer) {
        wl_buffer_destroy(state->buffer);
    }

    state->buffer = create_buffer(state);
    paint_buffer(state, state->color);

    wl_surface_attach(state->surface, state->buffer, 0, 0);
    wl_surface_damage_buffer(state->surface, 0, 0,
                             state->width, state->height);
    wl_surface_commit(state->surface);

    state->configured = true;
}

Phase 5: Event Loop and Cleanup (Day 5-6)

Goal: Main event loop and proper resource cleanup

Steps:

  1. Implement main event loop with wl_display_dispatch()
  2. Handle SIGINT for graceful shutdown
  3. Implement cleanup in reverse order of creation
  4. Verify no leaks with valgrind

Event Loop:

while (state.running && wl_display_dispatch(state.display) != -1) {
    // Events are handled in callbacks
}

Phase 6: Resize Handling (Day 6-7)

Goal: Properly handle window resize

Steps:

  1. Handle xdg_toplevel.configure with new dimensions
  2. Store new width/height
  3. Recreate buffer at new size on xdg_surface.configure
  4. Handle size (0, 0) meaning “client’s choice”

Testing Strategy

Manual Testing Checklist

  • Window appears on screen with correct color
  • Window can be resized - color fills new area
  • Window can be minimized and restored
  • Window can be maximized
  • Window can be closed with window controls
  • Program exits cleanly on Ctrl+C
  • No visual artifacts during resize

Automated Verification

# Check for memory leaks
valgrind --leak-check=full ./wayland_client

# Verify protocol correctness
WAYLAND_DEBUG=1 ./wayland_client 2>&1 | grep -E "(error|warning)"

# Test on different compositors
# - Sway
# - GNOME Wayland
# - weston

Expected Protocol Trace

A successful run should show this sequence in WAYLAND_DEBUG=1:

wl_display@1.get_registry(new id wl_registry@2)
wl_registry@2.bind(1, "wl_compositor", 4)
wl_registry@2.bind(3, "wl_shm", 1)
wl_registry@2.bind(6, "xdg_wm_base", 5)
wl_compositor@100.create_surface(new id wl_surface@200)
xdg_wm_base@102.get_xdg_surface(new id xdg_surface@300, wl_surface@200)
xdg_surface@300.get_toplevel(new id xdg_toplevel@400)
xdg_toplevel@400.set_title("My Wayland Client")
wl_surface@200.commit()
 -> xdg_toplevel@400.configure(800, 600, array)
 -> xdg_surface@300.configure(1234)
xdg_surface@300.ack_configure(1234)
wl_shm@101.create_pool(new id wl_shm_pool@500, fd 3, 1920000)
wl_shm_pool@500.create_buffer(new id wl_buffer@600, 0, 800, 600, 3200, 1)
wl_surface@200.attach(wl_buffer@600, 0, 0)
wl_surface@200.damage_buffer(0, 0, 800, 600)
wl_surface@200.commit()

Common Pitfalls and Debugging

Problem: Window doesn’t appear

Possible causes:

  1. Forgot to call wl_surface_commit() after initial setup
  2. Didn’t ack configure before committing content
  3. Buffer not attached before commit
  4. Running on X11 (check echo $XDG_SESSION_TYPE)

Debug:

WAYLAND_DEBUG=1 ./wayland_client 2>&1 | grep -i error

Problem: Black window instead of colored

Possible causes:

  1. Painting after commit (too late)
  2. Wrong pixel format (using ARGB instead of XRGB)
  3. Buffer size mismatch with surface size

Debug:

// Add after painting
fprintf(stderr, "Buffer: %dx%d, first pixel = 0x%08x\n",
        state->width, state->height,
        ((uint32_t*)state->buffer_data)[0]);

Problem: Crash on resize

Possible causes:

  1. Destroying buffer while still in use by compositor
  2. Not handling wl_buffer.release
  3. Memory corruption from size calculations

Fix: Use double buffering or wait for release event

Problem: Protocol error on startup

Common message: “invalid object”

Cause: Using object before it’s created, or after it’s destroyed

Debug: Check object creation order matches protocol requirements

Extensions and Challenges

Challenge 1: Gradient Background

Instead of solid color, render a gradient from top to bottom.

Challenge 2: Double Buffering

Implement proper double buffering with two buffers.

Challenge 3: Animation

Animate the color over time using frame callbacks.

Challenge 4: Keyboard Input

Bind to wl_seat, get keyboard, handle key events to change color.

Challenge 5: Multi-Monitor

Enumerate wl_output globals and display on a specific monitor.

Real-World Connections

How This Relates to Real Applications

  • GTK4: Uses similar code internally with GdkWaylandDisplay
  • Qt: QWaylandWindow implements the same surface lifecycle
  • SDL2: SDL_CreateWindow on Wayland does exactly this
  • Firefox: WebRender uses shared memory buffers like this
  • Electron: Ozone layer implements Wayland using these primitives

Career Applications

  • Graphics Driver Development: Understanding buffer sharing is essential
  • Window Manager Development: This is the client side; compositor is the other
  • Embedded Linux: Automotive/IVI systems use Wayland extensively
  • Gaming: Game engines need to understand display server protocols
  • Desktop Environment Development: GNOME, KDE rely on these concepts

Resources

Essential Reading

Resource Purpose
“The Wayland Book” Ch. 1-4 Protocol fundamentals
“The Wayland Book” Ch. 8-9 XDG-Shell specifics
“The Linux Programming Interface” Ch. 54 Shared memory
“Effective C” Ch. 6 Memory management patterns

Code References

  • weston/clients/simple-shm.c - Canonical minimal client
  • wayland/tests/ - Test clients from libwayland
  • GTK4 source: gdk/wayland/ - Production implementation

Online Documentation

  • https://wayland-book.com - The Wayland Book (free online)
  • https://wayland.app - Protocol documentation browser
  • /usr/share/wayland/wayland.xml - Core protocol definition
  • /usr/share/wayland-protocols/ - Extension protocols

Self-Assessment Checklist

Before considering this project complete, verify you can:

  • Explain why Wayland exists and how it differs from X11
  • Describe the role of wl_registry and global binding
  • Explain the configure/ack/commit cycle without looking at notes
  • Draw the buffer lifecycle state machine from memory
  • Debug a protocol error using WAYLAND_DEBUG=1
  • Modify the color without recompiling (via command line)
  • Add keyboard input to your client
  • Explain what happens when the user resizes the window
  • Describe how shared memory enables zero-copy rendering
  • Compare your code to a GTK4 simple window (how much is hidden?)

Completing this project gives you a solid foundation in Wayland client development. You now understand what every Wayland application does under the hood, even when hidden by toolkits. Next, consider Project 5 (X11 Comparison) while this knowledge is fresh, then progress to Project 2 (Compositor) to see the other side of the protocol.