class QRhiWidget

类 QRhiWidget 是一个通过加速图形API（如Vulkan、Metal或Direct 3D）渲染3D图形的小部件。 更多...

6.7 版本中引入。

摘要

属性

• colorBufferFormatᅟ

• fixedColorBufferSizeᅟ

• mirrorVerticallyᅟ

• sampleCountᅟ

方法

• 方法 __init__()

• 方法 api()

• 方法 colorBufferFormat()

• 方法 colorTexture()

• 方法 depthStencilBuffer()

• 方法 fixedColorBufferSize()

• 方法 grabFramebuffer()

• 方法 isAutoRenderTargetEnabled()

• 方法 isDebugLayerEnabled()

• 定义 isMirrorVerticallyEnabled()

• 定义 msaaColorBuffer()

• 定义 renderTarget()

• 定义 resolveTexture()

• 定义 rhi()

• 定义 sampleCount()

• 定义 setApi()

• 定义 setAutoRenderTarget()

• 定义 setColorBufferFormat()

• 定义 setDebugLayerEnabled()

• 定义 setFixedColorBufferSize()

• 定义 setMirrorVertically()

• 定义 setSampleCount()

虚函数

• 定义 initialize()

• 定义 releaseResources()

• 定义 render()

信号

• 定义 colorBufferFormatChanged()

• 定义 fixedColorBufferSizeChanged()

• 定义 frameSubmitted()

• 定义 mirrorVerticallyChanged()

• 定义 renderFailed()

• def sampleCountChanged()

注意

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

详细描述

警告

本节包含从 C++ 自动翻译成 Python 的代码片段，可能包含错误。

注意

QRhiWidget 在 Qt 6.7 中处于技术预览阶段。 API 正处于开发中，并可能发生变化。

QRhiWidget 提供在基于 QWidget 的应用程序中显示通过 QRhi API 渲染的 3D 内容的功能。在许多方面，它是 QOpenGLWidget 的可移植等效物，不受单个 3D 图形 API 的限制，而是可以与 QRhi 所支持的所有 API（例如，Direct 3D 11/12、Vulkan、Metal 和 OpenGL）一起工作。

QRhiWidget 预期将被子类化。为了将内容渲染到由 QRhiWidget 隐式创建和管理 的二维纹理，子类应重写虚拟函数 initialize() 和 render()。

默认情况下，纹理的大小将根据小部件的大小自动调整。如果更倾向于固定大小，可以通过调用 setFixedColorBufferSize() 来设置指定像素的固定大小。

除了用作颜色缓冲区的纹理外，还隐式维护了一个用于深度/模板缓冲区和将这些绑定的渲染目标缓冲区。

小部件的最顶层窗口的 QRhi 默认配置为使用特定平台的后端和图形 API：macOS 和 iOS 上的 Metal、Windows 上的 Direct 3D 11，否则为 OpenGL。通过调用 setApi() 来 Override 这一点。

注意

单个小部件窗口只能使用一个 QRhi 后端，因此只能使用一个 3D 图形 API。如果窗口的小部件层次结构中的两个 QRhiWidget 或 QQuickWidget 小部件请求不同的 API，则只有其中一个可以正常工作。

注意

QRhiWidget 是一个公共的 Qt API，但在 Qt Gui 模块中，包括 QRhi、QShader 和 QShaderDescription 在内的 QRhi 类族仅提供有限的兼容性保证。这些类的源代码或二进制兼容性没有保证，这意味着 API 仅保证与应用程序开发版本相同版本的 Qt 兼容。然而，源代码不兼容的更改目标是最大限度地减少，并且仅会在小版本（6.7、6.8 等等）中实施。文件 qrhiwidget.h 不会直接包含任何与 QRhi 相关的头部文件。要实现 QRhiWidget 的子类时使用这些类，如果使用 CMake，请链接到 Qt::GuiPrivate，并使用带有 rhi 前缀的适当头部文件，例如 #include <rhi/qrhi.h>。

以下是一个简单的 QRhiWidget 子类的示例，该子类渲染一个三角形：

