Expand QPaintedTextureImage documentation

Also make use of the newly documented pattern in the manual test.

Change-Id: Idefe271eea345848af3817e08ac5b45946843dad
Reviewed-by: Paul Lemire <paul.lemire@kdab.com>
(cherry picked from commit 3d2d67b571b0f6ed3df1c0d3eeed1e89097bef57)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

2 files changed, 17 insertions, 2 deletions

diff --git a/src/render/texture/qpaintedtextureimage.cpp b/src/render/texture/qpaintedtextureimage.cpp
index 6e220f340..86df2c562 100644
--- a/src/render/texture/qpaintedtextureimage.cpp
+++ b/src/render/texture/qpaintedtextureimage.cpp
@@ -199,8 +199,12 @@ void QPaintedTextureImage::setSize(QSize size)
 }
 
 /*!
-   Schedules the painted texture's paint() function to be called,
-   which in turn uploads the new image to the GPU.
+   Immediately triggers the painted texture's paint() function,
+   which in turn uploads the new image to the GPU. If you are
+   making multiple changes to a painted texture, consider waiting
+   until all changes are complete before calling update, in order
+   to minimize the number of repaints required.
+
    Parameter \a rect is currently unused.
 */
 void QPaintedTextureImage::update(const QRect &rect)
@@ -215,6 +219,15 @@ void QPaintedTextureImage::update(const QRect &rect)
     \fn Qt3DRender::QPaintedTextureImage::paint(QPainter *painter)
 
     Paints the texture image with the specified QPainter object \a painter.
+
+    QPainter considers the top-left corner of an image as its origin, while OpenGL considers
+    the bottom-left corner of a texture as its origin. An easy way to account for this difference
+    is to set a custom viewport on the painter before doing any other painting:
+
+    \code
+    painter->setViewport(0, height(), width(), -height());
+    ...
+    \endcode
 */
 QTextureImageDataGeneratorPtr QPaintedTextureImage::dataGenerator() const
 {
diff --git a/tests/manual/paintedtexture-cpp/scene.cpp b/tests/manual/paintedtexture-cpp/scene.cpp
index 19bcdbd22..568558358 100644
--- a/tests/manual/paintedtexture-cpp/scene.cpp
+++ b/tests/manual/paintedtexture-cpp/scene.cpp
@@ -75,6 +75,8 @@ protected:
         int w = painter->device()->width();
         int h = painter->device()->height();
 
+        painter->setViewport(0, h, w, -h);
+
         // clear to white
         painter->fillRect(0, 0, w, h, QColor(255, 255, 255));