PySide6.QtGui.QRhiShaderResourceBinding

class QRhiShaderResourceBinding

Describes the shader resource for a single binding point.

Details

A QRhiShaderResourceBinding cannot be constructed directly. Instead, use the static functions such as uniformBuffer() or sampledTexture() to get an instance.

Note

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

Added in version 6.6.

Synopsis

Methods

Static functions

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

class Type

Specifies type of the shader resource bound to a binding point

Constant

Description

QRhiShaderResourceBinding.Type.UniformBuffer

Uniform buffer

QRhiShaderResourceBinding.Type.SampledTexture

Combined image sampler (a texture and sampler pair). Even when the shading language associated with the underlying 3D API has no support for this concept (e.g. D3D and HLSL), this is still supported because the shader translation layer takes care of the appropriate translation and remapping of binding points or shader registers.

QRhiShaderResourceBinding.Type.Texture

Texture (separate)

QRhiShaderResourceBinding.Type.Sampler

Sampler (separate)

QRhiShaderResourceBinding.Type.ImageLoad

Image load (with GLSL this maps to doing imageLoad() on a single level - and either one or all layers - of a texture exposed to the shader as an image object)

QRhiShaderResourceBinding.Type.ImageStore

Image store (with GLSL this maps to doing imageStore() or imageAtomic*() on a single level - and either one or all layers - of a texture exposed to the shader as an image object)

QRhiShaderResourceBinding.Type.ImageLoadStore

Image load and store

QRhiShaderResourceBinding.Type.BufferLoad

Storage buffer load (with GLSL this maps to reading from a shader storage buffer)

QRhiShaderResourceBinding.Type.BufferStore

Storage buffer store (with GLSL this maps to writing to a shader storage buffer)

QRhiShaderResourceBinding.Type.BufferLoadStore

Storage buffer load and store
class StageFlag

(inherits enum.Flag) Flag values to indicate which stages the shader resource is visible in

Constant

Description

QRhiShaderResourceBinding.StageFlag.VertexStage

Vertex stage

QRhiShaderResourceBinding.StageFlag.TessellationControlStage

Tessellation control (hull shader) stage

QRhiShaderResourceBinding.StageFlag.TessellationEvaluationStage

Tessellation evaluation (domain shader) stage

QRhiShaderResourceBinding.StageFlag.FragmentStage

Fragment (pixel shader) stage

QRhiShaderResourceBinding.StageFlag.ComputeStage

Compute stage

QRhiShaderResourceBinding.StageFlag.GeometryStage

Geometry stage
PySide6.QtGui.QRhiShaderResourceBinding.LAYOUT_DESC_ENTRIES_PER_BINDING
__init__()
static bufferLoad(binding, stage, buf)
Parameters:
Return type:

QRhiShaderResourceBinding

Returns a shader resource binding for a read-only storage buffer with the given binding number and pipeline stage.

Note

When buf is not null, must have been created with StorageBuffer .

Note

buf can be null. It is valid to create a QRhiShaderResourceBindings with unspecified resources, but such an object cannot be used with setShaderResources() . It is however suitable for creating pipelines. Such a pipeline must then always be used together with another, layout compatible QRhiShaderResourceBindings with resources present passed to 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.

static bufferLoad(binding, stage, buf, offset, size)
Parameters:

  • binding – int

  • stage – Combination of StageFlag

  • buf – QRhiBuffer

  • offset – int

  • size – int

Return type:

QRhiShaderResourceBinding

Returns a shader resource binding for a read-only storage buffer with the given binding number and pipeline stage. This overload binds a region only, as specified by offset and size.

Note

When buf is not null, must have been created with StorageBuffer .

Note

buf can be null. It is valid to create a QRhiShaderResourceBindings with unspecified resources, but such an object cannot be used with setShaderResources() . It is however suitable for creating pipelines. Such a pipeline must then always be used together with another, layout compatible QRhiShaderResourceBindings with resources present passed to 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.

static bufferLoadStore(binding, stage, buf)
Parameters:
Return type:

QRhiShaderResourceBinding

Returns a shader resource binding for a read-write storage buffer with the given binding number and pipeline stage.

Note

When buf is not null, must have been created with StorageBuffer .

Note

buf can be null. It is valid to create a QRhiShaderResourceBindings with unspecified resources, but such an object cannot be used with setShaderResources() . It is however suitable for creating pipelines. Such a pipeline must then always be used together with another, layout compatible QRhiShaderResourceBindings with resources present passed to 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.

static bufferLoadStore(binding, stage, buf, offset, size)
Parameters:

  • binding – int

  • stage – Combination of StageFlag

  • buf – QRhiBuffer

  • offset – int

  • size – int

