QQuickRhiItem Class

Ausführliche Beschreibung

QQuickRhiItem ist im Grunde das Pendant zu QRhiWidget in der Welt von „ Qt Quick “. Beide sind dafür vorgesehen, unterklassifiziert zu werden, und beide ermöglichen die Aufzeichnung von „ QRhi “-basiertem Rendering, das auf einen Offscreen-Farbpuffer abzielt. Das resultierende 2D-Bild wird dann mit dem Rest der „ Qt Quick “-Szene zusammengesetzt.

QQuickRhiItem ist ein Ersatz für die veraltete Klasse „ QQuickFramebufferObject “. Letztere ist untrennbar mit OpenGL / OpenGL ES verbunden, während QQuickRhiItem mit den Klassen „ QRhi “ zusammenarbeitet, wodurch derselbe Rendering-Code mit Vulkan, Metal, Direct 3D 11/12 sowie OpenGL / OpenGL ES ausgeführt werden kann. Konzeptionell und funktional sind sie sich sehr ähnlich, und die Migration von „ QQuickFramebufferObject “ zu „QQuickRhiItem“ ist unkompliziert. „ QQuickFramebufferObject “ steht weiterhin zur Verfügung, um die Kompatibilität für bestehenden Anwendungscode zu gewährleisten, der direkt mit der OpenGL-API arbeitet.

Auf den meisten Plattformen erfolgt das Rendern des Szenengraphen und damit auch das von QQuickRhiItem durchgeführte Rendern in einem eigenen Thread. Aus diesem Grund erzwingt die Klasse QQuickRhiItem eine strikte Trennung zwischen der Item-Implementierung (der QQuickItem -Unterklasse) und der eigentlichen Renderlogik. Die gesamte Item-Logik, wie z. B. Eigenschaften und UI-bezogene Hilfsfunktionen, die für QML verfügbar sind, muss sich in der Unterklasse von `QQuickRhiItem` befinden. Alles, was mit dem Rendern zusammenhängt, muss sich in der Klasse ` QQuickRhiItemRenderer ` befinden. Um Race-Conditions und Lese-/Schreibprobleme durch zwei Threads zu vermeiden, ist es wichtig, dass der Renderer und das Item niemals gemeinsam genutzte Variablen lesen oder schreiben. Die Kommunikation zwischen dem Item und dem Renderer sollte in erster Linie über die Funktion `QQuickRhiItem::synchronize()` erfolgen. Diese Funktion wird im Render-Thread aufgerufen, während der GUI-Thread gesperrt ist. Die Verwendung von Queued-Verbindungen oder Ereignissen für die Kommunikation zwischen Item und Renderer ist ebenfalls möglich.

Anwendungen müssen sowohl von `QQuickRhiItem` als auch von ` QQuickRhiItemRenderer` ableiten. 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) handelt oder um eine ` QRhiRenderBuffer `, wenn Multisampling verwendet wird. (Einige 3D-APIs unterscheiden zwischen Texturen und Renderbuffern, während bei anderen die zugrunde liegende native Ressource dieselbe ist; Renderbuffer werden hauptsächlich verwendet, um Multisampling mit OpenGL ES 3.0 zu ermöglichen.)

Die Größe der Textur passt sich standardmäßig an die Größe des Elements an (unter Berücksichtigung von ` device pixel ratio `). Ändert sich die Größe des Elements, wird die Textur mit der korrekten 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 Textur-Provider nutzen.

Obwohl dies kein primärer Anwendungsfall ist, ermöglicht QQuickRhiItem auch die Einbindung von Rendering-Code, der direkt eine 3D-Grafik-API wie Vulkan, Metal, Direct 3D oder OpenGL nutzt. Weitere Informationen zum Aufzeichnen nativer Befehle innerhalb eines „ QRhi “-Renderdurchlaufs finden Sie unter „ QRhiCommandBuffer::beginExternal “ (), und unter „ QRhiTexture::createFrom “ () erfahren Sie, wie Sie eine vorhandene native Textur verpacken und anschließend in einem nachfolgenden Renderdurchlauf mit „ QRhi “ verwenden können. Siehe auch QQuickGraphicsConfiguration bezüglich der Konfiguration der nativen 3D-API-Umgebung (z. B. Geräteerweiterungen) und beachten Sie, dass die ` QQuickWindow ` durch einen frühzeitigen Aufruf von ` QWindow::setVulkanInstance()` mit einer benutzerdefinierten ` QVulkanInstance ` verknüpft werden kann.

Ein einfaches Beispiel

Betrachten Sie die folgende Unterklasse von `QQuickRhiItem`. Sie wird hier in vollständiger Form gezeigt. Sie rendert ein einzelnes Dreieck mit perspektivischer Projektion, wobei das Dreieck basierend auf der Eigenschaft ` angle ` des benutzerdefinierten Elements gedreht wird. (Das bedeutet, dass es beispielsweise mit Animationen wie ` NumberAnimation ` aus QML gesteuert werden kann.)

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

Bemerkenswert ist, dass diese einfache Klasse fast genau dem Code entspricht, der in der Einführung zu „ QRhiWidget “ gezeigt wird. Auch die Vertex- und Fragment-Shader sind 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 Befehlszeilentools „ qsb “ oder durch Verwendung der Funktion `qt_add_shaders()` in CMake. Das `QQuickRhiItem` lädt diese vorverarbeiteten ` .qsb `-Dateien, die im Lieferumfang der Anwendung enthalten sind. Weitere Informationen zur Shader-Übersetzungsinfrastruktur von Qt finden Sie unter 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);
}

Sobald unser benutzerdefiniertes Element in QML verfügbar ist (beachten Sie die Datei „ QML_NAMED_ELEMENT “), kann es in jeder Szene instanziiert werden. (Nach dem Import der entsprechenden Datei „ 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 }
}

Ein komplexeres Beispiel finden Sie unter „Szenengraph – RHI-Textur-Element “.