 |
Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
|
|
Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
|
\inmodule QtGuiPrivate \inheaderfile rhi/qrhi.h More...
#include <qrhi.h>
Classes | |
| struct | NativeRenderBuffer |
| \inmodule QtGuiPrivate \inheaderfile rhi/qrhi.h More... | |
Public Types | |
| enum | Type { DepthStencil , Color } |
| Specifies the type of the renderbuffer. More... | |
| enum | Flag { UsedWithSwapChainOnly = 1 << 0 , NoTransientBacking = 1 << 1 } |
| \variable QRhiRenderBuffer::NativeRenderBuffer::object More... | |
| Public Types inherited from QRhiResource | |
| enum | Type { Buffer , Texture , Sampler , RenderBuffer , RenderPassDescriptor , SwapChainRenderTarget , TextureRenderTarget , ShaderResourceBindings , GraphicsPipeline , SwapChain , ComputePipeline , CommandBuffer , ShadingRateMap , IndirectCommandBuffer } |
| Specifies type of the resource. More... | |
Public Member Functions | |
| QRhiResource::Type | resourceType () const override |
| Type | type () const |
| void | setType (Type t) |
| Sets the type to t. | |
| QSize | pixelSize () const |
| void | setPixelSize (const QSize &sz) |
| Sets the size (in pixels) to sz. | |
| int | sampleCount () const |
| void | setSampleCount (int s) |
| Sets the sample count to s. | |
| Flags | flags () const |
| void | setFlags (Flags f) |
| Sets the flags to f. | |
| virtual bool | create ()=0 |
| Creates the corresponding native graphics resources. | |
| virtual bool | createFrom (NativeRenderBuffer src) |
| Similar to create() except that no new native renderbuffer objects are created. | |
| virtual QRhiTexture::Format | backingFormat () const =0 |
| Public Member Functions inherited from QRhiResource | |
| virtual | ~QRhiResource () |
| Destructor. | |
| 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 | |
| QRhiRenderBuffer (QRhiImplementation *rhi, Type type_, const QSize &pixelSize_, int sampleCount_, Flags flags_, QRhiTexture::Format backingFormatHint_) | |
| Protected Member Functions inherited from QRhiResource | |
| QRhiResource (QRhiImplementation *rhi) | |
Protected Attributes | |
| Type | m_type |
| QSize | m_pixelSize |
| int | m_sampleCount |
| Flags | m_flags |
| QRhiTexture::Format | m_backingFormatHint |
| Protected Attributes inherited from QRhiResource | |
| QRhiImplementation * | m_rhi = nullptr |
| quint64 | m_id |
| QByteArray | m_objectName |
\inmodule QtGuiPrivate \inheaderfile rhi/qrhi.h
Renderbuffer resource.
Renderbuffers cannot be sampled or read but have some benefits over textures in some cases:
A \l DepthStencil renderbuffer may be lazily allocated and be backed by transient memory with some APIs. On some platforms this may mean the depth/stencil buffer uses no physical backing at all.
That transient nature has a consequence: the contents of a \l DepthStencil renderbuffer are not guaranteed to survive if a backend has to interrupt and restart a render pass internally. With Metal this happens when a draw call is implemented via indirect command buffers, which is the case for \l{QRhiCommandBuffer::drawIndirectCount()}{drawIndirectCount()} and its indexed variant, for a high draw count \l{QRhiCommandBuffer::drawIndirect()}{drawIndirect()} or \l{QRhiCommandBuffer::drawIndexedIndirect()}{drawIndexedIndirect()}, and also when tessellation is used. Draws recorded after such a call then depth-test against a depth buffer that lost its contents. When this matters, set the \l NoTransientBacking flag, which makes the contents preservable at the cost of the memory and bandwidth that the transient backing was saving. Alternatively, where a QRhiTextureRenderTarget is used anyway, attach a depth or depth-stencil QRhiTexture with \l{QRhiTextureRenderTargetDescription::setDepthTexture()}{setDepthTexture()} instead of a renderbuffer: that is preserved across an interruption, unless QRhiTextureRenderTarget::DoNotStoreDepthStencilContents is set.
Note that the indirect drawing cases above are avoidable. A QRhiIndirectCommandBuffer executed with \l{QRhiCommandBuffer::executeIndirect()}{executeIndirect()} is prepared before the render pass begins, so it never interrupts the pass however many commands it holds, and none of this applies to it. Only tessellation then remains as a reason to consider \l NoTransientBacking.
\l Color renderbuffers are useful since QRhi::MultisampleRenderBuffer may be supported even when QRhi::MultisampleTexture is not.
How the renderbuffer is implemented by a backend is not exposed to the applications. In some cases it may be backed by ordinary textures, while in others there may be a different kind of native resource used.
Renderbuffers that are used as (and are only used as) depth-stencil buffers in combination with a QRhiSwapChain's color buffers should have the UsedWithSwapChainOnly flag set. This serves a double purpose: such buffers, depending on the backend and the underlying APIs, be more efficient, and QRhi provides automatic sizing behavior to match the color buffers, which means calling setPixelSize() and create() are not necessary for such renderbuffers.
\variable QRhiRenderBuffer::NativeRenderBuffer::object
64-bit integer containing the native object handle.
Used with QRhiRenderBuffer::createFrom().
With OpenGL the native handle is a GLuint value. object is expected to be a valid OpenGL renderbuffer object ID.
Flag values for flags() and setFlags()
\value UsedWithSwapChainOnly For DepthStencil renderbuffers this indicates that the renderbuffer is only used in combination with a QRhiSwapChain, and never in any other way. This provides automatic sizing and resource rebuilding, so calling setPixelSize() or create() is not needed whenever this flag is set. This flag value may also trigger backend-specific behavior, for example with OpenGL, where a separate windowing system interface API is in use (EGL, GLX, etc.), the flag is especially important as it avoids creating any actual renderbuffer resource as there is already a windowing system provided depth/stencil buffer as requested by QSurfaceFormat.
\value [since 6.13] NoTransientBacking Requests that the renderbuffer is not backed by transient, lazily allocated memory. Only relevant for \l DepthStencil renderbuffers, and only with backends that would otherwise choose such storage, which in practice means Metal on Apple GPUs. Set this when the contents have to survive a render pass being interrupted and continued internally by a backend, as described in the \l{QRhiRenderBuffer}{class documentation}. It costs actual memory and bandwidth for the depth/stencil buffer, so do not set it when not needed. In particular it is not needed on account of \l{QRhiCommandBuffer::executeIndirect()}{executeIndirect()}, which never interrupts the pass.
| Enumerator | |
|---|---|
| UsedWithSwapChainOnly | |
| NoTransientBacking | |
|
protected |
|
pure virtual |
Implemented in QD3D11RenderBuffer, QGles2RenderBuffer, QMetalRenderBuffer, QNullRenderBuffer, and QVkRenderBuffer.
|
pure virtual |
Creates the corresponding native graphics resources.
If there are already resources present due to an earlier create() with no corresponding destroy(), then destroy() is called implicitly first.
true when successful, false when a graphics operation failed. Regardless of the return value, calling destroy() is always safe. Implemented in QD3D11RenderBuffer, QGles2RenderBuffer, QMetalRenderBuffer, QNullRenderBuffer, and QVkRenderBuffer.
|
virtual |
Similar to create() except that no new native renderbuffer objects are created.
Instead, the native renderbuffer object specified by src is used.
This allows importing an existing renderbuffer object (which must belong to the same device or sharing context, depending on the graphics API) from an external graphics engine.
false.true when successful, false when not supported. Reimplemented in QGles2RenderBuffer.
|
inline |
|
inline |
|
overridevirtual |
|
inline |
|
inline |
|
inline |
|
protected |
1.16.1