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>

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.
 

src/openglwidgets/qopenglwidget.cpp

@@ -178,6 +178,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: