Grafo de escena: OpenGL en QML
Muestra cómo renderizar OpenGL en una escena de « Qt Quick ».
Qt Quick con texto superpuesto" src="images/openglunderqml-example.jpg" title="Cuadrado-circulo animado renderizado con OpenGL en una escena de Qt Quick con texto superpuesto"/>
El ejemplo «OpenGL en QML» muestra cómo una aplicación puede utilizar la señal « QQuickWindow::beforeRendering()» para dibujar contenido OpenGL personalizado en una escena « Qt Quick ». Esta señal se emite al inicio de cada fotograma, antes de que el grafo de escena comience su renderizado; por lo tanto, cualquier llamada de dibujo de OpenGL que se realice en respuesta a esta señal se apilará bajo los elementos « Qt Quick ».
Como alternativa, las aplicaciones que deseen renderizar contenido OpenGL sobre la escena Qt Quick pueden hacerlo conectándose a la señal QQuickWindow::afterRendering().
En este ejemplo, también veremos cómo es posible disponer de valores expuestos a QML que afecten al renderizado de OpenGL. Animamos el valor umbral utilizando un ` NumberAnimation ` en el archivo QML y este valor es utilizado por el programa de sombreado de OpenGL que dibuja los «squircles».
El ejemplo es equivalente en la mayoría de los aspectos a los ejemplos «Direct3D 11 bajo QML», «Metal bajo QML» y «Vulkan bajo QML»; todos ellos renderizan el mismo contenido personalizado, solo que a través de diferentes API nativas.
class Squircle : public QQuickItem
{
Q_OBJECT
Q_PROPERTY(qreal t READ t WRITE setT NOTIFY tChanged)
QML_ELEMENT
public:
Squircle();
qreal t() const { return m_t; }
void setT(qreal t);
signals:
void tChanged();
public slots:
void sync();
void cleanup();
private slots:
void handleWindowChanged(QQuickWindow *win);
private:
void releaseResources() override;
qreal m_t;
SquircleRenderer *m_renderer;
};En primer lugar, necesitamos un objeto que podamos exponer a QML. Se trata de una subclase de ` QQuickItem `, por lo que podemos acceder fácilmente a ` QQuickItem::window()`. Lo exponemos a QML utilizando la macro ` QML_ELEMENT `.
class SquircleRenderer : public QObject, protected QOpenGLFunctions
{
Q_OBJECT
public:
~SquircleRenderer();
void setT(qreal t) { m_t = t; }
void setViewportSize(const QSize &size) { m_viewportSize = size; }
void setWindow(QQuickWindow *window) { m_window = window; }
public slots:
void init();
void paint();
private:
QSize m_viewportSize;
qreal m_t = 0.0;
QOpenGLShaderProgram *m_program = nullptr;
QQuickWindow *m_window = nullptr;
QOpenGLBuffer m_vbo;
};A continuación, necesitamos un objeto que se encargue de la representación. Esta instancia debe estar separada de QQuickItem, ya que el elemento reside en el hilo de la interfaz gráfica de usuario y la representación puede tener lugar en el hilo de representación. Dado que queremos conectarnos a QQuickWindow::beforeRendering(), hacemos que el renderizador sea un QObject. El renderizador contiene una copia de todo el estado que necesita, independiente del hilo de la interfaz gráfica de usuario.
Nota: No caigas en la tentación de fusionar los dos objetos en uno solo. Los QQuickItems pueden eliminarse en el hilo de la interfaz gráfica de usuario mientras el hilo de renderizado está realizando el renderizado.
Pasemos a la implementación.
Squircle::Squircle()
: m_t(0)
, m_renderer(nullptr)
{
connect(this, &QQuickItem::windowChanged, this, &Squircle::handleWindowChanged);
}El constructor de la clase ` Squircle ` simplemente inicializa los valores y se conecta a la señal `changed` de la ventana, que utilizaremos para preparar nuestro renderizador.
void Squircle::handleWindowChanged(QQuickWindow *win)
{
if (win) {
connect(win, &QQuickWindow::beforeSynchronizing, this, &Squircle::sync, Qt::DirectConnection);
connect(win, &QQuickWindow::sceneGraphInvalidated, this, &Squircle::cleanup, Qt::DirectConnection);Una vez que tenemos una ventana, nos conectamos a la señal « QQuickWindow::beforeSynchronizing()», que utilizaremos para crear el renderizador y copiar el estado en él de forma segura. También nos conectamos a la señal « QQuickWindow::sceneGraphInvalidated()» para gestionar la limpieza del renderizador.
Nota: Dado que el objeto `Squircle` tiene afinidad con el hilo de la interfaz gráfica de usuario (GUI) y las señales se emiten desde el hilo de renderizado, es fundamental que las conexiones se realicen con ` Qt::DirectConnection`. De no hacerlo, las ranuras se invocarán en el hilo incorrecto, sin que exista un contexto OpenGL.
// Ensure we start with cleared to black. The squircle's blend mode relies on this.
win->setColor(Qt::black);
}
}El comportamiento predeterminado del grafo de escena es borrar el búfer de fotogramas antes de renderizar. Esto está bien, ya que insertaremos nuestro propio código de renderizado después de que se haya puesto en cola este borrado. Sin embargo, asegúrate de que el color de fondo sea el deseado (negro).
void Squircle::sync()
{
if (!m_renderer) {
m_renderer = new SquircleRenderer();
connect(window(), &QQuickWindow::beforeRendering, m_renderer, &SquircleRenderer::init, Qt::DirectConnection);
connect(window(), &QQuickWindow::beforeRenderPassRecording, m_renderer, &SquircleRenderer::paint, Qt::DirectConnection);
}
m_renderer->setViewportSize(window()->size() * window()->devicePixelRatio());
m_renderer->setT(m_t);
m_renderer->setWindow(window());
}Utilizamos la función ` sync() ` para inicializar el renderizador y copiar el estado de nuestro elemento en el mismo. Cuando se crea el renderizador, también conectamos ` QQuickWindow::beforeRendering()` y ` QQuickWindow::beforeRenderPassRecording()` a las ranuras ` init() ` y ` paint() ` del renderizador.
Nota: La señal QQuickWindow::beforeSynchronizing() se emite en el hilo de renderizado mientras el hilo de la interfaz gráfica de usuario está bloqueado, por lo que es seguro limitarse a copiar el valor sin necesidad de protección adicional.
void Squircle::cleanup()
{
delete m_renderer;
m_renderer = nullptr;
}
class CleanupJob : public QRunnable
{
public:
CleanupJob(SquircleRenderer *renderer) : m_renderer(renderer) { }
void run() override { delete m_renderer; }
private:
SquircleRenderer *m_renderer;
};
void Squircle::releaseResources()
{
window()->scheduleRenderJob(new CleanupJob(m_renderer), QQuickWindow::BeforeSynchronizingStage);
m_renderer = nullptr;
}
SquircleRenderer::~SquircleRenderer()
{
delete m_program;
}En la función cleanup() eliminamos el renderizador, que a su vez libera sus propios recursos. Esto se complementa reimplementando QQuickWindow::releaseResources(), ya que limitarse a conectarse a la señal sceneGraphInvalidated() no es suficiente por sí solo para gestionar todos los casos.
void Squircle::setT(qreal t)
{
if (t == m_t)
return;
m_t = t;
emit tChanged();
if (window())
window()->update();
}Cuando cambia el valor de ` t `, llamamos a ` QQuickWindow::update()` en lugar de a ` QQuickItem::update()`, ya que la primera obligará a redibujar toda la ventana, incluso cuando el grafo de escena no haya cambiado desde el último fotograma.
void SquircleRenderer::init()
{
if (!m_program) {
QSGRendererInterface *rif = m_window->rendererInterface();
Q_ASSERT(rif->graphicsApi() == QSGRendererInterface::OpenGL);
initializeOpenGLFunctions();
const float values[] = { -1, -1, 1, -1, -1, 1, 1, 1 };
m_vbo.create();
m_vbo.bind();
m_vbo.allocate(values, sizeof(values));
glEnableVertexAttribArray(0);
glVertexAttribPointer(0, 2, GL_FLOAT, GL_FALSE, 2 * sizeof(GLfloat), nullptr);
m_program = new QOpenGLShaderProgram();
m_program->addCacheableShaderFromSourceCode(QOpenGLShader::Vertex,
"attribute highp vec4 vertices;"
"varying highp vec2 coords;"
"void main() {"
" gl_Position = vertices;"
" coords = vertices.xy;"
"}");
m_program->addCacheableShaderFromSourceCode(QOpenGLShader::Fragment,
"uniform lowp float t;"
"varying highp vec2 coords;"
"void main() {"
" lowp float i = 1. - (pow(abs(coords.x), 4.) + pow(abs(coords.y), 4.));"
" i = smoothstep(t - 0.8, t + 0.8, i);"
" i = floor(i * 20.) / 20.;"
" gl_FragColor = vec4(coords * .5 + .5, i, i);"
"}");
m_program->bindAttributeLocation("vertices", 0);
m_program->link();
}
}En la función ` init() ` de `SquircleRenderer`, comenzamos inicializando el programa de sombreado si aún no se ha hecho. El contexto de OpenGL está activo en el hilo cuando se invoca la ranura.
void SquircleRenderer::paint()
{
// Play nice with the RHI. Not strictly needed when the scenegraph uses
// OpenGL directly.
m_window->beginExternalCommands();
m_vbo.bind();
m_program->bind();
m_program->setUniformValue("t", (float)m_t);
glEnableVertexAttribArray(0);
glVertexAttribPointer(0, 2, GL_FLOAT, GL_FALSE, 2 * sizeof(GLfloat), nullptr);
glViewport(0, 0, m_viewportSize.width(), m_viewportSize.height());
glDisable(GL_DEPTH_TEST);
glEnable(GL_BLEND);
glBlendFunc(GL_SRC_ALPHA, GL_ONE);
glDrawArrays(GL_TRIANGLE_STRIP, 0, 4);
glDisableVertexAttribArray(0);
m_program->release();
m_window->endExternalCommands();
}Utilizamos el programa de sombreado para dibujar el «squircle» en ` paint()`.
int main(int argc, char **argv)
{
QGuiApplication app(argc, argv);
QQuickWindow::setGraphicsApi(QSGRendererInterface::OpenGL);
QQuickView view;
view.setResizeMode(QQuickView::SizeRootObjectToView);
view.setSource(QUrl("qrc:///scenegraph/openglunderqml/main.qml"));
view.show();
return QGuiApplication::exec();
}La función ` main() ` de la aplicación crea una instancia de ` QQuickView ` y ejecuta el archivo ` main.qml `.
import QtQuick
import OpenGLUnderQML
Item {
width: 320
height: 480
Squircle {
SequentialAnimation on t {
NumberAnimation { to: 1; duration: 2500; easing.type: Easing.InQuad }
NumberAnimation { to: 0; duration: 2500; easing.type: Easing.OutQuad }
loops: Animation.Infinite
running: true
}
}Importamos el tipo QML «Squircle» con el nombre que hemos registrado en la función « main() ». A continuación, lo instanciamos y creamos un « NumberAnimation » en ejecución en su propiedad « t ».
Rectangle {
color: Qt.rgba(1, 1, 1, 0.7)
radius: 10
border.width: 1
border.color: "white"
anchors.fill: label
anchors.margins: -10
}
Text {
id: label
color: "black"
wrapMode: Text.WordWrap
text: qsTr("The background here is a squircle rendered with raw OpenGL using the 'beforeRender()' signal in QQuickWindow. This text label and its border is rendered using QML")
anchors.right: parent.right
anchors.left: parent.left
anchors.bottom: parent.bottom
anchors.margins: 20
}
}A continuación, superponemos un breve texto descriptivo, para que quede claro que, de hecho, estamos representando OpenGL en nuestra escena « Qt Quick ».
© 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.