Grafo de escena - QSGRenderNode personalizado

Muestra cómo utilizar QSGRenderNode para implementar un renderizado personalizado en el grafo de escena Qt Quick.

El ejemplo del nodo de renderizado personalizado muestra cómo implementar una subclase de ` QQuickItem ` respaldada por un nodo del grafo de escena derivado de ` QSGRenderNode`, que proporciona su propio renderizado basado en ` QRhi`.

Triángulo RGB con rectángulos superpuestos, mostrado en los modos de renderizado «Directo» y «Capa»

Nota: Este ejemplo muestra una funcionalidad avanzada de bajo nivel que realiza un renderizado 3D portátil y multiplataforma, al tiempo que se basa en API del módulo Qt GUI con una garantía de compatibilidad limitada. Para poder utilizar las API de « QRhi », la aplicación se vincula a « Qt::GuiPrivate » e incluye « <rhi/qrhi.h> ».

QSGRenderNode permite el acceso directo a la interfaz de hardware de renderizado (RHI) dentro del grafo de escena. Este ejemplo muestra cómo crear un nodo de renderizado basado en QSGRenderNode y gestionarlo mediante un elemento personalizado. El nodo de renderizado crea un canal de RHI, actualiza los búferes de vértices y uniformes, y realiza el renderizado en el búfer de comandos de la RHI.

En la práctica, se trata de un enfoque portátil y multiplataforma para realizar un renderizado personalizado en línea con el propio renderizado del grafo de escena, sin recurrir a una API 3D nativa como OpenGL, Metal o Vulkan. En su lugar, la aplicación utiliza la capa de abstracción de gráficos y shaders de Qt.

QSGRenderNode es el elemento clave para una de las tres formas de integrar el renderizado 2D/3D personalizado en una escena de « Qt Quick ». Las otras dos opciones consisten en realizar el renderizado before o after el propio renderizado de la escena de « Qt Quick », o bien generar una pasada de renderizado completamente independiente dirigida a un objetivo de renderizado específico (una textura) y, a continuación, hacer que un elemento de la escena muestre dicha textura. El enfoque basado en QSGRenderNode es similar al anterior, en el sentido de que no implica pases de renderizado ni objetivos de renderizado adicionales, y permite inyectar comandos de renderizado personalizados «en línea» con el propio renderizado de la escena Qt Quick.

Consulte los siguientes ejemplos para conocer estos tres enfoques:

  • Grafo de escena - RHI «under» en QML: muestra un enfoque de «subcapa» basado en la señal QQuickWindow::beforeRendering(). No se necesitan pases de renderizado ni recursos adicionales, pero la composición y la fusión con el resto de la escena Qt Quick son bastante limitadas. El renderizado «debajo» o «encima» de la escena Qt Quick es el enfoque más sencillo.
  • Grafo de escena - Elemento de textura RHI - Muestra cómo crear un elemento personalizado QQuickItem que se renderiza en una textura y muestra un cuadrilátero texturizado con el contenido generado. Este método es muy flexible y permite una mezcla y composición completas de la imagen 2D resultante con el resto de la escena Qt Quick. Esto conlleva un paso de renderizado y un destino de renderizado adicionales.
  • Este ejemplo: muestra el enfoque «en línea», en el que el grafo de escena de ` Qt Quick ` recurre a la implementación del elemento y nodo personalizados durante la pasada de renderizado principal. Este enfoque puede ser excelente para el rendimiento (no implica pasadas de renderizado adicionales, texturizado ni mezcla), pero presenta posibles inconvenientes y es el método más complicado.

El elemento personalizado deriva de ` QQuickItem`. Lo más importante es que reimplementa ` updatePaintNode()` ().

class CustomRender : public QQuickItem
{
    Q_OBJECT
    Q_PROPERTY(QList<QVector2D> vertices READ vertices WRITE setVertices NOTIFY verticesChanged)
    QML_ELEMENT

public:
    explicit CustomRender(QQuickItem *parent = nullptr);

    QList<QVector2D> vertices() const;
    void setVertices(const QList<QVector2D> &newVertices);

signals:
    void verticesChanged();

protected:
    QSGNode *updatePaintNode(QSGNode *old, UpdatePaintNodeData *) override;

private:
    QList<QVector2D> m_vertices;
};

El constructor establece el indicador « ItemHasContents » para indicar que se trata de un elemento visual.

CustomRender::CustomRender(QQuickItem *parent)
    : QQuickItem(parent)
{
    setFlag(ItemHasContents, true);
    connect(this, &CustomRender::verticesChanged, this, &CustomRender::update);
}

La implementación de `updatePaintNode()` crea una instancia del nodo personalizado del grafo de escena, si aún no se ha hecho. El árbol ` QSGNode ` subyacente para este elemento consta de un único nodo, una instancia de una clase derivada de ` QSGRenderNode`. Cuando se utiliza el modelo de renderizado multihilo de Qt Quick, esta función se invoca en el hilo de renderizado con el hilo principal bloqueado. Por eso es seguro acceder a los datos del hilo principal (como los datos almacenados en QQuickItems). El nodo, la instancia de la subclase de QSGRenderNode, va a «permanecer» en el hilo de renderizado.

