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

Dokumentation der Mitgliedsfunktionen

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

Konstruiert ein Widget, das ein Kind von parent ist, wobei die Widget-Flags auf f gesetzt sind.

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

Zerstörer.

QRhiWidget::Api QRhiWidget::api() const

Gibt die aktuell eingestellte Grafik-API zurück (QRhi backend).

Siehe auch setApi().

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

Gibt die Textur zurück, die als Farbpuffer für das Widget dient.

Darf nur von initialize() und render() aufgerufen werden.

Anders als der Tiefenschablonenpuffer und QRhiRenderTarget ist diese Textur immer verfügbar und wird von QRhiWidget verwaltet, unabhängig vom Wert von autoRenderTarget.

Siehe auch msaaColorBuffer(), depthStencilBuffer(), renderTarget(), und resolveTexture().

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

Gibt den Tiefenschablonenpuffer zurück, der für das Rendering des Widgets verwendet wird.

Darf nur von initialize() und render() aufgerufen werden.

Nur verfügbar, wenn autoRenderTarget true ist. Andernfalls ist der zurückgegebene Wert nullptr und es obliegt der Neuimplementierung von initialize(), einen Tiefenschablonenpuffer und einen QRhiTextureRenderTarget zu erstellen und zu verwalten.

Siehe auch colorTexture() und renderTarget().

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

Reimplements: QWidget::event(QEvent *Event).

[signal] void QRhiWidget::frameSubmitted()

Dieses Signal wird ausgegeben, nachdem das Top-Level-Fenster des Widgets die Komposition beendet und submitted a frame aufgerufen hat.

QImage QRhiWidget::grabFramebuffer() const

Rendert einen neuen Frame, liest den Inhalt der Textur zurück und gibt ihn als QImage zurück.

Wenn ein Fehler auftritt, wird QImage als Null zurückgegeben.

Das zurückgegebene QImage hat ein Format von QImage::Format_RGBA8888, QImage::Format_RGBA16FPx4, QImage::Format_RGBA32FPx4 oder QImage::Format_BGR30, je nach colorBufferFormat().

QRhiWidget kennt den Ansatz des Renderers für Überblendung und Komposition nicht und kann daher nicht wissen, ob die Ausgabe Alpha in den RGB-Farbwerten vormultipliziert hat. Daher werden die Formate _Premultiplied QImage niemals für die zurückgegebenen QImage verwendet, selbst wenn dies angemessen wäre. Es ist dem Aufrufer überlassen, die resultierenden Daten nach eigenem Ermessen umzuinterpretieren.

Die Funktion heißt aus Gründen der Konsistenz mit QOpenGLWidget und QQuickWidget grabFramebuffer(). Sie ist nicht die einzige Möglichkeit, CPU-seitige Bilddaten aus dem Inhalt von QRhiWidget zu erhalten: Der Aufruf von QWidget::grab() auf einem QRhiWidget oder einem Vorgänger davon funktioniert ebenfalls (und liefert ein QPixmap). Neben der direkten Arbeit mit QImage besteht ein weiterer Vorteil von grabFramebuffer() darin, dass es etwas leistungsfähiger sein kann, einfach weil es nicht den Rest der QWidget -Infrastruktur durchlaufen muss, sondern sofort das Rendern eines neuen Frames auslösen und dann das Zurücklesen durchführen kann.

Siehe auch setColorBufferFormat().

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

Wird aufgerufen, wenn das Widget zum ersten Mal initialisiert wird, wenn sich die Größe, das Format oder die Anzahl der Samples der zugehörigen Textur ändert, oder wenn sich QRhi und die Textur aus irgendeinem Grund ändern. Von der Funktion wird erwartet, dass sie die vom Rendering-Code in render() verwendeten Grafikressourcen pflegt (erstellen, wenn noch nicht erstellt, anpassen und neu aufbauen, wenn sich die Größe geändert hat).

Um die Objekte QRhi, QRhiTexture und andere verwandte Objekte abzufragen, rufen Sie rhi(), colorTexture(), depthStencilBuffer() und renderTarget() auf.

Wenn sich die Größe des Widgets ändert, sind das QRhi Objekt, die Farbpuffertextur und die Tiefenschablonenpufferobjekte alle dieselben Instanzen (so dass die Getter dieselben Zeiger zurückgeben) wie zuvor, aber die Farb- und Tiefen-/Schablonenpuffer wurden wahrscheinlich neu erstellt, was bedeutet, dass die size und die zugrunde liegende native Texturressource anders sein können als beim letzten Aufruf.

