1. 课程导入

欢迎进入《Wayland多屏显示开发工程》课程。在嵌入式、车载、桌面与工业控制等场景中，多屏显示已经从“加分项”变成“基础能力”：主屏与副屏、仪表与中控、横屏与竖屏、不同刷新率与不同缩放比例，都要求显示系统具备清晰的输出管理、缓冲区协商与合成策略。Wayland 作为现代 Linux 显示协议栈的核心，其多屏能力并不是简单“多接一根线”，而是围绕 输出（output）、合成器（compositor）、客户端表面（surface）、缓冲区（buffer） 与 提交/反馈（commit/feedback） 形成的一整套协作机制。

本课程的目标不是只让你“会调 API”，而是让你能定位多屏问题的根因：为什么副屏没有画面？为什么缩放后模糊？为什么拖动窗口卡顿？为什么热插拔后应用崩溃？要回答这些问题，必须同时理解协议、合成器实现、客户端渲染与底层图形接口之间的关系。

学习目标：从“能显示”到“可交付”

• 理解 Wayland 多屏显示的核心对象模型：output、surface、buffer、frame callback、presentation feedback。
• 掌握多屏场景下的坐标系统、缩放、旋转、裁剪与跨屏合成逻辑。
• 能够使用 wlroots、Weston、Mutter 或自研合成器进行多屏配置与调试。
• 能够编写或改造客户端，使其在多输出、不同 DPI、不同刷新率下稳定渲染。
• 具备排障能力：通过日志、协议跟踪、DRM/KMS 状态与 GPU 工具定位黑屏、撕裂、卡顿、错位等问题。

核心概念：多屏显示的五组关键词

第一组是 输出与模式。Wayland 中的 output 代表一个可显示的逻辑区域，它可能对应一个物理接口（HDMI、DP、eDP、MIPI-DSI），也可能对应虚拟输出。每个 output 有自己的模式（分辨率、刷新率）、缩放、变换（旋转/翻转）与位置。

第二组是 合成与提交。客户端把渲染结果写入 buffer，通过 surface 提交给合成器；合成器决定在哪个 output 上、以什么顺序、用什么缩放和变换进行合成。多屏时，合成器需要处理多个 output 的独立刷新与共享资源竞争。

第三组是 坐标与空间。Wayland 使用逻辑坐标与物理像素分离的模型。缩放因子改变逻辑尺寸与物理像素的映射关系，跨屏移动窗口时，坐标需要从源 output 空间转换到目标 output 空间。

第四组是 同步与反馈。frame callback 让客户端知道何时可以绘制下一帧；presentation feedback 提供实际显示时间、刷新率与序列信息，是分析卡顿与延迟的关键。

第五组是 后端与硬件。Wayland 合成器最终要通过 DRM/KMS、GBM、EGL 或 Vulkan 把画面送到显示控制器。多屏时，plane、CRTC、connector 的分配与带宽限制会直接影响能否同时点亮。

整体知识框架：四层结构

为了便于工程化学习，我们把知识框架分为四层：协议层、合成器层、客户端层与硬件层。协议层定义“谁可以做什么”；合成器层决定“实际怎么做”；客户端层负责“如何适配”；硬件层提供“能不能做”的边界。

方法流程：多屏开发的标准工作流

无论你使用哪种合成器，多屏开发都可以遵循一条可复用的流程。第一步，确认硬件与内核状态：通过 DRM 接口查看 connector 是否连接、支持哪些模式。第二步，启动合成器并观察 output 枚举结果。第三步，配置输出布局：位置、缩放、旋转、主屏。第四步，运行客户端并验证 surface 是否按预期出现在目标输出。第五步，注入变化：热插拔、分辨率切换、缩放调整，观察客户端与合成器的响应。第六步，采集性能数据并优化。

# 查看 DRM 连接器与模式（示例）
cat /sys/class/drm/card0-HDMI-A-1/status
cat /sys/class/drm/card0-HDMI-A-1/modes

# 查看 Wayland 会话中的输出信息（以 wlr-randr 为例）
wlr-randr

# 查看合成器日志中的 output 事件
journalctl -u weston --no-pager | grep -i output

案例场景：车载双屏的典型需求

假设一套车载系统有中控屏（1920×1080，缩放 1.0）与仪表屏（1280×720，缩放 1.25）。中控屏需要显示导航与媒体，仪表屏需要显示车速与告警。开发中常见的问题是：仪表屏上的文字模糊、告警弹窗出现在中控屏、热插拔后仪表屏黑屏。解决思路是：为每个 output 建立独立的逻辑区域与缩放策略；客户端根据 output 的 scale 重新分配 buffer；合成器在 output 移除时通知客户端并重新布局；对关键告警使用独立的顶层 surface 并绑定到指定 output。

常见误区与复盘清单