14 files changed, 240 insertions, 38 deletions
diff --git a/.qmake.conf b/.qmake.conf
index a2a0d4189..aefa1e701 100644
--- a/.qmake.conf
+++ b/.qmake.conf
@@ -1,3 +1,3 @@
 load(qt_build_config)
 
-MODULE_VERSION = 5.7.1
+MODULE_VERSION = 5.8.0
diff --git a/doc/images/numbers/01.png b/doc/images/numbers/01.png
new file mode 100644
index 000000000..d73ab969b
--- /dev/null
+++ b/doc/images/numbers/01.png
diff --git a/doc/images/numbers/02.png b/doc/images/numbers/02.png
new file mode 100644
index 000000000..d0b4cfafe
--- /dev/null
+++ b/doc/images/numbers/02.png
diff --git a/doc/images/numbers/03.png b/doc/images/numbers/03.png
new file mode 100644
index 000000000..752373f91
--- /dev/null
+++ b/doc/images/numbers/03.png
diff --git a/doc/images/numbers/04.png b/doc/images/numbers/04.png
new file mode 100644
index 000000000..08fe1b820
--- /dev/null
+++ b/doc/images/numbers/04.png
diff --git a/doc/images/numbers/05.png b/doc/images/numbers/05.png
new file mode 100644
index 000000000..186dd9751
--- /dev/null
+++ b/doc/images/numbers/05.png
diff --git a/doc/images/numbers/06.png b/doc/images/numbers/06.png
new file mode 100644
index 000000000..f9454a746
--- /dev/null
+++ b/doc/images/numbers/06.png
diff --git a/doc/images/numbers/07.png b/doc/images/numbers/07.png
new file mode 100644
index 000000000..0f18d811c
--- /dev/null
+++ b/doc/images/numbers/07.png
diff --git a/doc/images/numbers/08.png b/doc/images/numbers/08.png
new file mode 100644
index 000000000..463f77016
--- /dev/null
+++ b/doc/images/numbers/08.png
diff --git a/doc/images/numbers/09.png b/doc/images/numbers/09.png
new file mode 100644
index 000000000..823c5c0db
--- /dev/null
+++ b/doc/images/numbers/09.png
diff --git a/doc/images/numbers/10.png b/doc/images/numbers/10.png
new file mode 100644
index 000000000..d689be3fa
--- /dev/null
+++ b/doc/images/numbers/10.png
diff --git a/doc/src/external-resources.qdoc b/doc/src/external-resources.qdoc
index f04350553..159f29f03 100644
--- a/doc/src/external-resources.qdoc
+++ b/doc/src/external-resources.qdoc
@@ -61,7 +61,12 @@
 */
 
 /*!
-    \externalpage http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html
+    \externalpage http://www.gnu.org/licenses/gpl-2.0.html
+    \title GNU General Public License, version 2
+*/
+
+/*!
+    \externalpage http://www.gnu.org/licenses/lgpl-2.1.html
     \title GNU Lesser General Public License, version 2.1
 */
 
diff --git a/doc/src/platforms/emb-linux.qdoc b/doc/src/platforms/emb-linux.qdoc
index 3407eaf33..836fb1c83 100644
--- a/doc/src/platforms/emb-linux.qdoc
+++ b/doc/src/platforms/emb-linux.qdoc
@@ -36,14 +36,13 @@
   is a superior solution. Multiple graphical processes can be supported
   through Wayland.
 
