Grafo de escena: elemento de textura RHI
Muestra cómo implementar un elemento de textura personalizado de « QQuickItem » que muestra una textura renderizada mediante « QRhi ».

Este ejemplo muestra cómo implementar un elemento que realiza un renderizado 3D portátil y multiplataforma en una textura utilizando las API de QRhi y, a continuación, muestra esa imagen.
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>.
Comparación con otros enfoques
El ejemplo «RHI Under QML » muestra cómo implementar un renderizado 3D portátil y multiplataforma con las API de QRhi de tal forma que el renderizado personalizado se ejecute antes que el propio renderizado del grafo de escena de Qt Quick, proporcionando así, en la práctica, una «capa subyacente». Este enfoque resulta eficiente, ya que, al no ser necesarios objetivos de renderizado ni pasadas de renderizado adicionales, el renderizado personalizado se inyecta en la pasada de renderizado principal antes de las llamadas de dibujo propias del grafo de escena.
Por el contrario, este ejemplo implica un objetivo de renderizado independiente, un QRhiTexture, cuya dimensions coincide con el tamaño del QQuickItem en la escena, y un paso de renderizado completo que se utiliza para borrar y, a continuación, dibujar sobre esa textura. A continuación, la textura se muestrea en el paso de renderizado principal y se utiliza para texturizar un cuadrilátero, mostrando de hecho una imagen 2D.
En comparación con el enfoque de capa inferior/superpuesta, esto permite mostrar, mezclar y transformar la imagen 2D aplanada del renderizado 3D en cualquier lugar de la escena Qt Quick, ya que aquí disponemos de una auténtica QQuickItem. Esto tiene como contrapartida un mayor coste en términos de recursos y rendimiento, ya que implica renderizar primero en una textura.
Descripción general
El ejemplo se ha implementado utilizando QQuickRhiItem y QQuickRhiItemRenderer. QQuickRhiItem es una clase de conveniencia de la que se pueden crear subclases para obtener de forma fácil y rápida un QQuickItem personalizado y con todas las funciones que muestre el contenido de un QRhiTexture utilizando QSGSimpleTextureNode en segundo plano. El contenido de la textura lo genera la lógica proporcionada por la aplicación e implementada en su subclase QQuickRhiItemRenderer.
ExampleRhiItem Es una subclase de « QQuickRhiItem » que ofrece algunas propiedades, como « angle » y « backgroundAlpha ». Estas se leerán, escribirán y animarán desde QML. Para dar soporte al modelo de renderizado multihilo de Qt Quick, QQQuickRhiItemRenderer cuenta con una función virtual synchronize() que puede reimplementarse para realizar de forma segura la copia de datos entre QQuickRhiItem (perteneciente al hilo principal/GUI) y QQuickRhiItemRenderer (perteneciente al hilo de renderizado, si existe).
QQuickRhiItemRenderer *ExampleRhiItem::createRenderer()
{
return new ExampleRhiItemRenderer;
}
void ExampleRhiItem::setAngle(float a)
{
if (m_angle == a)
return;
m_angle = a;
emit angleChanged();
update();
}
void ExampleRhiItem::setBackgroundAlpha(float a)
{
if (m_alpha == a)
return;
m_alpha = a;
emit backgroundAlphaChanged();
update();
}
void ExampleRhiItemRenderer::synchronize(QQuickRhiItem *rhiItem)
{
ExampleRhiItem *item = static_cast<ExampleRhiItem *>(rhiItem);
if (item->angle() != m_angle)
m_angle = item->angle();
if (item->backgroundAlpha() != m_alpha)
m_alpha = item->backgroundAlpha();
}initialize() se llama al menos una vez antes de la primera llamada a `render()`, pero en la práctica puede invocarse varias veces: si cambia la geometría de ` QQuickItem ` (debido a algún cambio en el diseño, al redimensionar la ventana, etc.), si cambia algún parámetro de QQuickRhiItem —como el número de muestras o el formato de textura— o si se cambia la relación de parentesco del elemento para que pertenezca a un nuevo QQuickWindow, todo ello desencadena una nueva llamada a initialize(), ya que implica que uno o varios de los recursos QQuickRhiItem gestionados cambian, lo que también tendrá repercusiones en la subclase. El código de ejemplo que se muestra aquí está preparado para gestionar estas situaciones especiales (cambio de QRhi, cambio del número de muestras, cambio del formato de textura). (Dado que no conserva la textura utilizada como búfer de color, el caso en el que la textura se recrea debido a un tamaño diferente no requiere un tratamiento especial).
void ExampleRhiItemRenderer::initialize(QRhiCommandBuffer *cb)
{
if (m_rhi != rhi()) {
m_rhi = rhi();
m_pipeline.reset();
}
if (m_sampleCount != renderTarget()->sampleCount()) {
m_sampleCount = renderTarget()->sampleCount();
m_pipeline.reset();
}
QRhiTexture *finalTex = m_sampleCount > 1 ? resolveTexture() : colorTexture();
if (m_textureFormat != finalTex->format()) {
m_textureFormat = finalTex->format();
m_pipeline.reset();
}El resto de la función `initialize()` es código sencillo basado en ` QRhi`.
La escena 3D utiliza una proyección en perspectiva, que se calcula en función del tamaño de salida, obtenido de QRhiRenderTarget por comodidad (ya que esto funciona independientemente de si se utiliza el multimuestreo o no, mientras que acceder a colorTexture() y msaaColorBuffer() requeriría una lógica de ramificación basada en cuál de los objetos resulta válido)
Cabe destacar el uso de QRhi::clipSpaceCorrMatrix() para tener en cuenta las diferencias en los sistemas de coordenadas entre las API de gráficos 3D.
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(":/scenegraph/rhitextureitem/shaders/color.vert.qsb")) },
{ QRhiShaderStage::Fragment, getShader(QLatin1String(":/scenegraph/rhitextureitem/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->setSampleCount(m_sampleCount);
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);La implementación de render() registra el dibujo de un único triángulo. El búfer uniforme con la matriz 4x4 se actualiza cada vez, ya que esperamos que el ángulo de rotación cambie. El color de fondo tiene incorporado el alfa de fondo proporcionado por el elemento. Recuerda que también es necesario premultiplicar el valor alfa en los componentes rojo, verde y azul.
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());
// Qt Quick expects premultiplied alpha
const QColor clearColor = QColor::fromRgbF(0.5f * m_alpha, 0.5f * m_alpha, 0.7f * m_alpha, m_alpha);
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();
}Véase también QQuickRhiItem, «Grafo de escena - RHI bajo QML» 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.