rhi: Auto-rebuild rt by tracking attachment id and generation

Unlike the shader resource binding lists that automatically recognize
in setShaderResources() when a referenced QRhiResource has been rebuilt
in the meantime (create() was called i.e. there may be completely
different native objects underneath), QRhiTextureRenderTarget has no
such thing. This leads to an asymmetric API and requires also rebuilding
the rt whenever an attachment is rebuilt:

rt = rhi->newTextureRenderTarget({ { texture } })
rt->create()
cb->beginPass(rt, ...)
texture->setPixelSize(...)
texture->create()
rt->create() // this should not be needed
cb->beginPass(rt, ...)

Avoid having to do that second rt->create().

Change-Id: If14eaa7aac3530950498bbdf834324d0741a7c4d
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Andy Nichols <andy.nichols@qt.io>

1 files changed, 35 insertions, 1 deletions

diff --git a/src/gui/rhi/qrhi.cpp b/src/gui/rhi/qrhi.cpp
index 952183f55e..70525689e9 100644
--- a/src/gui/rhi/qrhi.cpp
+++ b/src/gui/rhi/qrhi.cpp
@@ -330,9 +330,22 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general")
         ubuf->setSize(512);
         ubuf->create(); // same as ubuf->destroy(); ubuf->create();
 
-        // that's it, srb needs no changes whatsoever
+        // That's it, srb needs no changes whatsoever, any references in it to
+        // ubuf stay valid. When it comes to internal details, such as that
+        // ubuf may now be backed by a completely different native buffer
+        // resource, that is is recognized and handled automatically by the
+        // next setShaderResources().
     \endcode
 
+    QRhiTextureRenderTarget offers the same contract: calling
+    QRhiCommandBuffer::beginPass() is safe even when one of the render target's
+    associated textures or renderbuffers has been rebuilt (by calling \c
+    create() on it) since the creation of the render target object. This allows
+    the application to resize a texture by setting a new pixel size on the
+    QRhiTexture and calling create(), thus creating a whole new native texture
+    resource underneath, without having to update the QRhiTextureRenderTarget
+    as that will be done implicitly in beginPass().
+
     \section3 Pooled objects
 
     In addition to resources, there are pooled objects as well, such as,
@@ -5669,6 +5682,25 @@ void QRhiCommandBuffer::resourceUpdate(QRhiResourceUpdateBatch *resourceUpdates)
     called inside a pass. Also, with the exception of setGraphicsPipeline(),
     they expect to have a pipeline set already on the command buffer.
     Unspecified issues may arise otherwise, depending on the backend.
+
+    If \a rt is a QRhiTextureRenderTarget, beginPass() performs a check to see
+    if the texture and renderbuffer objects referenced from the render target
+    are up-to-date. This is similar to what setShaderResources() does for
+    QRhiShaderResourceBindings. If any of the attachments had been rebuilt
+    since QRhiTextureRenderTarget::create(), an implicit call to create() is
+    made on \a rt. Therefore, if \a rt has a QRhiTexture color attachment \c
+    texture, and one needs to make the texture a different size, the following
+    is then valid:
+    \badcode
+      rt = rhi->newTextureRenderTarget({ { texture } });
+      rt->create();
+      ...
+      texture->setPixelSize(new_size);
+      texture->create();
+      cb->beginPass(rt, ...); // this is ok, no explicit rt->create() is required before
+    \endcode
+
+    \sa endPass()
  */
 void QRhiCommandBuffer::beginPass(QRhiRenderTarget *rt,
                                   const QColor &colorClearValue,
@@ -5684,6 +5716,8 @@ void QRhiCommandBuffer::beginPass(QRhiRenderTarget *rt,
 
     \a resourceUpdates, when not null, specifies a resource update batch that
     is to be committed and then released.
+
+    \sa beginPass()
  */
 void QRhiCommandBuffer::endPass(QRhiResourceUpdateBatch *resourceUpdates)
 {