From 75ad13d2bc414058024bbf8b0886b3d7dd498059 Mon Sep 17 00:00:00 2001 From: Laszlo Agocs Date: Tue, 28 Jan 2020 16:08:34 +0100 Subject: [PATCH] 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 --- src/gui/rhi/qrhi.cpp | 33 ++++++++++++++++++++++++--------- 1 file 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