QQuickRhiItem Class

Description détaillée

QQuickRhiItem est en fait la contrepartie de QRhiWidget dans le monde de Qt Quick. Ces deux éléments sont destinés à être sous-classés, et ils permettent tous deux l'enregistrement QRhi-based rendering that targets an offscreen color buffer. L'image 2D résultante est ensuite composée avec le reste de la scène Qt Quick.

QQuickRhiItem remplace l'ancienne classe QQuickFramebufferObject. Cette dernière est intrinsèquement liée à OpenGL / OpenGL ES, alors que QQuickRhiItem fonctionne avec les classes QRhi, permettant d'exécuter le même code de rendu avec Vulkan, Metal, Direct 3D 11/12, et OpenGL / OpenGL ES. Conceptuellement et fonctionnellement, ils sont très proches, et la migration de QQuickFramebufferObject vers QQuickRhiItem est simple. QQuickFramebufferObject continue d'être disponible pour assurer la compatibilité avec le code d'application existant qui fonctionne directement avec l'API OpenGL.

Sur la plupart des plates-formes, le rendu du graphe de scène, et donc le rendu effectué par le QQuickRhiItem, se produira sur un thread dédié. C'est pourquoi la classe QQuickRhiItem impose une séparation stricte entre l'implémentation de l'élément (la sous-classe QQuickItem ) et la logique de rendu proprement dite. Toute la logique de l'élément, telle que les propriétés et les fonctions d'aide liées à l'interface utilisateur exposées à QML, doit se trouver dans la sous-classe QQuickRhiItem. Tout ce qui concerne le rendu doit se trouver dans la classe QQuickRhiItemRenderer. Pour éviter les conditions de course et les problèmes de lecture/écriture à partir de deux threads, il est important que le moteur de rendu et l'élément ne lisent ni n'écrivent jamais de variables partagées. La communication entre l'élément et le moteur de rendu doit se faire principalement via la fonction QQuickRhiItem::synchronize(). Cette fonction sera appelée sur le thread de rendu pendant que le thread de l'interface graphique est bloqué. Il est également possible d'utiliser des connexions ou des événements en file d'attente pour la communication entre l'élément et le moteur de rendu.

Les applications doivent sous-classer à la fois QQuickRhiItem et QQuickRhiItemRenderer. La fonction purement virtuelle createRenderer() doit être réimplémentée pour renvoyer une nouvelle instance de la sous-classe QQuickRhiItemRenderer.

Comme pour QRhiWidget, QQuickRhiItem gère automatiquement le tampon de couleur, qui est une texture 2D (QRhiTexture) normalement, ou une QRhiRenderBuffer lorsque le multi-échantillonnage est utilisé. (certaines API 3D font la différence entre les textures et les renderbuffers, alors que pour d'autres, la ressource native sous-jacente est la même ; les renderbuffers sont utilisés principalement pour permettre le multi-échantillonnage avec OpenGL ES 3.0).

La taille de la texture s'adapte par défaut à la taille de l'objet (en tenant compte de device pixel ratio ). Si la taille de l'objet change, la texture est recréée avec la taille correcte. Si vous préférez une taille fixe, définissez fixedColorBufferWidth et fixedColorBufferHeight à des valeurs non nulles.

QQuickRhiItem est un texture provider et peut être utilisé directement dans ShaderEffects et d'autres classes qui consomment des fournisseurs de textures.

Bien qu'il ne s'agisse pas d'un cas d'utilisation primaire, QQuickRhiItem permet également d'incorporer du code de rendu qui utilise directement une API graphique 3D telle que Vulkan, Metal, Direct 3D ou OpenGL. Voir QRhiCommandBuffer::beginExternal() pour plus de détails sur l'enregistrement de commandes natives dans une passe de rendu QRhi, ainsi que QRhiTexture::createFrom() pour un moyen d'envelopper une texture native existante et de l'utiliser avec QRhi dans une passe de rendu ultérieure. Voir également QQuickGraphicsConfiguration pour la configuration de l'environnement de l'API 3D native (par exemple, les extensions de périphériques) et noter que QQuickWindow peut être associé à une QVulkanInstance personnalisée en appelant QWindow::setVulkanInstance() suffisamment tôt.

Un exemple simple

Prenons la sous-classe suivante de QQuickRhiItem. Elle est présentée ici dans sa forme complète. Elle rend un simple triangle avec une projection en perspective, où le triangle est tourné en fonction de la propriété angle de l'élément personnalisé. (ce qui signifie qu'elle peut être pilotée, par exemple, par des animations telles que NumberAnimation à partir de QML).

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

Il est à noter que cette classe simple est presque exactement la même que le code montré dans l'introduction de QRhiWidget. Les vertex et fragment shaders sont également les mêmes. Ils sont fournis en tant que code source GLSL de style Vulkan et doivent d'abord être traités par l'infrastructure de shaders Qt. Ceci est réalisé soit en exécutant manuellement l'outil de ligne de commande qsb, soit en utilisant la fonction qt_add_shaders() dans CMake. Le QQuickRhiItem charge ces fichiers pré-traités .qsb qui sont livrés avec l'application. Voir Qt Shader Tools pour plus d'informations sur l'infrastructure de traduction des shaders de 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);
}

Une fois exposé à QML (notez le QML_NAMED_ELEMENT), notre élément personnalisé peut être instancié dans n'importe quelle scène. (après avoir importé le site URI approprié spécifié pour qt_add_qml_module dans le projet CMake).

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

Voir Scene Graph - RHI Texture Item pour un exemple plus complexe.