Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
Loading...
Searching...
No Matches
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
QRhiResource Class Referenceabstract

\inmodule QtGui More...

#include <qrhi.h>

+ Inheritance diagram for QRhiResource:
+ Collaboration diagram for QRhiResource:

Public Types

enum  Type {
  Buffer , Texture , Sampler , RenderBuffer ,
  RenderPassDescriptor , SwapChainRenderTarget , TextureRenderTarget , ShaderResourceBindings ,
  GraphicsPipeline , SwapChain , ComputePipeline , CommandBuffer
}
 Specifies type of the resource. More...
 

Public Member Functions

virtual ~QRhiResource ()
 Destructor.
 
virtual Type resourceType () const =0
 
virtual void destroy ()=0
 Releases (or requests deferred releasing of) the underlying native graphics resources.
 
void deleteLater ()
 When called without a frame being recorded, this function is equivalent to deleting the object.
 
QByteArray name () const
 
void setName (const QByteArray &name)
 Sets a name for the object.
 
quint64 globalResourceId () const
 
QRhi * rhi () const
 

Protected Member Functions

 QRhiResource (QRhiImplementation *rhi)
 

Protected Attributes

QRhiImplementation * m_rhi = nullptr
 
quint64 m_id
 
QByteArray m_objectName
 

Friends

class QRhiImplementation
 

Detailed Description

\inmodule QtGui

Since
6.6

Base class for classes encapsulating native resource objects.

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

Definition at line 803 of file qrhi.h.

Member Enumeration Documentation

◆ Type

enum QRhiResource::Type

Specifies type of the resource.

\value Buffer \value Texture \value Sampler \value RenderBuffer \value RenderPassDescriptor \value SwapChainRenderTarget \value TextureRenderTarget \value ShaderResourceBindings \value GraphicsPipeline \value SwapChain \value ComputePipeline \value CommandBuffer

Enumerator
Buffer 
Texture 
Sampler 
RenderBuffer 
RenderPassDescriptor 
SwapChainRenderTarget 
TextureRenderTarget 
ShaderResourceBindings 
GraphicsPipeline 
SwapChain 
ComputePipeline 
CommandBuffer 

Definition at line 806 of file qrhi.h.

Constructor & Destructor Documentation

◆ ~QRhiResource()

QRhiResource::~QRhiResource ( )
virtual

Destructor.

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

Definition at line 3481 of file qrhi.cpp.

◆ QRhiResource()

QRhiResource::QRhiResource ( QRhiImplementation * rhi)
protected

Definition at line 3464 of file qrhi.cpp.

References m_id, and QRhiGlobalObjectIdGenerator::newId().

+ Here is the call graph for this function:

Member Function Documentation

◆ deleteLater()

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();
QRhiBuffer
\inmodule QtGui
Definition qrhi.h:846
QRhiBuffer::Immutable
@ Immutable
Definition qrhi.h:849
QRhiBuffer::VertexBuffer
@ VertexBuffer
Definition qrhi.h:855
QRhiResourceUpdateBatch::uploadStaticBuffer
void uploadStaticBuffer(QRhiBuffer *buf, quint32 offset, quint32 size, const void *data)
Enqueues updating a region of a QRhiBuffer buf created with the type QRhiBuffer::Immutable or QRhiBuf...
Definition qrhi.cpp:9011
QRhiResource::rhi
QRhi * rhi() const
Definition qrhi.cpp:3603
QRhiResource::deleteLater
void deleteLater()
When called without a frame being recorded, this function is equivalent to deleting the object.
Definition qrhi.cpp:3545
QRhi::newBuffer
QRhiBuffer * newBuffer(QRhiBuffer::Type type, QRhiBuffer::UsageFlags usage, quint32 size)
Definition qrhi.cpp:10508
QRhi::beginFrame
FrameOpResult beginFrame(QRhiSwapChain *swapChain, BeginFrameFlags flags={})
Starts a new frame targeting the next available buffer of swapChain.
Definition qrhi.cpp:10745
QRhi::endFrame
FrameOpResult endFrame(QRhiSwapChain *swapChain, EndFrameFlags flags={})
Ends, commits, and presents a frame that was started in the last beginFrame() on swapChain.
Definition qrhi.cpp:10780
QRhi::nextResourceUpdateBatch
QRhiResourceUpdateBatch * nextResourceUpdateBatch()
Definition qrhi.cpp:9252
data
GLint GLsizei GLsizei GLenum GLenum GLsizei void * data
Definition qopengles2ext.h:206
buf
GLenum GLuint GLenum GLsizei const GLchar * buf
Definition qopengles2ext.h:151
See also
destroy()

