Qt Wayland Compositor

Wayland is a display server protocol to help in creating multi-process systems, where multiple client applications may render content on the same display, by going via a compositor process.

Compared to a system with a single-process design, a multi-process system gives several benefits:

  • Easier resource management, through the regular operating system mechanisms.
  • Better security, as each application can run with its own permissions or sandbox.
  • Clearer separation of application UI and compositor UI, so each can be modified independently.

In a typical Wayland-based system, multiple client processes will render their own contents to off-screen buffers. The information about these buffers will then be passed to a display server process by using the Wayland protocol. Finally, the display server process will composite and position the contents on a physical display.

Qt Wayland Compositor is a module that provides convenient and powerful QML and C++ APIs for developing custom display servers based on this protocol. The server displays content from client applications that support the Wayland protocol. The design philosophy of Wayland is to keep the core protocol simple and minimal, and to expand on this with use-case-specific extensions. Qt Wayland Compositor supports many common extensions by default, and also has APIs that enables the creation of new, custom extensions.

In one typical use case, a display server written with Qt Wayland Compositor will be a subsystem inside a larger application manager process. Qt Wayland Compositor provides the APIs to communicate with clients and display their contents on screen, using C++ for low-level access and the full set of Qt Quick effects, animations and convenience when using the QML APIs. A typical application manager would, in addition to this, implement features such as application life cycle, virtual keyboard input, security and IPC. Qt provides APIs that can be used to develop the remaining parts of an application manager in other modules. The Qt Automotive Suite provides a complete application manager which includes a display server developed using Qt Wayland Compositor.

Features of Qt Wayland Compositor

The Qt Wayland Compositor API includes features needed to create a display server.

  • A QML API that can be used 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 support to include custom extensions.

Environment Variables and Command-line Arguments

The Qt Wayland Compositor API recognizes some environment variables and command-line arguments that can be used to customize its behavior.

  • 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.


Take a look at the Qt Wayland Compositor Examples for a demonstration on how the APIs can be used to write custom display servers.

Licenses and Attributions

Qt Wayland Compositor and the Qt Wayland integration plugin are available under commercial licenses from The Qt Company. In addition, they are 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:

API Reference

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

© 2017 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.