Clarify some rhi related QQuickWindow docs

The "and graphics API other than OpenGL" note is clearly wrong.
All that applies to the RHI in general, regardless of the backend.
Also highlight more why connecting to beforeRendering() is problematic
on the RHI path.

Task-number: QTBUG-79221
Change-Id: I4875ff197f53ecb76c796b35f2ddf28bed1dc12c
Reviewed-by: Paul Olav Tvete <paul.tvete@qt.io>

1 files changed, 23 insertions, 22 deletions

diff --git a/src/quick/items/qquickwindow.cpp b/src/quick/items/qquickwindow.cpp
index 0bbc400d08..8fb023cf61 100644
--- a/src/quick/items/qquickwindow.cpp
+++ b/src/quick/items/qquickwindow.cpp
@@ -4209,16 +4209,18 @@ QQmlIncubationController *QQuickWindow::incubationController() const
     The OpenGL context used for rendering the scene graph will be bound
     at this point.
 
-    When using the RHI and a graphics API other than OpenGL, the signal is
-    emitted after the preparations for the frame have been done, meaning there
-    is a command buffer in recording mode, where applicable. If desired, the
-    slot function connected to this signal can query native resources like the
-    command before via QSGRendererInterface. Note however that the recording of
-    the main render pass is not yet started at this point and it is not
-    possible to add commands within that pass. Instead, use
-    beforeRenderPassRecording() for that. However, connecting to this signal is
-    still important if the recording of copy type of commands is desired since
-    those cannot be enqueued within a render pass.
+    When using the RHI, the signal is emitted after the preparations for the
+    frame have been done, meaning there is a command buffer in recording mode,
+    where applicable. If desired, the slot function connected to this signal
+    can query native resources like the command before via
+    QSGRendererInterface. Note however that the recording of the main render
+    pass is not yet started at this point and it is not possible to add
+    commands within that pass. Starting a pass means clearing the color, depth,
+    and stencil buffers so it is not possible to achieve an underlay type of
+    rendering by just connecting to this signal. Rather, connect to
+    beforeRenderPassRecording(). However, connecting to this signal is still
+    important if the recording of copy type of commands is desired since those
+    cannot be enqueued within a render pass.
 
     \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
@@ -4241,18 +4243,17 @@ QQmlIncubationController *QQuickWindow::incubationController() const
 
     The OpenGL context used for rendering the scene graph will be bound at this point.
 
-    When using the RHI and a graphics API other than OpenGL, the signal is
-    emitted after scene graph has added its commands to the command buffer,
-    which is not yet submitted to the graphics queue. If desired, the slot
-    function connected to this signal can query native resources, like the
-    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. 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.
+    When using the RHI, the signal is emitted after scene graph has added its
+    commands to the command buffer, which is not yet submitted to the graphics
+    queue. If desired, the slot function connected to this signal can query
+    native resources, like the 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. 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