-  There are multiple platform plugins that are potentially usable on Embedded
-  Linux systems: EGLFS, LinuxFB, KMS, DirectFB, Wayland. The availability of
-  these depend on the configuration of Qt. The default platform plugin is also
-  device-specific. For instance, on many boards \e eglfs is chosen as the
-  default one. If the default is not suitable, the \c QT_QPA_PLATFORM
-  environment variable parameter can be used to request another
-  plugin. Alternatively, for quick tests, the \c -platform command-line can be
-  used with the same syntax.
+  There are multiple platform plugins that are potentially usable on
+  Embedded Linux systems: EGLFS, LinuxFB, KMS, DirectFB, Wayland. The
+  availability of these depend on the configuration of Qt.  On many
+  boards \e eglfs is chosen as the default one. If the default is not
+  suitable, the \c QT_QPA_PLATFORM environment variable parameter can
+  be used to request another plugin. Alternatively, for quick tests,
+  the \c -platform command-line can be used with the same syntax.
 
   \section1 Configuring a Specific Device
 
@@ -51,8 +50,7 @@
   Additionally, some devices require vendor-specific adaptation code for EGL
   and OpenGL ES 2.0 support. This is not relevant for non-accelerated
   platforms, for example the ones using the LinuxFB plugin, which is meant for
-  software-based rendering only. This means Qt Quick 2 is not functional in
-  such a setup as it depends on OpenGL for rendering.
+  software-based rendering only.
 
   The directory \e qtbase/mkspecs/devices contains configuration and graphics
   adaptation code for a number of devices. For example, the
@@ -153,6 +151,49 @@
 
   \list
 
+  \li \c {QT_QPA_EGLFS_INTEGRATION} - In addition to the compiled-in \e hooks,
+  it is also possible to provide device or vendor-specific adaptation in the
+  form of dynamically loaded plugins. This environment variable enforces a
+  specific plugin. For example, setting it to \e{eglfs_kms} uses the KMS/DRM
+  backend. This is only an option when no static or compiled-in hooks were
+  specified in the device makespecs. In practice, the traditional compiled-in
+  hooks are rarely used, almost all backends are now migrated to plugins. The
+  device makespecs still contain a relevant \c EGLFS_DEVICE_INTEGRATION entry:
+  the name of the preferred backend for that particular device. This is
+  optional, but very useful to avoid the need to set this environment variable
+  in case there are more than one plugins present in the target system. In a
+  desktop environment the KMS or X11 backends are prioritized, depending on
+  the presence of the \c DISPLAY environment variable. Note that on some boards
+  the special value of \c none is used instead of an actual plugin. This
+  indicates that no special integration is necessary to use EGL with the
+  framebuffer and so no plugins must be loaded.
+
+  \li \c {QT_QPA_EGLFS_PHYSICAL_WIDTH} and \c
+  {QT_QPA_EGLFS_PHYSICAL_HEIGHT} - Physical screen width and height in
+  millimeters. On platforms where the value cannot be queried from the
+  framebuffer device \e{/dev/fb0} or via other means, a default DPI of
+  100 is used. This variable can be used to override any such
+  defaults. Setting this is important because QWidget or Qt Quick
+  Controls based applications rely on these values. Running with the
+  hard-coded settings may result in user interface element sizes
+  unsuitable for the display in use.
+
+  \li \c {QT_QPA_EGLFS_ROTATION} - Specifies the rotation applied to
+  software-rendered content in QWidget-based applications. Supported values are
+  180, 90, and -90. This does not apply to OpenGL-based windows, including Qt
+  Quick. Qt Quick applications can apply transformations in their QML scene
+  instead. The standard eglfs mouse cursor always takes the value into account,
+  with appropriately positioned and rotated pointer image, regardless of the
+  application type. The special cursor implementations, such as the KMS/DRM
+  backend's hardware cursor, may not support rotation.
+
+  \endlist
+
+  In addition, the following - less commonly used - variables are
+  available as well:
+
+  \list
+
   \li \c {QT_QPA_EGLFS_FB} - Overrides the framebuffer device. The default is
   \c /dev/fb0. On most embedded platforms this is not very relevant because the
   framebuffer is used only for querying settings like the display dimensions.
@@ -165,12 +206,6 @@
   from the framebuffer device \e{/dev/fb0}, but this does not work always and
   manually specifying the sizes may become necessary.
 
