QQuickRhiItemRenderer 类

成员函数说明

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管理，独立于autoRenderTarget的值。

另请参阅：msaaColorBuffer()，depthStencilBuffer()，renderTarget()和resolveTexture()。

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

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

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

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

另请参阅：colorTexture()和renderTarget()。

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

在项目首次初始化时、相关纹理的大小、格式或样本计数更改时以及QRhi或纹理由于任何原因更改时调用。该函数应维护（如果尚未创建，则创建；如果大小已更改，则调整和重建）在render()中使用的图形资源。

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

当项的大小发生变化时，QRhi对象、颜色缓冲纹理以及深度/模板缓冲对象保持相同的实例（因此获取器返回相同的指针），但颜色和深度/模板缓冲可能已被重建，这意味着与上一次调用相比，尺寸和底层本地纹理资源可能不同。

重实现还应该准备，在调用此函数时，QRhi对象和颜色缓冲纹理可能已更改。例如，当项被重新置于新的QQuickWindow之下，下一次调用此函数时，QRhi和由QQuickRhiItem管理的所有相关资源将不再是之前的实例。然后重要的是，先前由子类创建的所有现有QRhi资源都应该被销毁，因为它们属于不应再使用的先前QRhi。

当autoRenderTarget为true（默认值）时，将自动创建与colorTexture()（或msaaColorBuffer）相关的深度-模板QRhiRenderBuffer和一个QRhiTextureRenderTarget以及管理深度-模板缓冲。initialize()和render()的重实现可以通过depthStencilBuffer()和renderTarget查询这些对象。当autoRenderTarget设置为false时，这些对象不再自动创建和管理。相反，initialize()实现将根据需要进行缓冲区和渲染目标的创建和设置。当手动管理渲染目标的额外颜色或深度/模板附加时，它们的大小和样本计数必须始终与colorTexture()（或msaaColorBuffer）的大小和样本计数一致，否则可能会发生渲染或3D API验证错误。

子类创建的图形资源应在上一个子类的析构函数实现中释放。

cb是当前帧的QRhiCommandBuffer。此函数在记录帧时被调用，但没有任何活动的渲染通道。命令缓冲区主要包括允许在render之前排队资源更新。

如果在渲染线程上存在，则调用此函数。

另请参阅render。

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

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

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

当 sampleCount 大于 1，且启用多采样抗锯齿时，返回的 QRhiRenderBuffer 将具有匹配的样本数并作为颜色缓冲区使用。用于将内容渲染到该缓冲区的图形管线必须使用相同的样本数创建，并且深度-模板缓冲区的样本数也必须匹配。期望多采样内容将解析为从 resolveTexture() 返回的纹理。当 autoRenderTarget 为 true 时，自动设置 renderTarget() 以执行此操作，通过将 msaaColorBuffer() 设置为颜色附件 0 的 renderbuffer 和将其 resolveTexture() 作为其 resolveTexture。

当不支持 MSAA 时，返回值是 nullptr。请改用 colorTexture()。

根据底层 3D 图形 API，样本数大于 1 的多采样纹理与颜色渲染缓冲区之间可能没有实际区别（QRhi 可能将两者映射到相同的原生资源类型）。但是，一些较旧的 API 可能会在纹理和渲染缓冲区之间进行区分。为了支持 OpenGL ES 3.0，其中提供了多采样渲染缓冲区但未提供多采样纹理，QQuickRhiItem 总是通过使用多采样 QRhiRenderBuffer 作为颜色附件来执行 MSAA（而不使用多采样 QRhiTexture）。

另请参阅 colorTexture()，depthStencilBuffer()，renderTarget()，以及 resolveTexture()。

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

当需要更新后台颜色缓冲区的内容时被调用。

在调用此函数之前，始终至少有一个对 initialize() 的调用。

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

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

如果在渲染线程上存在，则调用此函数。

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

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

返回用于在 render() 的重实现中使用 QRhiCommandBuffer::beginPass() 的渲染目标对象。

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

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

创建 图形管线 时，需要一个 QRhiRenderPassDescriptor。这可以通过调用返回的 QRhiTextureRenderTarget 的 renderPassDescriptor() 来查询。

另请参阅：colorTexture()，depthStencilBuffer() 以及 QQuickWindow::effectiveDevicePixelRatio。

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

返回用于将多样本内容解析的非多样本纹理。

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

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

启用 MSAA 时，这是 Qt Quick 的主渲染通道中纹理化四边形时，项目下层的场景图节点使用的纹理。但是，QQuickRhiItemRenderer 的渲染必须针对从 msaaColorBuffer() 返回的（多样本）QRhiRenderBuffer。当 autoRenderTarget 为 true 时，这由从 renderTarget() 返回的 QRhiRenderTarget 自动处理。否则，应根据子类代码正确配置具有颜色缓冲区和解析纹理的渲染目标对象。

另请参阅：colorTexture。

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

返回当前 QRhi 对象。

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

[纯虚保护] void QQuickRhiItemRenderer::synchronize(QQuickRhiItem *item)

如果存在渲染线程，则在主/GUI 线程被阻塞时调用此函数。它来自 项的 synchronize 步骤，允许读取和写入属于主和渲染线程的数据。通常，将存储在 QQuickRhiItem 中的属性值复制到 QQuickRhiItemRenderer 中，以便之后可以在 render() 中安全地读取，此时渲染线程和主线程将并行工作。

另请参阅：initialize() 和 render。

[protected] void QQuickRhiItemRenderer::update()

当离屏颜色缓冲区的内容需要更新时，请调用此函数；（即请求再次调用 render()；调用将在稍后的某个时刻发生，注意更新通常被节流到显示速率）

可以从 render() 调用此函数来安排更新。