Update QHighDpiScaling internal documentation

Expand section on coordinate systems. Document the
AA_EnableHighDpiScaling / AA_DisableHighDpiScaling
flags added in commit add58ed. Add some notes for
platform plugin work.

Change-Id: Ie6fe2d818a88ba784c0ee675fabbd3fc04d64bf1
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@theqtcompany.com>
Reviewed-by: Morten Johan Sørvig <morten.sorvig@theqtcompany.com>

1 files changed, 113 insertions, 24 deletions

diff --git a/src/gui/kernel/qhighdpiscaling.cpp b/src/gui/kernel/qhighdpiscaling.cpp
index 4a0900ad97..a3201aa23f 100644
--- a/src/gui/kernel/qhighdpiscaling.cpp
+++ b/src/gui/kernel/qhighdpiscaling.cpp
@@ -94,32 +94,121 @@ static inline qreal initialGlobalScaleFactor()
     plugin interfacing parts of QtGui, for example the QWindow, QScreen and
     QWindowSystemInterface implementation.
 
-    The coordinate system scaling is enabled by setting one or more scale
-    factors. These will then be factored into the value returned by the
-    devicePixelRatio() accessors (any native scale factor will also be
-    included in this value). Several setters are available:
-
-    - A process-global scale factor
-        - QT_SCALE_FACTOR (environment variable)
-        - QHighDpiScaling::setGlobalFactor()
-
-    - A per-screen scale factor
-        - QT_AUTO_SCALE_FACTOR (environment variable)
-          Setting this to a true-ish value will make QHighDpiScaling
-          call QPlatformScreen::pixelDensity()
-        - QHighDpiScaling::setScreenFactor(screen, factor);
-        - QT_SCREEN_SCALE_FACTORS (environment variable)
-        Set this to a semicolon-separated list of scale factors
-        (matching the order of QGuiApplications::screens()),
-        or to a list of name=value pairs (where name matches
-        QScreen::name()).
-
-    All scale factors are of type qreal.
-
-    The main scaling functions for use in QtGui are:
+    There are now up to three active coordinate systems in Qt:
+
+     ---------------------------------------------------
+    |  Application            Device Independent Pixels |   devicePixelRatio
+    |  Qt Widgets                                       |         =
+    |  Qt Gui                                           |
+    |---------------------------------------------------|   Qt Scale Factor
+    |  Qt Gui QPlatform*      Native Pixels             |         *
+    |  Qt platform plugin                               |
+    |---------------------------------------------------|   OS Scale Factor
+    |  Display                Device Pixels             |
+    |  (Graphics Buffers)                               |
+    -----------------------------------------------------
+
+    This is an simplification and shows the main coordinate system. All layers
+    may work with device pixels in specific cases: OpenGL, creating the backing
+    store, and QPixmap management. The "Native Pixels" coordinate system is
+    internal to Qt and should not be exposed to Qt users: Seen from the outside
+    there are only two coordinate systems: device independent pixels and device
+    pixels.
+
+    The devicePixelRatio seen by applications is the product of the Qt scale
+    factor and the OS scale factor. The value of the scale factors may be 1,
+    in which case two or more of the coordinate systems are equivalent. Platforms
+    that (may) have an OS scale factor include OS X, iOS and Wayland.
+
+    Note that the functions in this file do not work with the OS scale factor
+    directly and are limited to converting between device independent and native
+    pixels. The OS scale factor is accunted for by QWindow::devicePixelRatio()
+    and similar functions.
+
+    Configuration Examples:
+
+    'Classic': Device Independent Pixels = Native Pixels = Device Pixels
+     ---------------------------------------------------    devicePixelRatio: 1
+    |  Application / Qt Gui             100 x 100       |
+    |                                                   |   Qt Scale Factor: 1
+    |  Qt Platform / OS                 100 x 100       |
+    |                                                   |   OS Scale Factor: 1
+    |  Display                          100 x 100       |
+    -----------------------------------------------------
+
+    'Retina Device': Device Independent Pixels = Native Pixels
+     ---------------------------------------------------    devicePixelRatio: 2
+    |  Application / Qt Gui             100 x 100       |
+    |                                                   |   Qt Scale Factor: 1
+    |  Qt Platform / OS                 100 x 100       |
+    |---------------------------------------------------|   OS Scale Factor: 2
+    |  Display                          200 x 200       |
+    -----------------------------------------------------
+
+    '2x Qt Scaling': Native Pixels = Device Pixels
+     ---------------------------------------------------    devicePixelRatio: 2
+    |  Application / Qt Gui             100 x 100       |
+    |---------------------------------------------------|   Qt Scale Factor: 2
+    |  Qt Platform / OS                 200 x 200       |
+    |                                                   |   OS Scale Factor: 1
+    |  Display                          200 x 200       |
+    -----------------------------------------------------
+
+    The Qt Scale Factor is the product of two sub-scale factors, which
+    are independently either set or determined by the platform plugin.
+    Several APIs are offered for this, targeting both developers and
+    end users. All scale factors are of type qreal.
+
+    1) A global scale factor
+        The QT_SCALE_FACTOR environment variable can be used to set
+        a global scale factor for all windows in the processs. This
+        is useful for testing and debugging (you can simulate any
+        devicePixelRatio without needing access to sepcial hardware),
+        and perhaps also for targeting a specific application to
+        a specific display type (embedded use cases).
+
+    2) A per-screen scale factors
+        Some platform plugins support providing a per-screen scale
+        factor based on display density information. These platforms
+        include X11, Windows, and Android.
+
+        There are two APIs for enabling or disabling this behavior:
+            - The QT_AUTO_SCALE_FACTOR environment variable.
+            - The AA_EnableHighDpiScaling and AA_DisableHighDpiScaling
+              application attributes
+
+        Enabling either will make QHighDpiScaling call QPlatformScreen::pixelDensity()
+        and use the value provided as the scale factor for the screen in
+        question. Disabling is done on a 'veto' basis where either the
+        environment or the application source can disable. The intended use
+        cases are 'My system is not providing correct display density
+        information' and 'My application needs to work in display pixels',
+        respectively.
+
+        The QT_SCREEN_SCALE_FACTORS environment variable can be used to set the screen
+        scale factors manually.Set this to a semicolon-separated
+        list of scale factors (matching the order of QGuiApplications::screens()),
+        or to a list of name=value pairs (where name matches QScreen::name()).
+
+    Coordinate conversion functions must be used when writing code that passes
+    geometry across the Qt Gui / Platform plugin boundary. The main conversion
+    functions are:
         T toNativePixels(T, QWindow *)
         T fromNativePixels(T, QWindow*)
-    Where T is QPoint, QSize, QRect etc.
+
+    The following classes in QtGui use native pixels, for the convenience of the
+    plataform plugins:
+        QPlatformWindow
+        QPlatformScreen
+        QWindowSystemInterface (API only - Events are in device independent pixels)
+
+    As a special consideration platform plugin code should be careful about
+    calling QtGui geometry accessor functions:
+        QRect r = window->geometry();
+    Here the returned geometry is in device independent pixels. Add a conversion call:
+        QRect r = QHighDpi::toNativePixels(window->geometry());
+    (Avoiding calling QWindow and instead using the QPlatformWindow geometry
+     might be a better course of action in this case.)
 */
 
 qreal QHighDpiScaling::m_factor = 1.0;