QRhiRenderBuffer Class
渲染缓冲区资源。更多...
| 头文件： | #include <rhi/qrhi.h> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS GuiPrivate) target_link_libraries(mytarget PRIVATE Qt6::GuiPrivate) |
| qmake： | QT += gui-private |
| 自： | Qt 6.6 |
| 继承自： | QRhiResource |
公共类型
| struct | NativeRenderBuffer |
| enum | Flag { UsedWithSwapChainOnly } |
| flags | Flags |
| enum | Type { DepthStencil, Color } |
公共函数
| 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 |
重新实现的公共函数
| virtual QRhiResource::Type | resourceType() const override |
详细说明
渲染缓冲区无法被采样或读取，但在某些情况下相对于纹理具有一些优势：
DepthStencil 渲染缓冲区可通过某些API以懒加载方式分配，并由临时内存作为后备。在某些平台上，这可能意味着深度/模板缓冲区完全不使用物理存储介质。
这种临时性带来了一项后果：如果后端必须在内部中断并重启渲染过程，则无法保证DepthStencil 渲染缓冲区的内容能够保留。在Metal中，当渲染调用通过间接命令缓冲区实现时（例如高渲染次数的drawIndexedIndirect()），以及使用曲面细分时，都会发生这种情况。 在此类调用之后记录的绘制操作，将针对一个已丢失内容的深度缓冲区进行深度测试。当此情况需要关注时，请使用setDepthTexture()将深度缓冲区或深度-模板缓冲区QRhiTexture 附加，而非渲染缓冲区：该缓冲区在中断期间将被保留，除非设置了QRhiTextureRenderTarget::DoNotStoreDepthStencilContents 。
Color 渲染缓冲区非常有用，因为即使QRhi::MultisampleTexture 不被支持，QRhi::MultisampleRenderBuffer 也可能被支持。
后端如何实现渲染缓冲区对应用程序是不可见的。在某些情况下，它可能由普通纹理作为后端支持，而在其他情况下则可能使用另一种原生资源。
那些仅作为深度-模板缓冲区，并与QRhiSwapChain 的颜色缓冲区结合使用的渲染缓冲区，应设置UsedWithSwapChainOnly 标志。 这有双重作用：此类渲染缓冲区（取决于后端和底层 API）效率更高；此外，QRhi 提供了与颜色缓冲区匹配的自动尺寸调整行为，这意味着对于此类渲染缓冲区，无需调用setPixelSize() 和create()。
注意：这是一个 兼容性保证有限的 RHI API，详情请参阅QRhi 。
成员类型文档
enum QRhiRenderBuffer::Flag
flags QRhiRenderBuffer::Flags
| 常量 | 值 | 描述 |
|---|---|---|
QRhiRenderBuffer::UsedWithSwapChainOnly | 1 << 0 | 对于DepthStencil 渲染缓冲区，这表示该渲染缓冲区仅与QRhiSwapChain 配合使用，绝不会以其他任何方式使用。这提供了自动调整大小和资源重建功能，因此只要设置了此标志，就无需调用setPixelSize() 或create()。 该标志值还可能触发后端特有的行为，例如在 OpenGL 中，当使用独立的窗口系统接口 API（如 EGL、GLX 等）时，该标志尤为重要，因为它避免了创建任何实际的渲染缓冲区资源——此时窗口系统已根据QSurfaceFormat 的要求提供了深度/模板缓冲区。 |
Flags 类型是QFlags<Flag> 的 typedef。它存储了 Flag 值的按“或”运算组合。
enum QRhiRenderBuffer::Type
指定渲染缓冲区的类型
| 常量 | 值 | 描述 |
|---|---|---|
QRhiRenderBuffer::DepthStencil | 0 | 深度/模板组合 |
QRhiRenderBuffer::Color | 1 | 颜色 |
成员函数文档
[pure virtual] bool QRhiRenderBuffer::create()
创建相应的本机图形资源。如果由于之前调用了 create() 且未调用相应的destroy()，导致已存在相关资源，则会先隐式调用destroy()。
成功时返回true ，图形操作失败时返回false 。无论返回值为何，调用destroy()始终是安全的。
[virtual] bool QRhiRenderBuffer::createFrom(QRhiRenderBuffer::NativeRenderBuffer src)
与create()类似，不同之处在于不会创建新的本机渲染缓冲区对象。而是使用由src 指定的本机渲染缓冲区对象。
这允许从外部图形引擎导入现有的渲染缓冲区对象（该对象必须属于同一设备或共享上下文，具体取决于图形 API）。
注意： 目前这 仅适用于 OpenGL。该函数的存在仅是为了允许导入绑定到某些特殊外部对象（例如 EGLImageKHR）的渲染缓冲区对象。 一旦应用程序执行了 glEGLImageTargetRenderbufferStorageOES 调用，渲染缓冲区对象就可以传递给此函数，以创建一个封装的QRhiRenderBuffer ，进而将其作为颜色附件传递给QRhiTextureRenderTarget ，从而实现对 EGLImage 的渲染。
注意： pixelSize()、sampleCount() 和flags() 仍必须设置正确。向QRhi::newRenderBuffer() 传递错误的大小和其他值，然后紧接着调用 createFrom()，并期望仅凭本机渲染缓冲区对象就足以推断出这些值，这是错误的，并将导致问题。
注意： QRhiRenderBuffer 不会获取原生对象的所有权，且destroy() 也不会释放该对象。
注意： 仅当QRhi::RenderBufferImport 功能被报告为supported 时，此 函数才会被实现。否则，该函数不执行任何操作，且返回值为false 。
成功时返回true ，不支持时返回false 。
QRhiRenderBuffer::Flags QRhiRenderBuffer::flags() const
返回标志。
另请参阅 setFlags()。
QSize QRhiRenderBuffer::pixelSize() const
返回像素大小。
另请参阅 setPixelSize()。
[override virtual] QRhiResource::Type QRhiRenderBuffer::resourceType() const
重写了：QRhiResource::resourceType() const。
返回资源类型。
int QRhiRenderBuffer::sampleCount() const
返回采样数。1 表示不进行多采样抗锯齿。
另请参阅 setSampleCount()。
void QRhiRenderBuffer::setFlags(QRhiRenderBuffer::Flags f)
将标志设置为f 。
另请参阅 flags()。
void QRhiRenderBuffer::setPixelSize(const QSize &sz)
将大小（以像素为单位）设置为sz 。
另请参阅 pixelSize()。
void QRhiRenderBuffer::setSampleCount(int s)
将采样数设置为s 。
另请参阅 sampleCount()。
void QRhiRenderBuffer::setType(QRhiRenderBuffer::Type t)
将类型设置为t 。
另请参阅 type()。
QRhiRenderBuffer::Type QRhiRenderBuffer::type() const
返回渲染缓冲区的类型。
另请参阅 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.
