Document the render loops a bit more

Task-number: QTBUG-42699
Change-Id: Ib8a1690bfe38bd0686799fac390207c26e5a6812
Reviewed-by: Topi Reiniö <topi.reinio@digia.com>
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@theqtcompany.com>

1 files changed, 29 insertions, 6 deletions

diff --git a/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc b/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc
index ec6e0e93d5..8ef77dac4c 100644
--- a/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc
+++ b/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc
@@ -173,8 +173,26 @@ defined by the render loop.
 For detailed description of how the scene graph renderer works, see
 \l {Qt Quick Scene Graph Renderer}.
 
-
-\section2 Threaded Render Loop
+There are three render loop variants available: \c basic, \c windows,
+and \c threaded. Out of these, \c basic and \c windows are
+single-threaded, while \c threaded performs scene graph rendering on a
+dedicated thread. Qt attempts to choose a suitable loop based on the
+platform and possibly the graphics drivers in use. When this is not
+satisfactory, or for testing purposes, the environment variable
+\c QSG_RENDER_LOOP can be used to force the usage of a given loop. To
+verify which render loop is in use, launch the application with
+\c QSG_INFO set to \c 1.
+
+\note The \c threaded and \c windows render loops rely on the OpenGL
+implementation for throttling by requesting a swap interval of 1. Some
+graphics drivers allow users to override this setting and turn it off,
+ignoring Qt's request. Without blocking in the swap buffers operation
+(or elsewhere), the render loop will run animations too fast and spin
+the CPU at 100%. If a system is known to be unable to provide
+vsync-based throttling, use the \c basic render loop instead by
+setting \c {QSG_RENDER_LOOP=basic} in the environment.
+
+\section2 Threaded Render Loop ("threaded")
 
 On many configurations, the scene graph rendering will happen on a
 dedicated render thread. This is done to increase parallelism of
@@ -245,11 +263,12 @@ animations, process events, etc.
 \endlist
 
 The threaded renderer is currently used by default on Windows with
-opengl32.dll, Linux with non-Mesa based drivers, OS X and EGLFS but
-this is subject to change. It is possible to force use of the threaded
-renderer by setting \c {QSG_RENDER_LOOP=threaded} in the environment.
+opengl32.dll, Linux with non-Mesa based drivers, OS X, mobile
+platforms, and Embedded Linux with EGLFS but this is subject to
+change. It is possible to force use of the threaded renderer by
+setting \c {QSG_RENDER_LOOP=threaded} in the environment.
 
-\section2 Non-threaded Render Loop
+\section2 Non-threaded Render Loops ("basic" and "windows")
 
 The non-threaded render loop is currently used by default on Windows
 with ANGLE or a non-default opengl32 implementation and Linux with
@@ -259,6 +278,10 @@ been tested. At the same time implementations like ANGLE or Mesa
 llvmpipe are not able to function properly with threaded rendering at
 all so not using threaded rendering is essential for these.
 
+By default \c windows is used for non-threaded rendering on Windows
+with ANGLE, while \c basic is used for all other platforms when
+non-threaded rendering is needed.
+
 Even when using the non-threaded render loop, you should write your
 code as if you are using the threaded renderer, as failing to do so
 will make the code non-portable.