Wayland 1.25：协议更新和协议

Wayland 1.25：关键协议更新和扩展

2026 年 3 月 19 日，Wayland 协议的 1.25 版本正式发布——这是一个为合成器提供进程间通信和库的图形协议。此次更新在 API 和 ABI 层面与之前的 1.x 版本向后兼容。主要重点在于错误修复、文档改进以及添加针对性的协议功能。所有组件均保留 MIT 许可。

参考合成器 Weston 继续独立演进，为桌面和嵌入式系统中 Wayland 的集成提供示例。

核心协议的变化

开发者全面重写了文档：DocBook 格式已被基于 Markdown 的 mdBook 取代。它全面覆盖了 Wayland XML 方言、内容更新模型以及颜色管理。

新增元素：

• 接口的 frozen 属性（适用于具有多个父接口的情况）——简化复杂层次结构中的状态处理。
• wl_surface.get_release 请求——为通过 wl_surface.attach 附加的缓冲区释放生成通知。与 wl_buffer.release 不同，此事件与特定渲染周期绑定，提升了渲染的可预测性。
• wl_display_dispatch_pending_single() 函数——从队列中检索并处理正好一个事件，与清空整个队列的 wl_display_dispatch_pending() 不同。

WAYLAND_DEBUG 调试输出现支持颜色高亮，提升日志可读性。

全新及优化的 Wayland 协议

自发布以来，新增扩展来补充核心协议。这些扩展单独分发，重点关注文本输入和颜色管理。

文本输入协议

• xx-input-method：允许应用为合成器生成文本。用于虚拟键盘和 IME（输入法编辑器）。客户端生成输入事件，服务器对其进行聚合。

• xx-text-input：服务器向应用发送文本。它标准化了：

- 文本输入传输。

- 输入焦点处理。

- 语言、选区和字段类型（密码、多行等）。

颜色管理

color-management-v1 和 color-representation-v1 协议得到优化：

• HDR 支持。
• 为 Wayland 表面定义颜色空间。
• 与缓冲区集成，实现准确的颜色配置文件传输。

这些扩展简化了如 Weston 或 Mutter 等合成器的实现。

开发者实用指南

这些更新针对使用自定义合成器的中高级开发者。新 frozen 属性在动态父接口场景（如叠加管理器）中非常有用。

wl_display_dispatch_pending_single() 函数解决了事件驱动架构中的问题，在这些架构中，完全处理队列可能会阻塞用户界面。

对于输入法开发，xx-input-method 和 xx-text-input 协议标准化了交互，减少了厂商特定的 hack。

在客户端集成 wl_surface.get_release 的示例（伪代码）：

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);
}

这确保了及时的资源清理，避免竞争条件。

关键要点

• mdBook 文档及完整的 XML/颜色覆盖加速了新开发者的上手。
• wl_surface.get_release 将事件绑定到帧，提升渲染精度。
• wl_display_dispatch_pending_single() 提供对事件的细粒度控制。
• 全新输入协议标准化了跨合成器的输入法兼容性。
• 颜色管理优化强化了 Wayland 生态中的 HDR 支持。

— Editorial Team