Qt Wayland Compositor

Qt Wayland Compositor 是一个模块，它为基于Wayland协议开发自定义显示服务器提供了便捷且强大的 QML 和 C++ API。显示服务器（通常称为合成器）负责显示支持 Wayland 协议的客户端应用程序的内容。

Wayland的设计理念是保持核心协议简单且精简。开发者可以在此核心协议基础上，通过针对特定用例的扩展进行扩展。Qt Wayland Compositor 默认支持许多常见扩展，同时也提供了用于创建新的自定义扩展的API。

通常，使用Qt Wayland Compositor 编写的合成器会作为子系统运行于更大的应用程序管理器进程之中。Qt Wayland Compositor 提供了与客户端通信并将内容显示在屏幕上的 API。 Qt Qml API 包含可与 Qt 其余部分轻松集成的高级 API，通过Qt Quick 能够便捷地实现动画、特效和用户界面。此外，还提供了 C++ API——如果您需要更底层的访问权限。

应用程序管理器通常会实现一些额外功能，例如应用程序生命周期、虚拟键盘输入、安全性和进程间通信（IPC）。Qt 提供了相应的 API，可用于在其他模块中开发应用程序管理器的其余部分。事实上，Qt 还提供了 Qt Application Manager，这是一个完整的应用程序管理器，其中包含基于Qt Wayland Compositor 构建的高级QML API，用于实现自定义合成器。

有关 Wayland 的更多信息，请参阅《Wayland 与 Qt》。

功能Qt Wayland Compositor

Qt Wayland Compositor 包含创建合成器所需的功能：

• 一个用于显示和操作客户端内容的 QML API，与Qt Quick 中的所有功能完全集成。
• 用于低级访问和控制的 C++ API。
• 支持常见扩展，包括 XDG Shell 和 IVI 应用程序。
• 用于轻松扩展对自定义扩展支持的 API。

环境变量和命令行参数

以下是Qt Wayland Compositor 所识别的环境变量和命令行参数的不完整列表：

• 环境变量：
  • QT_WAYLAND_HARDWARE_INTEGRATION定义合成器应提供的客户端缓冲区（硬件）集成方式。接受以分号分隔的列表（例如“linux-dmabuf-unstable-v1;wayland-egl”）。
  • QT_WAYLAND_CLIENT_BUFFER_INTEGRATION与 QT_WAYLAND_HARDWARE_INTEGRATION（后者具有优先级）在合成器层面的作用相同，但也会由客户端进行评估。客户端仅接受单一集成方式。
  • QT_IVI_SURFACE_ID在 IVI-compositor 环境中，指定客户端画面的 IVI 画面 ID。
• 命令行参数：
  • --wayland-socket-name <name> 覆盖用于与客户端通信的默认套接字名称。

运行 Wayland 合成器

只要不依赖任何不可用的平台特定功能，合成器就可以在基于 X11 的桌面系统上轻松进行测试。这在开发过程中非常有用，既可以简化调试，又能高效地快速验证新功能。

Qt Wayland 支持多种后端，用于在客户端和服务器之间共享图形缓冲区。主要后端为：

• wayland-egl：这是默认后端，应尽可能优先使用。其正常工作需要系统中的 OpenGL 驱动程序提供相应支持。

通过设置QT_WAYLAND_HARDWARE_INTEGRATION 环境变量，可以选择其他后端。

此外请注意，如果您的系统上已经运行着一个 Wayland 合成器，您可能需要将XDG_RUNTIME_DIR 指向其他位置。如果出现这种情况，在启动合成器时会看到警告。XDG_RUNTIME_DIR 可以指向任何可访问且尚未被占用的位置。

例如，若要使用linux-dmabuf-v1 后端运行fancy-compositor示例，可使用以下命令行：

% XDG_RUNTIME_DIR=~/my_temporary_runtime QT_XCB_GL_INTEGRATION=xcb_egl QT_WAYLAND_HARDWARE_INTEGRATION=linux-dmabuf-v1 ./fancy-compositor

随后，客户端可以通过设置相同的XDG_RUNTIME_DIR ，并传递 "-platform wayland" 作为命令行参数，在合成器上运行。QT_QPA_PLATFORM 环境变量也可用于在客户端选择 Wayland QPA 插件。

故障排除

有时，在开发复杂的合成器时，您可能会遇到需要进一步调查的问题。

将WAYLAND_DEBUG 环境变量设置为“1”将启用Wayland库本身的日志输出。这在调试Wayland协议的自定义扩展时非常有用。它将精确显示客户端与服务器之间传递的事件和请求，以及它们的时间戳。

此外，Qt XML 还提供了qt.waylandcompositor.* 和qt.qpa.wayland.* 这两个日志类别以启用额外日志。后者应在客户端设置，因为它会启用 Wayland QPA 插件的日志记录。

示例

请参阅Qt Wayland Compositor 示例，了解如何利用这些 API 编写自定义合成器。

API 参考

Qt Wayland Compositor 可通过 C++ 或 QML 调用：

• Qt Wayland Compositor QML Types
• Qt Wayland Compositor C++ Classes

此外，该模块还提供了 CMake 函数qt_generate_wayland_protocol_server_sources()。

模块演变

《移植到 Qt 6 -Qt Wayland Compositor 》列出了为 Qt 6 系列所做的模块 API 和功能方面的重大更改。

许可与归属

Qt Wayland Compositor 以及 Qt Wayland 集成插件均由The Qt Company 根据商业许可证提供。

此外，Qt Wayland Compositor 根据GNU 通用公共许可证第 3 版提供，而 Qt Wayland 集成插件则根据GNU 弱通用公共许可证第 3 版或GNU 通用公共许可证第 2 版提供。

有关更多详细信息，请参阅Qt 许可。

Qt Wayland Compositor 以及 Qt Wayland 集成插件使用的协议定义遵循以下宽松许可：