PySide6.QtQuick.QQuickRhiItemRenderer

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()
Return type:

QRhiTexture

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

必须只能从initialize()和render()中调用。

与深度模板缓冲区和QRhiRenderTarget不同，此纹理始终可用，并由QQuickRhiItem管理，独立于isAutoRenderTargetEnabled的值。

注意

当sampleCount大于1时，即启用了多重采样抗锯齿，返回值为None。相反，通过调用msaaColorBuffer()来查询QRhiRenderBuffer。

注意

支持纹理大小和样本计数也可以通过从renderTarget()返回的QRhiRenderTarget进行查询。这可能比从QRhiTexture或QRhiRenderBuffer查询更方便和紧凑，因为无论是否使用多重采样，它都能工作。

另请参阅

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

depthStencilBuffer()
Return type:

QRhiRenderBuffer

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

必须只能从initialize()和render()中调用。

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

abstract initialize(cb)
Parameters:

cb – QRhiCommandBuffer

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

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

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

重新实现时还应准备好，QRhi对象和颜色缓冲纹理可能在此函数的调用之间发生变化。例如，当项目被重新父级化，使其属于一个新的QQuickWindow时，QRhi和由QQuickRhiItem管理的所有相关资源在此函数的后续调用中将与之前不同。因此，重要的是要销毁之前由子类创建的所有现有QRhi资源，因为它们属于不应再使用的先前QRhi。

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

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

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

此函数在渲染线程上调用（如果有的话）。

另请参阅

render()

msaaColorBuffer()
Return type:

QRhiRenderBuffer

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

必须只能从initialize()和render()中调用。

当 sampleCount 大于 1 时，多重采样抗锯齿功能启用，返回的 QRhiRenderBuffer 具有匹配的采样计数并用作颜色缓冲区。用于渲染到此缓冲区的图形管道必须使用相同的采样计数创建，并且深度-模板缓冲区的采样计数也必须匹配。多重采样内容预计会解析为从 resolveTexture() 返回的纹理。当 isAutoRenderTargetEnabled 为 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)
Parameters:

cb – QRhiCommandBuffer

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

在调用此函数之前，总是至少有一次对initialize()的调用。

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

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

此函数在渲染线程上调用（如果有的话）。

renderTarget()
Return type:

QRhiRenderTarget

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

必须只能从initialize()和render()中调用。

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

在创建图形管道时，需要一个QRhiRenderPassDescriptor。可以通过调用renderPassDescriptor()从返回的QRhiTextureRenderTarget中查询到。

注意

返回的QRhiTextureRenderTarget总是报告devicePixelRatio()为1。这是因为只有交换链和相关的窗口有设备像素比的概念，而不是纹理，这里的渲染目标总是引用一个纹理。如果屏幕比例因子对渲染有影响，可以通过项目的synchronize()中的window()->effectiveDevicePixelRatio()查询并存储它。这样做时，总是优先使用effectiveDevicePixelRatio()而不是基类的devicePixelRatio()。

另请参阅

colorTexture() depthStencilBuffer() effectiveDevicePixelRatio()

resolveTexture()
Return type:

QRhiTexture

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

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

必须只能从initialize()和render()中调用。

启用MSAA后，这是在Qt Quick的主渲染过程中用于纹理化四边形时，项目的基础场景图节点使用的纹理。然而，QQuickRhiItemRenderer的渲染必须针对从msaaColorBuffer()返回的（多重采样）QRhiRenderBuffer。当isAutoRenderTargetEnabled为true时，这由从renderTarget()返回的QRhiRenderTarget处理。否则，子类代码需要正确配置一个包含颜色缓冲区和解析纹理的渲染目标对象。

另请参阅

colorTexture()

rhi()
Return type:

QRhi

返回当前的QRhi对象。

必须只能从initialize()和render()中调用。

abstract synchronize(item)
Parameters:

项目 – QQuickRhiItem

此函数在渲染线程上调用（如果有的话），而主/GUI线程被阻塞。它从item :meth:` `的同步步骤中调用，并允许读取和写入属于主线程和渲染线程的数据。通常存储在QQuickRhiItem中的属性值会被复制到QQuickRhiItemRenderer中，以便在渲染和主线程继续并行工作时，可以在render()中安全地读取这些值。

另请参阅

initialize() render()

update()

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

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

注意

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