class ExampleRhiWidget(QRhiWidget):

# public
    ExampleRhiWidget(QWidget parent = None) : QRhiWidget(parent) { }
    def initialize(cb):
    def render(cb):
# private
    m_rhi = None
    std.unique_ptr<QRhiBuffer> m_vbuf
    std.unique_ptr<QRhiBuffer> m_ubuf
    std.unique_ptr<QRhiShaderResourceBindings> m_srb
    std.unique_ptr<QRhiGraphicsPipeline> m_pipeline
    m_viewProjection = QMatrix4x4()
    m_rotation = 0.0f

vertexData = {
     0.0f, 0.5f, 1.0f, 0.0f, 0.0f,
    -0.5f, -0.5f, 0.0f, 1.0f, 0.0f,
     0.5f, -0.5f, 0.0f, 0.0f, 1.0f,

def getShader(name):

    f = QFile(name)
    return f.open(QIODevice.ReadOnly) if QShader.fromSerialized(f.readAll()) else QShader()

def initialize(self, cb):

    if m_rhi != rhi():
        m_pipeline.reset()
        m_rhi = rhi()

    if not m_pipeline:
        m_vbuf.reset(m_rhi.newBuffer(QRhiBuffer.Immutable, QRhiBuffer.VertexBuffer, sizeof(vertexData)))
        m_vbuf.create()
        m_ubuf.reset(m_rhi.newBuffer(QRhiBuffer.Dynamic, QRhiBuffer.UniformBuffer, 64))
        m_ubuf.create()
        m_srb.reset(m_rhi.newShaderResourceBindings())
        m_srb.setBindings({
            QRhiShaderResourceBinding.uniformBuffer(0, QRhiShaderResourceBinding.VertexStage, m_ubuf.get()),
        })
        m_srb.create()
        m_pipeline.reset(m_rhi.newGraphicsPipeline())
        m_pipeline.setShaderStages({
            { QRhiShaderStage.Vertex, getShader(":/shader_assets/color.vert.qsb") },
            { QRhiShaderStage.Fragment, getShader(":/shader_assets/color.frag.qsb") }
        })
        inputLayout = QRhiVertexInputLayout()
        inputLayout.setBindings({
            { 5 * sizeof(float) }
        })
        inputLayout.setAttributes({
            { 0, 0, QRhiVertexInputAttribute.Float2, 0 },
            { 0, 1, QRhiVertexInputAttribute.Float3, 2 * sizeof(float) }
        })
        m_pipeline.setVertexInputLayout(inputLayout)
        m_pipeline.setShaderResourceBindings(m_srb.get())
        m_pipeline.setRenderPassDescriptor(renderTarget().renderPassDescriptor())
        m_pipeline.create()
        resourceUpdates = m_rhi.nextResourceUpdateBatch()
        resourceUpdates.uploadStaticBuffer(m_vbuf.get(), vertexData)
        cb.resourceUpdate(resourceUpdates)

    outputSize = colorTexture().pixelSize()
    m_viewProjection = m_rhi.clipSpaceCorrMatrix()
    m_viewProjection.perspective(45.0f, outputSize.width() / (float) outputSize.height(), 0.01f, 1000.0f)
    m_viewProjection.translate(0, 0, -4)

def render(self, cb):

    resourceUpdates = m_rhi.nextResourceUpdateBatch()
    m_rotation += 1.0f
    modelViewProjection = m_viewProjection
    modelViewProjection.rotate(m_rotation, 0, 1, 0)
    resourceUpdates.updateDynamicBuffer(m_ubuf.get(), 0, 64, modelViewProjection.constData())
    clearColor = QColor.fromRgbF(0.4f, 0.7f, 0.0f, 1.0f)
    cb.beginPass(renderTarget(), clearColor, { 1.0f, 0 }, resourceUpdates)
    cb.setGraphicsPipeline(m_pipeline.get())
    outputSize = colorTexture().pixelSize()
    cb.setViewport(QRhiViewport(0, 0, outputSize.width(), outputSize.height()))
    cb.setShaderResources()
    QRhiCommandBuffer.VertexInput vbufBinding(m_vbuf.get(), 0)
    cb.setVertexInput(0, 1, vbufBinding)
    cb.draw(3)
    cb.endPass()
    update()

这是一个不断请求更新、由显示速率（与屏幕刷新率相关的 vsync）节流的窗口小部件。如果不需要连续渲染，应该从 render() 中的 update() 调用中删除，而是仅在更新渲染内容时发出。例如，如果立方体的旋转应该与一个 QSlider 的值绑定，那么将滑动条的值更改信号连接到一个槽或 lambda，该 lambda 将转发新值并调用 update() 即可。

顶点和片段着色器以 Vulkan 风格的 GLSL 提供，必须首先由 Qt 着色器基础设施处理。这可以通过手动运行 qsb 命令行工具实现，或者使用 CMake 中的 qt_add_shaders() 函数。QRhiWidget 实现将加载与应用程序一起提供的预处理的 .qsb 文件。有关 Qt 着色器翻译基础设施的更多信息，请参阅 Qt 着色器工具。

这些着色器的源代码可能是以下内容：

color.vert

#version 440
layout(location = 0) in vec4 position;
layout(location = 1) in vec3 color;
layout(location = 0) out vec3 v_color;
layout(std140, binding = 0) uniform buf {
    mat4 mvp;
};

void main()
{
    v_color = color;
    gl_Position = mvp * position;
}

color.frag

#version 440
layout(location = 0) in vec3 v_color;
layout(location = 0) out vec4 fragColor;

void main()
{
    fragColor = vec4(v_color, 1.0);
}

结果的窗口小部件显示以下内容：

有关完整的最小入门示例，请查看 简单 RHI 窗口小部件示例 。

有关具有更多功能和进一步概念的演示示例，请参阅 立方体 RHI 窗口小部件示例 。

QRhiWidget 总是涉及到将渲染输出到一个后缓冲纹理，而不是直接到窗口（由窗口系统提供的原生窗口的表面或层）。这允许正确地将内容与基于小部件的UI的其他部分进行合成，并提供一个简单紧凑的API，使得入门变得容易。所有这些都需要额外的资源，并可能对性能产生影响。这在实践中通常是完全可以接受的，但高级用户应该牢记不同方法的优势和劣势。有关这两种方法的具体信息，请参阅RHI窗口示例，并与简单RHI小部件示例进行比较。

将 QRhiWidget 调整到属于不同窗口（顶级小部件）的窗口层次结构中，或者将 QRhiWidget 本身作为顶级小部件（通过将父对象设置为 None），涉及到在 QRhiWidget 仍然保持活跃正常的同时更改相关的 QRhi（并可能销毁旧的一个）。为了支持这一点，期望健壯的 QRhiWidget 实现重新实现了 releaseResources() 虚拟函数，并且像在析构函数中原样丢弃它们的 QRhi 资源。《Cube RHI小部件示例》演示了这一实践。

虽然不是主要用例，但 QRhiWidget 也允许直接使用3D图形API，如Vulkan、Metal、Direct3D或OpenGL的渲染代码。有关在QRhi渲染通道中记录原生命令的详细信息，请参阅QRhiCommandBuffer::beginExternal()，以及有关如何包装现有原生纹理并随后在随后的渲染通道中使用它的QRhiTexture::createFrom()。但是请注意，由于 QRhiWidget 的主要目的是提供一个适合基于QRhi的渲染代码的环境，而不是启用任意、可能复杂的foreign渲染引擎，因此底层图形API的可配置性（其设备或上下文功能、层、扩展等）将会受到限制。

另请参阅

简单RHI小部件示例 Cube RHI小部件示例

class Api

指定要使用的3D API和QRhi后端

常数	描述
QRhiWidget.Api.Null
QRhiWidget.Api.OpenGL
QRhiWidget.Api.Metal
QRhiWidget.Api.Vulkan
QRhiWidget.Api.Direct3D11
QRhiWidget.Api.Direct3D12

另请参阅

QRhi

class TextureFormat

指定 QRhiWidget 生成的纹理的格式

常数	描述
QRhiWidget.TextureFormat.RGBA8	请参见QRhiTexture::RGBA8。
QRhiWidget.TextureFormat.RGBA16F	参见 QRhiTexture::RGBA16F。
QRhiWidget.TextureFormat.RGBA32F	参见 QRhiTexture::RGBA32F。
QRhiWidget.TextureFormat.RGB10A2	参见 QRhiTexture::RGB10A2。

另请参阅

QRhiTexture

注意

当使用 from __feature__ import true_property 时，可以直接使用属性，否则通过访问器函数进行访问。

属性colorBufferFormat: QRhiWidget.TextureFormat

该属性控制用作颜色缓冲区的纹理（或渲染缓冲区）的纹理格式。默认值是 RGBA8。PySide6.QtWidgets.QRhiWidget 支持渲染到 QRhiTexture 支持的一部分格式。只有从 QRhi::isTextureFormatSupported() 报告为支持的格式才应指定，否则渲染将无法正常工作。

注意

当小部件已经初始化并进行了渲染时设置新的格式意味着所有由渲染器创建的 QRhiGraphicsPipeline 对象可能变得不可用，如果由于纹理格式的不同，关联的 QRhiRenderPassDescriptor 现在不兼容。类似于动态更改 sampleCount，这意味着 initialize() 或 render() 的实现必须注意释放现有的管道并创建新的管道。

访问函数

• colorBufferFormat()

• setColorBufferFormat()

• 信号 colorBufferFormatChanged()

属性fixedColorBufferSize: QSize

该属性表示关联纹理的固定尺寸（以像素为单位）。当需要一个不依赖于小部件大小的固定纹理大小时，此属性很有用。该尺寸对小部件的几何形状（其大小和位于顶级窗口中的位置）没有影响，这意味着纹理的内容将拉伸（放大）或缩小到小部件的区域中。

例如，将大小设置为小部件大小（像素）的两倍实际上会执行 2x 超采样（以两倍分辨率渲染，然后在将对应于窗口中小部件的四边形进行纹理化时隐式缩小）。

默认情况下，值是一个空的QSize。空或空的QSize表示纹理的大小遵循：QRhiWidget 的大小。(texture size = widget size * device pixel ratio)。

访问函数

• fixedColorBufferSize()

• setFixedColorBufferSize()

• 信号 fixedColorBufferSizeChanged()

属性mirrorVertically:bool

当启用时，在组合QRhiWidget 的底层纹理和顶层窗口中其余控件内容时，会在X轴周围翻转图像。

默认值为 false。

访问函数

• isMirrorVerticallyEnabled()

• setMirrorVertically()

• 信号 mirrorVerticallyChanged()

属性sampleCount:int

该属性用于控制多采样抗锯齿的采样数。默认值为 1，表示已禁用MSAA。

有效值为 1, 4, 8，有时为 16 和 32。可以通过 QRhi::supportedSampleCounts() 在运行时查询支持哪些采样数，但通常应用程序应请求 1（无MSAA）、4x（普通MSAA）或 8x（高MSAA）。

注意

设置新值意味着渲染器创建的所有 QRhiGraphicsPipeline 对象都必须从那时起使用相同的采样数。已使用不同采样数创建的现有 QRhiGraphicsPipeline 对象不得再使用。当值更改时，所有颜色和深度-模板缓冲区将自动销毁并重新创建，并且将再次调用 initialize()。但是，当 autoRenderTarget 为 false 时，深度-模板缓冲区或额外颜色缓冲区的管理将由应用程序负责。

将样本数量从默认值1更改为更高值意味着 colorTexture() 变为 None，并且 msaaColorBuffer() 开始返回一个有效对象。切换回1（或0）意味着相反：在下一次调用 initialize() 时，msaaColorBuffer() 将返回 None，而 colorTexture() 再次变为有效。此外，resolveTexture() 在样本数量大于1（即使用MSAA）时返回一个有效的（非多采样）QRhiTexture。

另请参阅

msaaColorBuffer() resolveTexture()

访问函数

• sampleCount()

• setSampleCount()

• 信号 sampleCountChanged()

__init__([parent=None[, f={}]])

参数:

• parent – QWidget

• f – WindowType 的组合

构建一个作为 parent 的子对象的控件，其控件标志设置为 f。

api()

返回类型:

Api

返回当前设置的图形API（QRhi后端）。

另请参阅

setApi()

colorBufferFormat()

返回类型:

TextureFormat

另请参阅

setColorBufferFormat()

属性 colorBufferFormatᅟ 的获取器。

colorBufferFormatChanged(format)

参数:

format – TextureFormat

属性 colorBufferFormat 的通知信号。

colorTexture()

返回类型:

QRhiTexture

返回作为小部件颜色缓冲区的纹理。

仅可以从 initialize() 和 render() 调用。

与深度缓冲区和QRhiRenderTarget不同，这个纹理总是可用且由 QRhiWidget 管理，与 autoRenderTarget 的值无关。

注意

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

注意

也可以通过从 renderTarget() 返回的 QRhiRenderTarget 查询绑定量大小和样本数。这比从 QRhiTexture 或 QRhiRenderBuffer 中查询更方便、更紧凑，因为无论是否使用多采样，它都可以工作。

另请参阅

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

depthStencilBuffer()

返回类型:

QRhiRenderBuffer

返回小部件渲染所使用的深度-模板缓冲区。

仅可以从 initialize() 和 render() 调用。

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

另请参阅

colorTexture() renderTarget()

fixedColorBufferSize()

返回类型:

QSize

另请参阅

setFixedColorBufferSize()

属性 fixedColorBufferSize 的获取器。

fixedColorBufferSizeChanged(pixelSize)

参数:

pixelSize - QSize

属性 fixedColorBufferSize 的通知信号。

frameSubmitted()

在窗口完成合成并提交帧后发出此信号。

grabFramebuffer()

返回类型:

QImage

渲染新帧，读取纹理内容，并以 QImage 的形式返回。

出错时返回空的 QImage。

返回的 QImage 将具有以下格式之一：QImage::Format_RGBA8888，QImage::Format_RGBA16FPx4，QImage::Format_RGBA32FPx4 或 QImage::Format_BGR30，具体取决于 colorBufferFormat()。

QRhiWidget 不了解渲染器的混合和合成方法，因此无法确定输出 RGB 颜色值中是否预乘了 Alpha 值。因此，即使在适当的情况下，也不使用 _Premultiplied QImage 格式，调用者需要根据需要重新解释结果数据。

注意

当 QRhiWidget 未添加到属于屏幕顶层窗口的窗口层次结构时，也可以调用此函数。这使得可以生成来自屏幕外三维渲染的图像。

该函数命名为 grabFramebuffer() 以与 QOpenGLWidget 和 QQuickWidget 保持一致。这不是从 QRhiWidget 的内容获取 CPU 端图像数据的唯一方法：在 QRhiWidget 或其祖先上调用 grab() 也是一种功能（返回 QPixmap）。除了直接与 QImage 一起使用外，grabFramebuffer() 的另一个优点可能更高效，仅因为它不需要通过 QWidget 基础设施的其他部分，可以直接触发渲染新帧并进行读取。

另请参阅

setColorBufferFormat()

initialize(cb)

参数:

cb – QRhiCommandBuffer

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

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

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

实现应准备QRhi对象和颜色缓冲区纹理可能在函数调用之间发生变化。一个特殊情况是执行一个带有尚未显示的小部件的grabFramebuffer()，然后在一个顶级窗口中将小部件显示在屏幕上。在那里，抓取会在一个专门的QRhi上发生，然后在随后的initialize()和render()调用中使用顶级窗口相关联的QRhi代替。另一个更常见的例子是，当小部件被重新设置所有权以属于一个新的顶级窗口时。在这种情况下，QRhi和QRhiWidget管理的所有相关资源都将不同实例，在随后的函数调用中调用此函数。在这种情况下，确保销毁先前由子类创建的所有现有QRhi资源非常重要，因为这些资源属于之前不应再由小部件使用的QRhi。

当 autoRenderTarget 为真（默认值），则创建并自动管理与 colorTexture() （或 msaaColorBuffer()） 和深度模板缓存关联的深度模板 QRhiRenderBuffer 和 QRhiTextureRenderTarget。在 render() 的重新实现中，可以通过 depthStencilBuffer() 和 renderTarget() 进行对象查询。当 autoRenderTarget 被设置为 false 时，这些对象不再被自动创建和管理。相反，initialize() 实现将负责根据需要创建缓存和设置渲染目标。当手动管理用于渲染目标的附加颜色或深度模板时，它们的大小和采样数量必须始终遵循 colorTexture() / msaaColorBuffer() 的大小和采样数量，否则可能发生渲染或3D API验证错误。

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

cb 是窗口当前帧的 QRhiCommandBuffer。当需要记录帧时，调用此函数，但不激活渲染通道。命令缓存主要提供允许在不推迟到 render() 的情况下进行资源更新的可能性。

另请参阅

render()

isAutoRenderTargetEnabled()

返回类型:

bool

isDebugLayerEnabled()

返回类型:

bool

如果适用，如果正在使用的图形API请求调试或验证层，则返回 true。

另请参阅

setDebugLayerEnabled()

isMirrorVerticallyEnabled()

返回类型:

bool

属性 mirrorVertically 的获取器。

mirrorVerticallyChanged(enabled)

参数:

enabled - bool

mirrorVertically 属性的通知信号。

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，其中提供了多采样渲染缓冲区但未提供多采样纹理，`QRhiWidget` 始终通过使用多采样 QRhiRenderBuffer 作为颜色附加（而永远不会使用多采样 QRhiTexture）来执行 MSAA。

注意

也可以通过从 renderTarget() 返回的 QRhiRenderTarget 查询绑定量大小和样本数。这比从 QRhiTexture 或 QRhiRenderBuffer 中查询更方便、更紧凑，因为无论是否使用多采样，它都可以工作。

另请参阅

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

releaseResources()

在需要提前释放图形资源时调用。

这种情况通常不会发生在被添加到顶级控件子层次结构中并持续存在的 QRhiWidget 上。因此，在很多情况下，不需要重新实现此功能，例如，因为应用程序始终只有一个顶级控件（原生窗口）。然而，当涉及到控件（或其祖先）的重父子化时，对 QRhiWidget 子类的稳健、良好编写的重新实现此功能是必要的。

当调用此函数时，预期实现将销毁所有 QRhi 资源（QRhiBuffer、QRhiTexture 等对象），类似于在析构函数中预期的方式。还需要清空、使用智能指针或设置 resources-invalid 标志，因为最终会调用 initialize()。然而，将资源释放推迟到后续的 initialize() 是错误的。如果调用此函数，则在返回之前必须释放资源。此外，实现此函数并不代替类的析构函数（或智能指针）：必须在两个地方都释放图形资源。

请参阅 Cube RHI Widget 示例，了解此功能的实际应用。在那里，切换 QRhiWidget 之间的子控件（由于具有父控件）和顶级控件（由于没有父控件）的按钮，将在 QRhiWidget 的生命周期内触发调用此函数，因为在 QRhiWidget 中，相关的顶级控件、原生窗口和 QRhi 都发生了变化，使用过的 QRhi 被销毁，这意味着关联的资源提前释放。

调用此函数的另一个情况是当使用 grabFramebuffer() 时，如果没有将 QRhiWidget 添加到可见窗口中，即渲染是在屏幕外进行的。如果稍后使此 QRhiWidget 可见或添加到可见的控件层次结构中，关联的 QRhi 将从用于屏幕外渲染的临时 QRhi 变为窗口的专用 QRhi，从而触发此函数。

另请参阅

initialize()

render(cb)

参数:

cb – QRhiCommandBuffer

当控件内容（即纹理的内容）需要更新时调用。

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

要请求更新，请调用 update() 。在 render() 函数内部调用 update() 将导致持续更新，通过 vsync 进行节流。

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

另请参阅

initialize()

renderFailed()

此信号在组件应该将其后缓冲区渲染到组件的任何时间发出（无论是由于调用 widget update 还是由于调用 grabFramebuffer() ），但没有可用的 QRhi 组件，可能是因为图形配置问题引起的。

当出现问题时，该信号可能被多次发出。不要假设它只被发出一次。如果错误处理代码要通知一次，请以 Qt::SingleShotConnection 链接。

renderTarget()

返回类型:

QRhiRenderTarget

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

仅可以从 initialize() 和 render() 调用。

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

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

另请参阅

colorTexture() depthStencilBuffer()

resolveTexture()

返回类型:

QRhiTexture

返回多样本内容解相的多样本纹理。

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

仅可以从 initialize() 和 render() 调用。

启用MSAA后，这是与屏幕上其余QWidget内容进行合成的纹理。然而，QRhiWidget的渲染必须针对从msaaColorBuffer() 返回的（多重采样）QRhiRenderBuffer。当autoRenderTarget为true时，这是由renderTarget() 返回的QRhiRenderTarget来处理的。否则，就需要子类代码正确配置一个同时具有颜色缓冲区和解决纹理的渲染目标对象。

另请参阅

colorTexture()

rhi()

返回类型:

QRhi

返回当前的QRhi对象。

仅可以从 initialize() 和 render() 调用。

sampleCount()

返回类型:

int

另请参阅

setSampleCount()

属性sampleCount的获取器。

sampleCountChanged(samples)

参数:

samples – int

属性sampleCount的信号通知。

setApi(api)

参数:

api – Api

将图形单元和QRhi后端设置到使用api。

警告

必须尽早调用此函数，在将小部件添加到小部件层次结构并在屏幕上显示之前。例如，尝试在子类构造函数中对函数进行调用。如果调用过晚，函数将不起作用。

默认值取决于平台：macOS和iOS上的Metal，Windows上的Direct 3D 11，否则为OpenGL。

api只能为窗口设置一次，一旦完成并生效，窗口就只能使用该API和QRhi后端进行渲染。尝试设置另一个值，或尝试添加具有不同api的另一个QRhiWidget将无法按预期工作。

另请参阅

setColorBufferFormat() setDebugLayerEnabled() api()

setAutoRenderTarget(enabled)

参数:

enabled - bool

控制部件是否自动创建并维护深度-模板 QRhiRenderBuffer 和 QRhiTextureRenderTarget。默认值为 true。

在自动模式下，深度-模板缓冲区的大小和样本计数遵循颜色缓冲纹理的设置。在非自动模式下，renderTarget() 和 depthStencilBuffer() 总是返回 None，此时应用程序的 initialize() 实现需要负责设置和管理这些对象。

在早期调用此函数，例如在派生类的构造函数中，将 enabled 设置为 false 以禁用自动模式。

setColorBufferFormat(format)

参数:

format – TextureFormat

另请参阅

colorBufferFormat()

colorBufferFormatᅟ 属性的设置器。

setDebugLayerEnabled(enable)

参数:

enable – bool

当 enable 为 true 时，请求底层图形 API 的调试或验证层。

警告

必须尽早调用此函数，在将小部件添加到小部件层次结构并在屏幕上显示之前。例如，尝试在子类构造函数中对函数进行调用。如果调用过晚，函数将不起作用。

适用于 Vulkan 和 Direct 3D。

默认情况下，此选项已禁用。

另请参阅

setApi() isDebugLayerEnabled()

setFixedColorBufferSize(pixelSize)

参数:

pixelSize - QSize

另请参阅

fixedColorBufferSize()

fixedColorBufferSizeᅟ 属性的设置器。

setFixedColorBufferSize(w, h)

参数:

• w – int

• h – int

setMirrorVertically(enabled)

参数:

enabled - bool

属性 mirrorVerticallyᅟ 的设置器。

setSampleCount(samples)

参数:

samples – int

另请参阅

sampleCount()

属性 sampleCountᅟ 的设置器。