Qt Wayland Compositor

Qt Wayland Compositor 是提供用于开发自定义显示服务器,方便且强大的 QML 和 C++ API 模块,基于 Wayland 协议。显示服务器 (通常称为 Compositor 合成器) 显示来自支持 Wayland 协议的客户端应用程序的内容。

Wayland's design philosophy is to keep the core protocol simple and minimal. Developers can then expand on this core protocol with use-case-specific extensions. Qt Wayland Compositor supports many common extensions by default, and also has APIs to enable the creation of new, custom extensions.

Typically, a compositor written with Qt Wayland Compositor becomes a subsystem inside a larger application manager process. Qt Wayland Compositor provides the APIs to communicate with clients and display their content on the screen. The QML APIs contain high-level APIs that easily integrate with the rest of Qt, enabling convenient animations, effects, and UI through Qt Quick. There are also C++ APIs available - if you need more low-level access.

An application manager would typically implement additional features such as application life cycle, virtual keyboard input, security, and Inter-Process Communication (IPC). Qt provides the APIs that can be used to develop the remaining parts of an application manager in other modules. The Qt Automotive Suite 提供 Qt Application Manager , which is a complete application manager that includes a compositor developed using Qt Wayland Compositor.

有关 Wayland 的更多信息,见 Wayland and Qt .

Qt Wayland Compositor 的特征

The Qt Wayland Compositor includes features necessary to create a compositor:

  • A QML API to display and manipulate client content, fully integrated with all the features in Qt Quick.
  • A C++ API for low-level access and control.
  • Support for common extensions, including XDG Shell and IVI Application.
  • APIs to easily expand the support for custom extensions.

环境变量和命令行自变量

The Qt Wayland Compositor recognizes the following environment variables and command-line arguments:

  • 环境变量:
    • QT_WAYLAND_HARDWARE_INTEGRATION Selects the hardware integration plugin to use.
    • QT_WAYLAND_CLIENT_BUFFER_INTEGRATION Selects the client buffer integration plugin to use.
    • QT_WAYLAND_SERVER_BUFFER_INTEGRATION Selects the server integration plugin to use.
  • 命令行自变量:
    • --wayland-socket-name Overrides the default socket name used for communicating with clients.

运行 Wayland Compositor

As long as it does not depend on any unavailable platform-specific features, the compositor can easily be tested on an X11-based desktop system. This can be useful during development, both for simplified debugging and efficient turn-around on trying out new features.

Qt Wayland supports several backends for sharing graphics buffers between clients and the server. The main one is:

  • wayland-egl : This is the default backend and should be preferred whenever possible. It requires support in the OpenGL driver on the system for this to work.

Other backends may be selected by setting the QT_WAYLAND_CLIENT_BUFFER_INTEGRATION 环境变量。

注意: If Qt Wayland Compositor is unable to initialize the client buffer backend, then it will fall back to using the "shared memory" backend (based on wl_shm ) as a fail-safe. This backend will use CPU memory for sharing the graphics buffers and copy the data back and forth as needed. This has performance implications, especially on high density screens and limited graphics hardware. When investigating performance issues with Qt Wayland Compositor, start by checking that the correct client buffer integration is used.

Also bear in mind that if your system is already running a Wayland compositor, you may have to set XDG_RUNTIME_DIR to point to a different location. If this is the case, you will see warnings when starting the compositor. The XDG_RUNTIME_DIR can point to any accessible location which is not already in use.

For instance, if you want to run the pure-qml example with the wayland-egl backend, you could use the following command line:

% XDG_RUNTIME_DIR=~/my_temporary_runtime QT_XCB_GL_INTEGRATION=xcb_egl QT_WAYLAND_CLIENT_BUFFER_INTEGRATION=wayland-egl ./pure-qml
					

The client can subsequently be run on the compositor by setting the same XDG_RUNTIME_DIR and by passing "-platform wayland" as a command line argument. The QT_QPA_PLATFORM environment variable can also be used to select the Wayland QPA plugin on the client side.

注意: In most cases, the client will adapt to the same OpenGL as the server when it connects. However, when running with the EGL backend on some specific drivers, it is required that the initialization happens earlier. If you encounter this problem, you may pass "-platform wayland-egl" instead to pre-initialize the client to EGL.

故障排除

Sometimes, when you are developing a complex compositor, you may encounter issues that require further investigation.

设置 WAYLAND_DEBUG environment variable to "1" will enable log output for the Wayland library itself. This can be very useful, for example, when debugging custom extensions to the Wayland protocol. It will show you exactly which events and requests are being passed between the client and the server, as well as timestamps for these.

In addition, Qt has logging categories qt.waylandcompositor.* and qt.qpa.wayland.* to enable additional logging. The latter should be set on the client side, as it enables logging from the Wayland QPA plugin.

范例

查看 Qt Wayland Compositor 范例 to learn how these APIs can be used to write custom compositors.

API 参考

可以使用 Qt Wayland Compositor,从 C++ 或 QML:

模块演变

移植到 Qt 6 - Qt Wayland Compositor 列出了 Qt 的 Qt 6 系列在模块 API 和功能上所做出的重要改变。

许可和归属

Qt Wayland Compositor 和 Qt Wayland 集成插件在商业许可下是可用的来自 Qt 公司 .

此外,Qt Wayland Compositor 是可用的在 GNU GPL (一般公共许可) 第 3 版 ,而 Qt Wayland 集成插件可用于 GNU GPL (一般公共许可) 第 3 版 GNU GPL (一般公共许可) 第 2 版 .

Qt 许可 进一步了解细节。

Qt Wayland Compositor 和 Qt Wayland 集成插件所用协议定义遵循以下准许许可:

Presentation Time Protocol, version 1 MIT 许可
Wayland EGLStream Controller Protocol, version 1.1.1 MIT 许可
Wayland Fractional Scale Protocol, version 1 MIT 许可
Wayland Fullscreen Shell Protocol, version unstable v1 MIT 许可
Wayland IVI Extension Protocol, version 1.9.1 MIT 许可
Wayland Linux Dmabuf Unstable V1 Protocol, version unstable v1, version 3 MIT 许可
Wayland Pointer Gestures Protocol, version unstable v1, version 2 MIT 许可
Wayland Primary Selection Protocol, version 1 MIT 许可
Wayland Protocol, version 1.19.0 MIT 许可
Wayland Scaler 协议第 2 版 MIT 许可
Wayland Tablet Protocol, version unstable v2, version 1 MIT 许可
Wayland Text Input Protocol v1, version unstable v1 MIT 许可
Wayland Text Input Protocol v2, version unstable v2 HPND 许可
Wayland Text Input Protocol, version unstable v4, WIP HPND 许可
Wayland Viewporter Protocol, version 1 MIT 许可
Wayland XDG Foreign Protocol, version 1 MIT 许可
Wayland XDG Output Protocol, version unstable v1, version 3 MIT 许可
Wayland XDG Shell Protocol, version 1.18 MIT 许可
Wayland xdg-activation Protocol, version unstable v1, version 1 MIT 许可
Wayland xdg-decoration Protocol, version unstable v1, version 1 MIT 许可