Grafo de escenas - RHI bajo QML
Muestra cómo realizar el renderizado directamente con « QRhi » en una escena de « Qt Quick ».

Introducción
El ejemplo «RHI Under QML» muestra cómo una aplicación puede utilizar las señales QQuickWindow::beforeRendering() y QQuickWindow::beforeRenderPassRecording() para dibujar contenido personalizado basado en QRhi en una escena Qt Quick.
Para aquellas aplicaciones que deseen renderizar contenido de QRhi sobre la escena de Qt Quick, utilice QQuickWindow::beforeRendering() para cargar datos en los búferes y conéctese a la señal QQuickWindow::afterRenderPassRecording().
En este ejemplo, también veremos cómo es posible disponer de valores expuestos a QML que afecten a la representación basada en QRhi. Animamos el valor umbral utilizando un NumberAnimation en el archivo QML y, a continuación, este valor de tipo float se transmite en un búfer uniforme al sombreador de fragmentos.
El ejemplo es equivalente en la mayoría de los aspectos a los ejemplos «OpenGL bajo QML», «Direct3D 11 bajo QML», «Metal bajo QML» y «Vulkan bajo QML ». Esos ejemplos representan el mismo contenido utilizando directamente una API 3D. Este ejemplo, por el contrario, es totalmente multiplataforma y portátil, ya que admite de forma nativa el funcionamiento con todas las API 3D compatibles con QRhi (como OpenGL, Vulkan, Metal, Direct 3D 11 y 12).
Nota: Este ejemplo muestra funcionalidades avanzadas de bajo nivel que realizan un renderizado 3D portátil y multiplataforma, al tiempo que se basa en API con una garantía de compatibilidad limitada del módulo Qt GUI. Para poder utilizar las API de QRhi, la aplicación se vincula a Qt::GuiPrivate e incluye <rhi/qrhi.h>.
Añadir un renderizado personalizado como capa subyacente o superpuesta es una de las tres formas de integrar un renderizado 2D/3D personalizado en una escena de Qt Quick. Las otras dos opciones consisten en realizar el renderizado «en línea» con el propio renderizado de la escena de Qt Quick utilizando QSGRenderNode, o bien generar un paso de renderizado completamente independiente dirigido a un objetivo de renderizado específico (una textura) y, a continuación, hacer que un elemento de la escena muestre dicha textura. Consulta los ejemplos «Scene Graph - RHI Texture Item » y «Scene Graph - Custom QSGRenderNode » para conocer estos enfoques.
Conceptos básicos
La señal `beforeRendering()` se emite al inicio de cada fotograma, antes de que el grafo de escena comience su renderizado; por lo tanto, cualquier llamada de dibujo ` QRhi ` que se realice en respuesta a esta señal se apilará bajo los elementos ` Qt Quick `. Sin embargo, hay dos señales que son relevantes en este contexto: los comandos QRhi propios de la aplicación deben registrarse en el mismo búfer de comandos que utiliza el grafo de escena y, además, los comandos deben pertenecer a la misma pasada de renderizado. La función `beforeRendering()` por sí sola no es suficiente para esto, ya que se emite al inicio del fotograma, antes de comenzar a grabar un paso de renderizado mediante ` QRhiCommandBuffer::beginPass()`. Al conectarse también a `beforeRenderPassRecording()`, los comandos propios de la aplicación y el renderizado del grafo de escena acabarán en el orden correcto:
- El bucle de renderizado del grafo de escena llama a ` QRhi::beginFrame()`
- QQuickWindow::beforeRendering() se emite: la aplicación prepara los recursos para su renderizado personalizado
- El grafo de escena llama a QRhiCommandBuffer::beginPass()
- QQuickWindow::beforeRenderPassRecordingSe emite () — la aplicación registra las llamadas de dibujo
- El grafo de escena registra las llamadas de dibujo
Guía paso a paso
El renderizado personalizado está encapsulado en un ` QQuickItem` personalizado. ` RhiSquircle ` deriva de ` QQuickItem` y se expone a QML (fíjate en ` QML_ELEMENT`). La escena QML instancia ` RhiSquircle`. Sin embargo, ten en cuenta que no se trata de un elemento visual: el indicador ` QQuickItem::ItemHasContents ` no está activado. Por lo tanto, la posición y el tamaño del elemento no tienen relevancia y no reimplementa ` updatePaintNode()`.
class RhiSquircle : public QQuickItem
{
Q_OBJECT
Q_PROPERTY(qreal t READ t WRITE setT NOTIFY tChanged)
QML_ELEMENT
public:
RhiSquircle();
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 = 0;
SquircleRenderer *m_renderer = nullptr;
};En su lugar, cuando el elemento se asocia a un ` QQuickWindow`, se conecta a la señal ` QQuickWindow::beforeSynchronizing()`. Es importante utilizar ` Qt::DirectConnection `, ya que esta señal se emite en el hilo de renderizado ` Qt Quick `, si existe. Queremos que la ranura conectada se invoque en este mismo hilo.
RhiSquircle::RhiSquircle()
{
connect(this, &QQuickItem::windowChanged, this, &RhiSquircle::handleWindowChanged);
}
void RhiSquircle::handleWindowChanged(QQuickWindow *win)
{
if (win) {
connect(win, &QQuickWindow::beforeSynchronizing, this, &RhiSquircle::sync, Qt::DirectConnection);
connect(win, &QQuickWindow::sceneGraphInvalidated, this, &RhiSquircle::cleanup, Qt::DirectConnection);
// Ensure we start with cleared to black. The squircle's blend mode relies on this.
win->setColor(Qt::black);
}
}En la fase de sincronización del grafo de escena, se crea la infraestructura de renderizado, si aún no se ha hecho, y se sincronizan los datos relevantes para el renderizado, es decir, se copian del elemento RhiSquircle, que reside en el hilo principal, al objeto SquircleRenderer, que reside en el hilo de renderizado. (Si no hay hilo de renderizado, ambos objetos residen en el hilo principal). El acceso a los datos es seguro porque el hilo principal queda bloqueado mientras el hilo de renderizado ejecuta su fase de sincronización. Consulte Qt Quick Scene Graph para obtener más información sobre el modelo de hilos y renderizado del grafo de escena.
Además del valor de ` t`, también se copia el puntero ` QQuickWindow ` asociado. Aunque el ` SquircleRenderer ` podría consultar ` window()` en el elemento ` RhiSquircle ` incluso cuando opera en el hilo de renderizado, esto, en teoría, no es del todo seguro. De ahí que se realice una copia.
Al configurar el ` SquircleRenderer`, se establecen conexiones con ` beforeRendering()` y ` beforeRenderPassRecording()`, que son fundamentales para poder actuar e inyectar los comandos de renderizado 3D personalizados de la aplicación en el momento adecuado.
void RhiSquircle::sync()
{
// This function is invoked on the render thread, if there is one.
if (!m_renderer) {
m_renderer = new SquircleRenderer;
// Initializing resources is done before starting to record the
// renderpass, regardless of wanting an underlay or overlay.
connect(window(), &QQuickWindow::beforeRendering, m_renderer, &SquircleRenderer::frameStart, Qt::DirectConnection);
// Here we want an underlay and therefore connect to
// beforeRenderPassRecording. Changing to afterRenderPassRecording
// would render the squircle on top (overlay).
connect(window(), &QQuickWindow::beforeRenderPassRecording, m_renderer, &SquircleRenderer::mainPassRecordingStart, Qt::DirectConnection);
}
m_renderer->setT(m_t);
m_renderer->setWindow(window());
}Cuando se emite beforeRendering(), se crean, si aún no se han creado, los recursos de QRhi necesarios para nuestro renderizado personalizado, como QRhiBuffer, QRhiGraphicsPipeline y los objetos relacionados.
Los datos de los búferes se actualizan (más concretamente, las operaciones de actualización de datos se colocan en la cola) mediante QRhiResourceUpdateBatch y QRhiCommandBuffer::resourceUpdate(). El búfer de vértices no cambia su contenido una vez que se ha cargado en él el conjunto inicial de vértices. El búfer de uniformes, sin embargo, es un búfer « dynamic », como es habitual en este tipo de búferes. Su contenido, al menos en algunas regiones, se actualiza en cada fotograma. De ahí la llamada incondicional a ` updateDynamicBuffer()` para el desplazamiento 0 y un tamaño de byte de 4 (que es ` sizeof(float) `, ya que el tipo ` float ` de C++ coincide con el tipo de 32 bits ` float` de GLSL). Lo que se almacena en esa posición es el valor de t, y este se actualiza en cada fotograma, es decir, en cada invocación de frameStart().
Hay un valor float adicional en el búfer, que comienza en el desplazamiento 4. Se utiliza para adaptarse a las diferencias entre los sistemas de coordenadas de las API 3D: cuando isYUpInNDC() devuelve false —lo cual ocurre, en particular, con Vulkan—, el valor se establece en -1,0, lo que provoca que se invierta el valor de Y en el vector de dos componentes que se pasa (mediante interpolación) al sombreador de fragmentos, a partir del cual se calcula el color. De este modo, el resultado en pantalla es idéntico (es decir, la esquina superior izquierda tiene un tono verdoso y la inferior izquierda, un tono rojizo), independientemente de la API 3D que se utilice. Este valor se actualiza solo una vez en el búfer de uniformes, de forma similar al búfer de vértices. Esto pone de relieve un problema al que a menudo debe hacer frente el código de renderizado de bajo nivel que pretende ser portátil: las diferencias en el sistema de coordenadas entre las coordenadas normalizadas del dispositivo (NDC) y las de las imágenes y los búferes de fotogramas. Por ejemplo, las NDC utilizan un sistema con origen en la esquina inferior izquierda en todas partes, excepto en Vulkan. Por su parte, los framebuffers utilizan un sistema con origen en la esquina superior izquierda en todas partes, excepto en OpenGL. Los renderizadores típicos que trabajan con una proyección en perspectiva a menudo pueden ignorar este problema recurriendo convenientemente a ` QRhi::clipSpaceCorrMatrix()`, que es una matriz que se puede multiplicar por la matriz de proyección y que aplica tanto un cambio de Y cuando es necesario como tiene en cuenta el hecho de que la profundidad del espacio de recorte es « -1..1 » en OpenGL, pero « 0..1 » en todos los demás casos. Sin embargo, en algunos casos, como en este ejemplo, esto no es aplicable. En su lugar, la aplicación y la lógica del sombreador deben realizar los ajustes necesarios en las posiciones de los vértices y las coordenadas UV según corresponda, basándose en las consultas a QRhi::isYUpInNDC() y QRhi::isYUpInFramebuffer().
Para acceder a los objetos QRhi y QRhiSwapChain que utiliza Qt Quick, basta con consultarlos a través de QQuickWindow. Ten en cuenta que esto supone que QQuickWindow es una ventana normal en pantalla. Si, en cambio, utilizara QQuickRenderControl, por ejemplo, para realizar un renderizado fuera de pantalla en una textura, consultar la cadena de intercambio sería incorrecto, ya que en ese caso no habría ninguna cadena de intercambio.
Dado que la señal se emite después de que Qt Quick llame a QRhi::beginFrame(), ya es posible consultar el búfer de comandos y el destino de renderizado de la cadena de intercambio. Esto es lo que permite emitir cómodamente un QRhiCommandBuffer::resourceUpdate() sobre el objeto devuelto por QRhiSwapChain::currentFrameCommandBuffer(). Al crear un canal gráfico, se puede recuperar una QRhiRenderPassDescriptor a partir del QRhiRenderTarget devuelto por QRhiSwapChain::currentFrameRenderTarget(). (ten en cuenta que esto significa que el canal de gráficos creado aquí solo es adecuado para renderizar en la cadena de intercambio (swapchain) o, en el mejor de los casos, en otro destino de renderizado que sea « compatible » con ella; es probable que, si quisiéramos renderizar en una textura, se necesitara un « QRhiRenderPassDescriptor » diferente y, por lo tanto, un canal de gráficos diferente, ya que los formatos de la textura y de la cadena de intercambio pueden diferir)
void SquircleRenderer::frameStart()
{
// Esta función se invoca en el hilo de renderizado, si lo hay.
QRhi*rhi = m_window->rhi();
if (!rhi) {
qWarning("QQuickWindow is not using QRhi for rendering");
return;
}
QRhiSwapChain*swapChain = m_window->swapChain();
if (!swapChain) {
qWarning("No QRhiSwapChain?");
return;
}
QRhiResourceUpdateBatch*resourceUpdates = rhi->nextResourceUpdateBatch();
if (!m_pipeline) {
m_vertexShader = getShader(QLatin1String(":/scenegraph/rhiunderqml/squircle_rhi.vert.qsb"));
if (!m_vertexShader.isValid())
qWarning("Failed to load vertex shader; rendering will be incorrect");
m_fragmentShader = getShader(QLatin1String(":/scenegraph/rhiunderqml/squircle_rhi.frag.qsb"));
if (!m_fragmentShader.isValid())
qWarning("Failed to load fragment shader; rendering will be incorrect");
m_vertexBuffer.reset(rhi->newBuffer(QRhiBuffer::Immutable, QRhiBuffer::VertexBuffer, sizeof(vertices)));
m_vertexBuffer->create();
resourceUpdates->uploadStaticBuffer(m_vertexBuffer.get(), vertices);
const quint32 UBUF_SIZE = 4 + 4; // 2 flotantes
m_uniformBuffer.reset(rhi->newBuffer(QRhiBuffer::Dynamic, QRhiBuffer::UniformBuffer, UBUF_SIZE));
m_uniformBuffer->create();
float yDir = rhi->isYUpInNDC() ? 1.0f:-1.0f;
resourceUpdates->updateDynamicBuffer(m_uniformBuffer.get(), 4, 4, &yDir);
m_srb.reset(rhi->newShaderResourceBindings());
const auto visibleToAll = QRhiShaderResourceBinding::VertexStage | QRhiShaderResourceBinding::FragmentStage;
m_srb->setBindings({
QRhiShaderResourceBinding::uniformBuffer(0, visibleToAll, m_uniformBuffer.get())
});
m_srb->create();
QRhiVertexInputLayout inputLayout;
inputLayout.setBindings({
{ 2 * sizeof(float) }
});
inputLayout.setAttributes({
{ 0, 0, QRhiVertexInputAttribute::Float2, 0 }
});
m_pipeline.reset(rhi->newGraphicsPipeline());
m_pipeline->setTopology(QRhiGraphicsPipeline::TriangleStrip);
QRhiGraphicsPipeline::TargetBlendblend;
blend.enable = true;
blend.srcColor = QRhiGraphicsPipeline::SrcAlpha;
blend.srcAlpha = QRhiGraphicsPipeline::SrcAlpha;
blend.dstColor = QRhiGraphicsPipeline::One;
blend.dstAlpha = QRhiGraphicsPipeline::One;
m_pipeline->setTargetBlends({ blend });
m_pipeline->setShaderStages({
{ QRhiShaderStage::Vertex, m_vertexShader },
{ QRhiShaderStage::Fragment, m_fragmentShader }
});
m_pipeline->setVertexInputLayout(inputLayout);
m_pipeline->setShaderResourceBindings(m_srb.get());
m_pipeline->setRenderPassDescriptor(swapChain->currentFrameRenderTarget()->renderPassDescriptor());
m_pipeline->create();
}
float t = m_t;
resourceUpdates->updateDynamicBuffer(m_uniformBuffer.get(), 0, 4, &t);
swapChain->currentFrameCommandBuffer()->resourceUpdate(resourceUpdates);
}Por último, al llamar a ` QQuickWindow::beforeRenderPassRecording()`, se registra una llamada de dibujo para una tira de triángulos con 4 vértices. En la práctica, este ejemplo simplemente dibuja un cuadrilátero y calcula los colores de los píxeles utilizando la lógica de los sombreadores de fragmento, pero las aplicaciones tienen libertad para realizar dibujos más complejos: crear múltiples tuberías gráficas y registrar múltiples llamadas de dibujo también es perfectamente válido. Lo importante que hay que tener en cuenta es que, sea lo que sea lo que se registre en el ` QRhiCommandBuffer ` obtenido a partir del ` swapchain` de la ventana, se antepone efectivamente al propio renderizado del grafo de escena ` Qt Quick ` dentro de la pasada de renderizado principal.
Nota: Esto significa que, si se utiliza el búfer de profundidad con pruebas de profundidad y se escriben valores de profundidad, el contenido de Qt Quick puede verse afectado por los valores escritos en el búfer de profundidad. Consulte «Qt Quick Scene Graph Default Renderer» para obtener más detalles sobre el renderizador del grafo de escena, en particular las secciones sobre el manejo de primitivas opacas y con mezcla alfa.
Para obtener el tamaño de la ventana en píxeles, se utiliza QRhiRenderTarget::pixelSize(). Esto resulta práctico porque, de este modo, el ejemplo no necesita calcular el tamaño de la ventana de visualización por otros medios y no tiene que preocuparse de aplicar el high DPI scale factor, si lo hay.
void SquircleRenderer::mainPassRecordingStart()
{
// This function is invoked on the render thread, if there is one.
QRhi *rhi = m_window->rhi();
QRhiSwapChain *swapChain = m_window->swapChain();
if (!rhi || !swapChain)
return;
const QSize outputPixelSize = swapChain->currentFrameRenderTarget()->pixelSize();
QRhiCommandBuffer *cb = m_window->swapChain()->currentFrameCommandBuffer();
cb->setViewport({ 0.0f, 0.0f, float(outputPixelSize.width()), float(outputPixelSize.height()) });
cb->setGraphicsPipeline(m_pipeline.get());
cb->setShaderResources();
const QRhiCommandBuffer::VertexInput vbufBinding(m_vertexBuffer.get(), 0);
cb->setVertexInput(0, 1, &vbufBinding);
cb->draw(4);
}Los shaders de vértices y de fragmentos pasan por el proceso estándar de acondicionamiento de shaders de QRhi. Escritos inicialmente en GLSL compatible con Vulkan, se compilan a SPIR-V y, a continuación, se transpilan a otros lenguajes de sombreado mediante las herramientas de Qt. Al utilizar CMake, el ejemplo se basa en el comando qt_add_shaders, que permite de forma sencilla y cómoda incluir los sombreadores en la aplicación y realizar el procesamiento necesario en el momento de la compilación. Consulta qt_add_shaders() para obtener más detalles.
Especificar ` BASE ` ayuda a eliminar el prefijo « ../shared », mientras que ` PREFIX ` añade el prefijo deseado « /scenegraph/rhiunderqml ». Así, la ruta final es ` :/scenegraph/rhiunderqml/squircle_rhi.vert.qsb`.
qt_add_shaders(rhiunderqml "rhiunderqml_shaders"
PRECOMPILE
OPTIMIZED
PREFIX
/scenegraph/rhiunderqml
BASE
../shared
FILES
../shared/squircle_rhi.vert
../shared/squircle_rhi.frag
)Para ser compatible con qmake, el ejemplo sigue incluyendo los archivos .qsb que normalmente se generarían en el momento de la compilación, y los enumera en el archivo qrc. Sin embargo, este enfoque no se recomienda para nuevas aplicaciones que utilicen CMake como sistema de compilación.
Véase también «Grafo de escena: elemento de textura RHI» y «Grafo de escena: QSGRenderNode personalizado».
© 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.