Return type:

QRhiShaderResourceBinding

Returns a shader resource binding for a read-write storage buffer with the given binding number and pipeline stage. This overload binds a region only, as specified by offset and size.

Note

When buf is not null, must have been created with StorageBuffer .

Note

buf can be null. It is valid to create a QRhiShaderResourceBindings with unspecified resources, but such an object cannot be used with setShaderResources() . It is however suitable for creating pipelines. Such a pipeline must then always be used together with another, layout compatible QRhiShaderResourceBindings with resources present passed to 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.

static bufferStore(binding, stage, buf)
Parameters:
Return type:

QRhiShaderResourceBinding

Returns a shader resource binding for a write-only storage buffer with the given binding number and pipeline stage.

Note

When buf is not null, must have been created with StorageBuffer .

Note

buf can be null. It is valid to create a QRhiShaderResourceBindings with unspecified resources, but such an object cannot be used with setShaderResources() . It is however suitable for creating pipelines. Such a pipeline must then always be used together with another, layout compatible QRhiShaderResourceBindings with resources present passed to 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.

static bufferStore(binding, stage, buf, offset, size)
Parameters:

  • binding – int

  • stage – Combination of StageFlag

  • buf – QRhiBuffer

  • offset – int

  • size – int

Return type:

QRhiShaderResourceBinding

Returns a shader resource binding for a write-only storage buffer with the given binding number and pipeline stage. This overload binds a region only, as specified by offset and size.

Note

When buf is not null, must have been created with StorageBuffer .

Note

buf can be null. It is valid to create a QRhiShaderResourceBindings with unspecified resources, but such an object cannot be used with setShaderResources() . It is however suitable for creating pipelines. Such a pipeline must then always be used together with another, layout compatible QRhiShaderResourceBindings with resources present passed to 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.

static imageLoad(binding, stage, tex, level)
Parameters:
Return type:

QRhiShaderResourceBinding

Returns a shader resource binding for a read-only storage image with the given binding number and pipeline stage. The image load operations will have access to all layers of the specified level. (so if the texture is a cubemap, the shader must use imageCube instead of image2D)

Note

When tex is not null, it must have been created with UsedWithLoadStore .

Note

tex can be null. It is valid to create a QRhiShaderResourceBindings with unspecified resources, but such an object cannot be used with setShaderResources() . It is however suitable for creating pipelines. Such a pipeline must then always be used together with another, layout compatible QRhiShaderResourceBindings with resources present passed to setShaderResources() .

Note

Image load/store is only available within the compute and fragment stages.

static imageLoadStore(binding, stage, tex, level)
Parameters:
Return type:

QRhiShaderResourceBinding

Returns a shader resource binding for a read/write storage image with the given binding number and pipeline stage. The image load/store operations will have access to all layers of the specified level. (so if the texture is a cubemap, the shader must use imageCube instead of image2D)

Note

When tex is not null, it must have been created with UsedWithLoadStore .

Note

tex can be null. It is valid to create a QRhiShaderResourceBindings with unspecified resources, but such an object cannot be used with setShaderResources() . It is however suitable for creating pipelines. Such a pipeline must then always be used together with another, layout compatible QRhiShaderResourceBindings with resources present passed to setShaderResources() .

Note

Image load/store is only available within the compute and fragment stages.

static imageStore(binding, stage, tex, level)
Parameters:
Return type:

QRhiShaderResourceBinding

Returns a shader resource binding for a write-only storage image with the given binding number and pipeline stage. The image store operations will have access to all layers of the specified level. (so if the texture is a cubemap, the shader must use imageCube instead of image2D)

Note

When tex is not null, it must have been created with UsedWithLoadStore .

Note

tex can be null. It is valid to create a QRhiShaderResourceBindings with unspecified resources, but such an object cannot be used with setShaderResources() . It is however suitable for creating pipelines. Such a pipeline must then always be used together with another, layout compatible QRhiShaderResourceBindings with resources present passed to setShaderResources() .

Note

Image load/store is only available within the compute and fragment stages.

isLayoutCompatible(other)
Parameters:

other – QRhiShaderResourceBinding

Return type:

bool

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).

For example, a and b below are not equal, but are compatible layout-wise:

auto a = QRhiShaderResourceBinding::uniformBuffer(0, QRhiShaderResourceBinding::VertexStage, buffer);
auto b = QRhiShaderResourceBinding::uniformBuffer(0, QRhiShaderResourceBinding::VertexStage, someOtherBuffer, 256);
__ne__(b)
Parameters:

b – QRhiShaderResourceBinding

Return type:

bool

__eq__(b)
Parameters:

