En esta página

Grafo de escena: geometría personalizada

Muestra cómo implementar una geometría personalizada en el gráfico de escena de Qt Quick.

El ejemplo de geometría personalizada muestra cómo crear un « QQuickItem » que utiliza la API del grafo de escena para construir una geometría personalizada para el grafo de escena. Para ello, se crea un elemento « BezierCurve », que pasa a formar parte del módulo «CustomGeometry» y se utiliza en un archivo QML.

Curva de Bézier representada mediante geometría personalizada del grafo de escena con tiras de líneas

Declaración de BezierCurve

#include <QtQuick/QQuickItem>

class BezierCurve : public QQuickItem
{
    Q_OBJECT

    Q_PROPERTY(QPointF p1 READ p1 WRITE setP1 NOTIFY p1Changed)
    Q_PROPERTY(QPointF p2 READ p2 WRITE setP2 NOTIFY p2Changed)
    Q_PROPERTY(QPointF p3 READ p3 WRITE setP3 NOTIFY p3Changed)
    Q_PROPERTY(QPointF p4 READ p4 WRITE setP4 NOTIFY p4Changed)

    Q_PROPERTY(int segmentCount READ segmentCount WRITE setSegmentCount NOTIFY segmentCountChanged)
    QML_ELEMENT

public:
    BezierCurve(QQuickItem *parent = nullptr);
    ~BezierCurve();

    QSGNode *updatePaintNode(QSGNode *, UpdatePaintNodeData *) override;

    QPointF p1() const { return m_p1; }
    QPointF p2() const { return m_p2; }
    QPointF p3() const { return m_p3; }
    QPointF p4() const { return m_p4; }

    int segmentCount() const { return m_segmentCount; }

    void setP1(const QPointF &p);
    void setP2(const QPointF &p);
    void setP3(const QPointF &p);
    void setP4(const QPointF &p);

    void setSegmentCount(int count);

signals:
    void p1Changed(const QPointF &p);
    void p2Changed(const QPointF &p);
    void p3Changed(const QPointF &p);
    void p4Changed(const QPointF &p);

    void segmentCountChanged(int count);

private:
    QPointF m_p1;
    QPointF m_p2;
    QPointF m_p3;
    QPointF m_p4;

    int m_segmentCount;
};

La declaración del elemento hereda de la clase ` QQuickItem ` y añade cinco propiedades: una para cada uno de los cuatro puntos de control de la curva de Bézier y un parámetro para controlar el número de segmentos en los que se subdivide la curva. Para cada una de las propiedades disponemos de las funciones getter y setter correspondientes. Dado que estas propiedades pueden vincularse en QML, también es preferible disponer de señales de notificación para cada una de ellas, de modo que el motor QML detecte los cambios y los utilice en consecuencia.

    QSGNode *updatePaintNode(QSGNode *, UpdatePaintNodeData *) override;

El punto de sincronización entre la escena QML y el grafo de escena de renderizado es la función virtual ` QQuickItem::updatePaintNode()`, que deben implementar todos los elementos con lógica personalizada del grafo de escena.

Nota: En muchas configuraciones de hardware,el grafo de escena se renderizará en un hilo independiente. Por lo tanto, es fundamental que la interacción con el grafo de escena se produzca de forma controlada, ante todo a través de la función QQuickItem::updatePaintNode().

Implementación de BezierCurve

BezierCurve::BezierCurve(QQuickItem *parent)
    : QQuickItem(parent)
    , m_p1(0, 0)
    , m_p2(1, 0)
    , m_p3(0, 1)
    , m_p4(1, 1)
    , m_segmentCount(32)
{
    setFlag(ItemHasContents, true);
}

El constructor de BezierCurve establece los valores por defecto para los puntos de control y el número de segmentos. La curva de Bézier se especifica en coordenadas normalizadas relativas al rectángulo delimitador del elemento.

El constructor también establece el indicador ` QQuickItem::ItemHasContents`. Este indicador indica al lienzo que este elemento proporciona contenido visual y que llamará a ` QQuickItem::updatePaintNode()` cuando llegue el momento de sincronizar la escena QML con el grafo de escena de renderizado.

BezierCurve::~BezierCurve() = default;

La clase `BezierCurve` no tiene miembros de datos que deban liberarse, por lo que el destructor no realiza ninguna acción. Cabe mencionar que el grafo de escena de renderizado es gestionado por el propio grafo de escena, potencialmente en un hilo diferente, por lo que nunca se deben retener referencias ` QSGNode ` en la clase ` QQuickItem ` ni intentar liberarlas explícitamente.

