class QQuickRhiItemRenderer#

QQuickRhiItemRenderer实现了QQuickRhiItem的渲染逻辑。更多信息...

自6.7版本新增。

概述#

方法#

虚函数#

注意

此文档可能包含从C++自动翻译成Python的代码段。我们始终欢迎对代码段的翻译做出贡献。如果您发现翻译存在问题，也可以通过在https:/bugreports.qt.io/projects/PYSIDE创建工单的方式来告知我们。

详细说明#

注意

QQuickRhiItem和QQuickRhiItemRenderer在Qt 6.7中处于技术预览阶段。API处于开发中，可能会发生变化。

另请参阅

QQuickRhiItem QRhi

__init__()#

构造一个新的渲染器。

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

另请参阅

createRenderer()

colorTexture()#
返回类型:

QRhiTexture

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

仅应在initialize() 和 render() 中调用。

与深度-模板缓冲区和 QRhiRenderTarget 不同，此纹理始终可用，由 QQuickRhiItem 管理，与 autoRenderTarget 的值无关。

注意

当 sampleCount 大于 1，并且启用多样本抗锯齿时，返回值是 None。相反，请通过调用 msaaColorBuffer() 查询 QRhiRenderBuffer。

注意

还可以通过从 renderTarget() 返回的 QRhiRenderTarget 查询背地图素大小和样本数量。这可能比从 QRhiTexture 或 QRhiRenderBuffer 查询更方便和紧凑，因为它无论是否使用多采样都有效。

另请参阅

msaaColorBuffer() depthStencilBuffer() renderTarget() resolveTexture()

depthStencilBuffer()#
返回类型:

QRhiRenderBuffer

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

仅应在initialize() 和 render() 中调用。

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

抽象initialize(cb)#
参数:

cb – QRhiCommandBuffer

当项目第一次初始化、相关纹理的大小、格式或样本数发生变化，或者QRhi或纹理因任何原因而更改时，将被调用。该函数预计将维护（如果尚未创建则创建、如果大小已更改则调整和重建）在render()中使用的图形资源。

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

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

实现应准备QRhi对象和颜色缓冲纹理可能在多次调用此函数之间发生变化。例如，当项目被重新父化以属于新的QQuickWindow时，QRhi和由QQuickRhiItem管理的所有相关资源在随后的函数调用中将不同于之前。在这种情况下，非常重要的一点是销毁所有先前由子类创建的现有QRhi资源，因为它们属于不应再使用的旧的QRhi。

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

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

cb是当前帧的QRhiCommandBuffer。该函数在一个正在记录的帧上被调用，但没有活动的渲染通道。命令缓冲区主要提供允许在不需要render()的情况下排队资源更新。

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

另请参阅

render()

msaaColorBuffer()#
返回类型:

QRhiRenderBuffer

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

仅应在initialize() 和 render() 中调用。

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

当不使用 MSAA 时，返回值是 None。然后请使用 colorTexture()。

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

注意

还可以通过从 renderTarget() 返回的 QRhiRenderTarget 查询背地图素大小和样本数量。这可能比从 QRhiTexture 或 QRhiRenderBuffer 查询更方便和紧凑，因为它无论是否使用多采样都有效。

另请参阅

colorTexture() depthStencilBuffer() renderTarget() resolveTexture()

abstract render(cb)#
参数:

cb – QRhiCommandBuffer

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

在此函数被调用之前，总有至少一个调用到 initialize()。

要请求更新，请在主/GUI 线程中从 QML 调用 update()，或者在属性设置器中从 C++ 代码调用，或者从 update() 调用。如果从 QQuickRhiItemRenderer 回调中调用，则使用相同的 update()。在 render() 中调用 QQuickRhiItemRenderer 的 update() 将导致连续触发更新。

cb 是当前帧的 QRhiCommandBuffer。函数带有正在记录的帧调用，但没有激活的绘制通道。

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

另请参阅

initialize() 和 synchronize()

renderTarget()#
返回类型:

QRhiRenderTarget

返回必须与 QRhiCommandBuffer::beginPass() 一起使用的渲染目标对象，并在 render() 的重实现中。

仅应在initialize() 和 render() 中调用。

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

在创建图形管线时，需要 QRhiRenderPassDescriptor。这可以通过调用 renderPassDescriptor() 从返回的 QRhiTextureRenderTarget 获取。

注意

返回的 QRhiTextureRenderTarget 总是报告 devicePixelRatio() 为 1。这是因为只有交换链以及相关的窗口才有设备像素比的概念，而不是纹理，并且这里的渲染目标始终指向纹理。如果屏幕上的缩放因子对渲染有关键作用，请在 synchronize() 中通过项的 window()->effectiveDevicePixelRatio() 查询并存储它。在这种情况下，始终使用 effectiveDevicePixelRatio() 而不是基类的 devicePixelRatio()。

另请参阅

colorTexture() depthStencilBuffer() effectiveDevicePixelRatio()

resolveTexture()#
返回类型:

QRhiTexture

返回非多样本纹理，该纹理将多样本内容解算到其中。

当启用多采样抗锯齿时，结果为 None。

仅应在initialize() 和 render() 中调用。

启用MSAA后，这是在Qt Quick主渲染通道中对四边形进行着色时底层场景图节点使用的纹理。然而，QQuickRhiItemRenderer 的渲染必须针对从 msaaColorBuffer() 返回的（多采样）QRhiRenderBuffer。当 autoRenderTarget 为 true 时，由 renderTarget() 返回的 QRhiRenderTarget 会处理此事。否则，它就由子类代码正确地配置一个具有颜色缓冲区和解析纹理的渲染目标对象。

另请参阅

colorTexture()

rhi()#
返回类型:

QRhi

返回当前QRhi对象。

仅应在initialize() 和 render() 中调用。

抽象synchronize(item)#
参数:

item – QQuickRhiItem

当主/GUI线程被阻塞时，该函数在渲染线程上被调用（如果有的话）。它在 item :meth:` <PySide6.QtQuick.QQuickItem.updatePaintNode>` 的同步步骤中被调用，并允许读取和写入属于主和渲染线程的数据。通常存储在 QQuickRhiItem 中的属性值将被复制到 QQuickRhiItemRenderer 中，以便可以在 render() 中安全地读取，这样在渲染和主线程并行工作时可以安全读取。

另请参阅

initialize() render()

update()#

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

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

注意

此函数应在渲染器内部使用。要在GUI线程上更新项目，请使用 update()。