b – QRhiShaderResourceBinding

Return type:

bool

static sampledTexture(binding, stage, tex, sampler)
Parameters:
Return type:

QRhiShaderResourceBinding

Returns a shader resource binding for the given binding number, pipeline stages, texture, and sampler specified by binding, stage, tex, sampler.

Note

This function is equivalent to calling sampledTextures() with a count of 1.

Note

tex and sampler can be null. It is valid to create a QRhiShaderResourceBindings with unspecified resources, but such an object cannot be used with setShaderResources() . It is however suitable for creating pipelines. Such a pipeline must then always be used together with another, layout compatible QRhiShaderResourceBindings with resources present passed to setShaderResources() .

Note

A shader may not be able to consume more than 16 textures/samplers, depending on the underlying graphics API. This hard limit must be kept in mind in renderer design. This does not apply to texture arrays which consume a single binding point (shader register) and can contain 256-2048 textures, depending on the underlying graphics API. Arrays of textures (see sampledTextures() ) are however no different in this regard than using the same number of individual textures.

See also

sampledTextures()

static sampledTextures(binding, stage, count, texSamplers)
Parameters:
Return type:

QRhiShaderResourceBinding

Returns a shader resource binding for the given binding number, pipeline stages, and the array of texture-sampler pairs specified by binding, stage, count, and texSamplers.

Note

count must be at least 1, and not larger than 16.

Note

When count is 1, this function is equivalent to sampledTexture() .

This function is relevant when arrays of combined image samplers are involved. For example, in GLSL layout(binding = 5) uniform sampler2D shadowMaps[8]; declares an array of combined image samplers. The application is then expected provide a QRhiShaderResourceBinding for binding point 5, set up by calling this function with count set to 8 and a valid texture and sampler for each element of the array.

Warning

All elements of the array must be specified. With the above example, the only valid, portable approach is calling this function with a count of 8. Additionally, all QRhiTexture and QRhiSampler instances must be valid, meaning nullptr is not an accepted value. This is due to some of the underlying APIs, such as, Vulkan, that require a valid image and sampler object for each element in descriptor arrays. Applications are advised to provide “dummy” samplers and textures if some array elements are not relevant (due to not being accessed in the shader).

Note

texSamplers can be null. It is valid to create a QRhiShaderResourceBindings with unspecified resources, but such an object cannot be used with setShaderResources() . It is however suitable for creating pipelines. Such a pipeline must then always be used together with another, layout compatible QRhiShaderResourceBindings with resources present passed to setShaderResources() .

See also

sampledTexture()

static sampler(binding, stage, sampler)
Parameters:
Return type:

QRhiShaderResourceBinding

Returns a shader resource binding for the given binding number, pipeline stages, and sampler specified by binding, stage, sampler.

Note

sampler can be null. It is valid to create a QRhiShaderResourceBindings with unspecified resources, but such an object cannot be used with setShaderResources() . It is however suitable for creating pipelines. Such a pipeline must then always be used together with another, layout compatible QRhiShaderResourceBindings with resources present passed to setShaderResources() .

Arrays of separate samplers are not supported.

This creates a binding for a separate sampler object, whereas sampledTexture() is suitable for combined image samplers. In Vulkan-compatible GLSL code separate samplers are declared as sampler as opposed to sampler2D: layout(binding = 2) uniform sampler samp;

With both a texture2D and sampler present, they can be used together to sample the texture: fragColor = texture(sampler2D(tex, samp), texcoord);.

Note

A shader may not be able to consume more than 16 samplers, depending on the underlying graphics API. This hard limit must be kept in mind in renderer design.

See also

texture()

static texture(binding, stage, tex)
Parameters:
Return type:

QRhiShaderResourceBinding

Returns a shader resource binding for the given binding number, pipeline stages, and texture specified by binding, stage, tex.

Note

This function is equivalent to calling textures() with a count of 1.

Note

tex can be null. It is valid to create a QRhiShaderResourceBindings with unspecified resources, but such an object cannot be used with setShaderResources() . It is however suitable for creating pipelines. Such a pipeline must then always be used together with another, layout compatible QRhiShaderResourceBindings with resources present passed to setShaderResources() .

This creates a binding for a separate texture (image) object, whereas sampledTexture() is suitable for combined image samplers. In Vulkan-compatible GLSL code separate textures are declared as texture2D as opposed to sampler2D: layout(binding = 1) uniform texture2D tex;

Note

A shader may not be able to consume more than 16 textures, depending on the underlying graphics API. This hard limit must be kept in mind in renderer design. This does not apply to texture arrays which consume a single binding point (shader register) and can contain 256-2048 textures, depending on the underlying graphics API. Arrays of textures (see sampledTextures() ) are however no different in this regard than using the same number of individual textures.

