QQuickRhiItemRenderer Class

成员函数文档

QQuickRhiItemRenderer::QQuickRhiItemRenderer()

构造一个新的呈现器。

当 GUI 线程被阻塞时，渲染线程会在场景图同步阶段调用此函数。

另请参见 QQuickRhiItem::createRenderer()。

[virtual noexcept] QQuickRhiItemRenderer::~QQuickRhiItemRenderer()

当QQuickRhiItem 项目的场景图资源清理完毕后，渲染器会被自动删除。

该函数在呈现线程上调用。

在某些情况下，渲染器对象被销毁后又被重新创建是正常的，也是预料之中的。这是因为呈现器的生命周期实际上与底层场景图节点一致。例如，当改变QQuickRhiItem 对象的父对象，使其隶属于不同的QQuickWindow 时，场景图节点都会因窗口的改变而被丢弃和重新创建。这也会涉及到丢弃和创建一个新的QQuickRhiItemRenderer 。

与QRhiWidget 不同，QQuickRhiItemRenderer 无需为释放（或提前释放）通过QRhi 创建的图形资源而执行额外的代码路径。只需在析构函数中释放所有资源，或使用智能指针即可。

[protected] QRhiTexture *QQuickRhiItemRenderer::colorTexture() const

返回作为项目颜色缓冲区的纹理。

只能在initialize() 和render() 中调用。

与深度模版缓冲区和QRhiRenderTarget 不同，该纹理始终可用，由QQuickRhiItem 管理，与isAutoRenderTargetEnabled 的值无关。

另请参见 msaaColorBuffer()、depthStencilBuffer()、renderTarget() 和resolveTexture()。

[protected] QRhiRenderBuffer *QQuickRhiItemRenderer::depthStencilBuffer() const

返回项目渲染所使用的深度模板缓冲区。

只能在initialize() 和render() 中调用。

只有当isAutoRenderTargetEnabled 是true 时才可用。否则返回值为nullptr ，并由initialize() 的重新实现来创建和管理深度钢网缓冲区和QRhiTextureRenderTarget 。

另请参见 colorTexture() 和renderTarget()。

[pure virtual protected] void QQuickRhiItemRenderer::initialize(QRhiCommandBuffer *cb)

当项目首次初始化时，当相关纹理的大小、格式或样本数发生变化时，或者当QRhi 或纹理因任何原因发生变化时调用。该函数将维护render() 中渲染代码使用的图形资源（如果尚未创建，则创建；如果大小发生变化，则调整并重建）。

要查询QRhi 、QRhiTexture 和其他相关对象，请调用rhi()、colorTexture()、depthStencilBuffer() 和renderTarget() 。

当项目大小发生变化时，QRhi 对象、颜色缓冲区纹理和深度模版缓冲区对象都是与之前相同的实例（因此获取器返回相同的指针），但颜色和深度/模版缓冲区很可能已经重建，这意味着size 和底层本地纹理资源可能与上次调用时不同。

重新实现时还应注意，在两次调用该函数之间，QRhi 对象和颜色缓冲区纹理可能会发生变化。例如，当项目被重新赋予属性，使其属于一个新的QQuickWindow 时，在随后调用此函数时，QRhi 和由QQuickRhiItem 管理的所有相关资源将成为与之前不同的实例。然后，重要的是，子类之前创建的所有现有QRhi 资源都将被销毁，因为它们属于之前的QRhi ，不应再被使用。

当isAutoRenderTargetEnabled 为true 时（这是默认值），会自动创建并管理与colorTexture() （或msaaColorBuffer() ）和深度钢网缓冲区相关联的深度钢网QRhiRenderBuffer 和QRhiTextureRenderTarget 。初始化() 和render() 的重新实现可以通过depthStencilBuffer() 和renderTarget() 查询这些对象。当isAutoRenderTargetEnabled 设置为false 时，这些对象将不再自动创建和管理。相反，将由 initialize() 实现来创建缓冲区并设置合适的呈现目标。在手动管理渲染目标的附加颜色或深度模板附件时，它们的大小和样本数必须始终与colorTexture() （或msaaColorBuffer() ）的大小和样本数一致，否则可能会出现渲染或 3D API 验证错误。

子类创建的图形资源将在子类的析构函数中释放。

cb 是当前帧的 。调用该函数时正在记录帧，但没有活动的渲染传递。提供命令缓冲区主要是为了在不延迟 () 的情况下排队 。QRhiCommandBuffer render resource updates

如果有渲染线程，该函数将在渲染线程上调用。

另请参见 render()。

[protected] QRhiRenderBuffer *QQuickRhiItemRenderer::msaaColorBuffer() const

返回作为项目多采样颜色缓冲区的 renderbuffer。

