PySide6.QtGui.QRhiRenderPassDescriptor¶

class QRhiRenderPassDescriptor¶

Render pass resource.

Details

A render pass, if such a concept exists in the underlying graphics API, is a collection of attachments (color, depth, stencil) and describes how those attachments are used.

Note

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

Added in version 6.6.

Synopsis¶

Virtual methods¶

def isCompatible()
def nativeHandles()
def newCompatibleRenderPassDescriptor()
def serializedFormat()

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

abstract isCompatible(other)¶

Parameters:: other – QRhiRenderPassDescriptor
Return type:: bool

Returns true if the other QRhiRenderPassDescriptor is compatible with this one, meaning this and other can be used interchangebly in setRenderPassDescriptor() .

The concept of the compatibility of renderpass descriptors is similar to the layout compatibility of QRhiShaderResourceBindings instances. They allow better reuse of QRhiGraphicsPipeline instances: for example, a QRhiGraphicsPipeline instance cache is expected to use these functions to look for a matching pipeline, instead of just comparing pointers, thus allowing a different QRhiRenderPassDescriptor and QRhiShaderResourceBindings to be used in combination with the pipeline, as long as they are compatible.

The exact details of compatibility depend on the underlying graphics API. Two renderpass descriptors created from the same QRhiTextureRenderTarget are always compatible.

Similarly to QRhiShaderResourceBindings , compatibility can also be tested without having two existing objects available. Extracting the opaque blob by calling serializedFormat() allows testing for compatibility by comparing the returned vector to another QRhiRenderPassDescriptor ‘s serializedFormat() . This has benefits in certain situations, because it allows testing the compatibility of a QRhiRenderPassDescriptor with a QRhiGraphicsPipeline even when the QRhiRenderPassDescriptor the pipeline was originally built was is no longer available (but the data returned from its serializedFormat() still is).

See also

newCompatibleRenderPassDescriptor() serializedFormat()

nativeHandles()¶

Return type:: QRhiNativeHandles

Returns a pointer to a backend-specific QRhiNativeHandles subclass, such as QRhiVulkanRenderPassNativeHandles . The returned value is None when exposing the underlying native resources is not supported by the backend.

See also

QRhiVulkanRenderPassNativeHandles

abstract newCompatibleRenderPassDescriptor()¶

Return type:: QRhiRenderPassDescriptor

Returns a new QRhiRenderPassDescriptor that is compatible with this one.

This function allows cloning a QRhiRenderPassDescriptor . The returned object is ready to be used, and the ownership is transferred to the caller. Cloning a QRhiRenderPassDescriptor object can become useful in situations where the object is stored in data structures related to graphics pipelines (in order to allow creating new pipelines which in turn requires a renderpass descriptor object), and the lifetime of the renderpass descriptor created from a render target may be shorter than the pipelines. (for example, because the engine manages and destroys renderpasses together with the textures and render targets it was created from) In such a situation, it can be beneficial to store a cloned version in the data structures, and thus transferring ownership as well.

See also

isCompatible()

abstract serializedFormat()¶

Return type:: .list of quint32

Returns a vector of integers containing an opaque blob describing the data relevant for compatibility .

Given two QRhiRenderPassDescriptor objects rp1 and rp2, if the data returned from this function is identical, then rp1->isCompatible(rp2), 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.

Note

Calling this function is expected to be a cheap operation since the backends are not supposed to calculate the data in this function, but rather return an already calculated series of data.

When creating reusable components as part of a library, where graphics pipelines are created and maintained while targeting a QRhiRenderTarget (be it a swapchain or a texture) managed by the client of the library, the components must be able to deal with a changing QRhiRenderPassDescriptor . For example, because the render target changes and so invalidates the previously QRhiRenderPassDescriptor (with regards to the new render target at least) due to having a potentially different color format and attachments now. Or because variable rate shading is taken into use dynamically. A simple pattern that helps dealing with this is performing the following check on every frame, to recognize the case when the pipeline needs to be associated with a new QRhiRenderPassDescriptor , because something is different about the render target now, compared to earlier frames:

QRhiRenderPassDescriptor *rp = m_renderTarget->renderPassDescriptor();
if (m_pipeline && rp->serializedFormat() != m_renderPassFormat) {
    m_pipeline->setRenderPassDescriptor(rp);
    m_renderPassFormat = rp->serializedFormat();
    m_pipeline->create();
}
// remember to store m_renderPassFormat also when creating m_pipeline the first time