PySide6.QtWidgets.QRhiWidget¶

class QRhiWidget¶

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

在版本6.7中添加。

概要¶

注意

本文档可能包含从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 隐式创建和管理的2D纹理中，子类应重新实现虚函数 initialize() 和 render() 。

纹理的大小默认会适应小部件的大小。如果希望固定大小，可以通过调用setFixedColorBufferSize()来设置以像素为单位的固定大小。

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

小部件的顶级窗口的QRhi默认配置为使用平台特定的后端和图形API：在macOS和iOS上使用Metal，在Windows上使用Direct 3D 11，其他情况下使用OpenGL。调用setApi()来覆盖此设置。

注意

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

注意

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

以下是一个简单的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函数，该函数转发新值并调用update()就足够了。

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

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

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);
}

结果是一个显示以下内容的小部件：

要查看一个完整、最小化的入门示例，请查看 Simple RHI Widget Example 。

有关更多功能和进一步概念演示的示例，请参见Cube RHI Widget Example。

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

将一个QRhiWidget重新父级化到一个属于不同窗口（顶级小部件）的小部件层次结构中，或者使QRhiWidget本身成为顶级小部件（通过将父级设置为None），涉及更改关联的QRhi（并可能销毁旧的QRhi），而QRhiWidget继续保持活动状态。为了支持这一点，健壮的QRhiWidget实现应重新实现releaseResources()虚函数，并在析构函数中释放其QRhi资源。Cube RHI Widget Example在实践中展示了这一点。

虽然不是主要用例，QRhiWidget 也允许集成直接使用3D图形API（如Vulkan、Metal、Direct 3D或OpenGL）的渲染代码。有关在QRhi渲染过程中记录本地命令的详细信息，请参见QRhiCommandBuffer::beginExternal()，以及QRhiTexture::createFrom()，该方法可以包装现有的本地纹理，然后在后续的渲染过程中与QRhi一起使用。但请注意，底层图形API（其设备或上下文功能、层、扩展等）的可配置性将受到限制，因为QRhiWidget的主要目标是提供一个适合基于QRhi的渲染代码的环境，而不是启用任意、可能复杂的外部渲染引擎。

另请参阅

简单的RHI小部件示例立方体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

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

class TextureFormat¶

指定QRhiWidget渲染的纹理格式。

常量

描述

QRhiWidget.TextureFormat.RGBA8

参见 QRhiTexture::RGBA8。

QRhiWidget.TextureFormat.RGBA16F

参见 QRhiTexture::RGBA16F。

QRhiWidget.TextureFormat.RGBA32F

参见 QRhiTexture::RGBA32F。

QRhiWidget.TextureFormat.RGB10A2

参见 QRhiTexture::RGB10A2。

另请参阅

QRhiTexture

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

注意

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

property colorBufferFormatᅟ: QRhiWidget.TextureFormat¶

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

注意

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

Access functions:

colorBufferFormat()
setColorBufferFormat()
信号 colorBufferFormatChanged()

property fixedColorBufferSizeᅟ: QSize¶

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

例如，设置一个正好是部件（像素）大小两倍的尺寸，实际上执行了2倍超采样（以两倍分辨率渲染，然后在为窗口中对应部件的四边形进行纹理处理时隐式缩小）。

默认值为空的QSize。空或空的QSize意味着纹理的大小跟随QRhiWidget的大小。(texture size = widget size * device pixel ratio).

Access functions:

fixedColorBufferSize()
setFixedColorBufferSize()
信号 fixedColorBufferSizeChanged()

property mirrorVerticallyᅟ: bool¶

启用后，在将QRhiWidget的底层纹理与顶层窗口中的其他小部件内容合成时，围绕X轴翻转图像。

默认值为false。

Access functions:

isMirrorVerticallyEnabled()
setMirrorVertically()
信号 mirrorVerticallyChanged()

property 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()再次变为有效。此外，当样本计数大于1时（即使用MSAA），resolveTexture()返回一个有效的（非多重采样）QRhiTexture。