Reimplementierungen sollten auch darauf vorbereitet sein, dass sich das QRhi Objekt und die Farbpuffertextur zwischen Aufrufen dieser Funktion ändern können. Ein spezieller Fall, in dem die Objekte unterschiedlich sein können, ist die Ausführung von grabFramebuffer() mit einem noch nicht angezeigten Widget und das anschließende Sichtbarmachen des Widgets auf dem Bildschirm innerhalb eines Widgets der obersten Ebene. In diesem Fall wird das Grab mit einem dedizierten QRhi durchgeführt, das dann in den nachfolgenden Aufrufen von initialize() und render() durch das zugehörige QRhi des Top-Level-Fensters ersetzt wird. Ein anderer, häufigerer Fall ist, wenn das Widget reparented wird, so dass es zu einem neuen Fenster der obersten Ebene gehört. In diesem Fall werden die QRhi und alle zugehörigen Ressourcen, die von der QRhiWidget verwaltet werden, beim nachfolgenden Aufruf dieser Funktion andere Instanzen sein als zuvor. Es ist dann wichtig, dass alle bestehenden QRhi Ressourcen, die zuvor von der Unterklasse erstellt wurden, zerstört werden, da sie zu dem vorherigen QRhi gehören, das nicht mehr vom Widget verwendet werden sollte.

Wenn autoRenderTarget true ist, was die Voreinstellung ist, werden eine Tiefenschablone QRhiRenderBuffer und eine QRhiTextureRenderTarget, die mit colorTexture() (oder msaaColorBuffer()) und dem Tiefenschablonenpuffer verbunden sind, automatisch erstellt und verwaltet. Reimplementierungen von initialize() und render() können diese Objekte über depthStencilBuffer() und renderTarget() abfragen. Wenn autoRenderTarget auf false gesetzt wird, werden diese Objekte nicht mehr automatisch erstellt und verwaltet. Stattdessen obliegt es der initialize()-Implementierung, Puffer zu erstellen und das Rendering-Ziel nach eigenem Ermessen einzurichten. Wenn zusätzliche Farb- oder Tiefenschablonenanhänge für das Rendering-Ziel manuell verwaltet werden, müssen ihre Größe und Sampleanzahl immer der Größe und Sampleanzahl von colorTexture() / msaaColorBuffer() entsprechen, da sonst Rendering- oder 3D-API-Validierungsfehler auftreten können.

Es wird erwartet, dass die von der Unterklasse erstellten Grafikressourcen in der Destruktorimplementierung der Unterklasse freigegeben werden.

cb ist die QRhiCommandBuffer für den aktuellen Frame des Widgets. Die Funktion wird aufgerufen, wenn ein Frame aufgezeichnet wird, aber kein aktiver Rendering-Durchgang stattfindet. Der Befehlspuffer wird in erster Linie zur Verfügung gestellt, um das Einreihen von resource updates zu ermöglichen, ohne dass render() aufgeschoben werden muss.

Siehe auch render().

bool QRhiWidget::isDebugLayerEnabled() const

Gibt true zurück, wenn eine Debug- oder Validierungsebene angefordert wird, falls dies für die verwendete Grafik-API zutrifft.

Siehe auch setDebugLayerEnabled().

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

Gibt den Renderbuffer zurück, der als Multisample-Farbpuffer für das Widget dient.

Darf nur von initialize() und render() aufgerufen werden.

Wenn sampleCount größer als 1 ist und somit Multisample-Antialisierung aktiviert ist, hat der zurückgegebene QRhiRenderBuffer eine passende Sampleanzahl und dient als Farbpuffer. Grafikpipelines, die zum Rendern in diesen Puffer verwendet werden, müssen mit der gleichen Sampleanzahl erstellt werden, und die Sampleanzahl des Tiefenschablonenpuffers muss ebenfalls übereinstimmen. Es wird erwartet, dass der Multisample-Inhalt in die Textur aufgelöst wird, die von resolveTexture() zurückgegeben wird. Wenn autoRenderTarget true ist, wird renderTarget() automatisch für diese Aufgabe eingerichtet, indem msaaColorBuffer() als renderbuffer des Farbanhangs 0 und resolveTexture() als dessen resolveTexture eingerichtet werden.

Wenn MSAA nicht verwendet wird, ist der Rückgabewert nullptr. Verwenden Sie dann stattdessen colorTexture().

Abhängig von der zugrundeliegenden 3D-Grafik-API gibt es möglicherweise keinen praktischen Unterschied zwischen Multisample-Texturen und Farb-Renderbuffern mit einer Sample-Anzahl größer als 1 (QRhi kann einfach beide dem gleichen nativen Ressourcentyp zuordnen). Einige ältere APIs können jedoch zwischen Texturen und Renderbuffern unterscheiden. Um OpenGL ES 3.0 zu unterstützen, wo Multisample-Renderbuffer verfügbar sind, aber Multisample-Texturen nicht, führt QRhiWidget immer MSAA durch, indem ein Multisample QRhiRenderBuffer als Farbanhang verwendet wird (und niemals ein Multisample QRhiTexture).

