rhi: d3d11/vulkan: Allow passing in an array range override

Only (straightforwardly) implementable with modern APIs, and
only really exists to handle special platform cases, such as
when a video framework gives us a D3D texture array with
D3D11_BIND_DECODER | D3D11_BIND_SHADER_RESOURCE
which is only possible to use as a shader resource if the SRV
selects a single array layer.

Has no effect on the normal usage of texture arrays, where all
array layers are exposed, and it is the shader that selects the
layer when sampling or loading via the sampler2DArray. That
continues to be the standard way to work with texture arrays.

Change-Id: I0a656b605da21f50239b38abb83067e0208c1dbe
Reviewed-by: Piotr Srebrny <piotr.srebrny@qt.io>
Reviewed-by: Christian Strømme <christian.stromme@qt.io>

1 files changed, 22 insertions, 0 deletions

diff --git a/src/gui/rhi/qrhi.cpp b/src/gui/rhi/qrhi.cpp
index 70b99abbb6..adf7b781ff 100644
--- a/src/gui/rhi/qrhi.cpp
+++ b/src/gui/rhi/qrhi.cpp
@@ -722,6 +722,28 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general")
     implementation reports it as supported at run time. Geometry shaders have
     portability issues between APIs, and therefore no guarantees can be given
     for a universal solution for now.
+
+    \value TextureArrayRange Indicates that for
+    \l{QRhi::newTextureArray()}{texture arrays} it is possible to specify a
+    range that is exposed to the shaders. Normally all array layers are exposed
+    and it is up to the shader to select the layer (via the third coordinate
+    passed to texture() when sampling the \c sampler2DArray). When supported,
+    calling QRhiTexture::setArrayRangeStart() and
+    QRhiTexture::setArrayRangeLength() before
+    \l{QRhiTexture::create()}{building} or
+    \l{QRhiTexture::createFrom()}{importing} the native texture has an effect,
+    and leads to selecting only the specified range from the array. This will
+    be necessary in special cases, such as when working with accelerated video
+    decoding and Direct 3D 11, because a texture array with both
+    \c{D3D11_BIND_DECODER} and \c{D3D11_BIND_SHADER_RESOURCE} on it is only
+    usable as a shader resource if a single array layer is selected. Note that
+    all this is applicable only when the texture is used as a
+    QRhiShaderResourceBinding::SampledTexture or
+    QRhiShaderResourceBinding::Texture shader resource, and is not compatible
+    with image load/store. This feature is only available with some backends as
+    it does not map well to all graphics APIs, and it is only meant to provide
+    support for special cases anyhow. In practice the feature can be expected to
+    be supported with Direct3D 11 and Vulkan.
  */
 
 /*!