diff options
author | Kavindra Palaraja <kpalaraja@luxoft.com> | 2019-03-15 17:03:06 +0100 |
---|---|---|
committer | Robert Griebl <robert.griebl@pelagicore.com> | 2019-04-01 14:54:05 +0000 |
commit | 2d021dd91a018f18faf56647319510afb8f7e292 (patch) | |
tree | 4a6c96856046beca46ba78b651c7722439bf95ab | |
parent | 7268234726f41dec0615abfe651e882eef0cda48 (diff) |
[docs] Add documentation about Wayland architecturev5.13.0-beta2
* Created a new topic to provide some conceptual content on Wayland
* Added some diagrams to support the story
Task-number: AUTOSUITE-679
Change-Id: Iac4fb425f1bdce8fba79e06994f933ac86d55056
Reviewed-by: Johan Helsing <johan.helsing@qt.io>
-rw-r--r-- | doc/images/wayland-multi-process.png | bin | 0 -> 60264 bytes | |||
-rw-r--r-- | doc/images/wayland-single-process-develop.png | bin | 0 -> 12789 bytes | |||
-rw-r--r-- | doc/images/wayland-single-process-eglfs.png | bin | 0 -> 10952 bytes | |||
-rw-r--r-- | doc/src/wayland-and-qt.qdoc | 259 |
4 files changed, 259 insertions, 0 deletions
diff --git a/doc/images/wayland-multi-process.png b/doc/images/wayland-multi-process.png Binary files differnew file mode 100644 index 000000000..116688b4d --- /dev/null +++ b/doc/images/wayland-multi-process.png diff --git a/doc/images/wayland-single-process-develop.png b/doc/images/wayland-single-process-develop.png Binary files differnew file mode 100644 index 000000000..51e975fd0 --- /dev/null +++ b/doc/images/wayland-single-process-develop.png diff --git a/doc/images/wayland-single-process-eglfs.png b/doc/images/wayland-single-process-eglfs.png Binary files differnew file mode 100644 index 000000000..8572d08b4 --- /dev/null +++ b/doc/images/wayland-single-process-eglfs.png diff --git a/doc/src/wayland-and-qt.qdoc b/doc/src/wayland-and-qt.qdoc new file mode 100644 index 000000000..f73340073 --- /dev/null +++ b/doc/src/wayland-and-qt.qdoc @@ -0,0 +1,259 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \page wayland-and-qt.html + \title Wayland and Qt + \brief An overview of the Wayland protocol and how it fits into Qt. + + \l {https://wayland.freedesktop.org/}{Wayland} is a display server protocol + that helps you to create multi-process systems. Multiple client applications + ("clients") can render their own content to off-screen buffers. These buffers + are then passed to a display server, often called a compositor, using the + Wayland protocol. Finally, the compositor composites and positions the + content on a physical display. + + \section1 Why Use Multi-Process + + In a single-process system, all parts of the UI run in one, single process. + In a multi-process system, all clients run in their own, dedicated process. + With Qt, at any point in your development process, you can choose to switch + between single-process and multi-process. + + \image ../images/wayland-multi-process.png + \caption Multi-Process Client Architecture + + \image ../images/wayland-single-process-eglfs.png + \caption Single Process Client Architecture + + The use of multi-process has the following benefits: + + \list + \li \l{stability}{Stability} + \li \l{security}{Security} + \li \l{performance}{Performance} + \li \l{interoperability}{Interoperability} + \endlist + + \target stability + \table 100% + \header + \li {2,1} Stability + \row + \li Easier to recover when clients hang or crash + \li If you have a complex UI, then multi-process is useful because if one + part of the UI crashes, it doesn't affect the entire system. + Similarly, the display won't freeze, even when one client freezes. + + \note If your client is mandated by law to render safety-critical + information, consider using + \l{https://doc.qt.io/QtSafeRenderer/qtsr-overview.html}{Qt Safe Renderer Overview}. + \row + \li Protection against possible memory leaks + \li In a multi-process system, if one client has a memory leak and + consumes lots of memory, that memory is recovered when that client + exits. In contrast with single-process, the memory leak remains until + the entire system restarts. + \endtable + + \target security + \table 100% + \header + \li Security + \row + \li In a single-process system, all clients can access each other's + memory. For example, there's no isolation for sensitive data + transfer; every line of code must be equally trustworthy. This + isolation is there, by design, in multi-process systems. + \endtable + + \target performance + \table 100% + \header + \li Performance + \row + \li If you have a CPU with multiple cores, a multi-process system can + help distribute the load evenly across different cores, making more + efficient use of your CPU. + \endtable + + \target interoperability + \table 100% + \header + \li Interoperability + \row + \li You can interface with non-Qt clients in a multi-process system, as + long as your clients understand Wayland or X11. For example, if you + use gstreamer for video or if you want to use a navigation + application built with another UI toolkit, you can run these clients + alongside your other Qt-based clients. + \endtable + + \section1 Why Use Wayland Instead of X11 or Custom Solutions + + X11, a desktop protocol from the 80s, no longer fits with how graphics + hardware works today. It is large, complex, and lacks customizability. In + fact, it is difficult to run a client fluidly with X11, and reach 60 fps + without tearing. Wayland, in contrast, is easier to implement, has better + performance, and contains all the necessary parts to run efficiently on + modern graphics hardware. For embedded, multi-process systems on Linux, + Wayland is the standard. + + However, if you are working with old hardware or legacy applications, + then Wayland may not be a good option. The Wayland protocol is designed with + security and isolation in mind, and is strict/conservative about what + information and functionality is available to clients. While this leads to a + cleaner and more secure interface, some functionality that legacy + applications expect may no longer be available on Wayland. + + Particularly, there are three common use cases where Wayland may not be the + best option: + \list 1 + \li The hardware or platform is old and only supports X11; in which case + you have no choice. + \li You have to support legacy applications that depend on features that + are absent in the Wayland protocol for security and simplicity. + \li You have to support legacy applications that use a UI toolkit that + doesn't run on Wayland at all. In some cases, you may be able to work + around this by running those applications on + \l{https://wayland.freedesktop.org/xserver.html}{XWayland} instead. + \endlist + + Back when X11 was very popular, developers wrote their own custom solutions + to circumvent X11 issues. Older Qt versions had the Qt Windowing System + (QWS), which is now discontinued. Today, most of these use cases are covered + by Wayland, and custom solutions are becoming less and less common. + + \section1 Possible Trade-Offs with Multi-Process + + Use of multi-process systems do bring about the following trade-offs: + + \list + \li \l{increased-video-memory}{Increased video memory consumption} + \li \l{increased-main-memory}{Increased main memory consumption} + \li \l{repeated-storage}{Repeated storage of graphical resources} + \endlist + + \target increased-video-memory + \table 100% + \header + \li Increased video memory consumption + \row + \li This can be a constraint for embedded devices. In multi-process, each + client needs to have its own graphics buffer, which it sends to the + compositor. Consequently, you use more video memory compared to the + single-process case: where everything is drawn at once and there is + no need to store the different parts in intermediary buffers. + \endtable + + \target increased-main-memory + \table 100% + \header + \li Increased main memory consumption + \row + \li Apart from some extra overhead at the OS level, running multiple + clients may also use more main memory as some parts need to be + duplicated once per client. For example, if you run QML, each client + requires a separate QML engine. Consequently, if you run a single + client that uses Qt Quick Controls, it's loaded once. If you then + split this client into multiple clients, you're loading Qt Quick + Controls multiple times, resulting in a higher startup cost to + initialize your clients. + \endtable + + \target repeated-storage + \table 100% + \header + \li Repeated storage of graphical resources + \row + \li In a single-process system, if you're using the same textures, + background, or icons in many places, those images are only stored + once. In contrast, if you use these images in a multi-process system, + then you have to store them multiple times. In this case, one + solution is to share graphical resource between clients. Qt already + allows sharing image resources in main memory across processes + without involving Wayland. Sharing GPU textures across processes, on + the other hand, requires more intricate solutions. Such solutions are + currently in development for the Qt Wayland Compositor. + \endtable + + \section1 What Qt Wayland Offers + + \b{For Clients} + \br + Qt clients can run on any Wayland compositor, including Weston, the reference + compositor developed as part of the Wayland project. + + Any Qt program can run as a Wayland client (as part of a multi-process system) + or a standalone client (single-process). This is determined on startup, where + you can choose between the different backends. During the development process, + you can develop the client on the desktop first, then test it on the target + hardware later. You don't need to run your clients on the actual target + hardware all the time. + + \image ../images/wayland-single-process-develop.png + \caption Single-Process Client Development + + If you develop on a Linux machine, you can also run the compositor within a + window on your development machine. This lets you run clients in an + environment that closely resembles the target device. Without rebuilding the + client, you can also run it with \c{-platform wayland} to run it inside the + compositor. If you use \c{-platform xcb} (for X11), you can run the client on + the desktop. In other words, you can start developing your clients before the + compositor is ready for use. + + \b{For Servers} + \br + The server, or compositor, connects to the display and shows the contents of + each client on the screen. The compositor handles input and sends input + events to the corresponding client. In turn, each client connects to the + compositor and sends the content of its windows. It's up to the compositor to + decide: + + \list + \li How and where to show the content + \li Which content to show + \li What to do with the different client graphics buffers + \endlist + + This means, it's up to the compositor to decide what a multi-process system + is. For instance, the clients could be part of a 3D scene with windows on the + walls, on a VR system, mapped to a sphere, and so on. + + The Qt Wayland Compositor is an API for building your own compositor. It + gives you full freedom to build a custom compositor UI and manage the windows + of various clients. You can combine both Qt Quick and QML with the Qt Wayland + Compositor to create impressive, imaginative UIs. For more information, see + \l{Qt Wayland Compositor}. + + \section2 Related Content + \list + \li \l{https://resources.qt.io/qt-world-summit-2017/qtws17-qt-wayland-compositor-creating-multi-process-user-interface-johan-helsing-the-qt-company}{QtWS17 - Qt Wayland Compositor: Creating multi-process user interface} + \li \l{https://doc.qt.io/QtApplicationManager/introduction.html}{Qt Application Manager} + \endlist + +*/ |