Siehe auch colorTexture(), depthStencilBuffer(), renderTarget(), und resolveTexture().

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

Reimplements: QWidget::paintEvent(QPaintEvent *event).

Behandelt Malereignisse.

Der Aufruf von QWidget::update() führt zum Senden eines Malereignisses e und damit zum Aufrufen dieser Funktion. Das Senden des Ereignisses ist asynchron und wird irgendwann nach der Rückkehr von update() erfolgen. Diese Funktion wird dann, nach einer gewissen Vorbereitung, die virtuelle Funktion render() aufrufen, um den Inhalt der zugehörigen Textur von QRhiWidget zu aktualisieren. Das Top-Level-Fenster des Widgets wird dann die Textur mit dem Rest des Fensters zusammensetzen.

[virtual protected] void QRhiWidget::releaseResources()

Wird aufgerufen, wenn die Notwendigkeit besteht, die Grafikressourcen frühzeitig freizugeben.

Dies geschieht normalerweise nicht für ein QRhiWidget, das der Kinderhierarchie eines Widgets der obersten Ebene hinzugefügt wird und dort für den Rest seiner und der Lebensdauer der obersten Ebene verbleibt. Daher besteht in vielen Fällen keine Notwendigkeit, diese Funktion neu zu implementieren, z. B. weil die Anwendung immer nur ein einziges Top-Level-Widget (natives Fenster) hat. Wenn jedoch das Reparenting des Widgets (oder eines Vorgängers davon) involviert ist, wird die Neuimplementierung dieser Funktion in robusten, gut geschriebenen QRhiWidget Unterklassen notwendig werden.

Wenn diese Funktion aufgerufen wird, wird von der Implementierung erwartet, dass sie alle QRhi Ressourcen (QRhiBuffer, QRhiTexture, etc. Objekte) zerstört, ähnlich wie dies im Destruktor erwartet wird. Nulling out, die Verwendung eines Smart Pointers oder das Setzen eines resources-invalid Flags wird ebenfalls erforderlich sein, da initialize() schließlich danach aufgerufen wird. Beachten Sie jedoch, dass es falsch ist, die Freigabe von Ressourcen auf die nachfolgende Funktion initialize() zu verschieben. Wenn diese Funktion aufgerufen wird, muss die Ressource vor der Rückkehr freigegeben werden. Beachten Sie auch, dass die Implementierung dieser Funktion den Destruktor der Klasse (oder Smart Pointer) nicht ersetzt: die Grafikressourcen müssen in beiden weiterhin freigegeben werden.

Ein Beispiel dafür finden Sie im Cube RHI Widget Example. Dort löst die Schaltfläche, die QRhiWidget zwischen einem Kind-Widget (aufgrund eines Eltern-Widgets) und einem Top-Level-Widget (aufgrund eines fehlenden Eltern-Widgets) umschaltet, den Aufruf dieser Funktion aus, da sich das zugehörige Top-Level-Widget, das native Fenster und QRhi alle während der Lebensdauer von QRhiWidget ändern, wobei das zuvor verwendete QRhi zerstört wird, was eine frühzeitige Freigabe der zugehörigen Ressourcen bedeutet, die von dem noch lebenden QRhiWidget verwaltet werden.

Ein weiterer Fall, in dem diese Funktion aufgerufen wird, ist, wenn grabFramebuffer() mit einem QRhiWidget verwendet wird, das nicht zu einem sichtbaren Fenster hinzugefügt wird, d.h. das Rendering wird außerhalb des Bildschirms durchgeführt. Wenn dieses QRhiWidget später sichtbar gemacht oder zu einer sichtbaren Widget-Hierarchie hinzugefügt wird, ändert sich das zugehörige QRhi von dem temporären Rendering, das für das Offscreen-Rendering verwendet wird, zum dedizierten Rendering des Fensters, wodurch diese Funktion ebenfalls ausgelöst wird.

Siehe auch initialize().

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

Wird aufgerufen, wenn der Inhalt des Widgets (d. h. der Inhalt der Textur) aktualisiert werden muss.

Es gibt immer mindestens einen Aufruf von initialize(), bevor diese Funktion aufgerufen wird.

Um Aktualisierungen anzufordern, rufen Sie QWidget::update() auf. Der Aufruf von update() innerhalb von render() führt zu einer kontinuierlichen Aktualisierung, die durch vsync gedrosselt wird.

cb ist die QRhiCommandBuffer für den aktuellen Frame des Widgets. Die Funktion wird aufgerufen, während ein Frame aufgezeichnet wird, aber ohne einen aktiven Rendering-Durchgang.

