From eda1276f80e39d519c88e7a491ff1d960c7a4dac Mon Sep 17 00:00:00 2001
From: Laszlo Agocs <laszlo.agocs@qt.io>
Date: Wed, 15 Sep 2021 14:33:01 +0200
Subject: [PATCH] rhi: document serializedLayoutDescription
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The docs are internal still but won't hurt to keep them up-to-date.
At the same time, enhance the QRhiRenderPassDescriptor
serializedFormat() docs as well, with appropriate notes about the
intended usage of the "serialized" data.

Pick-to: 6.2
Change-Id: I8425fff625903468621e3b09d089b345fada85f4
Reviewed-by: Christian Strømme <christian.stromme@qt.io>
---
 src/gui/rhi/qrhi.cpp | 35 +++++++++++++++++++++++++++++++----
 1 file changed, 31 insertions(+), 4 deletions(-)

diff --git a/src/gui/rhi/qrhi.cpp b/src/gui/rhi/qrhi.cpp
index 072d100c59d..f13da926b82 100644
--- a/src/gui/rhi/qrhi.cpp
+++ b/src/gui/rhi/qrhi.cpp
@@ -2778,10 +2778,16 @@ QRhiResource::Type QRhiRenderPassDescriptor::resourceType() const
     \fn QVector<quint32> QRhiRenderPassDescriptor::serializedFormat() const
 
     \return a vector of integers containing an opaque blob describing the data
-    relevant for \l{isCompatible()}{compatibility}. Given two
-    QRhiRenderPassDescriptor objects \c rp1 and \c rp2, if the data returned
-    from this function is identical, then \c{rp1->isCompatible(rp2)}, and vice
-    versa hold true as well.
+    relevant for \l{isCompatible()}{compatibility}.
+
+    Given two QRhiRenderPassDescriptor objects \c rp1 and \c rp2, if the data
+    returned from this function is identical, then \c{rp1->isCompatible(rp2)},
+    and vice versa hold true as well.
+
+    \note The returned data is meant to be used for storing in memory and
+    comparisons during the lifetime of the QRhi the object belongs to. It is not
+    meant for storing on disk, reusing between processes, or using with multiple
+    QRhi instances with potentially different backends.
 
     \sa isCompatible()
  */
@@ -3054,6 +3060,8 @@ QRhiResource::Type QRhiShaderResourceBindings::resourceType() const
     is more efficient than iterating through two binding lists and calling
     QRhiShaderResourceBinding::isLayoutCompatible() on each pair. This becomes
     relevant especially when this function is called at a high frequency.
+
+    \sa serializedLayoutDescription()
  */
 bool QRhiShaderResourceBindings::isLayoutCompatible(const QRhiShaderResourceBindings *other) const
 {
@@ -3072,6 +3080,25 @@ bool QRhiShaderResourceBindings::isLayoutCompatible(const QRhiShaderResourceBind
             && m_layoutDesc == other->m_layoutDesc;
 }
 
+/*!
+    \fn QVector<quint32> QRhiShaderResourceBindings::serializedLayoutDescription() const
+
+    \return a vector of integers containing an opaque blob describing the layout
+    of the binding list, i.e. the data relevant for
+    \l{isLayoutCompatible()}{layout compatibility tests}.
+
+    Given two objects \c srb1 and \c srb2, if the data returned from this
+    function is identical, then \c{srb1->isLayoutCompatible(srb2), and vice
+    versa hold true as well.
+
+    \note The returned data is meant to be used for storing in memory and
+    comparisons during the lifetime of the QRhi the object belongs to. It is not
+    meant for storing on disk, reusing between processes, or using with multiple
+    QRhi instances with potentially different backends.
+
+    \sa isLayoutCompatible()
+ */
+
 void QRhiImplementation::updateLayoutDesc(QRhiShaderResourceBindings *srb)
 {
     srb->m_layoutDescHash = 0;