Ejemplo sencillo de un widget RHI
Muestra cómo dibujar un triángulo utilizando « QRhi », la API Qt 3D y la capa de abstracción del lenguaje de sombreado.

Captura de pantalla del ejemplo de widget RHI sencillo
Este ejemplo es, en muchos aspectos, el equivalente al ejemplo de ventana RHI en el entorno de QWidget. La subclase « QRhiWidget » de esta aplicación dibuja un único triángulo utilizando un sencillo proceso de renderizado con sombreadores de vértices y fragmentos básicos. A diferencia de la aplicación sencilla basada en « QWindow », este ejemplo no tiene que preocuparse por detalles de bajo nivel, como la configuración de la ventana y el « QRhi », ni por gestionar la cadena de intercambio (swapchain) y los eventos de ventana, ya que de ello se encarga aquí el marco de trabajo « QWidget ». La instancia de la subclase QRhiWidget se añade a un QVBoxLayout. Para que el ejemplo sea lo más sencillo y compacto posible, no se introducen más widgets ni contenido 3D.
Una vez que se añade una instancia de ` ExampleRhiWidget`, una subclase de ` QRhiWidget `, a la jerarquía de hijos de un widget de nivel superior, la ventana correspondiente se convierte automáticamente en una ventana renderizada con Direct 3D, Vulkan, Metal u OpenGL. El contenido del widget renderizado por « QPainter », es decir, todo lo que no sea un « QRhiWidget », « QOpenGLWidget » o « QQuickWidget », se carga entonces en una textura, mientras que cada uno de los widgets especiales mencionados se renderiza en una textura. El conjunto resultante de « textures » se compone mediante el «backingstore» del widget de nivel superior.
Estructura y main()
La función main() es bastante sencilla. El widget de nivel superior tiene por defecto un tamaño de 720p (este tamaño está expresado en unidades lógicas; el tamaño real en píxeles puede variar en función de scale factor). La ventana es redimensionable. QRhiWidget facilita la implementación de subclases que gestionen correctamente el redimensionamiento del widget debido a cambios en el tamaño de la ventana o en el diseño.
int main(int argc, char **argv)
{
QApplication app(argc, argv);
ExampleRhiWidget *rhiWidget = new ExampleRhiWidget;
QVBoxLayout *layout = new QVBoxLayout;
layout->addWidget(rhiWidget);
QWidget w;
w.setLayout(layout);
w.resize(1280, 720);
w.show();
return app.exec();
}La subclase ` QRhiWidget ` reimplementa los dos métodos virtuales: ` initialize()` y ` render()`. initialize() se llama al menos una vez antes de render(), pero también se invoca ante una serie de cambios importantes, como cuando se recrea la textura de fondo del widget debido a un cambio en su tamaño, cuando cambian los parámetros del destino de renderizado o cuando el widget pasa a un nuevo « QRhi » al trasladarse a una nueva ventana de nivel superior.
Nota: A diferencia del modelo heredado de QOpenGLWidget( initializeGL - resizeGL - paintGL ), en QRhiWidget solo hay dos métodos virtuales. Esto se debe a que hay más eventos especiales que pueden requerir atención, además del simple cambio de tamaño; por ejemplo, al cambiar de ventana principal. (Las implementaciones robustas de QOpenGLWidget tenían que hacer frente a esto realizando un seguimiento adicional, por ejemplo, controlando el ciclo de vida asociado de QOpenGLContext, lo que significa que los tres métodos virtuales no eran realmente suficientes). Para esto resulta más adecuado un par más sencillo de initialize - render, en el que initialize se vuelve a invocar ante cambios importantes.
La instancia de QRhi no es propiedad del widget. Se consultará en initialize() from the base class . Almacenarla como miembro permite reconocer los cambios cuando se vuelve a invocar initialize(). Sin embargo, los recursos gráficos, como los búferes de vértices y uniformes, o el canal de procesamiento gráfico, están bajo el control de ExampleRhiWidget.
#include <QRhiWidget>
#include <rhi/qrhi.h>
class ExampleRhiWidget : public QRhiWidget
{
public:
ExampleRhiWidget(QWidget *parent = nullptr) : QRhiWidget(parent) { }
void initialize(QRhiCommandBuffer *cb) override;
void render(QRhiCommandBuffer *cb) override;
private:
QRhi *m_rhi = nullptr;
std::unique_ptr<QRhiBuffer> m_vbuf;
std::unique_ptr<QRhiBuffer> m_ubuf;
std::unique_ptr<QRhiShaderResourceBindings> m_srb;
std::unique_ptr<QRhiGraphicsPipeline> m_pipeline;
QMatrix4x4 m_viewProjection;
float m_rotation = 0.0f;
};Para que la instrucción ` #include <rhi/qrhi.h> ` funcione, la aplicación debe enlazarse con ` GuiPrivate ` (o ` gui-private ` con qmake). Consulte QRhi para obtener más detalles sobre la promesa de compatibilidad de la familia de API QRhi.
CMakeLists.txt
target_link_libraries(simplerhiwidget PRIVATE
Qt6::Core
Qt6::Gui
Qt6::GuiPrivate
Qt6::Widgets
)Configuración de la representación
En examplewidget.cpp, la implementación del widget utiliza una función auxiliar para cargar un objeto QShader desde un archivo .qsb. Esta aplicación incluye archivos .qsb preconfigurados e incrustados en el ejecutable a través del sistema de recursos de Qt. Debido a las dependencias de los módulos (y a que aún se mantiene la compatibilidad con qmake), este ejemplo no utiliza la práctica función de CMake qt_add_shaders(), sino que incluye los archivos .qsb como parte del árbol de fuentes. Se recomienda que las aplicaciones reales eviten esto y utilicen en su lugar las funciones de integración con CMake del módulo Qt « Shader Tools » (qt_add_shaders). Independientemente del enfoque, en el código C++ la carga de los archivos « .qsb » incluidos o generados es la misma.
static QShader getShader(const QString &name)
{
QFile f(name);
return f.open(QIODevice::ReadOnly) ? QShader::fromSerialized(f.readAll()) : QShader();
}Veamos la implementación de `initialize()`. En primer lugar, se consulta el objeto ` QRhi ` y se almacena para su uso posterior, así como para permitir la comparación en futuras invocaciones de la función. Cuando se produce una discrepancia (por ejemplo, al mover el widget de una ventana a otra), se desencadena la recreación de los recursos gráficos necesarios mediante la destrucción y la asignación del valor `null` a un objeto adecuado, en este caso el ` m_pipeline`. El ejemplo no muestra de forma activa el cambio de padre entre ventanas, pero está preparado para gestionarlo. También está preparado para gestionar los cambios en el tamaño del widget que pueden producirse al redimensionar la ventana. Esto no requiere ningún tratamiento especial, ya que cada vez que ocurre se invoca ` initialize() `, por lo que consultar ` renderTarget()->pixelSize() ` o ` colorTexture()->pixelSize() ` siempre proporciona el tamaño más reciente y actualizado en píxeles. Para lo que este ejemplo no está preparado es para cambios en color buffer formats y multisample settings, ya que siempre utiliza los valores predeterminados (RGBA8 y sin antialiasing multisample).
void ExampleRhiWidget::initialize(QRhiCommandBuffer *cb)
{
if (m_rhi != rhi()) {
m_pipeline.reset();
m_rhi = rhi();
}Cuando es necesario (re)crear los recursos gráficos, initialize() lo hace utilizando un código bastante típico basado en QRhi. Basta con un único búfer de vértices con los datos de vértices entrelazados (posición-color), mientras que la matriz de proyección model-view se expone a través de un búfer uniforme de 64 bytes (16 flotantes). El búfer uniforme es el único recurso visible para el shader, y solo se utiliza en el shader de vértices. La canalización gráfica se basa en numerosos valores predeterminados (por ejemplo, prueba de profundidad desactivada, mezcla desactivada, escritura de color activada, culling de caras desactivado, la topología predeterminada de los triángulos, etc.). La disposición de los datos de vértices es x, y, r, g, b; por lo tanto, el paso es de 5 números de tipo float, mientras que el segundo atributo de entrada de vértices (el color) tiene un desplazamiento de 2 números de tipo float (omitiendo x y y). Cada canalización gráfica debe estar asociada a un QRhiRenderPassDescriptor. Esto se puede obtener del QRhiRenderTarget gestionado por la clase base.
Nota: Este ejemplo se basa en que el valor por defecto de QRhiWidget, autoRenderTarget, está establecido en true. Por eso no es necesario gestionar el destino de renderizado, sino que basta con consultar el existente llamando a renderTarget().
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(":/shader_assets/color.vert.qsb")) },
{ QRhiShaderStage::Fragment, getShader(QLatin1String(":/shader_assets/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->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);
}Por último, se calcula la matriz de proyección. Esto depende del tamaño del widget y, por lo tanto, se realiza de forma incondicional en cada invocación de las funciones.
Nota: Cualquier cálculo de tamaño y ventana de visualización debe basarse siempre y exclusivamente en el tamaño en píxeles obtenido del recurso que actúa como búfer de color, ya que ese es el destino de renderizado real. Evita calcular manualmente tamaños, ventanas de visualización, recortadores, etc., basándote en el tamaño indicado por QWidget o en la relación de píxeles del dispositivo.
Nota: La matriz de proyección incluye el correction matrix de QRhi para tener en cuenta las diferencias entre las API 3D en las coordenadas normalizadas del dispositivo (por ejemplo, Y hacia abajo frente a Y hacia arriba).
Se aplica una traslación de -4 únicamente para garantizar que el triángulo con valores de z iguales a 0 sea visible.
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);
}Renderizado
El widget registra una única pasada de renderizado, que contiene una única llamada de dibujo.
La matriz de proyección de la vista, calculada en la fase de inicialización, se combina con la matriz del modelo, que en este caso resulta ser una simple rotación. A continuación, la matriz resultante se escribe en el búfer uniforme. Obsérvese cómo se pasa resourceUpdates a beginPass(), lo cual es un atajo para no tener que invocar resourceUpdate() manualmente.
void ExampleRhiWidget::render(QRhiCommandBuffer *cb)
{
QRhiResourceUpdateBatch *resourceUpdates = m_rhi->nextResourceUpdateBatch();
m_rotation += 1.0f;
QMatrix4x4 modelViewProjection = m_viewProjection;
modelViewProjection.rotate(m_rotation, 0, 1, 0);
resourceUpdates->updateDynamicBuffer(m_ubuf.get(), 0, 64, modelViewProjection.constData());En la pasada de renderizado, se registra una única llamada de dibujo con 3 vértices. La canalización gráfica creada en el paso de inicialización se vincula al búfer de comandos, y la ventana de visualización se configura para cubrir todo el widget. Para que el búfer de uniformes sea visible para el sombreador (de vértices), se llama a setShaderResources() sin ningún argumento, lo que significa utilizar el m_srb, ya que este se asoció a la canalización en el momento de su creación. En renderizadores más complejos, no es raro pasar un objeto ` QRhiShaderResourceBindings ` diferente, siempre y cuando est layout-compatible e con el proporcionado en el momento de la creación de la canalización. No hay búfer de índices, y existe un único enlace de búfer de vértices (el único elemento de ` vbufBinding ` hace referencia a la única entrada de la lista de enlaces del ` QRhiVertexInputLayout ` que se especificó al crear la canalización).
const QColor clearColor = QColor::fromRgbF(0.4f, 0.7f, 0.0f, 1.0f);
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();Una vez registrado el paso de renderizado, se llama a update(). Esto solicita un nuevo fotograma y se utiliza para garantizar que el widget se actualice continuamente y que el triángulo aparezca girando. El hilo de renderizado (el hilo principal en este caso) está limitado por la frecuencia de presentación de forma predeterminada. En este ejemplo no hay un sistema de animación propiamente dicho, por lo que la rotación aumentará en cada fotograma, lo que significa que el triángulo girará a diferentes velocidades en pantallas con diferentes frecuencias de actualización.
update();
}Véase también QRhi, Ejemplo de widget RHI de cubo y Ejemplo de ventana RHI.
© 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.