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 （这是默认值）时，系统会自动创建并管理一个深度-模板缓冲区QRhiRenderBuffer 以及一个与colorTexture()（或msaaColorBuffer()）及深度-模板缓冲区关联的QRhiTextureRenderTarget 。initialize()和render()的重写实现可通过depthStencilBuffer()和renderTarget()查询这些对象。 当isAutoRenderTargetEnabled 设置为false 时，这些对象将不再被自动创建和管理。取而代之的是，将由initialize()的实现根据需要创建缓冲区并设置渲染目标。 当手动管理渲染目标的额外颜色或深度-模板附件时，其大小和采样数必须始终与 `colorTexture()`（或 `msaaColorBuffer()`）的大小和采样数一致，否则可能会发生渲染或 3D API 验证错误。

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

cb 是当前帧的QRhiCommandBuffer 。该函数在录制帧时被调用，但此时没有活动的渲染通道。提供该命令缓冲区主要是为了允许将resource updates 加入队列，而无需推迟到render()。

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

另请参阅 render()。

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

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

该函数仅可从initialize()和render()中调用。

当sampleCount 大于1（即启用了多采样抗锯齿）时，返回的QRhiRenderBuffer 具有与之匹配的采样数，并作为颜色缓冲区使用。用于渲染到该缓冲区的图形管道必须使用相同的采样数创建，且深度-模板缓冲区的采样数也必须与之匹配。 多采样内容预计将解析为由resolveTexture()返回的纹理。当isAutoRenderTargetEnabled 为true 时，renderTarget()会自动配置以实现此功能，具体做法是将msaaColorBuffer()设置为颜色附件0的renderbuffer ，并将resolveTexture()设置为其resolveTexture 。

当未使用 MSAA 时，返回值为nullptr 。此时请改用colorTexture()。

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

另请参阅 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)

如果存在渲染线程，则该函数会在渲染线程上被调用，而此时主线程/GUI线程处于阻塞状态。该函数由 the item's synchronize step调用，并允许读写属于主线程和渲染线程的数据。通常，存储在QQuickRhiItem 中的属性值会被复制到QQuickRhiItemRenderer 中，以便在渲染线程和主线程继续并行工作时，后续可在render()中安全地读取这些数据。

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

[protected] void QQuickRhiItemRenderer::update()

当需要更新屏幕外颜色缓冲区的内容时，调用此函数。（即请求再次调用render()；该调用将在稍后进行，请注意，更新通常会限制在渲染速率之内）

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