diff options
Diffstat (limited to 'src/compositor/doc')
8 files changed, 262 insertions, 131 deletions
diff --git a/src/compositor/doc/qtwaylandcompositor.qdocconf b/src/compositor/doc/qtwaylandcompositor.qdocconf index 45928b640..fae83583f 100644 --- a/src/compositor/doc/qtwaylandcompositor.qdocconf +++ b/src/compositor/doc/qtwaylandcompositor.qdocconf @@ -4,6 +4,7 @@ include($QT_INSTALL_DOCS/config/exampleurl-qtwayland.qdocconf) project = QtWaylandCompositor description = Qt Wayland Compositor Reference Documentation version = $QT_VERSION +buildversion = Qt Wayland Compositor | Commercial or GPLv3 qhp.projects = QtWaylandCompositor @@ -12,9 +13,6 @@ qhp.QtWaylandCompositor.namespace = org.qt-project.qtw qhp.QtWaylandCompositor.virtualFolder = qtwaylandcompositor qhp.QtWaylandCompositor.indexTitle = Qt Wayland Compositor qhp.QtWaylandCompositor.indexRoot = -qhp.QtWaylandCompositor.filterAttributes = qtwaylandcompositor $QT_VERSION qtrefdoc -qhp.QtWaylandCompositor.customFilters.Qt.name = QtWaylandCompositor $QT_VERSION -qhp.QtWaylandCompositor.customFilters.Qt.filterAttributes = qtwaylandcompositor $QT_VERSION qhp.QtWaylandCompositor.subprojects = qmltypes classes examples qhp.QtWaylandCompositor.subprojects.qmltypes.title = QML Types @@ -30,18 +28,41 @@ qhp.QtWaylandCompositor.subprojects.examples.indexTitle = Qt Wayland Composi qhp.QtWaylandCompositor.subprojects.examples.selectors = fake:example qhp.QtWaylandCompositor.subprojects.examples.sortPages = true -depends += qtcore qtqml qtquick qtdoc qtquickcontrols qmake qtgui +depends += qtcore \ + qtqml \ + qtquick \ + qtdoc \ + qtquickcontrols \ + qmake \ + qtgui \ + qtqmlmodels \ + qtwidgets \ + qtvirtualkeyboard \ + qtcmake \ + qtopengl \ + qtwaylandclient exampledirs += ../../../examples/wayland -headerdirs += .. -sourcedirs += .. +headerdirs += \ + ../ \ + ../../imports/ +sourcedirs += \ + ../ \ + ../../imports/ imagedirs += images examplesinstallpath = wayland -Cpp.ignoretokens += Q_WAYLAND_COMPOSITOR_EXPORT -Cpp.ignoredirectives += Q_DECLARE_LOGGING_CATEGORY +# Add generic thumbnail for all examples +manifestmeta.thumbnail.names = * + +manifestmeta.highlighted.names = \ + "QtWaylandCompositor/Minimal QML" \ + "QtWaylandCompositor/IVI Compositor" navigation.landingpage = "Qt Wayland Compositor" navigation.qmltypespage = "Qt Wayland Compositor QML Types" navigation.cppclassespage = "Qt Wayland Compositor C++ Classes" + +# Enforce zero documentation warnings +warninglimit = 0 diff --git a/src/compositor/doc/src/cmake/qt_generate_wayland_protocol_server_sources.qdoc b/src/compositor/doc/src/cmake/qt_generate_wayland_protocol_server_sources.qdoc new file mode 100644 index 000000000..5a5849463 --- /dev/null +++ b/src/compositor/doc/src/cmake/qt_generate_wayland_protocol_server_sources.qdoc @@ -0,0 +1,47 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-generate-wayland-protocol-server-sources.html +\ingroup cmake-commands-qtwaylandcompositor + +\title qt_generate_wayland_protocol_server_sources +\keyword qt6_generate_wayland_protocol_server_sources + +\summary {Generates server-side C++ bindings for a Wayland protocol .XML file} + +\cmakecommandsince 6.0 + +The command is defined in the \c WaylandCompositor component of the \c Qt6 package, which +can be loaded like so: + +\badcode +find_package(Qt6 REQUIRED COMPONENTS WaylandCompositor) +\endcode + +\section1 Synopsis + +\badcode +qt_generate_wayland_protocol_server_sources(target + FILES file1.xml [file2.xml ...]) +\endcode + +\versionlessCMakeCommandsNote qt6_generate_wayland_protocol_server_sources() + +\section1 Description + +qt_generate_wayland_protocol_server_sources() creates the build steps to run \c{waylandscanner} and +\c{qtwaylandscanner} on one or more Wayland protocol files. The tools will in turn generate binding +code in C and C++ for implementing the protocols, and the resulting files will be built as part +of the \c target. + +qt_generate_wayland_protocol_server_sources() will trigger generation of the files needed to +implement the compositor side of the protocol. + +\l{qt_generate_wayland_protocol_client_sources}{qt_generate_wayland_protocol_client_sources()} +is the equivalent function for the client. + +See the \l{Custom Shell} or \l{Custom Extension} examples for a demonstration of how to use these +functions. +*/ + diff --git a/src/compositor/doc/src/qt6-changes.qdoc b/src/compositor/doc/src/qt6-changes.qdoc new file mode 100644 index 000000000..7a9a12016 --- /dev/null +++ b/src/compositor/doc/src/qt6-changes.qdoc @@ -0,0 +1,30 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtwayland-changes-qt6.html + \title Porting to Qt 6 - Qt Wayland Compositor + + Qt 6 is a result of the conscious effort to make the framework more + efficient and easy to use. + + We try to maintain binary and source compatibility for all the public + APIs in each release. But some changes were inevitable in an effort to + make Qt a better framework. + + In this topic we summarize those changes in Qt Wayland Compositor, and + provide guidance to handle them. + + \section1 Import of Shell Classes + + In Qt 5, a few auxiliary classes were available through the Qt Wayland + Compositor namespace. In order to improve the logical separation of + these from the primary functionality of the compositor, they have been + moved into separate imports in Qt 6. + + \list + \li \l WlShell types are now available in \c QtWayland.Compositor.WlShell + \li \l XdgShell types are now available in \c QtWayland.Compositor.XdgShell + \li \l IviApplication types are now available in \c QtWayland.Compositor.IviApplication + \endlist +*/ diff --git a/src/compositor/doc/src/qtwaylandcompositor-cpp.qdoc b/src/compositor/doc/src/qtwaylandcompositor-cpp.qdoc index c406b81e1..a61278d73 100644 --- a/src/compositor/doc/src/qtwaylandcompositor-cpp.qdoc +++ b/src/compositor/doc/src/qtwaylandcompositor-cpp.qdoc @@ -1,49 +1,26 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \module QtWaylandCompositor \title Qt Wayland Compositor C++ Classes \ingroup modules + \qtcmakepackage WaylandCompositor \qtvariable waylandcompositor \brief Provides C++ classes for writing custom Wayland display servers. - To include the definitions of the module's classes, use the following directive: + \section1 Using the Module - \code - #include <QtWaylandCompositor> - \endcode + \include {module-use.qdocinc} {using the c++ api} {WaylandCompositor} - To link against the module, add this line to your \l qmake \c .pro file: + \section2 Building with CMake - \code - QT += waylandcompositor - \endcode + \include {module-use.qdocinc} {building with cmake} {WaylandCompositor} + + \section2 Building with qmake + + \include {module-use.qdocinc} {building_with_qmake} {waylandcompositor} For more information about using these classes in your application, see the \l{Qt Wayland Compositor} documentation. diff --git a/src/compositor/doc/src/qtwaylandcompositor-examples.qdoc b/src/compositor/doc/src/qtwaylandcompositor-examples.qdoc index 560844242..9cc27779e 100644 --- a/src/compositor/doc/src/qtwaylandcompositor-examples.qdoc +++ b/src/compositor/doc/src/qtwaylandcompositor-examples.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \group qtwaylandcompositor-examples diff --git a/src/compositor/doc/src/qtwaylandcompositor-overview.qdoc b/src/compositor/doc/src/qtwaylandcompositor-overview.qdoc index 440a793cb..cf24fbc57 100644 --- a/src/compositor/doc/src/qtwaylandcompositor-overview.qdoc +++ b/src/compositor/doc/src/qtwaylandcompositor-overview.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtwaylandcompositor-index.html @@ -54,7 +30,7 @@ Communication (IPC). Qt provides the APIs that can be used to develop the remaining parts of an application manager in other modules. The \l {https://www.qt.io/qt-automotive-suite/}{Qt Automotive Suite} provides - \l{Qt Application Manager}, which is a complete application manager that + \l{https://doc.qt.io/QtApplicationManager}{Qt Application Manager}, which is a complete application manager that includes a compositor developed using Qt Wayland Compositor. For more information on Wayland, see \l{Wayland and Qt}. @@ -93,6 +69,64 @@ \endlist \endlist + \section1 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: + + \list + \li \c{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. + \endlist + + Other backends may be selected by setting the \c QT_WAYLAND_CLIENT_BUFFER_INTEGRATION environment variable. + + \note 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 \c{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 + \c XDG_RUNTIME_DIR to point to a different location. If this is the case, you will see warnings + when starting the compositor. The \c XDG_RUNTIME_DIR can point to any accessible location which + is not already in use. + + For instance, if you want to run the \l{Fancy Compositor}{fancy-compositor} + example with the \c wayland-egl backend, you could use the following command line: + + \code + % XDG_RUNTIME_DIR=~/my_temporary_runtime QT_XCB_GL_INTEGRATION=xcb_egl QT_WAYLAND_CLIENT_BUFFER_INTEGRATION=wayland-egl ./fancy-compositor + \endcode + + The client can subsequently be run on the compositor by setting the same \c XDG_RUNTIME_DIR and + by passing "-platform wayland" as a command line argument. The \c QT_QPA_PLATFORM environment + variable can also be used to select the Wayland QPA plugin on the client side. + + \note 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. + + \section1 Troubleshooting + + Sometimes, when you are developing a complex compositor, you may encounter issues that require + further investigation. + + Setting the \c 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 \c qt.waylandcompositor.* and \c 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. + \section1 Examples Take a look at the \l{Qt Wayland Compositor Examples} to learn how these APIs @@ -107,13 +141,24 @@ \li \l{Qt Wayland Compositor C++ Classes} \endlist + In addition, the module provides the CMake function + \l{qt_generate_wayland_protocol_server_sources}{qt_generate_wayland_protocol_server_sources()}. + + \section1 Module Evolution + \l{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. + \section1 Licenses and Attributions Qt Wayland Compositor and the Qt Wayland integration plugin are available under commercial licenses from \l{The Qt Company}. - In addition, they are available under the - \l{GNU Lesser General Public License, version 3}, or - the \l{GNU General Public License, version 2}. + + In addition, Qt Wayland Compositor is available under the + \l{GNU General Public License, version 3}, while + the Qt Wayland integration plugin is available under the + \l{GNU Lesser General Public License, version 3} or the + \l{GNU General Public License, version 2}. + See \l{Qt Licensing} for further details. Qt Wayland Compositor and the Qt Wayland integration plugin diff --git a/src/compositor/doc/src/qtwaylandcompositor-qmltypes.qdoc b/src/compositor/doc/src/qtwaylandcompositor-qmltypes.qdoc index a89e07d78..a496d3e00 100644 --- a/src/compositor/doc/src/qtwaylandcompositor-qmltypes.qdoc +++ b/src/compositor/doc/src/qtwaylandcompositor-qmltypes.qdoc @@ -1,32 +1,8 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \qmlmodule QtWayland.Compositor 1.\QtMinorVersion + \qmlmodule QtWayland.Compositor \title Qt Wayland Compositor QML Types \ingroup qmlmodules \brief Provides QML types for writing custom Wayland display servers. @@ -37,14 +13,22 @@ The QML types can be imported into your application using the following import statement: - \qml \QtMinorVersion - import QtWayland.Compositor 1.\1 - \endcode + \section1 Using the Module - To link against the module, add this line to your \l qmake \c .pro file: + \include {module-use.qdocinc} {using the c++ api} {WaylandCompositor} - \code - QT += waylandcompositor + \section2 Building with CMake + + \include {module-use.qdocinc} {building with cmake} {WaylandCompositor} + + \section2 Building with qmake + + \include {module-use.qdocinc} {building_with_qmake} {waylandcompositor} + + \section2 QML import + + \qml + import QtWayland.Compositor \endqml For more information about using these types in your application, diff --git a/src/compositor/doc/src/qtwaylandcompositor-shellextensions.qdoc b/src/compositor/doc/src/qtwaylandcompositor-shellextensions.qdoc new file mode 100644 index 000000000..5494eeda3 --- /dev/null +++ b/src/compositor/doc/src/qtwaylandcompositor-shellextensions.qdoc @@ -0,0 +1,51 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtwaylandcompositor-shellextensions.html + \title Shell Extensions - Qt Wayland Compositor + + In Wayland, \e{shells} are extensions which provide \e{surface semantics}. This means that they + provide ways for the server and client to communicate about surfaces. Surfaces, in this context, + are often also referred to as "windows", which is typically the representation of the surface in + the compositor. + + Shell extensions provide tools for the client and server to communicate about certain things: + \list + \li They can provide a way for the client to inform the server about the purpose of a surface: + Is it a tool-tip, a pop-up menu, or a regular application window, for instance? Based on + this, the server can decide on the geometry of the window and how the user can interact + with it. + \li They can also provide protocols for manipulating the surface, such as resizing, moving, + and hiding them. + \endlist + + Like other extensions, support for shells is added to a compositor by instantiating them + as direct children of the \l WaylandCompositor top-level object. The shell extensions supported + by Qt are: \l{WlShell}, \l{XdgShell} and \l{IviApplication}. + + \list + \li \l XdgShell is an appropriate shell for desktop-style systems, where any number of + applications can connect and where windows can be manually resized and repositioned by + the user. + \li \l IviApplication is a minimalistic protocol, originally intended for In-vehicle + Infotainment systems. It is useful for embedded systems, where a pre-defined set of + applications can run, often with pre-assigned screen real estate. For some more details + on this protocol, see the \l{IVI Compositor}{IVI Compositor example}. + \li \l QtShell is a specialized shell for Qt applications which supports the window management + features available in Qt. It may be suitable on a platform where both the compositor and + client applications are written with Qt, and where applications are trusted not to abuse + features such as manual window positioning and "bring-to-front". + \li \l WlShell is mostly useful for compatibility with third-party applications. This is also + a desktop-style shell, but it has been deprecated and replaced by \l XdgShell. + \endlist + + When designing an embedded system from the bottom up, there are no rules determining which + shell extension to use. It will typically be either \l XdgShell or \l{IviApplication}. The + decision should be influenced by what features the system will need, and whether there are + applications involved which are not written in Qt and which have their own requirements. + + A Qt Wayland Compositor can also support multiple shell extensions at once. See the + \l{Minimal QML}{Minimal QML example} for an example where all three shell extensions listed + above are supported. +*/ |