另请参阅

msaaColorBuffer() resolveTexture()

Access functions:

sampleCount()
setSampleCount()
信号 sampleCountChanged()

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

Parameters:

parent – QWidget
f – WindowType 的组合

构造一个作为parent子部件的小部件，小部件标志设置为f。

api()¶

Return type:: Api

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

另请参阅

setApi()

colorBufferFormat()¶

Return type:: TextureFormat

另请参阅

setColorBufferFormat()

属性 colorBufferFormatᅟ 的获取器。

colorBufferFormatChanged(format)¶

Parameters:: 格式 – TextureFormat

属性 colorBufferFormatᅟ 的通知信号。

colorTexture()¶

Return type:: QRhiTexture

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

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

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

注意

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

注意

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

另请参阅

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

depthStencilBuffer()¶

Return type:: QRhiRenderBuffer

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

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

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

另请参阅

colorTexture() renderTarget()

fixedColorBufferSize()¶

Return type:: QSize

另请参阅

setFixedColorBufferSize()

属性 fixedColorBufferSizeᅟ 的获取器。

fixedColorBufferSizeChanged(pixelSize)¶

Parameters:: pixelSize – QSize

属性 fixedColorBufferSizeᅟ 的通知信号。

frameSubmitted()¶

此信号在小部件的顶层窗口完成组合并提交帧后发出。

grabFramebuffer()¶

Return type:: QImage

渲染一个新帧，读取纹理的内容，并将其作为QImage返回。

当发生错误时，返回一个空的QImage。

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

QRhiWidget 不知道渲染器的混合和合成方法，因此无法知道输出是否在RGB颜色值中预乘了alpha。因此，即使合适，返回的QImage也从不使用_Premultiplied QImage格式。由调用者根据需要重新解释结果数据。

注意

此函数也可以在QRhiWidget未添加到属于屏幕上顶层窗口的小部件层次结构时调用。这允许从屏幕外的3D渲染生成图像。

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

另请参阅

setColorBufferFormat()

initialize(cb)¶

Parameters:: cb – QRhiCommandBuffer

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

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

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

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

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

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

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

另请参阅

render()

isAutoRenderTargetEnabled()¶

Return type:: 布尔

isDebugLayerEnabled()¶

Return type:: 布尔

如果适用，将请求调试或验证层，则返回 true。

另请参阅

setDebugLayerEnabled()

isMirrorVerticallyEnabled()¶

Return type:: 布尔

属性 mirrorVerticallyᅟ 的获取器。

mirrorVerticallyChanged(enabled)¶

Parameters:: enabled – 布尔值

属性 mirrorVerticallyᅟ 的通知信号。

msaaColorBuffer()¶

Return type:: QRhiRenderBuffer

返回作为小部件多重采样颜色缓冲区的渲染缓冲区。

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

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

当未使用MSAA时，返回值为None。此时请使用colorTexture()代替。

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

注意

另请参阅

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

releaseResources()¶

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

这通常不会发生在一个被添加到顶级窗口部件子层次结构中的QRhiWidget，并且它会在其和顶级窗口部件的生命周期内一直存在。因此，在许多情况下，不需要重新实现此函数，例如因为应用程序只有一个顶级窗口部件（原生窗口）。然而，当涉及到窗口部件（或其祖先）的重新父级化时，在健壮、编写良好的QRhiWidget子类中重新实现此函数将变得必要。

当调用此函数时，实现应销毁所有QRhi资源（QRhiBuffer、QRhiTexture等对象），类似于在析构函数中所期望的操作。同样需要将资源置空、使用智能指针或设置resources-invalid标志，因为initialize()最终会在之后被调用。但请注意，将资源的释放推迟到后续的initialize()是错误的。如果调用了此函数，必须在返回之前释放资源。还要注意，实现此函数并不能替代类析构函数（或智能指针）：图形资源仍然必须在两者中释放。

请参阅Cube RHI Widget示例以查看实际操作的示例。在那里，切换QRhiWidget作为子部件（由于有父部件）和作为顶级部件（由于没有父部件）的按钮将触发调用此函数，因为相关的顶级部件、本机窗口和QRhi在QRhiWidget的生命周期内都会发生变化，之前使用的QRhi将被销毁，这意味着由仍然存活的QRhiWidget管理的相关资源将提前释放。

另一个调用此函数的情况是当grabFramebuffer()与未添加到可见窗口的QRhiWidget一起使用时，即渲染是在屏幕外执行的。如果稍后这个QRhiWidget变为可见，或者被添加到可见的小部件层次结构中，关联的QRhi将从用于屏幕外渲染的临时QRhi更改为窗口的专用QRhi，从而也会触发此函数。

另请参阅

initialize()

render(cb)¶

Parameters:: cb – QRhiCommandBuffer

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

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

要请求更新，请调用update()。在render()中调用update()将导致持续更新，受vsync限制。

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

另请参阅

initialize()

renderFailed()¶

每当小部件应该渲染到其背景纹理时（无论是由于widget update还是由于调用了grabFramebuffer()），但小部件没有可用的QRhi，可能是由于与图形配置相关的问题，就会发出此信号。

当问题出现时，此信号可能会多次发出。不要假设它只发出一次。如果错误处理代码只需要被通知一次，请使用Qt::SingleShotConnection进行连接。

renderTarget()¶

Return type:: QRhiRenderTarget

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

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

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

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

另请参阅

colorTexture() depthStencilBuffer()

resolveTexture()¶

Return type:: QRhiTexture

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

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

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

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

另请参阅

colorTexture()

rhi()¶

Return type:: QRhi

返回当前的QRhi对象。

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

sampleCount()¶

Return type:: 整数

另请参阅

setSampleCount()

属性 sampleCountᅟ 的获取器。

sampleCountChanged(samples)¶

Parameters:: 样本 – int

属性 sampleCountᅟ 的通知信号。

setApi(api)¶

Parameters:: api – Api

设置要使用的图形API和QRhi后端为api。

警告

此函数必须在足够早的时候调用，即在部件被添加到部件层次结构并在屏幕上显示之前。例如，目标是为此子类的构造函数调用该函数。如果调用得太晚，该函数将不会产生任何效果。

默认值取决于平台：在macOS和iOS上为Metal，在Windows上为Direct 3D 11，其他情况下为OpenGL。

对于小部件及其顶层窗口，api 只能设置一次，一旦设置并生效，窗口只能使用该 API 和 QRhi 后端进行渲染。尝试设置另一个值，或添加另一个具有不同 api 的 QRhiWidget 将不会按预期工作。

另请参阅

setColorBufferFormat() setDebugLayerEnabled() api()

setAutoRenderTarget(enabled)¶

Parameters:: enabled – 布尔值

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

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

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

setColorBufferFormat(format)¶

Parameters:: 格式 – TextureFormat

另请参阅

colorBufferFormat()

属性 colorBufferFormatᅟ 的设置器。

setDebugLayerEnabled(enable)¶

Parameters:: enable – 布尔值

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

警告

适用于Vulkan和Direct 3D。

默认情况下，这是禁用的。

另请参阅

setApi() isDebugLayerEnabled()

setFixedColorBufferSize(pixelSize)¶

Parameters:: pixelSize – QSize

另请参阅

fixedColorBufferSize()

属性 fixedColorBufferSizeᅟ 的设置器。

setFixedColorBufferSize(w, h)

Parameters:

w – 整数
h – 整数

setMirrorVertically(enabled)¶

Parameters:: enabled – 布尔值

属性 mirrorVerticallyᅟ 的设置器。

setSampleCount(samples)¶

Parameters:: 样本 – int

另请参阅

sampleCount()

属性 sampleCountᅟ 的设置器。

PySide6.QtWidgets.QRhiWidget¶

概要¶

属性¶

方法¶

虚拟方法¶

信号¶

详细描述¶