-  \li \c {QT_QPA_EGLFS_PHYSICAL_WIDTH} and \c {QT_QPA_EGLFS_PHYSICAL_HEIGHT} -
-  Physical screen width and height in millimeters. On platforms where the
-  framebuffer device \e{/dev/fb0} is not available or the query is not
-  successful, the values are calculated based on a default DPI of 100. This
-  variable can be used to override any such defaults.
-
   \li \c {QT_QPA_EGLFS_DEPTH} - Overrides the color depth for the screen. On
   platforms where the framebuffer device \e{/dev/fb0} is not available or the
   query is not successful, the default of \c 32 is used. This variable can be used
@@ -203,23 +238,6 @@
   useful information for troubleshooting issues related to the EGL
   configuration.
 
-  \li \c {QT_QPA_EGLFS_INTEGRATION} - In addition to the compiled-in \e hooks,
-  it is also possible to provide device or vendor-specific adaptation in the
-  form of dynamically loaded plugins. This environment variable enforces a
-  specific plugin. For example, setting it to \e{eglfs_kms} uses the KMS/DRM
-  backend. This is only an option when no static or compiled-in hooks were
-  specified in the device makespecs. In practice, the traditional compiled-in
-  hooks are rarely used, almost all backends are now migrated to plugins. The
-  device makespecs still contain a relevant \c EGLFS_DEVICE_INTEGRATION entry:
-  the name of the preferred backend for that particular device. This is
-  optional, but very useful to avoid the need to set this environment variable
-  in case there are more than one plugins present in the target system. In a
-  desktop environment the KMS or X11 backends are prioritized, depending on
-  the presence of the \c DISPLAY environment variable. Note that on some boards
-  the special value of \c none is used instead of an actual plugin. This
-  indicates that no special integration is necessary to use EGL with the
-  framebuffer and so no plugins must be loaded.
-
   \endlist
 
   In addition to \c {QT_QPA_EGLFS_DEBUG}, \c eglfs also supports the more modern
@@ -239,6 +257,38 @@
 
   \endlist
 
+  After running \c configure, make sure to inspect the output of
+  it. Not having the necessary eglfs backend, libudev, or libinput
+  enabled due to the corresponding configure tests failing are fairly
+  common issues that can be easily and quickly recognized this
+  way. When there is an undesired "no" result, run \c configure with
+  \c{-v} to turn on verbose output in order to see the compiler and
+  linker invocations for each configure test.
+
+  \note Errors about missing headers, libraries or seemingly cryptic
+  linker failures are often a sign of an incomplete or broken sysroot
+  and have nothing to do with and cannot be solved by Qt.
+
+  As an example, when targeting the Raspberry Pi with the Broadcom
+  proprietary graphics drivers, the output should contain something
+  like the following. If this is not the case, there is no point in
+  proceeding further with the build since accelerated graphics will
+  not be functional without the Raspberry Pi-specific backend, even if
+  the rest of Qt compiles successfully.
+
+  \badcode
+    QPA backends:
+    EGLFS ................................ yes
+    EGLFS details:
+      EGLFS i.Mx6 ........................ no
+      EGLFS i.Mx6 Wayland ................ no
+      EGLFS EGLDevice .................... no
+      EGLFS GBM .......................... no
+      EGLFS Mali ......................... no
+      EGLFS Rasberry Pi .................. yes
+      EGL on X11 ......................... no
+  \endcode
+
   \section2 LinuxFB
 
   This plugin writes directly to the framebuffer. Only software-rendered content
@@ -484,6 +534,10 @@
   --timeout} arguments shows a rotating Qt logo on each connected screen for a few
   seconds.
 
+  \note Most of the configuration options described below apply to all
+  KMS/DRM-based backends, regardless of the buffer management technology (GBM or
+  EGLStreams).
+
   The KMS/DRM backend also supports custom configurations via a JSON file.  Set
   the environment variable \c QT_QPA_EGLFS_KMS_CONFIG to the name of the file to
   enable this. The file can also be embedded into the application via the Qt
