/****************************************************************************
**
** 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

*/