1. 课程导入
欢迎进入《Wayland与OpenGL ES集成》课程。本课程面向已经具备一定 Linux 图形栈基础、希望把 OpenGL ES 渲染真正落到 Wayland 合成器上的开发者。很多同学在嵌入式或桌面 Linux 上写 OpenGL ES 程序时，习惯使用 EGL 直接创建窗口表面，但在 Wayland 环境下，窗口、缓冲区、同步、输入和显示提交都由合成器统一管理，渲染端不再直接“画到屏幕上”，而是把渲染结果交给合成器合成。理解这条链路，是后续所有章节的基础。
一、学习目标
完成本课程后，你应当能够独立完成以下任务：
- 理解 Wayland 协议中客户端、合成器、表面、区域、缓冲区等核心对象及其职责边界。
- 掌握 EGL 在 Wayland 上的初始化流程，包括
wl_display、wl_surface与EGLSurface的绑定关系。 - 能够使用 OpenGL ES 在 Wayland 客户端中完成渲染、提交、同步与重绘。
- 理解
wl_buffer、wl_shm、dmabuf等缓冲区机制，并能根据场景选择合适方案。 - 掌握帧同步、输入事件、窗口缩放、多输出等常见问题的排查方法。
二、核心概念
Wayland 是一个显示服务器协议，它规定了客户端与合成器之间如何通信。与 X11 不同，Wayland 客户端不能直接访问显示硬件，也不能直接绘制到屏幕。客户端通过 Unix 域套接字连接合成器，使用 wl_surface 表示一个可绘制区域，使用 wl_buffer 表示像素数据，通过 wl_surface.attach 和 wl_surface.commit 把缓冲区提交给合成器。
OpenGL ES 是渲染 API，它负责把图元渲染到当前绑定的帧缓冲中。在 Wayland 上，OpenGL ES 并不直接与 Wayland 协议交互，而是通过 EGL 作为桥梁。EGL 负责把 wl_display 和 wl_surface 包装成 EGLDisplay 和 EGLSurface，使 OpenGL ES 的渲染目标与 Wayland 的缓冲区机制对接。
因此，本课程涉及三个层次：
| 层次 | 代表对象 | 主要职责 |
|---|---|---|
| 协议层 | wl_display、wl_surface、wl_buffer |
客户端与合成器通信，管理表面、缓冲区和输入 |
| 桥接层 | EGLDisplay、EGLSurface、EGLContext |
把 Wayland 对象映射为 EGL 资源，连接渲染与提交 |
| 渲染层 | OpenGL ES 上下文、FBO、纹理、着色器 | 执行实际绘制，生成像素数据 |
这三层的关系可以用下面的信号链图表示。图中从应用侧开始，经过 EGL 桥接，进入 Wayland 协议对象，最终由合成器完成显示输出。理解这张图，后续章节中的初始化、渲染循环、缓冲区交换和同步问题都会变得清晰。
三、整体框架与学习路径
本课程共 30 章，按照“先建立认知，再打通链路，最后处理复杂场景”的顺序展开。前几章会从 Wayland 协议对象和 EGL 初始化入手，帮助你搭建最小可运行程序；中间章节会深入缓冲区管理、渲染循环、输入事件和窗口状态变化；后段则聚焦多输出、缩放、性能优化、调试与排障。
建议的学习方法是：每学完一个概念，就在本地写一个最小示例验证。例如，学习 wl_surface 时，先创建一个纯色表面；学习 EGL 绑定时，再把它替换为 OpenGL ES 渲染的三角形。这样可以把抽象协议和实际代码对应起来。
四、典型场景与常见误区
一个典型场景是嵌入式设备上的全屏 OpenGL ES 应用。应用启动后连接 Wayland 合成器，创建 wl_surface，通过 EGL 创建上下文和窗口表面，然后在渲染循环中绘制场景，调用 eglSwapBuffers 提交。合成器收到新缓冲区后，在下一个垂直同步周期把它合成到屏幕上。
常见误区主要有三个：
- 认为
eglSwapBuffers会立即显示。实际上它只是提交缓冲区，显示时机由合成器决定。 - 忽略帧回调。Wayland 推荐使用
wl_surface.frame回调来驱动下一帧，而不是盲目循环渲染。 - 混淆
wl_shm与dmabuf。前者适合软件渲染和简单场景，后者适合 GPU 直接共享，性能和格式要求不同。
五、本章小结与准备
本章建立了课程的整体认知：Wayland 负责协议与合成，OpenGL ES 负责渲染，EGL 负责桥接。后续章节将围绕这条主线逐步展开。开始下一章之前，请确认你的开发环境已经具备 Wayland 客户端库、EGL 和 OpenGL ES 开发头文件，并能够运行一个最小的 Wayland 客户端程序。
# 检查基础开发环境
pkg-config --exists wayland-client && echo "wayland-client OK"
pkg-config --exists egl && echo "egl OK"
pkg-config --exists glesv2 && echo "glesv2 OK"
# 查看当前 Wayland 显示
echo $WAYLAND_DISPLAY
当这些检查通过后，你就具备了进入后续实操章节的条件。接下来，我们将从 Wayland 协议对象开始，逐步搭建完整的集成链路。