只能在initialize() 和render() 中调用。

如果sampleCount 大于 1，并且启用了多采样反锯齿功能，则返回的QRhiRenderBuffer 将具有匹配的采样计数并用作颜色缓冲区。用于渲染到该缓冲区的图形管道必须使用相同的样本数创建，深度模板缓冲区的样本数也必须匹配。多采样内容有望解析为从resolveTexture() 返回的纹理。当isAutoRenderTargetEnabled 为true 时，renderTarget() 会自动设置为这样做，方法是将 msaaColorBuffer() 设置为颜色附件 0 的renderbuffer ，并将resolveTexture() 设置为其resolveTexture 。

当不使用 MSAA 时，返回值为nullptr 。这时请使用colorTexture() 代替。

根据底层 3D 图形 API 的不同，多采样纹理和采样数大于 1 的彩色呈现缓冲区之间可能没有实际区别（QRhi 可能只是将两者映射到相同的本地资源类型）。不过，一些较早的应用程序接口可能会区分纹理和呈现缓冲区。在 OpenGL ES 3.0 中，多采样呈现缓冲区可用，但多采样纹理不可用，为了支持 OpenGL ES 3.0，QQuickRhiItem 在执行 MSAA 时总是使用多采样QRhiRenderBuffer 作为颜色附件（而不是多采样QRhiTexture ）。

另请参见 colorTexture()、depthStencilBuffer()、renderTarget() 和resolveTexture()。

[pure virtual protected] void QQuickRhiItemRenderer::render(QRhiCommandBuffer *cb)

当背景颜色缓冲区的内容需要更新时调用。

在调用此函数之前，总会至少调用一次initialize() 。

要请求更新，从 QML 或主/GUI 线程上的 C++ 代码（如在属性设置器中）调用QQuickItem::update() 或从QQuickRhiItemRenderer 回调器中调用update() 即可。在 render() 中调用QQuickRhiItemRenderer 的update() 会导致连续触发更新。

cb 是当前帧的 。调用该函数时正在记录帧，但没有活动的渲染传递。QRhiCommandBuffer

如果有渲染线程，该函数将在渲染线程上调用。

另请参见 initialize() 和synchronize()。

[protected] QRhiRenderTarget *QQuickRhiItemRenderer::renderTarget() const

返回在重新实现render() 时必须与QRhiCommandBuffer::beginPass() 一起使用的呈现目标对象。

只能从initialize() 和render() 调用。

仅当isAutoRenderTargetEnabled 为true 时可用。否则，返回值为nullptr ，并由initialize() 的重新实现来创建和管理深度模板缓冲区和QRhiTextureRenderTarget 。

创建graphics pipelines 时，需要一个QRhiRenderPassDescriptor 。可以通过调用renderPassDescriptor() 从返回的QRhiTextureRenderTarget 中查询。

另请参见 colorTexture()、depthStencilBuffer() 和QQuickWindow::effectiveDevicePixelRatio()。

[protected] QRhiTexture *QQuickRhiItemRenderer::resolveTexture() const

返回多采样内容解析到的非多采样纹理。

未启用多采样抗锯齿时，结果为nullptr 。

只能在initialize() 和render() 中调用。

启用 MSAA 后，在Qt Quick 的主渲染传递中对四边形进行纹理处理时，项目的底层场景图节点将使用该纹理。但是，QQuickRhiItemRenderer 的渲染必须以从msaaColorBuffer() 返回的（多采样）QRhiRenderBuffer 为目标。当isAutoRenderTargetEnabled 是true 时，由renderTarget() 返回的QRhiRenderTarget 处理。否则，就需要子类代码正确配置具有颜色缓冲区和解析纹理的呈现目标对象。

另请参见 colorTexture()。

[protected] QRhi *QQuickRhiItemRenderer::rhi() const

返回当前QRhi 对象。

只能在initialize() 和render() 中调用。

[pure virtual protected] void QQuickRhiItemRenderer::synchronize(QQuickRhiItem *item)

如果有呈现线程，则在主/图形用户界面线程阻塞时，在呈现线程上调用该函数。它从 the item's synchronize step中调用，允许读写属于主线程和呈现线程的数据。通常情况下，存储在QQuickRhiItem 中的属性值会被复制到QQuickRhiItemRenderer 中，这样当呈现线程和主线程继续并行工作时，就可以在render() 中安全地读取这些属性值。

另请参见 initialize() 和render()。

[protected] void QQuickRhiItemRenderer::update()

当需要更新屏幕外色彩缓冲区的内容时，调用此函数。(即请求再次调用render() ；调用将在稍后进行，注意更新通常会根据演示速率进行节流）。

该函数可从render() 中调用，以安排更新。