rhi: Enhance internal docs about buffer and image load/store

Comparing the backends revealed that one cannot expect that
exposing a storage buffer or a texture to a shader with
bufferLoad, imageLoad, bufferStore, imageStore, etc. will
always be functional in any graphics and compute pipeline
stage. In fact the only place where this is universally
supported are compute shaders.

In other shaders some backends will not expose the resources
at all, e.g. because in D3D11 unordered access views (for a
buffer or image used with load/store) have limitations on the
API level, whereas others may have runtime limits, e.g. with
OpenGL ES an implementation may just say
GL_MAX_VERTEX_SHADER_STORAGE_BLOCKS is 0 meaning no SSBOs in
vertex shaders. (apparently the case on some embedded GPUs,
presumably due to the tiled architecture, e.g. on Mali)

So for now add a note to all the relevant
QRhiShaderResourceBinding functions.

It should be possible to make it work with fragment shaders
to a degree at least, but for D3D we then have to deal with
OMSetRenderTargetsAndUnorderedAccessViews and some remapping
of binding points, whereas elsewhere they may be issues with
missing or incorrect barriers. So do not go there now.

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

1 files changed, 63 insertions, 0 deletions

diff --git a/src/gui/rhi/qrhi.cpp b/src/gui/rhi/qrhi.cpp
index 3cc6a8da83..e822568c4f 100644
--- a/src/gui/rhi/qrhi.cpp
+++ b/src/gui/rhi/qrhi.cpp
@@ -3654,6 +3654,13 @@ QRhiShaderResourceBinding QRhiShaderResourceBinding::sampler(int binding, StageF
    pipelines. Such a pipeline must then always be used together with another,
    layout compatible QRhiShaderResourceBindings with resources present passed
    to QRhiCommandBuffer::setShaderResources().
+
+   \note Image load/store is only guaranteed to be available within a compute
+   pipeline. While some backends may support using these resources in a
+   graphics pipeline as well, this is not universally supported, and even when
+   it is, unexpected problems may arise when it comes to barriers and
+   synchronization. Therefore, avoid using such resources with shaders other
+   than compute.
  */
 QRhiShaderResourceBinding QRhiShaderResourceBinding::imageLoad(
         int binding, StageFlags stage, QRhiTexture *tex, int level)
@@ -3682,6 +3689,13 @@ QRhiShaderResourceBinding QRhiShaderResourceBinding::imageLoad(
    pipelines. Such a pipeline must then always be used together with another,
    layout compatible QRhiShaderResourceBindings with resources present passed
    to QRhiCommandBuffer::setShaderResources().
+
+   \note Image load/store is only guaranteed to be available within a compute
+   pipeline. While some backends may support using these resources in a
+   graphics pipeline as well, this is not universally supported, and even when
+   it is, unexpected problems may arise when it comes to barriers and
+   synchronization. Therefore, avoid using such resources with shaders other
+   than compute.
  */
 QRhiShaderResourceBinding QRhiShaderResourceBinding::imageStore(
         int binding, StageFlags stage, QRhiTexture *tex, int level)
@@ -3710,6 +3724,13 @@ QRhiShaderResourceBinding QRhiShaderResourceBinding::imageStore(
    pipelines. Such a pipeline must then always be used together with another,
    layout compatible QRhiShaderResourceBindings with resources present passed
    to QRhiCommandBuffer::setShaderResources().
+
+   \note Image load/store is only guaranteed to be available within a compute
+   pipeline. While some backends may support using these resources in a
+   graphics pipeline as well, this is not universally supported, and even when
+   it is, unexpected problems may arise when it comes to barriers and
+   synchronization. Therefore, avoid using such resources with shaders other
+   than compute.
  */
 QRhiShaderResourceBinding QRhiShaderResourceBinding::imageLoadStore(
         int binding, StageFlags stage, QRhiTexture *tex, int level)
@@ -3736,6 +3757,13 @@ QRhiShaderResourceBinding QRhiShaderResourceBinding::imageLoadStore(
     suitable for creating pipelines. Such a pipeline must then always be used
     together with another, layout compatible QRhiShaderResourceBindings with
     resources present passed to QRhiCommandBuffer::setShaderResources().
+
+    \note Buffer load/store is only guaranteed to be available within a compute
+    pipeline. While some backends may support using these resources in a
+    graphics pipeline as well, this is not universally supported, and even when
+    it is, unexpected problems may arise when it comes to barriers and
+    synchronization. Therefore, avoid using such resources with shaders other
+    than compute.
  */
 QRhiShaderResourceBinding QRhiShaderResourceBinding::bufferLoad(
         int binding, StageFlags stage, QRhiBuffer *buf)
@@ -3764,6 +3792,13 @@ QRhiShaderResourceBinding QRhiShaderResourceBinding::bufferLoad(
     suitable for creating pipelines. Such a pipeline must then always be used
     together with another, layout compatible QRhiShaderResourceBindings with
     resources present passed to QRhiCommandBuffer::setShaderResources().
+
+    \note Buffer load/store is only guaranteed to be available within a compute
+    pipeline. While some backends may support using these resources in a
+    graphics pipeline as well, this is not universally supported, and even when
+    it is, unexpected problems may arise when it comes to barriers and
+    synchronization. Therefore, avoid using such resources with shaders other
+    than compute.
  */
 QRhiShaderResourceBinding QRhiShaderResourceBinding::bufferLoad(
         int binding, StageFlags stage, QRhiBuffer *buf, quint32 offset, quint32 size)
@@ -3792,6 +3827,13 @@ QRhiShaderResourceBinding QRhiShaderResourceBinding::bufferLoad(
     suitable for creating pipelines. Such a pipeline must then always be used
     together with another, layout compatible QRhiShaderResourceBindings with
     resources present passed to QRhiCommandBuffer::setShaderResources().
+
+    \note Buffer load/store is only guaranteed to be available within a compute
+    pipeline. While some backends may support using these resources in a
+    graphics pipeline as well, this is not universally supported, and even when
+    it is, unexpected problems may arise when it comes to barriers and
+    synchronization. Therefore, avoid using such resources with shaders other
+    than compute.
  */
 QRhiShaderResourceBinding QRhiShaderResourceBinding::bufferStore(
         int binding, StageFlags stage, QRhiBuffer *buf)
@@ -3820,6 +3862,13 @@ QRhiShaderResourceBinding QRhiShaderResourceBinding::bufferStore(
     suitable for creating pipelines. Such a pipeline must then always be used
     together with another, layout compatible QRhiShaderResourceBindings with
     resources present passed to QRhiCommandBuffer::setShaderResources().
+
+    \note Buffer load/store is only guaranteed to be available within a compute
+    pipeline. While some backends may support using these resources in a
+    graphics pipeline as well, this is not universally supported, and even when
+    it is, unexpected problems may arise when it comes to barriers and
+    synchronization. Therefore, avoid using such resources with shaders other
+    than compute.
  */
 QRhiShaderResourceBinding QRhiShaderResourceBinding::bufferStore(
         int binding, StageFlags stage, QRhiBuffer *buf, quint32 offset, quint32 size)
@@ -3848,6 +3897,13 @@ QRhiShaderResourceBinding QRhiShaderResourceBinding::bufferStore(
     suitable for creating pipelines. Such a pipeline must then always be used
     together with another, layout compatible QRhiShaderResourceBindings with
     resources present passed to QRhiCommandBuffer::setShaderResources().
+
+    \note Buffer load/store is only guaranteed to be available within a compute
+    pipeline. While some backends may support using these resources in a
+    graphics pipeline as well, this is not universally supported, and even when
+    it is, unexpected problems may arise when it comes to barriers and
+    synchronization. Therefore, avoid using such resources with shaders other
+    than compute.
  */
 QRhiShaderResourceBinding QRhiShaderResourceBinding::bufferLoadStore(
         int binding, StageFlags stage, QRhiBuffer *buf)
@@ -3876,6 +3932,13 @@ QRhiShaderResourceBinding QRhiShaderResourceBinding::bufferLoadStore(
     suitable for creating pipelines. Such a pipeline must then always be used
     together with another, layout compatible QRhiShaderResourceBindings with
     resources present passed to QRhiCommandBuffer::setShaderResources().
+
+    \note Buffer load/store is only guaranteed to be available within a compute
+    pipeline. While some backends may support using these resources in a
+    graphics pipeline as well, this is not universally supported, and even when
+    it is, unexpected problems may arise when it comes to barriers and
+    synchronization. Therefore, avoid using such resources with shaders other
+    than compute.
  */
 QRhiShaderResourceBinding QRhiShaderResourceBinding::bufferLoadStore(
         int binding, StageFlags stage, QRhiBuffer *buf, quint32 offset, quint32 size)