Add QOpenGLWindow/Widget doc note about depth/stencil

Pick-to: 6.5 6.2 5.15
Fixes: QTBUG-108050
Change-Id: If011d6efff996870ff23eff3c2d1cf455d31b7a6
Reviewed-by: Kristoffer Skau <kristoffer.skau@qt.io>
Reviewed-by: Andy Nichols <andy.nichols@qt.io>

1 files changed, 17 insertions, 0 deletions

diff --git a/src/opengl/qopenglwindow.cpp b/src/opengl/qopenglwindow.cpp
index e29c79fdcb..b2a1a35a90 100644
--- a/src/opengl/qopenglwindow.cpp
+++ b/src/opengl/qopenglwindow.cpp
@@ -60,6 +60,23 @@ QT_BEGIN_NAMESPACE
   given OpenGL version and profile, or enabling depth and stencil
   buffers.
 
+  \note It is up to the application to ensure depth and stencil buffers are
+  requested from the underlying windowing system interface. Without requesting
+  a non-zero depth buffer size there is no guarantee that a depth buffer will
+  be available, and as a result depth testing related OpenGL operations may fail
+  to function as expected.
+
+  Commonly used depth and stencil buffer size requests are 24 and 8,
+  respectively. For example, a QOpenGLWindow subclass could do this in its
+  constructor:
+
+  \code
+      QSurfaceFormat format;
+      format.setDepthBufferSize(24);
+      format.setStencilBufferSize(8);
+      setFormat(format);
+  \endcode
+
   Unlike QWindow, QOpenGLWindow allows opening a painter on itself and perform
   QPainter-based drawing.