Do not create depth/stencil buffer when the env var says so

Both for the swapchain and more importantly, layers. The latter was
never implemented, not in Qt 5 with OpenGL either, and it becomes a
problem for resource-limited use cases because QSG_NO_DEPTH_BUFFER still
creates depth/stencil attachments for layers even though the 2D
rendering has no use for those then.

Clarify the QQuickGraphicsConfiguration docs as well. The story is
fairly convoluted, because the useDepthFor2D flag one can set from C++
is not 100% the same as the env.var. (and it really should not be)
The flag is about relying on depth testing in 2D (and so enabling the
potentially more efficient opaque batches), but it does not prevent adding
a View3D or other stuff that requires a depth buffer. The env.var on
the other hand does both: it (depending on the platform) disables
depth (and often stencil) buffers, thus using fewer resources, and also
triggers the depth-less 2D rendering path (alpha batches only). But that
is not always compatible with 3D then (like an offscren View3D will work,
other modes may not)

Change-Id: I5ac1ce154fe78a3ec8bd1a698c1c0b944ce8077e
Reviewed-by: Andy Nichols <andy.nichols@qt.io>

1 files changed, 11 insertions, 0 deletions

diff --git a/src/quick/items/qquickgraphicsconfiguration.cpp b/src/quick/items/qquickgraphicsconfiguration.cpp
index ba03e4f401..f9fb4c682c 100644
--- a/src/quick/items/qquickgraphicsconfiguration.cpp
+++ b/src/quick/items/qquickgraphicsconfiguration.cpp
@@ -172,6 +172,17 @@ void QQuickGraphicsConfiguration::setDeviceExtensions(const QByteArrayList &exte
     can cause unexpected results, because the way the scene graph renderer
     handles depth values is not necessarily compatible with how a 3D scene
     works. In that case, \a enable can be set to false.
+
+    \note This flag is not fully identical to setting the
+    \c{QSG_NO_DEPTH_BUFFER} environment variable. This flag does not control the
+    depth-stencil buffers' presence. It is rather relevant for the rendering
+    pipeline. To force not having depth/stencil attachments at all, set
+    \c{QSG_NO_DEPTH_BUFFER} and \c{QSG_NO_STENCIL_BUFFER}. Be aware however
+    that such a QQuickWindow, and any Item layers in it, may then become
+    incompatible with items, such as View3D with certain operating modes,
+    because 3D content requires a depth buffer. Calling this function is always
+    safe, but can mean that resources, such as depth buffers, are created even
+    though they are not actively used.
  */
 void QQuickGraphicsConfiguration::setDepthBufferFor2D(bool enable)
 {