rhi: Improve isClipDepthZeroToOne() doc

Quick 3D is now having a use case for calling this directly, so use this
opportunity for enhancing the docs to make it clear what this is about.

Change-Id: I19ec956ac25175dbfb754192abaad8d65a6eeb0e
Reviewed-by: Eirik Aavitsland <eirik.aavitsland@qt.io>

1 files changed, 24 insertions, 9 deletions

diff --git a/src/gui/rhi/qrhi.cpp b/src/gui/rhi/qrhi.cpp
index 6f21ec7be1..d4fdff2930 100644
--- a/src/gui/rhi/qrhi.cpp
+++ b/src/gui/rhi/qrhi.cpp
@@ -5058,13 +5058,24 @@ bool QRhi::isYUpInNDC() const
 }
 
 /*!
-    \return \c true if the underlying graphics API uses depth 0 - 1 in clip
-    space.
+    \return \c true if the underlying graphics API uses depth range [0, 1] in
+    clip space.
 
-    In practice this is \c false for OpenGL only.
+    In practice this is \c false for OpenGL only, because OpenGL uses a
+    post-projection depth range of [-1, 1]. (not to be confused with the
+    NDC-to-window mapping controlled by glDepthRange(), which uses a range of
+    [0, 1], unless overridden by the QRhiViewport) In some OpenGL versions
+    glClipControl() could be used to change this, but the OpenGL backend of
+    QRhi does not use that function as it is not available in OpenGL ES or
+    OpenGL versions lower than 4.5.
 
     \note clipSpaceCorrMatrix() includes the corresponding adjustment in its
-    returned matrix.
+    returned matrix. Therefore, many users of QRhi do not need to take any
+    further measures apart from pre-multiplying their projection matrices with
+    clipSpaceCorrMatrix(). However, some graphics techniques, such as, some
+    types of shadow mapping, involve working with and outputting depth values
+    in the shaders. These will need to query and take the value of this
+    function into account as appropriate.
  */
 bool QRhi::isClipDepthZeroToOne() const
 {
@@ -5074,11 +5085,15 @@ bool QRhi::isClipDepthZeroToOne() const
 /*!
     \return a matrix that can be used to allow applications keep using
     OpenGL-targeted vertex data and perspective projection matrices (such as,
-    the ones generated by QMatrix4x4::perspective()), regardless of the
-    backend. Once \c{this_matrix * mvp} is used instead of just \c mvp, vertex
-    data with Y up and viewports with depth range 0 - 1 can be used without
-    considering what backend and so graphics API is going to be used at run
-    time.
+    the ones generated by QMatrix4x4::perspective()), regardless of the active
+    QRhi backend.
+
+    In a typical renderer, once \c{this_matrix * mvp} is used instead of just
+    \c mvp, vertex data with Y up and viewports with depth range 0 - 1 can be
+    used without considering what backend (and so graphics API) is going to be
+    used at run time. This way branching based on isYUpInNDC() and
+    isClipDepthZeroToOne() can be avoided (although such logic may still become
+    required when implementing certain advanced graphics techniques).
 
     See
     \l{https://matthewwellings.com/blog/the-new-vulkan-coordinate-system/}{this