QRhiRenderBuffer Class
Renderbuffer resource. More...
| Header: | #include <rhi/qrhi.h> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS GuiPrivate)target_link_libraries(mytarget PRIVATE Qt6::GuiPrivate) |
| qmake: | QT += gui-private |
| Since: | Qt 6.6 |
| Inherits: | QRhiResource |
Public Types
| struct | NativeRenderBuffer |
| enum | Flag { UsedWithSwapChainOnly, NoTransientBacking } |
| flags | Flags |
| enum | Type { DepthStencil, Color } |
Public Functions
| virtual bool | create() = 0 |
| virtual bool | createFrom(QRhiRenderBuffer::NativeRenderBuffer src) |
| QRhiRenderBuffer::Flags | flags() const |
| QSize | pixelSize() const |
| int | sampleCount() const |
| void | setFlags(QRhiRenderBuffer::Flags f) |
| void | setPixelSize(const QSize &sz) |
| void | setSampleCount(int s) |
| void | setType(QRhiRenderBuffer::Type t) |
| QRhiRenderBuffer::Type | type() const |
Reimplemented Public Functions
| virtual QRhiResource::Type | resourceType() const override |
Detailed Description
Renderbuffers cannot be sampled or read but have some benefits over textures in some cases:
A 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 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 drawIndirectCount() and its indexed variant, for a high draw count drawIndirect() or 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 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 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 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 NoTransientBacking.
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.
Note: This is a RHI API with limited compatibility guarantees, see QRhi for details.
Member Type Documentation
enum QRhiRenderBuffer::Flag
flags QRhiRenderBuffer::Flags
Flag values for flags() and setFlags()
| Constant | Value | Description |
|---|---|---|
QRhiRenderBuffer::UsedWithSwapChainOnly | 1 << 0 | 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. |
QRhiRenderBuffer::NoTransientBacking (since Qt 6.13) | 1 << 1 | Requests that the renderbuffer is not backed by transient, lazily allocated memory. Only relevant for 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 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 executeIndirect(), which never interrupts the pass. |
The Flags type is a typedef for QFlags<Flag>. It stores an OR combination of Flag values.
enum QRhiRenderBuffer::Type
Specifies the type of the renderbuffer
| Constant | Value | Description |
|---|---|---|
QRhiRenderBuffer::DepthStencil | 0 | Combined depth/stencil |
QRhiRenderBuffer::Color | 1 | Color |
Member Function Documentation
[pure virtual] bool QRhiRenderBuffer::create()
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.
Returns true when successful, false when a graphics operation failed. Regardless of the return value, calling destroy() is always safe.
[virtual] bool QRhiRenderBuffer::createFrom(QRhiRenderBuffer::NativeRenderBuffer src)
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.
Note: This is currently applicable to OpenGL only. This function exists solely to allow importing a renderbuffer object that is bound to some special, external object, such as an EGLImageKHR. Once the application performed the glEGLImageTargetRenderbufferStorageOES call, the renderbuffer object can be passed to this function to create a wrapping QRhiRenderBuffer, which in turn can be passed in as a color attachment to a QRhiTextureRenderTarget to enable rendering to the EGLImage.
Note: pixelSize(), sampleCount(), and flags() must still be set correctly. Passing incorrect sizes and other values to QRhi::newRenderBuffer() and then following it with a createFrom() expecting that the native renderbuffer object alone is sufficient to deduce such values is wrong and will lead to problems.
Note: QRhiRenderBuffer does not take ownership of the native object, and destroy() will not release that object.
Note: This function is only implemented when the QRhi::RenderBufferImport feature is reported as supported. Otherwise, the function does nothing and the return value is false.
Returns true when successful, false when not supported.
QRhiRenderBuffer::Flags QRhiRenderBuffer::flags() const
Returns the flags.
See also setFlags().
QSize QRhiRenderBuffer::pixelSize() const
Returns the pixel size.
See also setPixelSize().
[override virtual] QRhiResource::Type QRhiRenderBuffer::resourceType() const
Reimplements: QRhiResource::resourceType() const.
Returns the resource type.
int QRhiRenderBuffer::sampleCount() const
Returns the sample count. 1 means no multisample antialiasing.
See also setSampleCount().
void QRhiRenderBuffer::setFlags(QRhiRenderBuffer::Flags f)
Sets the flags to f.
See also flags().
void QRhiRenderBuffer::setPixelSize(const QSize &sz)
Sets the size (in pixels) to sz.
See also pixelSize().
void QRhiRenderBuffer::setSampleCount(int s)
Sets the sample count to s.
See also sampleCount().
void QRhiRenderBuffer::setType(QRhiRenderBuffer::Type t)
Sets the type to t.
See also type().
QRhiRenderBuffer::Type QRhiRenderBuffer::type() const
Returns the renderbuffer type.
See also setType().
© 2026 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.
