QRhiShaderResourceBindings Class

Encapsulates resources for making buffer, texture, sampler resources visible to shaders. More...

Header: #include <QRhiShaderResourceBindings>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui
Since: Qt 6.6
Inherits: QRhiResource

Public Types

flags UpdateFlags

Public Functions

const QRhiShaderResourceBinding *bindingAt(qsizetype index) const
qsizetype bindingCount() const
const QRhiShaderResourceBinding *cbeginBindings() const
const QRhiShaderResourceBinding *cendBindings() const
bool isLayoutCompatible(const QRhiShaderResourceBindings *other) const
QVector<quint32> serializedLayoutDescription() const
void setBindings(std::initializer_list<QRhiShaderResourceBinding> list)
void setBindings(InputIterator first, InputIterator last)

Reimplemented Public Functions

virtual QRhiResource::Type resourceType() const override

Detailed Description

A QRhiShaderResourceBindings is a collection of QRhiShaderResourceBinding objects, each of which describe a single binding.

Take a fragment shader with the following interface:

layout(std140, binding = 0) uniform buf {
    mat4 mvp;
    int flip;
} ubuf;

layout(binding = 1) uniform sampler2D tex;

To make resources visible to the shader, the following QRhiShaderResourceBindings could be created and then passed to QRhiGraphicsPipeline::setShaderResourceBindings():

QRhiShaderResourceBindings *srb = rhi->newShaderResourceBindings();
srb->setBindings({
    QRhiShaderResourceBinding::uniformBuffer(0, QRhiShaderResourceBinding::VertexStage | QRhiShaderResourceBinding::FragmentStage, ubuf),
    QRhiShaderResourceBinding::sampledTexture(1, QRhiShaderResourceBinding::FragmentStage, texture, sampler)
});
srb->create();
// ...
QRhiGraphicsPipeline *ps = rhi->newGraphicsPipeline();
// ...
ps->setShaderResourceBindings(srb);
ps->create();
// ...
cb->setGraphicsPipeline(ps);
cb->setShaderResources(); // binds srb

This assumes that ubuf is a QRhiBuffer, texture is a QRhiTexture, while sampler is a QRhiSampler. The example also assumes that the uniform block is present in the vertex shader as well so the same buffer is made visible to the vertex stage too.

Advanced usage

Building on the above example, let's assume that a pass now needs to use the exact same pipeline and shaders with a different texture. Creating a whole separate QRhiGraphicsPipeline just for this would be an overkill. This is why QRhiCommandBuffer::setShaderResources() allows specifying a srb argument. As long as the layouts (so the number of bindings and the binding points) match between two QRhiShaderResourceBindings, they can both be used with the same pipeline, assuming the pipeline was created with one of them in the first place. See isLayoutCompatible() for more details.

QRhiShaderResourceBindings *srb2 = rhi->newShaderResourceBindings();
// ...
cb->setGraphicsPipeline(ps);
cb->setShaderResources(srb2); // binds srb2

Note: This is a RHI API with limited compatibility guarantees, see QRhi for details.

Member Function Documentation

const QRhiShaderResourceBinding *QRhiShaderResourceBindings::bindingAt(qsizetype index) const

Returns the binding at the specified index.

qsizetype QRhiShaderResourceBindings::bindingCount() const

Returns the number of bindings.

const QRhiShaderResourceBinding *QRhiShaderResourceBindings::cbeginBindings() const

Returns a const iterator pointing to the first item in the binding list.

const QRhiShaderResourceBinding *QRhiShaderResourceBindings::cendBindings() const

Returns a const iterator pointing just after the last item in the binding list.

bool QRhiShaderResourceBindings::isLayoutCompatible(const QRhiShaderResourceBindings *other) const

Returns true if the layout is compatible with other. The layout does not include the actual resource (such as, buffer or texture) and related parameters (such as, offset or size). It does include the binding point, pipeline stage, and resource type, however. The number and order of the bindings must also match in order to be compatible.

When there is a QRhiGraphicsPipeline created with this QRhiShaderResourceBindings, and the function returns true, other can then safely be passed to QRhiCommandBuffer::setShaderResources(), and so be used with the pipeline in place of this QRhiShaderResourceBindings.

Note: This function must only be called after a successful create(), because it relies on data generated during the baking of the underlying data structures. This way the function can implement a comparison approach that 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.

See also serializedLayoutDescription().

[override virtual] QRhiResource::Type QRhiShaderResourceBindings::resourceType() const

Reimplements: QRhiResource::resourceType() const.

Returns the resource type.

QVector<quint32> QRhiShaderResourceBindings::serializedLayoutDescription() const

Returns a vector of integers containing an opaque blob describing the layout of the binding list, i.e. the data relevant for layout compatibility tests.

Given two objects srb1 and srb2, if the data returned from this function is identical, then 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.

See also isLayoutCompatible().

void QRhiShaderResourceBindings::setBindings(std::initializer_list<QRhiShaderResourceBinding> list)

Sets the list of bindings.

template <typename InputIterator> void QRhiShaderResourceBindings::setBindings(InputIterator first, InputIterator last)

Sets the list of bindings from the iterators first and last.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.