📚 课程目录第4章 Wayland协议核心

4. Wayland协议核心

在车载 Linux HMI 中，Wayland 已经取代 X11 成为主流显示协议。它并不是一个“图形库”，而是一套客户端与合成器之间的通信协议：客户端负责把界面画进缓冲区，合成器负责把这些缓冲区按窗口层级、屏幕位置和显示时序合成为最终画面。理解 Wayland 的核心对象与角色分工，是后续开发仪表、中控、HUD 等 HMI 应用的基础。

一、Wayland 架构：合成器是显示中枢

Wayland 架构采用典型的 C/S 模型。服务端称为 Wayland Compositor（合成器），它同时承担显示服务器、窗口管理器和合成器的职责；客户端称为 Wayland Client，通常是 Qt、GTK、Flutter 或自研 EGL 应用。两者通过 Unix Domain Socket 交换二进制协议消息，消息中携带对象 ID、操作码和参数。

合成器掌握 DRM/KMS、输入设备、GPU 渲染上下文等系统资源。客户端不能直接操作屏幕，只能申请 wl_surface、提交 wl_buffer，由合成器决定何时、以何种方式显示。这种“客户端渲染、合成器合成”的分工，使 Wayland 天然具备更好的安全性、隔离性和垂直同步控制能力。

核心链路：客户端 EGL 渲染 → wl_buffer 提交 → wl_surface 绑定 → 合成器收集 → DRM/KMS 扫描输出 → 屏幕显示。

二、合成器与客户端：职责边界

合成器端常见实现有 Weston、KWin、Mutter、Sway 以及车载领域常用的自定义合成器。它负责：

管理全局对象注册表 wl_registry，向客户端暴露可用接口；
接收并解析客户端请求，维护 surface 状态；
处理输入事件，将键盘、触摸、鼠标事件路由到焦点 surface；
按 z-order、位置、缩放、裁剪等规则合成画面；
通过 DRM/KMS 在正确时序提交帧，避免撕裂。

客户端则负责：

连接 socket，获取 wl_display 并绑定所需全局对象；
创建 wl_surface，使用 EGL/OpenGL ES 或软件渲染绘制内容；
创建 wl_buffer 并附加到 surface；
提交 wl_surface.commit，等待合成器反馈 wl_buffer.release；
处理输入事件并更新界面。

三、wl_surface 与 wl_buffer：画面载体与像素数据

wl_surface 是客户端在合成器中的“画布”抽象，它本身不存储像素，只保存位置、尺寸、变换、裁剪、输入区域等状态。wl_buffer 才是真正的像素数据载体，通常由 wl_shm 共享内存或 zwp_linux_dmabuf_v1 DMA-BUF 创建。客户端把 buffer 附加到 surface 后提交，合成器读取 buffer 内容进行合成。

一个典型提交周期如下：

wl_surface_attach(surface, buffer, 0, 0);
wl_surface_damage_buffer(surface, 0, 0, width, height);
wl_surface_commit(surface);
// 合成器合成后发送 wl_buffer.release
// 客户端收到 release 后才能复用该 buffer

这里的关键是双缓冲/多缓冲机制：客户端不能在前一帧 buffer 尚未 release 时反复写入同一块内存，否则会出现画面撕裂或内容错乱。车载 HMI 中常使用 2~3 个 buffer 轮转，以平衡延迟与吞吐。

四、wl_shell 与 xdg_shell：窗口语义的演进

早期 Wayland 使用 wl_shell 提供最基础的窗口语义，如全屏、最大化、临时弹窗等。但它过于简单，无法表达现代桌面和车载 HMI 所需的标题栏、最小化、焦点切换、弹窗父子关系等复杂行为，因此已被废弃。

取而代之的是 xdg_shell，它定义了 xdg_surface、xdg_toplevel、xdg_popup 等接口，支持：

顶层窗口的标题、app_id、最小/最大尺寸约束；
窗口状态：最大化、全屏、激活、平铺；
弹窗相对父窗口的定位与抓取；
配置确认机制 xdg_surface.configure，避免客户端与合成器状态不一致。

在车载场景中，仪表、中控、HUD 往往不是传统“可拖动窗口”，而是固定区域、固定层级的 surface。此时合成器可能直接使用 wl_surface 加自定义协议，而不走 xdg_shell；但涉及应用窗口、设置页、弹窗时，xdg_shell 仍是标准选择。

五、核心对象对比与选型清单

对象/接口	作用	典型使用场景	注意事项
`wl_display`	客户端与合成器连接的入口	所有 Wayland 客户端初始化	需先连接 socket 再获取 registry
`wl_registry`	全局对象注册表	绑定 compositor、shm、seat 等	需监听 global 事件并过滤接口名
`wl_surface`	画面抽象，保存状态	所有可视内容的基础	不存像素，需 attach buffer
`wl_buffer`	像素数据载体	shm 软件渲染或 dmabuf GPU 渲染	release 前不可复用
`wl_shell`	旧窗口语义	已废弃，仅兼容旧代码	新项目不应使用
`xdg_shell`	现代窗口语义	应用窗口、弹窗、全屏	需处理 configure 确认

六、案例：车载中控界面的 Wayland 渲染流程

假设中控应用使用 Qt Wayland 后端，启动后经历以下阶段：

连接 wayland-0 socket，获取 wl_display；
通过 wl_registry 绑定 wl_compositor、wl_shm、xdg_wm_base、wl_seat；
创建 wl_surface，再创建 xdg_surface 和 xdg_toplevel，设置标题与 app_id；
合成器发送 xdg_toplevel.configure，客户端确认尺寸后 ack_configure；
Qt 使用 EGL 渲染到 DMA-BUF，封装为 wl_buffer；
wl_surface_attach + commit，合成器合成并送显；
触摸事件通过 wl_seat 分发到对应 surface，应用更新界面。

调试建议：使用 WAYLAND_DEBUG=1 启动客户端，可打印完整协议消息流，快速定位 attach/commit/configure 时序问题。

七、常见误区与复盘

误区一：认为 wl_surface 就是窗口。实际上它只是画面抽象，窗口语义由 xdg_shell 提供。
误区二：buffer 提交后立即复用。必须等待 wl_buffer.release，否则合成器可能仍在读取。
误区三：忽略 configure 确认。xdg_shell 要求客户端 ack_configure，否则合成器可能拒绝后续提交。
误区四：在车载固定区域场景强行套用桌面窗口模型，导致层级和输入区域管理复杂化。

掌握 Wayland 的核心，关键在于分清“谁拥有资源、谁负责渲染、谁负责合成”。合成器是显示中枢，客户端是内容生产者，wl_surface 是状态载体，wl_buffer 是像素载体，xdg_shell 是现代窗口语义的标准入口。把这几个对象的关系和时序理顺，后续的输入处理、多屏输出、性能优化才有稳固基础。