See also

textures() sampler()

static textures(binding, stage, count, tex)
Parameters:
Return type:

QRhiShaderResourceBinding

Returns a shader resource binding for the given binding number, pipeline stages, and the array of (separate) textures specified by binding, stage, count, and tex.

Note

count must be at least 1, and not larger than 16.

Note

When count is 1, this function is equivalent to texture() .

Warning

All elements of the array must be specified.

Note

tex can be null. It is valid to create a QRhiShaderResourceBindings with unspecified resources, but such an object cannot be used with setShaderResources() . It is however suitable for creating pipelines. Such a pipeline must then always be used together with another, layout compatible QRhiShaderResourceBindings with resources present passed to setShaderResources() .

See also

texture() sampler()

static uniformBuffer(binding, stage, buf)
Parameters:
Return type:

QRhiShaderResourceBinding

Returns a shader resource binding for the given binding number, pipeline stages, and buffer specified by binding, stage, and buf.

Note

When buf is not null, it must have been created with UniformBuffer .

Note

buf can be null. It is valid to create a QRhiShaderResourceBindings with unspecified resources, but such an object cannot be used with setShaderResources() . It is however suitable for creating pipelines. Such a pipeline must then always be used together with another, layout compatible QRhiShaderResourceBindings with resources present passed to setShaderResources() .

Note

If the size of buf exceeds the limit reported for MaxUniformBufferRange , unexpected errors may occur.

static uniformBuffer(binding, stage, buf, offset, size)
Parameters:

  • binding – int

  • stage – Combination of StageFlag

  • buf – QRhiBuffer

  • offset – int

  • size – int

Return type:

QRhiShaderResourceBinding

Returns a shader resource binding for the given binding number, pipeline stages, and buffer specified by binding, stage, and buf. This overload binds a region only, as specified by offset and size.

Note

It is up to the user to ensure the offset is aligned to ubufAlignment() .

Note

size must be greater than 0.

Note

When buf is not null, it must have been created with UniformBuffer .

Note

buf can be null. It is valid to create a QRhiShaderResourceBindings with unspecified resources, but such an object cannot be used with setShaderResources() . It is however suitable for creating pipelines. Such a pipeline must then always be used together with another, layout compatible QRhiShaderResourceBindings with resources present passed to setShaderResources() .

Note

If size exceeds the limit reported for MaxUniformBufferRange , unexpected errors may occur.

static uniformBufferWithDynamicOffset(binding, stage, buf, size)
Parameters:
Return type:

QRhiShaderResourceBinding

Returns a shader resource binding for the given binding number, pipeline stages, and buffer specified by binding, stage, and buf. The uniform buffer is assumed to have dynamic offset. The dynamic offset can be specified in setShaderResources() , thus allowing using varying offset values without creating new bindings for the buffer. The size of the bound region is specified by size. Like with non-dynamic offsets, offset + size cannot exceed the size of buf.

Note

When buf is not null, it must have been created with UniformBuffer .

Note

buf can be null. It is valid to create a QRhiShaderResourceBindings with unspecified resources, but such an object cannot be used with setShaderResources() . It is however suitable for creating pipelines. Such a pipeline must then always be used together with another, layout compatible QRhiShaderResourceBindings with resources present passed to setShaderResources() .

Note

If size exceeds the limit reported for MaxUniformBufferRange , unexpected errors may occur.

class Data

Synopsis

Methods

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

PySide6.QtGui.QRhiShaderResourceBinding.Data.binding
PySide6.QtGui.QRhiShaderResourceBinding.Data.stage
PySide6.QtGui.QRhiShaderResourceBinding.Data.type
PySide6.QtGui.QRhiShaderResourceBinding.Data.MAX_TEX_SAMPLER_ARRAY_SIZE
arraySize()
Return type:

int

class StorageImageData

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

PySide6.QtGui.QRhiShaderResourceBinding.Data.StorageImageData.tex
PySide6.QtGui.QRhiShaderResourceBinding.Data.StorageImageData.level
class StorageBufferData

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

PySide6.QtGui.QRhiShaderResourceBinding.Data.StorageBufferData.buf
PySide6.QtGui.QRhiShaderResourceBinding.Data.StorageBufferData.offset
PySide6.QtGui.QRhiShaderResourceBinding.Data.StorageBufferData.maybeSize
class TextureAndSampler

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

PySide6.QtGui.QRhiShaderResourceBinding.TextureAndSampler.tex
PySide6.QtGui.QRhiShaderResourceBinding.TextureAndSampler.sampler