QRhiResource Class

Base class for classes encapsulating native resource objects. More...

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

QRhiBuffer, QRhiCommandBuffer, QRhiComputePipeline, QRhiGraphicsPipeline, QRhiRenderBuffer, QRhiRenderPassDescriptor, QRhiRenderTarget, QRhiSampler, QRhiShaderResourceBindings, QRhiSwapChain, and QRhiTexture

Public Types

enum Type { Buffer, Texture, Sampler, RenderBuffer, RenderPassDescriptor, …, CommandBuffer }

Public Functions

virtual ~QRhiResource()
void deleteLater()
virtual void destroy() = 0
quint64 globalResourceId() const
QByteArray name() const
virtual QRhiResource::Type resourceType() const = 0
QRhi *rhi() const
void setName(const QByteArray &name)

Detailed Description

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

Member Type Documentation

enum QRhiResource::Type

Specifies type of the resource.


Member Function Documentation

[virtual noexcept] QRhiResource::~QRhiResource()


Releases (or requests deferred releasing of) the underlying native graphics resources, if there are any.

Note: Resources referenced by commands for the current frame should not be released until the frame is submitted by QRhi::endFrame().

See also destroy().

void QRhiResource::deleteLater()

When called without a frame being recorded, this function is equivalent to deleting the object. Between a QRhi::beginFrame() and QRhi::endFrame() however the behavior is different: the QRhiResource will not be destroyed until the frame is submitted via QRhi::endFrame(), thus satisfying the QRhi requirement of not altering QRhiResource objects that are referenced by the frame being recorded.

If the QRhi that created this object is already destroyed, the object is deleted immediately.

Using deleteLater() can be a useful convenience in many cases, and it complements the low-level guarantee (that the underlying native graphics objects are never destroyed until it is safe to do so and it is known for sure that they are not used by the GPU in an still in-flight frame), by offering a way to make sure the C++ object instances (of QRhiBuffer, QRhiTexture, etc.) themselves also stay valid until the end of the current frame.

The following example shows a convenient way of creating a throwaway buffer that is only used in one frame and gets automatically released in endFrame(). (when it comes to the underlying native buffer(s), the usual guarantee applies: the QRhi backend defers the releasing of those until it is guaranteed that the frame in which the buffer is accessed by the GPU has completed)

QRhiBuffer *buf = rhi->newBuffer(QRhiBuffer::Immutable, QRhiBuffer::VertexBuffer, 256);
buf->deleteLater(); // !
u = rhi->nextResourceUpdateBatch();
u->uploadStaticBuffer(buf, data);
// ... draw with buf

See also destroy().

[pure virtual] void QRhiResource::destroy()

Releases (or requests deferred releasing of) the underlying native graphics resources. Safe to call multiple times, subsequent invocations will be a no-op then.

Once destroy() is called, the QRhiResource instance can be reused, by calling create() again. That will then result in creating new native graphics resources underneath.

Note: Resources referenced by commands for the current frame should not be released until the frame is submitted by QRhi::endFrame().

The QRhiResource destructor also performs the same task, so calling this function is not necessary before deleting a QRhiResource.

See also deleteLater().

quint64 QRhiResource::globalResourceId() const

Returns the global, unique identifier of this QRhiResource.

User code rarely needs to deal with the value directly. It is used internally for tracking and bookkeeping purposes.

QByteArray QRhiResource::name() const

Returns the currently set object name. By default the name is empty.

See also setName().

[pure virtual] QRhiResource::Type QRhiResource::resourceType() const

Returns the type of the resource.

QRhi *QRhiResource::rhi() const

Returns the QRhi that created this resource.

If the QRhi that created this object is already destroyed, the result is nullptr.

void QRhiResource::setName(const QByteArray &name)

Sets a name for the object.

This allows getting descriptive names for the native graphics resources visible in graphics debugging tools, such as RenderDoc and XCode.

When it comes to naming native objects by relaying the name via the appropriate graphics API, note that the name is ignored when QRhi::DebugMarkers are not supported, and may, depending on the backend, also be ignored when QRhi::EnableDebugMarkers is not set.

Note: The name may be ignored for objects other than buffers, renderbuffers, and textures, depending on the backend.

Note: The name may be modified. For slotted resources, such as a QRhiBuffer backed by multiple native buffers, QRhi will append a suffix to make the underlying native buffers easily distinguishable from each other.

See also name().

© 2023 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.