QQuickRhiItem Class

Detaillierte Beschreibung

QQuickRhiItem ist praktisch das Gegenstück zu QRhiWidget in der Welt von Qt Quick. Beide sind als Unterklassen gedacht und ermöglichen ein QRhi-basiertes Rendering, das auf einen Farbpuffer außerhalb des Bildschirms abzielt. Das resultierende 2D-Bild wird dann mit dem Rest der Qt Quick Szene zusammengesetzt.

QQuickRhiItem ist ein Ersatz für die Legacy-Klasse QQuickFramebufferObject. Letztere ist von Natur aus an OpenGL / OpenGL ES gebunden, wohingegen QQuickRhiItem mit den QRhi Klassen arbeitet und es ermöglicht, denselben Rendering-Code mit Vulkan, Metal, Direct 3D 11/12 und OpenGL / OpenGL ES auszuführen. Konzeptionell und funktionell sind sie sehr ähnlich, und die Migration von QQuickFramebufferObject zu QQuickRhiItem ist unkompliziert. QQuickFramebufferObject ist weiterhin verfügbar, um die Kompatibilität für bestehenden Anwendungscode zu gewährleisten, der direkt mit der OpenGL-API arbeitet.

Auf den meisten Plattformen erfolgt das Rendering des Szenegraphen und damit auch das Rendering durch QQuickRhiItem in einem eigenen Thread. Aus diesem Grund erzwingt die Klasse QQuickRhiItem eine strikte Trennung zwischen der Item-Implementierung (der Unterklasse QQuickItem ) und der eigentlichen Rendering-Logik. Die gesamte Logik des Elements, wie z. B. Eigenschaften und UI-bezogene Hilfsfunktionen, die QML zur Verfügung gestellt werden, müssen sich in der Unterklasse QQuickRhiItem befinden. Alles, was sich auf das Rendering bezieht, muss sich in der Klasse QQuickRhiItemRenderer befinden. Um Race Conditions und Lese-/Schreibprobleme von zwei Threads zu vermeiden, ist es wichtig, dass der Renderer und das Item niemals gemeinsame Variablen lesen oder schreiben. Die Kommunikation zwischen dem Element und dem Renderer sollte hauptsächlich über die Funktion QQuickRhiItem::synchronize() erfolgen. Diese Funktion wird auf dem Render-Thread aufgerufen, während der GUI-Thread blockiert ist. Die Verwendung von Warteschlangenverbindungen oder Ereignissen für die Kommunikation zwischen Element und Renderer ist ebenfalls möglich.

Anwendungen müssen sowohl QQuickRhiItem als auch QQuickRhiItemRenderer subclassifizieren. Die rein virtuelle Funktion createRenderer() muss neu implementiert werden, um eine neue Instanz der Unterklasse QQuickRhiItemRenderer zurückzugeben.

Wie bei QRhiWidget verwaltet QQuickRhiItem automatisch den Farbpuffer, bei dem es sich normalerweise um eine 2D-Textur (QRhiTexture) oder um QRhiRenderBuffer handelt, wenn Multisampling verwendet wird. (einige 3D-APIs unterscheiden zwischen Texturen und Renderbuffern, während bei einigen anderen die zugrunde liegende native Ressource die gleiche ist; Renderbuffer werden hauptsächlich verwendet, um Multisampling mit OpenGL ES 3.0 zu ermöglichen)

Die Größe der Textur wird standardmäßig an die Größe des Objekts angepasst (unter Berücksichtigung von device pixel ratio ). Ändert sich die Größe des Objekts, wird die Textur in der richtigen Größe neu erstellt. Wenn eine feste Größe bevorzugt wird, setzen Sie fixedColorBufferWidth und fixedColorBufferHeight auf Werte ungleich Null.

QQuickRhiItem ist ein texture provider und kann direkt in ShaderEffects und anderen Klassen verwendet werden, die Texturanbieter nutzen.

