4. Wayland协议详解

Wayland 协议本质上是一套“对象 + 请求 + 事件”的远程过程调用规范。客户端与合成器之间通过 Unix 域套接字建立连接，所有接口都以对象形式存在，每个对象拥有唯一 ID。理解这些核心接口的职责与调用顺序，是车载显示系统开发中排查黑屏、窗口不显示、尺寸异常等问题的基础。

一、核心接口的职责与层级关系

Wayland 协议中的接口并非平级，而是围绕“连接—注册—绘制—窗口管理”形成清晰的层级。最顶层是 wl_display，它代表客户端与合成器之间的连接本身，是所有其他对象的入口。通过 wl_display 可以获取注册表、同步请求、刷新连接。

wl_registry 是全局对象注册表，客户端通过它发现合成器暴露了哪些全局接口，例如 wl_compositor、wl_shm、xdg_wm_base、wl_seat 等。注册表通过 global 事件逐个通告全局对象，客户端根据接口名和版本号决定是否绑定。

wl_compositor 是绘制能力的入口，负责创建 wl_surface 和 wl_region。wl_surface 是真正承载像素内容的画布，但它本身不知道自己是窗口、光标还是子表面，需要配合角色接口使用。

wl_shell 是 Wayland 早期定义的窗口角色接口，现已废弃；xdg_shell（协议中通常以 xdg_wm_base 全局对象出现）是当前桌面与车载系统的主流窗口管理扩展，提供 xdg_surface、xdg_toplevel、xdg_popup 等角色对象，用于定义窗口标题、最小/最大尺寸、全屏、关闭等语义。

二、通信机制：请求、事件与对象 ID

Wayland 通信采用二进制消息帧，每条消息包含对象 ID、操作码（opcode）和参数。客户端调用接口方法时生成“请求”，合成器处理完成后通过“事件”异步通知客户端。例如客户端调用 wl_surface.attach 附加缓冲区，随后调用 wl_surface.commit 提交状态；合成器在合适时机发送 wl_surface.enter 或 wl_callback.done 事件。

对象 ID 由客户端分配，服务端在 wl_display 的 delete_id 事件中回收。所有对象生命周期由客户端管理，销毁对象后 ID 可复用。这种设计使协议紧凑高效，但也要求开发者严格管理对象引用，避免悬空 ID 导致协议错误。

三、典型调用流程与代码示例

下面以创建一个简单窗口为例，展示从连接建立到窗口映射的典型顺序。实际开发中通常使用 libwayland-client 或更高层框架（如 Qt Wayland、GTK），但理解底层顺序有助于定位问题。

// 1. 连接合成器
struct wl_display *display = wl_display_connect(NULL);

// 2. 获取注册表并监听 global 事件
struct wl_registry *registry = wl_display_get_registry(display);
wl_registry_add_listener(registry, &registry_listener, NULL);
wl_display_roundtrip(display);  // 等待 global 事件到达

// 3. 绑定 compositor 与 xdg_wm_base
struct wl_compositor *compositor = wl_registry_bind(
    registry, compositor_id, &wl_compositor_interface, 4);
struct xdg_wm_base *wm_base = wl_registry_bind(
    registry, wm_base_id, &xdg_wm_base_interface, 1);

// 4. 创建 surface 并绑定 xdg 角色
struct wl_surface *surface = wl_compositor_create_surface(compositor);
struct xdg_surface *xdg_surf = xdg_wm_base_get_xdg_surface(wm_base, surface);
struct xdg_toplevel *toplevel = xdg_surface_get_toplevel(xdg_surf);

// 5. 设置标题、提交并等待 configure
xdg_toplevel_set_title(toplevel, "IVI Main Window");
wl_surface_commit(surface);
// 收到 xdg_surface.configure 后调用 ack_configure
// 再附加 buffer 并 commit，窗口才会显示

四、接口对比与常见误区

五、车载场景下的实践要点

在车载 IVI 系统中，通常存在多个显示输出（中控屏、仪表屏、副驾屏），合成器可能基于 wl_output 管理不同区域。应用窗口通过 xdg_toplevel 设置全屏或指定输出，仪表类应用往往要求固定层级和确定性延迟，因此需要关注 wl_surface.commit 与 frame callback 的配合，避免撕裂和掉帧。

此外，车载系统常使用 wl_shm 进行软件渲染缓冲区共享，或使用 dmabuf 实现零拷贝硬件合成。排查显示异常时，可按“连接是否成功 → registry 是否绑定到所需全局对象 → surface 是否绑定角色 → configure 是否 ack → buffer 是否有效 → commit 是否到达合成器”的顺序逐层检查，这比盲目修改渲染代码更高效。