QQuickRhiItem Class

Description détaillée

QQuickRhiItem est en fait l’équivalent de QRhiWidget dans l’univers d’ Qt Quick. Ces deux classes sont destinées à être sous-classées et permettent toutes deux d’enregistrer un rendu basé sur l’ QRhi, ciblant un tampon de couleurs hors écran. L’image 2D obtenue est ensuite composée avec le reste de la scène d’ Qt Quick.

QQuickRhiItem remplace l’ancienne classe QQuickFramebufferObject. Cette dernière est intrinsèquement liée à OpenGL / OpenGL ES, tandis que QQuickRhiItem fonctionne avec les classes QRhi, ce qui permet d’exécuter le même code de rendu avec Vulkan, Metal, Direct 3D 11/12 et OpenGL / OpenGL ES. Sur le plan conceptuel et fonctionnel, elles sont très proches, et la migration d’ QQuickFramebufferObject vers QQuickRhiItem est simple. QQuickFramebufferObject reste disponible pour assurer la compatibilité avec le code des applications existantes qui fonctionnent directement avec l’API OpenGL.

Sur la plupart des plateformes, le rendu du graphe de scène, et donc le rendu effectué par QQuickRhiItem, s’effectuera 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 de QQuickRhiItem. Tout ce qui concerne le rendu doit se trouver dans la classe QQuickRhiItemRenderer. Pour éviter les conditions de concurrence et les problèmes de lecture/écriture entre 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 principalement s’effectuer via la fonction `QQuickRhiItem::synchronize()`. Cette fonction sera appelée sur le thread de rendu tandis que le thread de l’interface graphique est bloqué. Il est également possible d’utiliser des connexions en file d’attente ou des événements pour la communication entre l’élément et le moteur de rendu.

Les applications doivent créer des sous-classes à la fois de `QQuickRhiItem` et de ` QQuickRhiItemRenderer`. La fonction virtuelle pure ` 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 généralement une texture 2D (`QRhiTexture`) ou un ` QRhiRenderBuffer ` lorsque le multisampling est utilisé. (Certaines API 3D font la distinction entre les textures et les tampons de rendu, tandis que pour d’autres, la ressource native sous-jacente est la même ; les tampons de rendu sont principalement utilisés pour permettre le multisampling avec OpenGL ES 3.0)

Par défaut, la taille de la texture s’adapte à celle de l’élément (en tenant compte de la valeur de ` device pixel ratio `). Si la taille de l’élément change, la texture est recréée avec la taille correcte. Si vous préférez une taille fixe, définissez ` fixedColorBufferWidth ` et ` fixedColorBufferHeight ` sur des valeurs non nulles.

QQuickRhiItem est un « texture provider » et peut être utilisé directement dans ShaderEffects et d’autres classes qui utilisent des fournisseurs de textures.

Bien que ce ne soit pas un cas d'utilisation principal, QQuickRhiItem permet également d'intégrer du code de rendu utilisant directement une API graphique 3D telle que Vulkan, Metal, Direct 3D ou OpenGL. Consultez QRhiCommandBuffer::beginExternal() pour plus de détails sur l’enregistrement de commandes natives au sein d’un passage de rendu QRhi, ainsi que QRhiTexture::createFrom() pour savoir comment encapsuler une texture native existante puis l’utiliser avec QRhi lors d’un passage de rendu ultérieur. Voir également QQuickGraphicsConfiguration concernant la configuration de l’environnement de l’API 3D native (par exemple, les extensions de périphérique) et notez que l’ QQuickWindow peut être associé à un QVulkanInstance personnalisé en appelant QWindow::setVulkanInstance() suffisamment tôt.

Un exemple simple

Prenons la sous-classe suivante de `QQuickRhiItem`. Elle est présentée ici dans son intégralité. Elle affiche un seul triangle avec une projection en perspective, le triangle étant pivoté en fonction de la propriété ` angle ` de l’élément personnalisé. (Ce qui signifie qu’elle peut être pilotée, par exemple, à l’aide d’animations telles que ` NumberAnimation ` depuis 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 identique au code présenté dans l’introduction à l’ QRhiWidget. Les shaders de sommets et de fragments sont également les mêmes. Ceux-ci sont fournis sous forme de code source GLSL de type Vulkan et doivent d’abord être traités par l’infrastructure de shaders Qt. Pour ce faire, on peut soit exécuter manuellement l’outil en ligne de commande qsb, soit utiliser la fonction qt_add_shaders() dans CMake. Le QQuickRhiItem charge ces fichiers .qsb pré-traités qui sont fournis avec l’application. Consultez 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 intégré à QML (voir QML_NAMED_ELEMENT), notre élément personnalisé peut être instancié dans n’importe quelle scène. (après avoir importé le fichier ` 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 }
}

Consultez la section « Graphique de scène - Élément de texture RHI » pour un exemple plus complexe.