diff options
authorLaszlo Agocs <>2021-01-13 16:45:47 +0100
committerQt Cherry-pick Bot <>2021-01-15 19:28:56 +0000
commitf90b77e1010e59b63c787042b998e48d5269c3e7 (patch)
parent85fd5b70d6af42e5db14a17a21f56770b3f448b7 (diff)
Document QOpenGLWidget limitations without an alpha channel
Task-number: QTBUG-85869 Change-Id: I20fb70a451fc1ed93089ed699539fa12ac38fe73 Reviewed-by: Andy Nichols <> (cherry picked from commit b5ce973b29875d8cea6302de8ccfaa06d0b7c870) Reviewed-by: Qt Cherry-pick Bot <>
1 files changed, 13 insertions, 0 deletions
diff --git a/src/openglwidgets/qopenglwidget.cpp b/src/openglwidgets/qopenglwidget.cpp
index a596416471..2ae1a7f215 100644
--- a/src/openglwidgets/qopenglwidget.cpp
+++ b/src/openglwidgets/qopenglwidget.cpp
@@ -401,6 +401,19 @@ QT_BEGIN_NAMESPACE
each frame. To restore the preserved behavior, call setUpdateBehavior() with
\c PartialUpdate.
+ \note Displaying a QOpenGLWidget requires an alpha channel in the associated
+ top-level window's backing store due to the way composition with other
+ QWidget-based content works. If there is no alpha channel, the content
+ rendered by the QOpenGLWidget will not be visible. This can become
+ particularly relevant on Linux/X11 in remote display setups (such as, with
+ Xvnc), when using a color depth lower than 24. For example, a color depth of
+ 16 will typically map to using a backing store image with the format
+ QImage::Format_RGB16 (RGB565), leaving no room for an alpha
+ channel. Therefore, if experiencing problems with getting the contents of a
+ QOpenGLWidget composited correctly with other the widgets in the window, make
+ sure the server (such as, vncserver) is configured with a 24 or 32 bit depth
+ instead of 16.
\section1 Alternatives
Adding a QOpenGLWidget into a window turns on OpenGL-based