Siehe auch initialize().

[signal] void QRhiWidget::renderFailed()

Dieses Signal wird immer dann ausgegeben, wenn das Widget auf seine Hintergrundtextur rendern soll (entweder aufgrund einer widget update oder aufgrund eines Aufrufs von grabFramebuffer()), aber es gibt keine QRhi für das Widget zu verwenden, wahrscheinlich aufgrund von Problemen im Zusammenhang mit der Grafikkonfiguration.

Dieses Signal kann mehrfach ausgegeben werden, wenn ein Problem auftritt. Gehen Sie nicht davon aus, dass es nur einmal ausgegeben wird. Verbinden Sie sich mit Qt::SingleShotConnection, wenn der Fehlerbehandlungscode nur einmal benachrichtigt werden soll.

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

Gibt das Rendering-Zielobjekt zurück, das mit QRhiCommandBuffer::beginPass() in Reimplementierungen von render() verwendet werden muss.

Darf nur von initialize() und render() aufgerufen werden.

Nur verfügbar, wenn autoRenderTarget true ist. Andernfalls ist der zurückgegebene Wert nullptr und es obliegt der Neuimplementierung von initialize(), einen Tiefenschablonenpuffer und einen QRhiTextureRenderTarget zu erstellen und zu verwalten.

Beim Erstellen von graphics pipelines wird ein QRhiRenderPassDescriptor benötigt. Dieser kann aus dem zurückgegebenen QRhiTextureRenderTarget durch Aufruf von renderPassDescriptor() abgefragt werden.

Siehe auch colorTexture() und depthStencilBuffer().

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

Reimplements: QWidget::resizeEvent(QResizeEvent *event).

Verarbeitet Größenänderungsereignisse, die mit dem Parameter e event übergeben werden. Ruft die virtuelle Funktion initialize() auf.

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

Gibt die Nicht-Multisample-Textur zurück, in die der Multisample-Inhalt aufgelöst wird.

Das Ergebnis ist nullptr, wenn Multisample-Antialiasing nicht aktiviert ist.

Darf nur von initialize() und render() aufgerufen werden.

Wenn MSAA aktiviert ist, ist dies die Textur, die mit dem Rest des QWidget Inhalts auf dem Bildschirm zusammengesetzt wird. Das Rendering von QRhiWidget muss jedoch auf das (Multisample) QRhiRenderBuffer abzielen, das von msaaColorBuffer() zurückgegeben wird. Wenn autoRenderTarget true ist, wird dies von dem von renderTarget() zurückgegebenen QRhiRenderTarget übernommen. Andernfalls obliegt es dem Code der Unterklasse, ein Rendering-Zielobjekt mit dem Farbpuffer und den aufgelösten Texturen korrekt zu konfigurieren.

Siehe auch colorTexture().

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

Gibt das aktuelle QRhi Objekt zurück.

Darf nur von initialize() und render() aufgerufen werden.

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

Setzt die zu verwendende Grafik-API und das QRhi Backend auf api.

Der Standardwert hängt von der jeweiligen Plattform ab: Metal unter macOS und iOS, Direct 3D 11 unter Windows, ansonsten OpenGL.

Die api kann nur einmal für das Widget und sein Top-Level-Fenster gesetzt werden. Sobald dies geschehen ist und in Kraft tritt, kann das Fenster nur noch dieses API und QRhi Backend zum Rendern verwenden. Der Versuch, einen anderen Wert zu setzen oder einen anderen QRhiWidget mit einem anderen api hinzuzufügen, wird nicht wie erwartet funktionieren.

Siehe auch setColorBufferFormat(), setDebugLayerEnabled(), und api().

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

Steuert, ob eine Tiefenschablone QRhiRenderBuffer und eine QRhiTextureRenderTarget automatisch vom Widget erstellt und gepflegt wird. Der Standardwert ist true.

Im automatischen Modus folgen die Größe und die Anzahl der Samples des Tiefenschablonenpuffers den Einstellungen der Farbpuffertextur. Im nicht-automatischen Modus geben renderTarget() und depthStencilBuffer() immer nullptr zurück und es liegt dann an der Implementierung von initialize() in der Anwendung, diese Objekte einzurichten und zu verwalten.

Rufen Sie die Funktion enabled mit dem Wert false frühzeitig auf, z. B. im Konstruktor der abgeleiteten Klasse, um den automatischen Modus zu deaktivieren.

void QRhiWidget::setDebugLayerEnabled(bool enable)

Fordert die Debug- oder Validierungsschicht der zugrunde liegenden Grafik-API an, wenn enable true ist.

Gilt für Vulkan und Direct 3D.

Standardmäßig ist diese Funktion deaktiviert.

Siehe auch setApi() und isDebugLayerEnabled().