Add QOpenGLWindow/Widget doc note about depth/stencil

Fixes: QTBUG-108050
Change-Id: If011d6efff996870ff23eff3c2d1cf455d31b7a6
Reviewed-by: Kristoffer Skau <kristoffer.skau@qt.io>
Reviewed-by: Andy Nichols <andy.nichols@qt.io>
(cherry picked from commit 27ab0f012a1099267888ed0e8ab9700efffec0f4)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

2 files changed, 24 insertions, 0 deletions

diff --git a/src/opengl/qopenglwindow.cpp b/src/opengl/qopenglwindow.cpp
index cdd8221e22..e06bd75d28 100644
--- a/src/opengl/qopenglwindow.cpp
+++ b/src/opengl/qopenglwindow.cpp
@@ -96,6 +96,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.
 
diff --git a/src/openglwidgets/qopenglwidget.cpp b/src/openglwidgets/qopenglwidget.cpp
index c7c3ac3979..cd84c8d041 100644
--- a/src/openglwidgets/qopenglwidget.cpp
+++ b/src/openglwidgets/qopenglwidget.cpp
@@ -211,6 +211,13 @@ QT_BEGIN_NAMESPACE
 
   \snippet code/doc_gui_widgets_qopenglwidget.cpp 2
 
+  \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.
+
   With OpenGL 3.0+ contexts, when portability is not important, the versioned
   QOpenGLFunctions variants give easy access to all the modern OpenGL functions
   available in a given version: