Qt Wayland Compositor

The Qt Wayland Compositor is a module that provides convenient and powerful QML and C++ APIs for developing custom display servers based on the Wayland protocol. The display server, often called a compositor, displays content from client applications that support the Wayland protocol.

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 provides Qt Application Manager, which is a complete application manager that includes a compositor developed using Qt Wayland Compositor.

For more information on Wayland, see Wayland and Qt.

Features of 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.

Environment Variables and Command-line Arguments

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

• Environment variables:
  • 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.
• Command-line arguments:
  • --wayland-socket-name Overrides the default socket name used for communicating with clients.

Running the 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 environment variable.

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 fancy-compositor 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 ./fancy-compositor

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.

Troubleshooting

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

Setting the 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.

Examples

Take a look at the Qt Wayland Compositor Examples to learn how these APIs can be used to write custom compositors.

API Reference

The Qt Wayland Compositor can be used from C++ or QML:

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

In addition, the module provides the CMake function qt_generate_wayland_protocol_server_sources().

Module Evolution

Porting to Qt 6 - Qt Wayland Compositor lists important changes in the module API and functionality that were done for the Qt 6 series of Qt.

Licenses and Attributions

Qt Wayland Compositor and the Qt Wayland integration plugin are available under commercial licenses from The Qt Company.

In addition, Qt Wayland Compositor is available under the GNU General Public License, version 3, while the Qt Wayland integration plugin is available under the GNU Lesser General Public License, version 3 or the GNU General Public License, version 2.

See Qt Licensing for further details.

Qt Wayland Compositor and the Qt Wayland integration plugin use protocol definitions under following permissive licenses: