PySide6.QtGui.QRhiTextureRenderTargetDescription¶

class QRhiTextureRenderTargetDescription¶

Describes the color and depth or depth/stencil attachments of a render target.

Details

A texture render target has zero or more textures as color attachments, zero or one renderbuffer as combined depth/stencil buffer or zero or one texture as depth buffer.

Note

depthStencilBuffer() and depthTexture() cannot be both set (cannot be non-null at the same time).

Let’s look at some example usages in combination with QRhiTextureRenderTarget .

Due to the constructors, the targeting a texture (and no depth/stencil buffer) is simple:

QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(256, 256), 1, QRhiTexture::RenderTarget);
texture->create();
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ texture }));

The following creates a texture render target that is set up to target mip level #2 of a texture:

QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(512, 512), 1, QRhiTexture::RenderTarget | QRhiTexture::MipMapped);
texture->create();
QRhiColorAttachment colorAtt(texture);
colorAtt.setLevel(2);
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ colorAtt });

Another example, this time to render into a depth texture:

QRhiTexture *shadowMap = rhi->newTexture(QRhiTexture::D32F, QSize(1024, 1024), 1, QRhiTexture::RenderTarget);
shadowMap->create();
QRhiTextureRenderTargetDescription rtDesc;
rtDesc.setDepthTexture(shadowMap);
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget(rtDesc);

A very common case, having a texture as the color attachment and a renderbuffer as depth/stencil to enable depth testing:

QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(512, 512), 1, QRhiTexture::RenderTarget);
texture->create();
QRhiRenderBuffer *depthStencil = rhi->newRenderBuffer(QRhiRenderBuffer::DepthStencil, QSize(512, 512));
depthStencil->create();
QRhiTextureRenderTargetDescription rtDesc({ texture }, depthStencil);
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget(rtDesc);

Finally, to enable multisample rendering in a portable manner (so also supporting OpenGL ES 3.0), using a QRhiRenderBuffer as the (multisample) color buffer and then resolving into a regular (non-multisample) 2D texture. To enable depth testing, a depth-stencil buffer, which also must use the same sample count, is used as well:

QRhiRenderBuffer *colorBuffer = rhi->newRenderBuffer(QRhiRenderBuffer::Color, QSize(512, 512), 4); // 4x MSAA
colorBuffer->create();
QRhiRenderBuffer *depthStencil = rhi->newRenderBuffer(QRhiRenderBuffer::DepthStencil, QSize(512, 512), 4);
depthStencil->create();
QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(512, 512), 1, QRhiTexture::RenderTarget);
texture->create();
QRhiColorAttachment colorAtt(colorBuffer);
colorAtt.setResolveTexture(texture);
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ colorAtt, depthStencil });

Note

when multisample resolving is enabled, the multisample data may not be written out at all. This means that the multisample texture in a color attachment must not be used afterwards with shaders for sampling (or other purposes) whenever a resolve texture is set, since the multisample color buffer is merely an intermediate storage then that gets no data written back on some GPU architectures at all. See PreserveColorContents for more details.

Note

When using setDepthTexture() , not setDepthStencilBuffer() , and the depth (stencil) data is not of interest afterwards, set the DoNotStoreDepthStencilContents flag on the QRhiTextureRenderTarget . This allows indicating to the underlying 3D API that the depth/stencil data can be discarded, leading potentially to better performance with tiled GPU architectures. When the depth-stencil buffer is a QRhiRenderBuffer (and also for the multisample color texture, see previous note) this is implicit, but with a depth (stencil) QRhiTexture the intention needs to be declared explicitly. By default QRhi assumes that the data is of interest (e.g., the depth texture is sampled in a shader afterwards).

Note

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

Synopsis¶

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

__init__()¶

Constructs an empty texture render target description.

__init__(colorAttachment)

Parameters:: colorAttachment – QRhiColorAttachment

Constructs a texture render target description with one attachment described by colorAttachment.

__init__(colorAttachment, depthStencilBuffer)

Parameters:

colorAttachment – QRhiColorAttachment
depthStencilBuffer – QRhiRenderBuffer

Constructs a texture render target description with two attachments, a color attachment described by colorAttachment, and a depth/stencil attachment with depthStencilBuffer.

__init__(colorAttachment, depthTexture)

Parameters:

colorAttachment – QRhiColorAttachment
depthTexture – QRhiTexture

Constructs a texture render target description with two attachments, a color attachment described by colorAttachment, and a depth attachment with depthTexture.

Note

depthTexture must have a suitable format, such as D16 or D32F .

cbeginColorAttachments()¶

Return type:: QRhiColorAttachment

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

cendColorAttachments()¶

Return type:: QRhiColorAttachment

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

colorAttachmentAt(index)¶

Parameters:: index – int
Return type:: QRhiColorAttachment

Returns the color attachment at the specified index.

colorAttachmentCount()¶

Return type:: int

Returns the number of currently set color attachments.

depthResolveTexture()¶

Return type:: QRhiTexture

Returns the texture to which a multisample depth (or depth-stencil) texture (or texture array) is resolved to. None if there is none, which is the most common case.

See also

setDepthResolveTexture() resolveTexture() depthTexture()

depthStencilBuffer()¶

Return type:: QRhiRenderBuffer

Returns the renderbuffer used as depth-stencil buffer, or None if none was set.

See also

setDepthStencilBuffer()

depthTexture()¶

Return type:: QRhiTexture

Returns the currently referenced depth texture, or None if none was set.

See also

setDepthTexture()

setColorAttachments(bcolor_attachments)¶

Parameters:: bcolor_attachments – .list of QRhiColorAttachment

setDepthResolveTexture(tex)¶

Parameters:: tex – QRhiTexture

Sets the depth (or depth-stencil) resolve texture tex.

tex is expected to be a 2D texture or a 2D texture array with a format matching the texture set via setDepthTexture() .

Note

Resolving depth (or depth-stencil) data is only functional when the ResolveDepthStencil feature is reported as supported at run time. Support for depth-stencil resolve is not universally available among the graphics APIs. Designs assuming unconditional availability of depth-stencil resolve are therefore non-portable, and should be avoided.

Note

As an additional limitation for OpenGL ES in particular, setting a depth resolve texture may only be functional in combination with setDepthTexture() , not with setDepthStencilBuffer() .