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 = {})

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

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

析构函数。

QRhiWidget::Api QRhiWidget::api() const

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

另请参阅 setApi()。

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

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

该函数仅可从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）。因此，即使在适用情况下，返回的QImage 也绝不会采用_Premultiplied 或QImage 格式。调用方应根据自身需求对生成的数据进行重新解释。

该函数命名为 grabFramebuffer()，是为了与QOpenGLWidget 和QQuickWidget 保持一致。这并非从QRhiWidget 的内容中获取 CPU 端图像数据的唯一方法：在QRhiWidget 或其祖先对象上调用QWidget::grab() 同样有效（返回QPixmap ）。 除了能直接处理QImage 外，grabFramebuffer()的另一个优势在于其性能可能略高，原因很简单：它无需经过QWidget 基础设施的其他环节，而是可以立即触发新帧的渲染，随后直接进行读回操作。

另请参阅 setColorBufferFormat()。

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

在小部件首次初始化时、关联纹理的大小、格式或采样数发生变化时，或者因任何原因导致QRhi 和纹理发生变化时调用。该函数应维护（若尚未创建则创建，若大小已发生变化则调整并重建）render()中渲染代码所使用的图形资源。

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

当控件尺寸发生变化时，QRhi 对象、颜色缓冲区纹理以及深度/模板缓冲区对象均与之前属于同一实例（因此获取器返回相同的指针），但颜色缓冲区和深度/模板缓冲区很可能已被重建，这意味着size 及其底层原生纹理资源可能与上次调用时不同。

重写时还应做好准备，以应对该函数不同调用之间QRhi 对象和颜色缓冲区纹理可能发生变化的情况。一种对象会不同的特殊情况是：当对尚未显示的小部件执行grabFramebuffer()操作，随后在顶级小部件内将其显示在屏幕上时。 此时，抓取操作将使用专用的QRhi 进行，随后在后续的initialize()和render()调用中，该抓取对象将被替换为顶级窗口关联的QRhi 。另一种更常见的情况是，当控件被重新父化，从而属于一个新的顶级窗口时。 在这种情况下，在后续调用此函数时，QRhi 以及由QRhiWidget 管理的所有相关资源都将与之前不同。此时，必须销毁子类之前创建的所有现有QRhi 资源，因为它们属于之前的QRhi ，而该窗口不应再被该小部件使用。

当autoRenderTarget 的值为true （这是默认值）时，系统会自动创建并管理与colorTexture()（或msaaColorBuffer()）及深度-模板缓冲区关联的深度-模板QRhiRenderBuffer 和QRhiTextureRenderTarget 。initialize()和render()的重写实现可通过depthStencilBuffer()和renderTarget()查询这些对象。当autoRenderTarget 设置为false 时，这些对象将不再被自动创建和管理。 相反，将由 `initialize()` 的实现根据需要创建缓冲区并设置渲染目标。当手动管理渲染目标的额外颜色或深度-模板附件时，其大小和采样数必须始终遵循 `colorTexture()` / `msaaColorBuffer()` 的大小和采样数，否则可能会发生渲染或 3D API 验证错误。

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

cb 是小部件当前帧的QRhiCommandBuffer 。该函数在录制帧时被调用，但此时没有活动的渲染通道。提供该命令缓冲区主要是为了允许将resource updates 加入队列，而无需交由render()处理。

另请参阅 render()。

bool QRhiWidget::isDebugLayerEnabled() const

如果所使用的图形 API 支持，且需要请求调试或验证层，则返回 true。

另请参阅 setDebugLayerEnabled()。

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

返回用作该控件多采样颜色缓冲区的渲染缓冲区。

该函数仅可从initialize()和render()中调用。

当sampleCount 大于1（即启用了多采样抗锯齿）时，返回的QRhiRenderBuffer 具有匹配的采样数，并作为颜色缓冲区使用。用于渲染到该缓冲区的图形管道必须使用相同的采样数创建，且深度-模板缓冲区的采样数也必须匹配。 多采样内容应解析为由resolveTexture()返回的纹理。当autoRenderTarget 为true 时，renderTarget()会自动进行此配置：将msaaColorBuffer()设为颜色附件0的renderbuffer ，并将resolveTexture()设为其resolveTexture 。

当未启用 MSAA 时，返回值为nullptr 。此时请改用colorTexture()。

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

另请参阅 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 等对象），这与在析构函数中应执行的操作类似。此外，还必须将资源清零、使用智能指针或设置resources-invalid 标志，因为随后最终会调用initialize()。 但请注意，将资源释放推迟到后续的initialize()中是错误的。如果调用了此函数，必须在返回之前释放资源。另请注意，实现此函数并不能替代类的析构函数（或智能指针）：图形资源仍必须在这两者中都得到释放。

请参阅“Cube RHI 控件示例”以了解实际应用。在该示例中，用于切换QRhiWidget 状态的按钮（使其在“作为子控件”（因拥有父控件）与“作为顶级控件”（因无父控件）之间切换），将触发此函数的调用，因为关联的顶级控件、本机窗口、 以及QRhi 在QRhiWidget 的生命周期内均会发生变化，此时先前使用的QRhi 将被销毁，这意味着由仍存活的QRhiWidget 管理的关联资源会被提前释放。

调用此函数的另一种情况是，当grabFramebuffer() 与未添加到可见窗口的QRhiWidget 配合使用时，即渲染在屏幕外进行。 如果随后将该QRhiWidget 设为可见，或将其添加到可见的小部件层次结构中，则关联的QRhi 将从用于离屏渲染的临时窗口切换为该窗口的专用窗口，从而也会触发此函数。

另请参阅 initialize()。

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

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

在调用此函数之前，总会至少调用一次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)

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

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

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

void QRhiWidget::setDebugLayerEnabled(bool enable)

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

适用于 Vulkan 和 Direct 3D。

默认情况下，此功能处于禁用状态。

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