QSGNode *CustomRender::updatePaintNode(QSGNode *old, UpdatePaintNodeData *)
{
    CustomRenderNode *node = static_cast<CustomRenderNode *>(old);

    if (!node)
        node = new CustomRenderNode(window());

    node->setVertices(m_vertices);

    return node;
}

La clase « CustomRenderNode » deriva de « QSGRenderNode », reimplementando varias funciones virtuales. Para gestionar los recursos de QRhi (búferes, canalizaciones, etc.), los punteros inteligentes resultan muy útiles en este caso, ya que el nodo es destruido por el grafo de escena junto con el resto de la escena en el hilo de renderizado (si lo hay), mientras que QRhi sigue estando disponible; por lo tanto, liberar recursos desde el destructor o mediante punteros inteligentes es válido y seguro.

class CustomRenderNode : public QSGRenderNode
{
public:
    CustomRenderNode(QQuickWindow *window);

    void setVertices(const QList<QVector2D> &vertices);

    void prepare() override;
    void render(const RenderState *state) override;
    void releaseResources() override;
    RenderingFlags flags() const override;
    QSGRenderNode::StateFlags changedStates() const override;

protected:
    QQuickWindow *m_window;
    std::unique_ptr<QRhiBuffer> m_vertexBuffer;
    std::unique_ptr<QRhiBuffer> m_uniformBuffer;
    std::unique_ptr<QRhiShaderResourceBindings> m_resourceBindings;
    std::unique_ptr<QRhiGraphicsPipeline> m_pipeline;
    QList<QRhiShaderStage> m_shaders;
    bool m_verticesDirty = true;
    QList<QVector2D> m_vertices;
};

Las subclases de ` QSGRenderNode ` que se comportan correctamente también reimplementan ` releaseResources()`, que en este caso puede consistir en un simple conjunto de llamadas a `reset()`.

void CustomRenderNode::releaseResources()
{
    m_vertexBuffer.reset();
    m_uniformBuffer.reset();
    m_pipeline.reset();
    m_resourceBindings.reset();
}

Este ` QSGRenderNode ` realiza su renderizado a través de las API de ` QRhi ` (y no directamente a través de OpenGL, Vulkan, Metal, etc.), y tiene en cuenta la transformación del elemento (ya que, en realidad, solo realiza renderizado 2D). Por lo tanto, se especifican los indicadores adecuados, lo que puede suponer una pequeña mejora en el rendimiento.

QSGRenderNode::RenderingFlags CustomRenderNode::flags() const
{
    // We are rendering 2D content directly into the scene graph using QRhi, no
    // direct usage of a 3D API. Hence NoExternalRendering. This is a minor
    // optimization.

    // Additionally, the node takes the item transform into account by relying
    // on projectionMatrix() and matrix() (see prepare()) and never rendering at
    // other Z coordinates. Hence DepthAwareRendering. This is a potentially
    // bigger optimization.

    return QSGRenderNode::NoExternalRendering | QSGRenderNode::DepthAwareRendering;
}

Las funciones prepare() y render() se invocan cada vez que se renderiza la escena de Qt Quick. La primera se invoca al preparar (pero aún sin grabar) la pasada de renderizado. Normalmente, esto crea recursos —como búferes, texturas y canalizaciones gráficas—, si aún no se han creado, y pone en cola la carga de datos en ellos.

void CustomRenderNode::prepare()
{
    QRhi *rhi = m_window->rhi();
    QRhiResourceUpdateBatch *resourceUpdates = rhi->nextResourceUpdateBatch();

    if (m_verticesDirty) {
        m_vertexBuffer.reset();
        m_verticesDirty = false;
    }

    if (!m_vertexBuffer) {
        m_vertexBuffer.reset(rhi->newBuffer(QRhiBuffer::Immutable, QRhiBuffer::VertexBuffer,
                                            m_vertices.count() * sizeof(QVector2D)));
        m_vertexBuffer->create();
        resourceUpdates->uploadStaticBuffer(m_vertexBuffer.get(), m_vertices.constData());
    }

La función render() se invoca mientras está activa la grabación de una pasada de renderizado, ya sea dirigida a la cadena de intercambio (swapchain) de QQuickWindow o a una textura (en el caso de elementos en capas o cuando se encuentra dentro de un ShaderEffectSource).

void CustomRenderNode::render(const RenderState *)
{
    QRhiCommandBuffer *cb = commandBuffer();
    cb->setGraphicsPipeline(m_pipeline.get());
    QSize renderTargetSize = renderTarget()->pixelSize();
    cb->setViewport(QRhiViewport(0, 0, renderTargetSize.width(), renderTargetSize.height()));
    cb->setShaderResources();
    QRhiCommandBuffer::VertexInput vertexBindings[] = { { m_vertexBuffer.get(), 0 } };
    cb->setVertexInput(0, 1, vertexBindings);
    cb->draw(m_vertices.count());
}

Proyecto de ejemplo en code.qt.io

Véase también QSGRenderNode, QRhi, «Scene Graph - RHI Under QML», «Scene Graph - RHI Texture Item» y «Qt Quick Scene Graph».

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.