void BezierCurve::setP1(const QPointF &p)
{
    if (p == m_p1)
        return;

    m_p1 = p;
    emit p1Changed(p);
    update();
}

La función setter de la propiedad p1 comprueba si el valor no ha cambiado y, en caso afirmativo, sale anticipadamente. A continuación, actualiza el valor interno y emite la señal «changed». Después, procede a llamar a la función QQuickItem::update(), que notificará al grafo de escena de renderizado que el estado de este objeto ha cambiado y debe sincronizarse con dicho grafo. Una llamada a update() dará lugar a una llamada a QQuickItem::updatePaintNode() más adelante.

Los demás setters de propiedades son equivalentes y se omiten en este ejemplo.

QSGNode *BezierCurve::updatePaintNode(QSGNode *oldNode, UpdatePaintNodeData *)
{
    QSGGeometryNode *node = nullptr;
    QSGGeometry *geometry = nullptr;

    if (!oldNode) {
        node = new QSGGeometryNode;

La función `updatePaintNode()` es el principal punto de integración para sincronizar el estado de la escena QML con el grafo de escena de renderizado. A la función se le pasa un ` QSGNode `, que es la instancia devuelta en la última llamada a la función. Será nulo la primera vez que se llame a la función, momento en el que creamos nuestro ` QSGGeometryNode `, al que rellenaremos con geometría y un material.

        geometry = new QSGGeometry(QSGGeometry::defaultAttributes_Point2D(), m_segmentCount);
        geometry->setLineWidth(2);
        geometry->setDrawingMode(QSGGeometry::DrawLineStrip);
        node->setGeometry(geometry);
        node->setFlag(QSGNode::OwnsGeometry);

A continuación, creamos la geometría y la añadimos al nodo. El primer argumento del constructor de QSGGeometry es una definición del tipo de vértice, denominada «conjunto de atributos». Dado que los gráficos que se utilizan habitualmente en QML se basan en unos pocos conjuntos de atributos estándar comunes, estos se proporcionan por defecto. Aquí utilizamos el conjunto de atributos Point2D, que tiene dos valores de tipo float, uno para las coordenadas x y otro para las coordenadas y. El segundo argumento es el número de vértices.

También se pueden crear conjuntos de atributos personalizados, pero eso no se trata en este ejemplo.

Dado que no tenemos ninguna necesidad especial en cuanto a la gestión de la memoria de la geometría, especificamos que el ` QSGGeometryNode ` debe ser el propietario de la geometría.

Para minimizar las asignaciones, reducir la fragmentación de la memoria y mejorar el rendimiento, también sería posible hacer que la geometría formara parte de una subclase de ` QSGGeometryNode `; en ese caso, no habríamos establecido el indicador `QSGGeometryNode::OwnsGeometry`.

        auto *material = new QSGFlatColorMaterial;
        material->setColor(QColor(255, 0, 0));
        node->setMaterial(material);
        node->setFlag(QSGNode::OwnsMaterial);

La API del grafo de escena proporciona algunas implementaciones de materiales de uso común. En este ejemplo utilizamos el ` QSGFlatColorMaterial`, que rellenará la forma definida por la geometría con un color sólido. De nuevo, transferimos la propiedad del material al nodo, para que el grafo de escena pueda liberarlo.

    } else {
        node = static_cast<QSGGeometryNode *>(oldNode);
        geometry = node->geometry();
        geometry->allocate(m_segmentCount);
    }

En el caso de que el elemento QML haya cambiado y solo queramos modificar la geometría del nodo existente, convertimos el ` oldNode ` en una instancia de ` QSGGeometryNode ` y extraemos su geometría. En caso de que haya cambiado el número de segmentos, llamamos a ` QSGGeometry::allocate()` para asegurarnos de que tiene el número correcto de vértices.

    QSizeF itemSize = size();
    QSGGeometry::Point2D *vertices = geometry->vertexDataAsPoint2D();
    for (int i = 0; i < m_segmentCount; ++i) {
        qreal t = i / qreal(m_segmentCount - 1);
        qreal invt = 1 - t;

        QPointF pos = invt * invt * invt * m_p1
                    + 3 * invt * invt * t * m_p2
                    + 3 * invt * t * t * m_p3
                    + t * t * t * m_p4;

        float x = pos.x() * itemSize.width();
        float y = pos.y() * itemSize.height();

        vertices[i].set(x, y);
    }
    node->markDirty(QSGNode::DirtyGeometry);

Para rellenar la geometría, primero extraemos de ella la matriz de vértices. Dado que estamos utilizando uno de los conjuntos de atributos predeterminados, podemos usar la función de conveniencia QSGGeometry::vertexDataAsPoint2D(). A continuación, recorremos cada segmento, calculamos su posición y escribimos ese valor en el vértice.

    return node;
}