@@ -526,9 +580,105 @@
   Additionally, such a configuration also disables looking for a device via
   \c libudev and instead the specified device is used.
 
+  When \c mode is not defined, the mode that is reported as preferred by the
+  system is chosen. The accepted values for \c mode are: \c off, \c current,
+  \c preferred, width\c{x}height, or a modeline string.
+
+  All screens reported by the DRM layer will be treated as one big virtual
+  desktop by default. The mouse cursor implementation will take this into
+  account and move across the screens as expected. Although not recommended, the
+  virtual desktop mode can be disabled by setting \c separateScreens to \c false
+  in the configuration, if desired.
+
+  By default, the virtual desktop is formed left to right, based on the order of
+  connectors as reported by the system. This can be changed by setting
+  \c virtualIndex to a value starting from 0. For example, the following
+  configuration uses the preferred resolution but ensures that the left side in
+  the virtual desktop is the screen connected to the HDMI port, while the right
+  side is the screen connected to the DisplayPort:
+
+  \badcode
+    {
+      "device": "drm-nvdc",
+      "outputs": [
+        {
+          "name": "HDMI1",
+          "virtualIndex": 0
+        },
+        {
+          "name": "DP1",
+          "virtualIndex": 1
+        }
+      ]
+    }
+  \endcode
+
+  The order of elements in the array is not relevant. Outputs with unspecified
+  virtual indices will be placed after the others, with the original order in
+  the DRM connector list preserved.
+
+  To create a vertical desktop space (that is, to stack top to bottom instead of
+  left to right), add a \c virtualDesktopLayout property after \c device
+  with the value of \c vertical.
+
+  \note It is recommended that all screens in the virtual desktop use the same
+  resolution, otherwise elements like the mouse cursor may behave in unexpected
+  ways when entering areas that only exist on one given screen.
+
+  In some cases the automatic querying of the physical screen size via DRM may
+  fail. Normally the \c QT_QPA_EGLFS_PHYSICAL_WIDTH and
+  \c QT_QPA_EGLFS_PHYSICAL_HEIGHT environment variable would be used to provide the
+  missing values, however this is not suitable anymore when multiple screens are
+  present. Instead, use the \c physicalWidth and \c physicalHeight properties
+  in the \c outputs list to specify the sizes in millimeters.
+
+  \note Different physical sizes and thus differing logical DPIs are discouraged
+  because it may lead to unexpected issues due to some graphics stack components
+  not knowing about multiple screens and relying solely on the first screen's
+  values.
+
   For troubleshooting it might be useful to enable debug logs from the KMS/DRM
   backend. To do this, enable the categorized logging rule, \c qt.qpa.eglfs.kms.
 
+  \note In an embedded environment virtual desktops are more limited than with a
+  full windowing system. Windows overlapping multiple screens, non-fullscreen
+  windows and moving windows between screens should be avoided and may not
+  function as expected.
+
+  The most common and best supported use case for a multi-screen setup is to
+  open a dedicated QQuickWindow or QQuickView for each screen. With the default
+  \c threaded render loop of the Qt Quick scenegraph, each of these windows will
+  get its own dedicated render thread. This is good because the threads can be
+  throttled independently based on vsync, and will not interfere with each
+  other. With the \c basic loop this can get problematic and animations may
+  degrade as a result.
+
+  As an example, discovering all connected screens and creating a QQuickView for
+  each of them can be done like this:
+
+  \badcode
+    int main(int argc, char **argv)
+    {
+        QGuiApplication app(argc, argv);
+
+        QVector<QQuickView *> views;
+        for (QScreen *screen : app.screens()) {
+            QQuickView *view = new QQuickView;
+            view->setScreen(screen);
+            view->setResizeMode(QQuickView::SizeRootObjectToView);
+            view->setSource(QUrl("qrc:/main.qml"));
+            QObject::connect(view->engine(), &QQmlEngine::quit, qGuiApp, &QCoreApplication::quit);
+            views.append(view);
+            view->showFullScreen();
+        }
+
+        int result = app.exec();
+
+        qDeleteAll(views);
+        return result;
+    }
+  \endcode
+
   \section2 eglfs with eglfs_kms_egldevice backend
 
   This backend, typically used on Tegra devices, is similar to the KMS/DRM