Definition at line 3545 of file qrhi.cpp.

References QRhiImplementation::addDeleteLater(), and m_rhi.

Referenced by QRhiWidgetPrivate::ensureTexture(), QSSGReflectionMapEntry::renderMips(), renderToKTXFileInternal(), QRhiWidgetPrivate::resetRenderTargetObjects(), QQuickRhiItemNode::sync(), and QQuick3DItem2D::updateSpatialNode().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ destroy()

void QRhiResource::destroy ( )
pure virtual

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

Implemented in QD3D11Buffer, QD3D11RenderBuffer, QD3D11Texture, QD3D11Sampler, QD3D11RenderPassDescriptor, QD3D11SwapChainRenderTarget, QD3D11TextureRenderTarget, QD3D11ShaderResourceBindings, QD3D11GraphicsPipeline, QD3D11ComputePipeline, QD3D11CommandBuffer, QD3D11SwapChain, QGles2Buffer, QGles2RenderBuffer, QGles2Texture, QGles2Sampler, QGles2RenderPassDescriptor, QGles2SwapChainRenderTarget, QGles2TextureRenderTarget, QGles2ShaderResourceBindings, QGles2GraphicsPipeline, QGles2ComputePipeline, QGles2CommandBuffer, QGles2SwapChain, QMetalBuffer, QMetalRenderBuffer, QMetalTexture, QMetalSampler, QMetalRenderPassDescriptor, QMetalSwapChainRenderTarget, QMetalTextureRenderTarget, QMetalShaderResourceBindings, QMetalGraphicsPipeline, QMetalComputePipeline, QMetalCommandBuffer, QMetalSwapChain, QNullBuffer, QNullRenderBuffer, QNullTexture, QNullSampler, QNullRenderPassDescriptor, QNullSwapChainRenderTarget, QNullTextureRenderTarget, QNullShaderResourceBindings, QNullGraphicsPipeline, QNullComputePipeline, QNullCommandBuffer, QNullSwapChain, QVkBuffer, QVkRenderBuffer, QVkTexture, QVkSampler, QVkRenderPassDescriptor, QVkSwapChainRenderTarget, QVkTextureRenderTarget, QVkShaderResourceBindings, QVkGraphicsPipeline, QVkComputePipeline, QVkCommandBuffer, and QVkSwapChain.

◆ globalResourceId()

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.

Definition at line 3592 of file qrhi.cpp.

References m_id.

◆ name()

QByteArray QRhiResource::name ( ) const
Returns
the currently set object name. By default the name is empty.

Definition at line 3556 of file qrhi.cpp.

References m_objectName.

Referenced by QSSGRhiContextStats::beginRenderPass(), QRhiPassResourceTracker::registerTexture(), and setName().

+ Here is the caller graph for this function:

◆ resourceType()

QRhiResource::Type QRhiResource::resourceType ( ) const
pure virtual
Returns
the type of the resource.

Implemented in QRhiBuffer, QRhiTexture, QRhiSampler, QRhiRenderBuffer, QRhiRenderPassDescriptor, QRhiSwapChainRenderTarget, QRhiTextureRenderTarget, QRhiShaderResourceBindings, QRhiGraphicsPipeline, QRhiSwapChain, QRhiComputePipeline, and QRhiCommandBuffer.

Referenced by QRhiD3D11::beginPass(), QRhiGles2::beginPass(), QRhiMetal::beginPass(), QRhiNull::beginPass(), QRhiVulkan::beginPass(), QRhiD3D11::endPass(), QRhiGles2::endPass(), endTessellationComputeEncoding(), QRhiGles2::enqueueBindFramebuffer(), maybeRenderTargetData(), and rtData().

+ Here is the caller graph for this function:

◆ rhi()

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.

Definition at line 3603 of file qrhi.cpp.

References m_rhi, and QRhiImplementation::q.

Referenced by QSGGuiThreadRenderLoop::ensureRhi(), OpaquePass::prep(), TransparentPass::prep(), RenderHelpers::rhiRenderDepthPass(), RenderHelpers::rhiRenderRenderable(), QSSGCustomMaterialSystem::rhiRenderRenderable(), and RenderHelpers::rhiRenderShadowMap().

