Clarify docs and comments regarding under and overlays

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

3 files changed, 17 insertions, 3 deletions

diff --git a/examples/quick/scenegraph/metalunderqml/metalsquircle.mm b/examples/quick/scenegraph/metalunderqml/metalsquircle.mm
index 92aceeb433..8a1a03dc68 100644
--- a/examples/quick/scenegraph/metalunderqml/metalsquircle.mm
+++ b/examples/quick/scenegraph/metalunderqml/metalsquircle.mm
@@ -186,7 +186,12 @@ void MetalSquircle::sync()
 {
     if (!m_renderer) {
         m_renderer = new SquircleRenderer;
+        // Initializing resources is done before starting to encode render
+        // commands, regardless of wanting an underlay or overlay.
         connect(window(), &QQuickWindow::beforeRendering, m_renderer, &SquircleRenderer::frameStart, Qt::DirectConnection);
+        // Here we want an underlay and therefore connect to
+        // beforeRenderPassRecording. Changing to afterRenderPassRecording
+        // would render the squircle on top (overlay).
         connect(window(), &QQuickWindow::beforeRenderPassRecording, m_renderer, &SquircleRenderer::mainPassRecordingStart, Qt::DirectConnection);
     }
     m_renderer->setViewportSize(window()->size() * window()->devicePixelRatio());
diff --git a/examples/quick/scenegraph/vulkanunderqml/vulkansquircle.cpp b/examples/quick/scenegraph/vulkanunderqml/vulkansquircle.cpp
index 3f2067a803..59e9606e7b 100644
--- a/examples/quick/scenegraph/vulkanunderqml/vulkansquircle.cpp
+++ b/examples/quick/scenegraph/vulkanunderqml/vulkansquircle.cpp
@@ -186,7 +186,12 @@ void VulkanSquircle::sync()
 {
     if (!m_renderer) {
         m_renderer = new SquircleRenderer;
+        // Initializing resources is done before starting to record the
+        // renderpass, regardless of wanting an underlay or overlay.
         connect(window(), &QQuickWindow::beforeRendering, m_renderer, &SquircleRenderer::frameStart, Qt::DirectConnection);
+        // Here we want an underlay and therefore connect to
+        // beforeRenderPassRecording. Changing to afterRenderPassRecording
+        // would render the squircle on top (overlay).
         connect(window(), &QQuickWindow::beforeRenderPassRecording, m_renderer, &SquircleRenderer::mainPassRecordingStart, Qt::DirectConnection);
     }
     m_renderer->setViewportSize(window()->size() * window()->devicePixelRatio());
diff --git a/src/quick/items/qquickwindow.cpp b/src/quick/items/qquickwindow.cpp
index 4e65c60b85..6fe2891242 100644
--- a/src/quick/items/qquickwindow.cpp
+++ b/src/quick/items/qquickwindow.cpp
@@ -4193,7 +4193,11 @@ QQmlIncubationController *QQuickWindow::incubationController() const
     command buffer, before via QSGRendererInterface. Note however that the
     render pass (or passes) are already recorded at this point and it is not
     possible to add more commands within the scenegraph's pass. Instead, use
-    afterRenderPassRecording() for that.
+    afterRenderPassRecording() for that. This signal has therefore limited use
+    and is rarely needed in an RHI-based setup. Rather, it is the combination
+    of beforeRendering() + beforeRenderPassRecording() or beforeRendering() +
+    afterRenderPassRecording() that is typically used to achieve under- or
+    overlaying of the custom rendering.
 
     \warning This signal is emitted from the scene graph rendering thread. If your
     slot function needs to finish before execution continues, you must make sure that
@@ -4229,7 +4233,7 @@ QQmlIncubationController *QQuickWindow::incubationController() const
 
     \note Resource updates (uploads, copies) typically cannot be enqueued from
     within a render pass. Therefore, more complex user rendering will need to
-    connect to both the beforeRendering() and this signals.
+    connect to both beforeRendering() and this signal.
 
     \warning This signal is emitted from the scene graph rendering thread. If your
     slot function needs to finish before execution continues, you must make sure that
@@ -4260,7 +4264,7 @@ QQmlIncubationController *QQuickWindow::incubationController() const
 
     \note Resource updates (uploads, copies) typically cannot be enqueued from
     within a render pass. Therefore, more complex user rendering will need to
-    connect to both the beforeRendering() and this signals.
+    connect to both beforeRendering() and this signal.
 
     \warning This signal is emitted from the scene graph rendering thread. If your
     slot function needs to finish before execution continues, you must make sure that