Al final de la función, devolvemos el nodo para que el grafo de escena pueda renderizarlo.

Punto de entrada de la aplicación

int main(int argc, char **argv)
{
    QGuiApplication app(argc, argv);

    QQuickView view;
    QSurfaceFormat format = view.format();
    format.setSamples(16);
    view.setFormat(format);
    view.setSource(QUrl("qrc:///scenegraph/customgeometry/main.qml"));
    view.show();

    return app.exec();
}

La aplicación es una sencilla aplicación QML, con un ` QGuiApplication ` y un ` QQuickView ` a los que pasamos un archivo .qml.

    QML_ELEMENT

Para utilizar el elemento `BezierCurve`, debemos registrarlo en el motor QML mediante la macro ` QML_ELEMENT `. Esto le asigna el nombre `BezierCurve` y lo integra en el módulo ` CustomGeometry 1.0 `, tal y como se define en los archivos de compilación del proyecto:

# Copyright (C) 2022 The Qt Company Ltd.
# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause

cmake_minimum_required(VERSION 3.16)
project(customgeometry_declarative LANGUAGES CXX)

find_package(Qt6 REQUIRED COMPONENTS Core Gui Quick)

qt_standard_project_setup()

qt_add_executable(customgeometry_declarative WIN32 MACOSX_BUNDLE
    beziercurve.cpp beziercurve.h
    main.cpp
)

target_link_libraries(customgeometry_declarative PRIVATE
    Qt6::Core
    Qt6::Gui
    Qt6::Quick
)

qt_add_qml_module(customgeometry_declarative
    URI CustomGeometry
    QML_FILES main.qml
    RESOURCE_PREFIX /scenegraph/customgeometry
    NO_RESOURCE_TARGET_PATH
)

install(TARGETS customgeometry_declarative
    BUNDLE  DESTINATION .
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
)

qt_generate_deploy_qml_app_script(
    TARGET customgeometry_declarative
    OUTPUT_SCRIPT deploy_script
    NO_UNSUPPORTED_PLATFORM_ERROR
    DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM
)
install(SCRIPT ${deploy_script})
TARGET = customgeometry
QT += quick

CONFIG += qmltypes
QML_IMPORT_NAME = CustomGeometry
QML_IMPORT_MAJOR_VERSION = 1

SOURCES += \
    main.cpp \
    beziercurve.cpp

HEADERS += \
    beziercurve.h

RESOURCES += customgeometry.qrc

target.path = $$[QT_INSTALL_EXAMPLES]/quick/scenegraph/customgeometry
INSTALLS += target

Dado que la curva Bézier se dibuja como tiras de líneas, especificamos que la vista debe someterse a multimuestreo para conseguir el suavizado. Esto no es obligatorio, pero hará que el elemento tenga un aspecto un poco mejor en los dispositivos que lo admitan. El multimuestreo no está activado por defecto, ya que a menudo conlleva un mayor consumo de memoria.

Uso del elemento

import QtQuick
import CustomGeometry

Nuestro archivo .qml importa el módulo « QtQuick 2.0 » para obtener los tipos estándar y también nuestro propio módulo « CustomGeometry 1.0 », que contiene nuestros objetos «BezierCurve» recién creados.

Item {
    width: 300
    height: 200

    BezierCurve {
        id: line
        anchors.fill: parent
        anchors.margins: 20

A continuación, creamos nuestro elemento raíz y una instancia de BezierCurve que anclamos para rellenar la raíz.

        property real t
        SequentialAnimation on t {
            NumberAnimation { to: 1; duration: 2000; easing.type: Easing.InOutQuad }
            NumberAnimation { to: 0; duration: 2000; easing.type: Easing.InOutQuad }
            loops: Animation.Infinite
        }

        p2: Qt.point(t, 1 - t)
        p3: Qt.point(1 - t, t)
    }

Para que el ejemplo resulte un poco más interesante, añadimos una animación para modificar los dos puntos de control de la curva. Los puntos finales permanecen inalterados.

    Text {
        anchors.bottom: line.bottom

        x: 20
        width: parent.width - 40
        wrapMode: Text.WordWrap

        text: qsTr("This curve is a custom scene graph item, implemented using line strips")
    }
}

Por último, superponemos un breve texto que resume lo que muestra el ejemplo.

Proyecto de ejemplo en code.qt.io

© 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.