Update fbo toImage() docs regarding premultiplied alpha

Task-number: QTBUG-42510
Task-number: QTBUG-37261
Change-Id: Ic11bec0a25e66df9d022f640621686be867e84d2
Reviewed-by: Gunnar Sletta <gunnar@sletta.org>

1 files changed, 14 insertions, 0 deletions

diff --git a/src/opengl/qglframebufferobject.cpp b/src/opengl/qglframebufferobject.cpp
index 49b28c36b9..4537f5bfae 100644
--- a/src/opengl/qglframebufferobject.cpp
+++ b/src/opengl/qglframebufferobject.cpp
@@ -1111,6 +1111,20 @@ QGLFramebufferObjectFormat QGLFramebufferObject::format() const
 
     Returns the contents of this framebuffer object as a QImage.
 
+    The returned image has a format of premultiplied ARGB32 or RGB32. The latter is used
+    only when internalTextureFormat() is set to \c GL_RGB.
+
+    If the rendering in the framebuffer was not done with premultiplied alpha in mind,
+    create a wrapper QImage with a non-premultiplied format. This is necessary before
+    performing operations like QImage::save() because otherwise the image data would get
+    unpremultiplied, even though it was not premultiplied in the first place. To create
+    such a wrapper without performing a copy of the pixel data, do the following:
+
+    \code
+    QImage fboImage(fbo.toImage());
+    QImage image(fboImage.constBits(), fboImage.width(), fboImage.height(), QImage::Format_ARGB32);
+    \endcode
+
     On QNX the back buffer is not preserved when a buffer swap occures. So this function
     might return old content.
 */