QQuickRhiItem ist zwar nicht der primäre Anwendungsfall, ermöglicht aber auch die Einbindung von Rendering-Code, der direkt eine 3D-Grafik-API wie Vulkan, Metal, Direct 3D oder OpenGL verwendet. Siehe QRhiCommandBuffer::beginExternal() für Details zur Aufzeichnung nativer Befehle in einem QRhi Rendering-Durchgang sowie QRhiTexture::createFrom() für eine Möglichkeit, eine vorhandene native Textur zu umhüllen und sie dann mit QRhi in einem nachfolgenden Rendering-Durchgang zu verwenden. Siehe auch QQuickGraphicsConfiguration bezüglich der Konfiguration der nativen 3D-API-Umgebung (z. B. Geräteerweiterungen) und beachten Sie, dass QQuickWindow mit einem benutzerdefinierten QVulkanInstance verbunden werden kann, indem QWindow::setVulkanInstance() früh genug aufgerufen wird.

Ein einfaches Beispiel

Nehmen Sie die folgende Unterklasse von QQuickRhiItem. Sie ist hier in vollständiger Form dargestellt. Sie rendert ein einzelnes Dreieck mit einer perspektivischen Projektion, wobei das Dreieck auf der Grundlage der Eigenschaft angle des benutzerdefinierten Elements gedreht wird. (d.h. es kann z.B. mit Animationen wie NumberAnimation aus QML gesteuert werden)

class ExampleRhiItemRenderer : public QQuickRhiItemRenderer
{
public:
    void initialize(QRhiCommandBuffer *cb) override;
    void synchronize(QQuickRhiItem *item) 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_angle = 0.0f;
};

class ExampleRhiItem : public QQuickRhiItem
{
    Q_OBJECT
    QML_NAMED_ELEMENT(ExampleRhiItem)
    Q_PROPERTY(float angle READ angle WRITE setAngle NOTIFY angleChanged)

public:
    QQuickRhiItemRenderer *createRenderer() override;

    float angle() const { return m_angle; }
    void setAngle(float a);

signals:
    void angleChanged();

private:
    float m_angle = 0.0f;
};

QQuickRhiItemRenderer *ExampleRhiItem::createRenderer()
{
    return new ExampleRhiItemRenderer;
}

void ExampleRhiItem::setAngle(float a)
{
    if (m_angle == a)
        return;

    m_angle = a;
    emit angleChanged();
    update();
}

void ExampleRhiItemRenderer::synchronize(QQuickRhiItem *rhiItem)
{
    ExampleRhiItem *item = static_cast<ExampleRhiItem *>(rhiItem);
    if (item->angle() != m_angle)
        m_angle = item->angle();
}

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

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

void ExampleRhiItemRenderer::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(":/shaders/color.vert.qsb")) },
            { QRhiShaderStage::Fragment, getShader(QLatin1String(":/shaders/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 = renderTarget()->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 ExampleRhiItemRenderer::render(QRhiCommandBuffer *cb)
{
    QRhiResourceUpdateBatch *resourceUpdates = m_rhi->nextResourceUpdateBatch();
    QMatrix4x4 modelViewProjection = m_viewProjection;
    modelViewProjection.rotate(m_angle, 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 = renderTarget()->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();
}

Es ist bemerkenswert, dass diese einfache Klasse fast genau dem Code entspricht, der in der Einführung von QRhiWidget gezeigt wird. Die Vertex- und Fragment-Shader sind ebenfalls identisch. Diese werden als GLSL-Quellcode im Vulkan-Stil bereitgestellt und müssen zunächst von der Qt-Shader-Infrastruktur verarbeitet werden. Dies geschieht entweder durch manuelles Ausführen des qsb Kommandozeilen-Tools oder durch Verwendung der Funktion qt_add_shaders() in CMake. Das QQuickRhiItem lädt diese vorverarbeiteten .qsb Dateien, die mit der Anwendung ausgeliefert werden. Siehe Qt Shader Tools für weitere Informationen über die Shader-Übersetzungsinfrastruktur von 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);
}

Sobald es QML ausgesetzt ist (beachten Sie die QML_NAMED_ELEMENT), kann unser benutzerdefiniertes Element in jeder Szene instanziiert werden. (nach dem Importieren der entsprechenden URI, die für qt_add_qml_module im CMake-Projekt angegeben wurde)

ExampleRhiItem {
    anchors.fill: parent
    anchors.margins: 10
    NumberAnimation on angle { from: 0; to: 360; duration: 5000; loops: Animation.Infinite }
}

Siehe Scene Graph - RHI Texture Item für ein komplexeres Beispiel.