@@ -541,7 +691,7 @@
   As of Qt 5.7 this backend shares many of its internal implementation with the
   GBM-based backend. This means that multiple screens and the advanced
   configuration via \c QT_QPA_EGLFS_KMS_CONFIG are supported. Some settings,
-  like hardware cursors, may not be applicable however.
+  such as \c hwcursor and \c pbuffers are not applicable however.
 
   By default the backend will find the first available display and pick the EGL
   layer that corresponds to it. When necessary, this can be overridden by
@@ -554,6 +704,53 @@
   environment variable \c QT_QPA_EGLFS_ALWAYS_SET_MODE to a non-zero value and
   relaunch the application.
 
+  \section2 Touch input in systems with multiple screens on KMS/DRM
+
+  Touchscreens require additional considerations in multi-display systems
+  because touch events have to be routed to the correct virtual screen, and this
+  requires a correct mapping between touchscreens and display outputs.
+
+  The mapping is done via the JSON configuration file specified in
+  \c QT_QPA_EGLFS_KMS_CONFIG and described in the previous sections. When a
+  \c touchDevice property is present in an element of the \c outputs array, the
+  value is treated as a device node and the touch device is associated with the
+  display output in question. Note that this can only function when all elements
+  in the \c outputs array have an explicit \c virtualIndex.
+
+  For example, assuming our touchscreen has a device node of /dev/input/event5
+  and is a touchscreen integrated into the monitor connected via HDMI as the
+  secondary screen, the following configuration ensures correct touch (and
+  synthesized mouse) event translation:
+
+  \badcode
+     {
+        "device": "drm-nvdc",
+        "outputs": [
+          {
+            "name": "HDMI1",
+            "touchDevice": "/dev/input/event5",
+            "virtualIndex": 1
+          },
+          {
+            "name": "DP1",
+            "virtualIndex": 0
+          }
+        ]
+    }
+  \endcode
+
+  \note When in doubt, enable logging from both the graphics and input
+  subsystems by setting the environment variable
+  \c{QT_LOGGING_RULES=qt.qpa.*=true} before launching the application. This will
+  help identifying the correct input device nodes and may uncover output
+  configuration issues that can be difficult to debug otherwise.
+
+  \note As of Qt 5.8, the above is only supported for the evdevtouch input
+  backend. Other variants, such as the libinput-based one, will continue to
+  route events to the primary screen. To force the usage of evdevtouch on
+  systems where multiple input backends are available, set the environment
+  variable \c QT_QPA_EGLFS_NO_LIBINPUT to \c 1.
+
   \section2 eglfs with other backends
 
   Other backends, that are typically based on targeting the framebuffer or a
diff --git a/doc/src/platforms/osx.qdoc b/doc/src/platforms/osx.qdoc
index eb61e2bb5..155cd82f7 100644
--- a/doc/src/platforms/osx.qdoc
+++ b/doc/src/platforms/osx.qdoc
@@ -383,9 +383,9 @@
     \section2 Special Keys
 
     To provide the expected behavior for Qt applications on OS X,
-    the Qt::Meta, Qt::MetaModifier, and Qt::META enum values
+    the Qt::Key_Meta, Qt::MetaModifier, and Qt::META enum values
     correspond to the Control keys on the standard Apple keyboard,
-    and the Qt::Control, Qt::ControlModifier, and Qt::CTRL enum values
+    and the Qt::Key_Control, Qt::ControlModifier, and Qt::CTRL enum values
     correspond to the Command keys.
 
     \section2 Dock