QRhiResource Class

Member Function Documentation

[virtual noexcept] QRhiResource::~QRhiResource()

Destructor.

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

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)

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

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.

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.

See also name().