Improve QOpenGLWidget docs regarding fb preservation

QOpenGLWindow already has some notes regarding this. It must be
mentioned in QOpenGLWidget too.

Change-Id: I0af90c9410a1c44cb9dd9ce58aa0371a58c57f65
Reviewed-by: Paul Olav Tvete <paul.tvete@digia.com>

1 files changed, 17 insertions, 1 deletions

diff --git a/src/widgets/kernel/qopenglwidget.cpp b/src/widgets/kernel/qopenglwidget.cpp
index d8f31bfcc8..757cac8cea 100644
--- a/src/widgets/kernel/qopenglwidget.cpp
+++ b/src/widgets/kernel/qopenglwidget.cpp
@@ -228,6 +228,22 @@ QT_BEGIN_NAMESPACE
   regarding stacking orders for example. QOpenGLWidget avoids this by not
   creating a separate native window.
 
+  Due to being backed by a framebuffer object, the behavior of QOpenGLWidget is
+  very similar to QOpenGLWindow with the update behavior set to \c
+  PartialUpdateBlit or \c PartialUpdateBlend. This means that the contents are
+  preserved between paintGL() calls so that incremental rendering is
+  possible. With QGLWidget (and naturally QOpenGLWindow with the default update
+  behavior) this is usually not the case because swapping the buffers leaves the
+  back buffer with undefined contents.
+
+  \note Most applications do not need incremental rendering because they will
+  render everything in the view on every paint call. In this case it is
+  important to call glClear() as early as possible in paintGL(). This helps
+  mobile GPUs that use a tile-based architecture to recognize that the tile
+  buffer does not need to be reloaded with the framebuffer's previous
+  contents. Omitting the clear call can lead to significant performance drops on
+  such systems.
+
   \section1 Multisampling
 
   To enable multisampling, set the number of requested samples on the
@@ -372,7 +388,7 @@ QT_BEGIN_NAMESPACE
   \e{OpenGL is a trademark of Silicon Graphics, Inc. in the United States and other
   countries.}
 
-  \sa QOpenGLFunctions
+  \sa QOpenGLFunctions, QOpenGLWindow
 */
 
 /*!