Wayland 1.25: protocol updates and protocols

# Wayland 1.25: Key Protocol Updates and Extensions

On March 19, 2026, version 1.25 of the Wayland protocol was released—a graphics protocol that provides inter-process communication and libraries for compositors. The update is backward compatible with previous 1.x releases at the API and ABI levels. The main focus is on bug fixes, documentation improvements, and adding targeted protocol features. The MIT license is retained for all components.

The reference compositor Weston continues to evolve separately, offering examples of Wayland integration in desktops and embedded systems.

Changes in the Core Protocol

Developers have overhauled the documentation: the DocBook format has been replaced with mdBook based on Markdown. It fully covers the Wayland XML dialect, content update model, and color management.

New elements added:

• The frozen attribute for interfaces with multiple parents—simplifies state handling in complex hierarchies.
• The wl_surface.get_release request—generates a notification for releasing the buffer attached via wl_surface.attach. Unlike wl_buffer.release, the event is tied to a specific render cycle, improving predictability in rendering.
• The wl_display_dispatch_pending_single() function—retrieves and processes exactly one event from the queue, unlike wl_display_dispatch_pending(), which drains the entire queue.

WAYLAND_DEBUG debug output now supports color highlighting for better log readability.

New and Refined Wayland Protocols

Since the release, extensions have been added to complement the core protocol. They are distributed separately and focus on text input and color management.

Protocols for Text Input

• xx-input-method: Allows applications to form text for compositors. Used in virtual keyboards and IME (Input Method Editor). Clients generate input events, and the server aggregates them.

• xx-text-input: The server sends text to applications. It standardizes:

- Text input transmission.

- Input focus handling.

- Language, selection, and field type (password, multiline, etc.).

Color Management

The color-management-v1 and color-representation-v1 protocols have been refined:

• HDR support.
• Defining color space for Wayland surfaces.
• Integration with buffers for accurate color profile transmission.

These extensions simplify implementation in compositors like Weston or Mutter.

Practical Use for Developers

The updates are aimed at mid- and senior-level developers working with custom compositors. The new frozen attribute is useful in scenarios with dynamic parents, such as overlay managers.

The wl_display_dispatch_pending_single() function addresses issues in event-driven architectures, where fully processing the queue can block the UI.

For IME development, the xx-input-method and xx-text-input protocols standardize interactions, minimizing vendor-specific hacks.

Example of integrating wl_surface.get_release in a client (pseudocode):

wl_surface_add_listener(surface, &surface_listener, data);

static void surface_release(void *data, struct wl_surface *surface, uint32_t serial) {
    // Buffer released after commit
    buffer_pool_release(buffer);
}

This ensures timely resource cleanup without race conditions.

Key Points

• mdBook documentation and full XML/color coverage speed up onboarding for new developers.
• wl_surface.get_release ties events to frames, improving rendering accuracy.
• wl_display_dispatch_pending_single() provides granular control over events.
• New input protocols standardize IME for cross-compositor compatibility.
• Color-management refinements strengthen HDR support in the Wayland ecosystem.

— Editorial Team