+ Here is the caller graph for this function:

◆ setName()

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 \l{https://renderdoc.org/}{RenderDoc} and \l{https://developer.apple.com/xcode/}{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.
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.

Definition at line 3581 of file qrhi.cpp.

References m_objectName, and name().

Referenced by QSSGRenderReflectionMap::addReflectionMapEntry(), QSSGRenderShadowMap::addShadowMapEntry(), QVkRenderBuffer::create(), RenderHelpers::rhiPrepareAoTexture(), RenderHelpers::rhiPrepareDepthTexture(), RenderHelpers::rhiPrepareScreenTexture(), and QQuick3DSceneRenderer::synchronize().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

Friends And Related Symbol Documentation

◆ QRhiImplementation

friend class QRhiImplementation
friend

Definition at line 839 of file qrhi.h.

Member Data Documentation

◆ m_id

quint64 QRhiResource::m_id
protected

Definition at line 841 of file qrhi.h.

Referenced by QRhiResource(), and globalResourceId().

◆ m_objectName

QByteArray QRhiResource::m_objectName
protected

Definition at line 842 of file qrhi.h.

Referenced by QD3D11Buffer::create(), QD3D11RenderBuffer::create(), QD3D11Texture::create(), QGles2Buffer::create(), QGles2RenderBuffer::create(), QGles2Texture::create(), QGles2TextureRenderTarget::create(), QGles2GraphicsPipeline::create(), QMetalBuffer::create(), QMetalRenderBuffer::create(), QMetalTexture::create(), QVkBuffer::create(), QVkRenderBuffer::create(), QVkTexture::create(), name(), and setName().

◆ m_rhi

QRhiImplementation* QRhiResource::m_rhi = nullptr
protected

Definition at line 840 of file qrhi.h.

Referenced by QRhiCommandBuffer::beginComputePass(), QRhiCommandBuffer::beginExternal(), QRhiCommandBuffer::beginPass(), QRhiCommandBuffer::debugMarkBegin(), QRhiCommandBuffer::debugMarkEnd(), QRhiCommandBuffer::debugMarkMsg(), deleteLater(), QRhiCommandBuffer::dispatch(), QRhiCommandBuffer::draw(), QRhiCommandBuffer::drawIndexed(), QSSGRhiContext::dummyTexture(), QRhiCommandBuffer::endComputePass(), QRhiCommandBuffer::endExternal(), QRhiCommandBuffer::endPass(), QRhiCommandBuffer::lastCompletedGpuTime(), QRhiCommandBuffer::nativeHandles(), QD3D11RenderPassDescriptor::newCompatibleRenderPassDescriptor(), QGles2RenderPassDescriptor::newCompatibleRenderPassDescriptor(), QMetalRenderPassDescriptor::newCompatibleRenderPassDescriptor(), QNullRenderPassDescriptor::newCompatibleRenderPassDescriptor(), QVkRenderPassDescriptor::newCompatibleRenderPassDescriptor(), QD3D11TextureRenderTarget::newCompatibleRenderPassDescriptor(), QD3D11SwapChain::newCompatibleRenderPassDescriptor(), QGles2TextureRenderTarget::newCompatibleRenderPassDescriptor(), QGles2SwapChain::newCompatibleRenderPassDescriptor(), QMetalTextureRenderTarget::newCompatibleRenderPassDescriptor(), QMetalSwapChain::newCompatibleRenderPassDescriptor(), QNullTextureRenderTarget::newCompatibleRenderPassDescriptor(), QNullSwapChain::newCompatibleRenderPassDescriptor(), QVkTextureRenderTarget::newCompatibleRenderPassDescriptor(), QVkSwapChain::newCompatibleRenderPassDescriptor(), QRhiCommandBuffer::resourceUpdate(), rhi(), QSSGRhiContext::sampler(), QRhiCommandBuffer::setBlendConstants(), QRhiCommandBuffer::setComputePipeline(), QRhiCommandBuffer::setGraphicsPipeline(), QRhiCommandBuffer::setScissor(), QRhiCommandBuffer::setShaderResources(), QRhiCommandBuffer::setStencilRef(), QRhiCommandBuffer::setVertexInput(), and QRhiCommandBuffer::setViewport().

The documentation for this class was generated from the following files: