QRhiWidget Class

class ExampleRhiWidget : public QRhiWidget
{
public:
    ExampleRhiWidget(QWidget *parent = nullptr) : QRhiWidget(parent) { }
    void initialize(QRhiCommandBuffer *cb) override;
    void render(QRhiCommandBuffer *cb) override;
private:
    QRhi *m_rhi = nullptr;
    std::unique_ptr<QRhiBuffer> m_vbuf;
    std::unique_ptr<QRhiBuffer> m_ubuf;
    std::unique_ptr<QRhiShaderResourceBindings> m_srb;
    std::unique_ptr<QRhiGraphicsPipeline> m_pipeline;
    QMatrix4x4 m_viewProjection;
    float m_rotation = 0.0f;
};

float 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,
};

QShader getShader(const QString &name)
{
    QFile f(name);
    return f.open(QIODevice::ReadOnly) ? QShader::fromSerialized(f.readAll()) : QShader();
}

void ExampleRhiWidget::initialize(QRhiCommandBuffer *cb)
{
    if (m_rhi != rhi()) {
        m_pipeline.reset();
        m_rhi = rhi();
    }

    if (!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(QLatin1String(":/shader_assets/color.vert.qsb")) },
            { QRhiShaderStage::Fragment, getShader(QLatin1String(":/shader_assets/color.frag.qsb")) }
        });
        QRhiVertexInputLayout inputLayout;
        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();

        QRhiResourceUpdateBatch *resourceUpdates = m_rhi->nextResourceUpdateBatch();
        resourceUpdates->uploadStaticBuffer(m_vbuf.get(), vertexData);
        cb->resourceUpdate(resourceUpdates);
    }

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

void ExampleRhiWidget::render(QRhiCommandBuffer *cb)
{
    QRhiResourceUpdateBatch *resourceUpdates = m_rhi->nextResourceUpdateBatch();
    m_rotation += 1.0f;
    QMatrix4x4 modelViewProjection = m_viewProjection;
    modelViewProjection.rotate(m_rotation, 0, 1, 0);
    resourceUpdates->updateDynamicBuffer(m_ubuf.get(), 0, 64, modelViewProjection.constData());

    const QColor clearColor = QColor::fromRgbF(0.4f, 0.7f, 0.0f, 1.0f);
    cb->beginPass(renderTarget(), clearColor, { 1.0f, 0 }, resourceUpdates);

    cb->setGraphicsPipeline(m_pipeline.get());
    const QSize outputSize = colorTexture()->pixelSize();
    cb->setViewport(QRhiViewport(0, 0, outputSize.width(), outputSize.height()));
    cb->setShaderResources();
    const QRhiCommandBuffer::VertexInput vbufBinding(m_vbuf.get(), 0);
    cb->setVertexInput(0, 1, &vbufBinding);
    cb->draw(3);

    cb->endPass();

    update();
}

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

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

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

成员函数文档

[explicit] QRhiWidget::QRhiWidget(QWidget *parent = nullptr, Qt::WindowFlags f = {})

构造一个 widget，它是parent 的子 widget，widget 标志设置为f 。

[override virtual noexcept] QRhiWidget::~QRhiWidget()

毁灭者

QRhiWidget::Api QRhiWidget::api() const

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

另请参阅 setApi().

[protected] QRhiTexture *QRhiWidget::colorTexture() const

返回作为 widget 颜色缓冲器的纹理。

只能在initialize() 和render() 中调用。

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

另请参见 msaaColorBuffer()、depthStencilBuffer()、renderTarget() 和resolveTexture()。

[protected] QRhiRenderBuffer *QRhiWidget::depthStencilBuffer() const

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

只能在initialize() 和render() 中调用。

只有当autoRenderTarget 是true 时才可用。否则返回值为nullptr ，并由initialize() 的重新实现来创建和管理深度钢网缓冲区和QRhiTextureRenderTarget 。

另请参见 colorTexture() 和renderTarget()。

[override virtual protected] bool QRhiWidget::event(QEvent *e)

重实现：QWidget::event(QEvent *event).

[signal] void QRhiWidget::frameSubmitted()

该信号在窗口部件的顶层窗口完成组成并显示submitted a frame 后发出。

QImage QRhiWidget::grabFramebuffer() const

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

如果出现错误，则会返回一个空的QImage 。

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

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

为了与QOpenGLWidget 和QQuickWidget 保持一致，该函数被命名为 grabFramebuffer()。这并不是从QRhiWidget 的内容中获取 CPU 端图像数据的唯一方法：在QRhiWidget 或其祖先上调用QWidget::grab() 也同样有效（返回QPixmap ）。除了直接使用QImage 外，grabFramebuffer() 的另一个优点是性能略高，因为它无需使用QWidget 基础架构的其他部分，而是可以立即触发渲染新帧，然后进行回读。

另请参见 setColorBufferFormat().

[virtual protected] void QRhiWidget::initialize(QRhiCommandBuffer *cb)

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

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

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

重新实现时还应做好准备，QRhi 对象和颜色缓冲区纹理可能会在调用该函数之间发生变化。在一种特殊情况下，对象会有所不同，那就是在对一个尚未显示的部件执行grabFramebuffer() 时，然后在一个顶层部件中使该部件在屏幕上可见。在这种情况下，将使用专用的QRhi 进行抓取，然后在随后的初始化() 和render() 调用中用顶层窗口的相关QRhi 代替。另一种更常见的情况是，当窗口部件被重新转属到一个新的顶层窗口时。在这种情况下，在随后调用该函数时，QRhi 和QRhiWidget 管理的所有相关资源都将是与之前不同的实例。重要的是，子类之前创建的所有QRhi 资源都将被销毁，因为它们属于之前的QRhi ，而小工具不应再使用这些资源。

当autoRenderTarget 为true 时（这是默认值），深度钢网QRhiRenderBuffer 和与colorTexture() （或msaaColorBuffer() ）相关的QRhiTextureRenderTarget 以及深度钢网缓冲区会自动创建和管理。初始化() 和render() 的重新实现可以通过depthStencilBuffer() 和renderTarget() 查询这些对象。当autoRenderTarget 设置为false 时，这些对象将不再自动创建和管理。相反，将由 initialize() 实现来创建缓冲区并设置合适的呈现目标。在手动管理渲染目标的附加颜色或深度模板附件时，它们的大小和样本数必须始终遵循colorTexture() /msaaColorBuffer() 的大小和样本数，否则可能会出现渲染或 3D API 验证错误。

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

cb 是部件当前帧的 。调用该函数时正在记录帧，但没有活动的渲染传递。提供命令缓冲区主要是为了在不延迟 () 的情况下排队 。QRhiCommandBuffer render resource updates

另请参阅 render()。

bool QRhiWidget::isDebugLayerEnabled() const

如果将请求调试层或验证层（如果适用于使用中的图形 API），则返回 true。

另请参见 setDebugLayerEnabled()。

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

返回作为 widget 多采样颜色缓冲区的 renderbuffer。

只能在initialize() 和render() 中调用。

当sampleCount 大于 1 且启用多采样反锯齿时，返回的QRhiRenderBuffer 将具有匹配的采样计数，并用作颜色缓冲区。用于渲染到该缓冲区的图形管道必须使用相同的样本数创建，深度模板缓冲区的样本数也必须匹配。多采样内容有望解析为从resolveTexture() 返回的纹理。当autoRenderTarget 为true 时，renderTarget() 会自动设置为这样做，方法是将 msaaColorBuffer() 设置为颜色附件 0 的renderbuffer ，并将resolveTexture() 设置为其resolveTexture 。

当不使用 MSAA 时，返回值为nullptr 。这时请使用colorTexture() 代替。

根据底层 3D 图形 API 的不同，多采样纹理和采样数大于 1 的彩色呈现缓冲区之间可能没有实际区别（QRhi 可能只是将两者映射到相同的本地资源类型）。不过，一些较早的应用程序接口可能会区分纹理和呈现缓冲区。在 OpenGL ES 3.0 中，多采样呈现缓冲区可用，但多采样纹理不可用，为了支持 OpenGL ES 3.0，QRhiWidget 在执行 MSAA 时总是使用多采样QRhiRenderBuffer 作为颜色附件（而不是多采样QRhiTexture ）。

另请参见 colorTexture()、depthStencilBuffer()、renderTarget() 和resolveTexture()。

[override virtual protected] void QRhiWidget::paintEvent(QPaintEvent *e)

重实现：QWidget::paintEvent(QPaintEvent *event).

处理绘画事件。

调用QWidget::update() 将导致发送油漆事件e ，从而调用此函数。事件的发送是异步的，将在从update() 返回后的某个时刻发生。然后，经过一些准备工作后，该函数将调用虚拟render() 来更新QRhiWidget 的相关纹理内容。然后，窗口小部件的顶层窗口将把纹理与窗口的其他内容合成在一起。

[virtual protected] void QRhiWidget::releaseResources()

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

通常情况下，如果QRhiWidget 被添加到顶层窗口部件的子层级结构中，并且在顶层窗口部件和顶层窗口部件的剩余生命周期中一直保留在该层级结构中，就不会出现这种情况。因此，在很多情况下，例如应用程序只有一个顶层部件（本地窗口），就没有必要重新实现该功能。但是，当涉及到部件（或其祖先）的再父系化时，在健壮、编写良好的QRhiWidget 子类中就有必要重新实现该函数。

调用该函数时，实现过程应销毁所有QRhi 资源（QRhiBuffer 、QRhiTexture 等对象），这与在析构函数中的做法类似。由于initialize() 最终会被调用，因此还需要清空、使用智能指针或设置resources-invalid 标志。但请注意，将释放资源的操作推迟到随后的initialize() 是错误的。如果调用了该函数，必须在返回之前放弃资源。还要注意的是，执行该函数并不能取代类的析构函数（或智能指针）：图形资源仍必须在这两个函数中释放。

请参阅Cube RHI Widget 示例以了解实际操作。在该示例中，在作为子窗口部件（由于有父窗口部件）和作为顶层窗口部件（由于没有父窗口部件）之间切换QRhiWidget 的按钮会触发调用该函数，因为相关的顶层窗口部件、本地窗口和QRhi 都会在QRhiWidget 的生命周期内发生变化，先前使用的QRhi 会被销毁，这意味着仍在运行的QRhiWidget 所管理的相关资源会被提前释放。

调用该函数的另一种情况是grabFramebuffer() 与未添加到可见窗口的QRhiWidget 一起使用，即在屏幕外进行渲染。如果以后该QRhiWidget 变为可见，或添加到可见部件层次结构中，相关的QRhi 将从用于离屏渲染的临时部件变为窗口的专用部件，从而也会触发该函数。

另请参见 initialize().

[virtual protected] void QRhiWidget::render(QRhiCommandBuffer *cb)

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

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

要请求更新，请调用QWidget::update() 。在 render() 中调用update() 会导致在 vsync 的控制下持续更新。

cb 是部件当前帧的 。调用该函数时正在记录一帧，但没有活动的渲染传递。QRhiCommandBuffer

另请参见 initialize()。

[signal] void QRhiWidget::renderFailed()

当部件本应渲染到其衬底纹理时（可能是由于widget update ，也可能是由于调用了grabFramebuffer()) ，但可能由于与图形配置相关的问题，没有QRhi 供部件使用时，就会发出该信号。

出现问题时，该信号可能会多次发出。不要认为它只会发出一次。如果只想通知错误处理代码一次，请连接Qt::SingleShotConnection 。

[protected] QRhiRenderTarget *QRhiWidget::renderTarget() const

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

只能从initialize() 和render() 调用。

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

创建graphics pipelines 时，需要一个QRhiRenderPassDescriptor 。可以通过调用renderPassDescriptor() 从返回的QRhiTextureRenderTarget 中查询。

另请参见 colorTexture() 和depthStencilBuffer()。

[override virtual protected] void QRhiWidget::resizeEvent(QResizeEvent *e)

重实现：QWidget::resizeEvent(QResizeEvent *event)。

处理通过e 事件参数传递的调整大小事件。调用虚拟函数initialize().

[protected] QRhiTexture *QRhiWidget::resolveTexture() const

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

未启用多采样抗锯齿时，结果为nullptr 。

只能在initialize() 和render() 中调用。

启用 MSAA 后，该纹理将与屏幕上其他QWidget 内容合成。但是，QRhiWidget 的渲染必须以msaaColorBuffer() 返回的（多采样）QRhiRenderBuffer 为目标。如果autoRenderTarget 是true ，则由renderTarget() 返回的QRhiRenderTarget 来处理。否则，就需要子类代码来正确配置具有颜色缓冲区和解析纹理的呈现目标对象。

另请参见 colorTexture()。

[protected] QRhi *QRhiWidget::rhi() const

返回当前QRhi 对象。

只能在initialize() 和render() 中调用。

void QRhiWidget::setApi(QRhiWidget::Api api)

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

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

api 只能为部件及其顶层窗口设置一次，一旦设置完成并生效，窗口就只能使用该 API 和QRhi 后端进行渲染。如果试图设置其他值，或使用不同的api 添加另一个QRhiWidget ，将无法实现预期功能。

另请参阅 setColorBufferFormat()、setDebugLayerEnabled() 和api()。

[protected] void QRhiWidget::setAutoRenderTarget(bool enabled)

控制 widget 是否自动创建和维护深度模版QRhiRenderBuffer 和QRhiTextureRenderTarget 。默认值为true 。

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

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

void QRhiWidget::setDebugLayerEnabled(bool enable)

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

适用于 Vulkan 和 Direct 3D。

默认情况下禁用。

另请参见 setApi() 和isDebugLayerEnabled()。