1 files changed, 28 insertions, 5 deletions
diff --git a/src/gui/rhi/qrhi.cpp b/src/gui/rhi/qrhi.cpp
index 7a0d53e1e4..c805e23ad0 100644
--- a/src/gui/rhi/qrhi.cpp
+++ b/src/gui/rhi/qrhi.cpp
@@ -2048,11 +2048,9 @@ QRhiResource::Type QRhiBuffer::resourceType() const
     UniformBuffer may not even be backed by a native buffer object at all if
     uniform buffers are not used or supported by a given backend and graphics
     API. There are also differences to how data is written to the buffer and
-    the type of backing memory used, and, if host visible memory is involved,
-    when memory writes become available and visible. Therefore, in general it
-    is recommended to limit native buffer object access to vertex and index
-    buffers with types Static or Immutable, because these operate in a
-    relatively uniform manner with all backends.
+    the type of backing memory used. For buffers backed by host visible memory,
+    calling this function guarantees that pending host writes are executed for
+    all the returned native buffers.
 
     \sa QRhi::currentFrameSlot(), QRhi::FramesInFlight
  */
@@ -2342,6 +2340,31 @@ bool QRhiTexture::buildFrom(QRhiTexture::NativeTexture src)
 }
 
 /*!
+    With some graphics APIs, such as Vulkan, integrating custom rendering code
+    that uses the graphics API directly needs special care when it comes to
+    image layouts. This function allows communicating the expected layout the
+    image backing the QRhiTexture is in after the native rendering commands.
+
+    For example, consider rendering into a QRhiTexture's VkImage directly with
+    Vulkan in a code block enclosed by QRhiCommandBuffer::beginExternal() and
+    QRhiCommandBuffer::endExternal(), followed by using the image for texture
+    sampling in a QRhi-based render pass. To avoid potentially incorrect image
+    layout transitions, this function can be used to indicate what the image
+    layout will be once the commands recorded in said code block complete.
+
+    Calling this function makes sense only after
+    QRhiCommandBuffer::endExternal() and before a subsequent
+    QRhiCommandBuffer::beginPass().
+
+    This function has no effect with QRhi backends where the underlying
+    graphics API does not expose a concept of image layouts.
+ */
+void QRhiTexture::setNativeLayout(int layout)
+{
+    Q_UNUSED(layout);
+}
+
+/*!
     \class QRhiSampler
     \internal
     \inmodule QtGui