Ejemplo de widget «Cube RHI»

Muestra cómo renderizar un cubo con textura e integrarlo con QPainter y widgets, utilizando QRhi, la API Qt 3D y la capa de abstracción del lenguaje de sombreado.

Aplicación que muestra superposiciones de renderizado complejas

Captura de pantalla del ejemplo del widget «Cubo RHI»

Este ejemplo se basa en el ejemplo «Simple RHI Widget». Mientras que el ejemplo sencillo es intencionadamente minimalista y lo más compacto posible —solo renderiza un único triángulo sin widgets adicionales en la ventana—, esta aplicación muestra:

  • La presencia de varios widgets en la ventana, algunos de los cuales controlan datos que son utilizados por la subclase « QRhiWidget ».
  • En lugar de solicitar actualizaciones continuamente, el « QRhiWidget » solo actualiza aquí el contenido de su textura de fondo cuando cambian algunos datos relacionados.
  • El cubo se texturiza utilizando un ` QRhiTexture ` que obtiene su contenido de un ` QImage ` que contiene un renderizado basado en software realizado con ` QPainter`.
  • El contenido del ` QRhiWidget ` ` can be read back ` se guarda en un archivo de imagen (por ejemplo, un archivo PNG).
  • Antialiasing de 4x multisample can be toggled en tiempo de ejecución. La subclase QRhiWidget está preparada para gestionar correctamente el recuento de muestras variable.
  • La aplicación de un « explicitly specified backing texture size » se puede activar o desactivar dinámicamente y controlar mediante un control deslizante con valores que van desde 16x16 hasta 512x512 píxeles.
  • La subclase QRhiWidget gestiona correctamente un QRhi variable. Esto se puede observar en acción al convertir el widget en de nivel superior (sin padre; se convierte en una ventana independiente) y, a continuación, volver a vincularlo a la jerarquía de hijos de la ventana principal.
  • Y lo más importante: algunos widgets, incluso con semitransparencia, pueden colocarse sobre el ` QRhiWidget`, lo que demuestra que es posible apilarlos y superponerlos correctamente. Este es un caso en el que el ` QRhiWidget ` es superior a la incrustación de una ventana nativa, es decir, un ` QWindow ` basado en ` QRhi` que utiliza ` QWidget::createWindowContainer()`, ya que permite el apilamiento y el recorte de la misma forma que cualquier QWidget normal renderizado por software, mientras que la incrustación de una ventana nativa puede, dependiendo de la plataforma, presentar diversas limitaciones; por ejemplo, a menudo puede resultar difícil o ineficiente colocar controles adicionales encima.

En la reimplementación de initialize(), lo primero que hay que hacer es comprobar si el QRhi con el que trabajamos por última vez sigue estando actualizado y si ha cambiado el recuento de muestras (para el antialiasing multimuestra). Lo primero es importante porque todos los recursos gráficos deben liberarse cuando cambia el QRhi, mientras que, con un recuento de muestras que cambia dinámicamente, surge un problema similar específicamente para los objetos QRhiGraphicsPipeline, ya que estos incorporan el recuento de muestras. Para simplificar, la aplicación gestiona todos estos cambios de la misma manera, restableciendo su estructura scene a una construida por defecto, lo que, convenientemente, libera todos los recursos gráficos. A continuación, se vuelven a crear todos los recursos.

Cuando cambia el tamaño de la textura de fondo (es decir, el tamaño del destino de renderizado), no es necesaria ninguna acción especial, pero se emite una señal por comodidad, simplemente para que main() pueda reposicionar la etiqueta superpuesta. El nombre de la API 3D también se expone a través de una señal al consultar QRhi::backendName() cada vez que cambia QRhi.

La implementación debe tener en cuenta que el antialiasing multimuestra implica que ` colorTexture()` es ` nullptr`, mientras que ` msaaColorBuffer()` es válido. Esto es lo contrario de lo que ocurre cuando no se utiliza MSAA. La razón para diferenciar y utilizar distintos tipos (QRhiTexture, QRhiRenderBuffer) es permitir el uso de MSAA con API de gráficos 3D que no admiten texturas multisample, pero sí admiten búferes de renderizado multisample. Un ejemplo de ello es OpenGL ES 3.0.

A la hora de comprobar el tamaño de píxel y el recuento de muestras actualizados, una solución práctica y compacta consiste en realizar la consulta a través de ` QRhiRenderTarget`, ya que de esta forma no es necesario comprobar cuál de las funciones `colorTexture()` y `msaaColorBuffer()` es válida.

void ExampleRhiWidget::initialize(QRhiCommandBuffer *)
{
    if (m_rhi != rhi()) {
        m_rhi = rhi();
        scene = {};
        emit rhiChanged(QString::fromUtf8(m_rhi->backendName()));
    }
    if (m_pixelSize != renderTarget()->pixelSize()) {
        m_pixelSize = renderTarget()->pixelSize();
        emit resized();
    }
    if (m_sampleCount != renderTarget()->sampleCount()) {
        m_sampleCount = renderTarget()->sampleCount();
        scene = {};
    }

El resto se explica por sí solo. Los búferes y las tuberías se (re)crean, si es necesario. Se actualiza el contenido de la textura que se utiliza para texturizar la malla del cubo. La escena se renderiza utilizando una proyección en perspectiva. La vista es, por ahora, una simple traslación.

    if (!scene.vbuf) {
        initScene();
        updateCubeTexture();
    }

    scene.mvp = m_rhi->clipSpaceCorrMatrix();
    scene.mvp.perspective(45.0f, m_pixelSize.width() / (float) m_pixelSize.height(), 0.01f, 1000.0f);
    scene.mvp.translate(0, 0, -4);
    updateMvp();
}

La función que lleva a cabo la puesta en cola efectiva de la escritura en el búfer uniforme también tiene en cuenta la rotación proporcionada por el usuario, generando así la matriz final de proyección del modelo-vista.

void ExampleRhiWidget::updateMvp()
{
    QMatrix4x4 mvp = scene.mvp * QMatrix4x4(QQuaternion::fromEulerAngles(QVector3D(30, itemData.cubeRotation, 0)).toRotationMatrix());
    if (!scene.resourceUpdates)
        scene.resourceUpdates = m_rhi->nextResourceUpdateBatch();
    scene.resourceUpdates->updateDynamicBuffer(scene.ubuf.get(), 0, 64, mvp.constData());
}

Actualizar el « QRhiTexture » que se muestrea en el sombreador de fragmentos al renderizar el cubo es bastante sencillo, aunque allí sucedan muchas cosas: primero se genera un dibujo basado en « QPainter » dentro de un « QImage ». Este utiliza el texto proporcionado por el usuario. A continuación, los datos de píxeles del lado de la CPU se cargan en una textura (más concretamente, la operación de carga se registra en un ` QRhiResourceUpdateBatch`, que luego se envía más adelante en `render()`).

void ExampleRhiWidget::updateCubeTexture()
{
    QImage image(CUBE_TEX_SIZE, QImage::Format_RGBA8888);
    const QRect r(QPoint(0, 0), CUBE_TEX_SIZE);
    QPainter p(&image);
    p.fillRect(r, QGradient::DeepBlue);
    QFont font;
    font.setPointSize(24);
    p.setFont(font);
    p.drawText(r, itemData.cubeText);
    p.end();

    if (!scene.resourceUpdates)
        scene.resourceUpdates = m_rhi->nextResourceUpdateBatch();
    scene.resourceUpdates->uploadTexture(scene.cubeTex.get(), image);
}

La inicialización de los recursos gráficos es sencilla. Solo hay un búfer de vértices, ningún búfer de índices y un búfer uniforme que contiene únicamente una matriz de 4x4 (16 números de tipo float).

La textura que contiene el dibujo generado por QPainter tiene un tamaño de 512x512. Ten en cuenta que todos los tamaños (tamaños de textura, ventanas de visualización, áreas de recorte, regiones de carga de texturas, etc.) se expresan siempre en píxeles cuando se trabaja con QRhi. Para muestrear esta textura en el sombreador, se necesita un « sampler object » (independientemente de que las aplicaciones basadas en QRhi suelen utilizar muestreadores de imagen combinados en el código del sombreador GLSL, que luego pueden transpilarse a objetos de textura y muestreador separados con algunos lenguajes de sombreado, o puede seguir siendo un objeto combinado de textura y muestreador junto con otros, lo que significa que puede que en realidad no haya un objeto muestreador nativo «bajo el capó» en tiempo de ejecución, dependiendo de la API 3D, pero todo esto es transparente para la aplicación)

El sombreador de vértices lee desde el búfer de uniformes en el punto de enlace 0, por lo que scene.ubuf queda expuesto en esa ubicación de enlace. El sombreador de fragmentos muestrea una textura proporcionada en el punto de enlace 1, por lo que se especifica un par combinado de textura y muestreador para esa ubicación de enlace.

QRhiGraphicsPipeline permite la prueba y escritura de profundidad, y elimina las caras posteriores. También se basa en una serie de valores predeterminados; por ejemplo, la función de comparación de profundidad se establece por defecto en ` Less`, lo cual nos viene bien, y el modo de cara frontal es en sentido antihorario, lo que también está bien tal cual, por lo que no es necesario volver a configurarlo.

    scene.vbuf.reset(m_rhi->newBuffer(QRhiBuffer::Immutable, QRhiBuffer::VertexBuffer, sizeof(cube)));
    scene.vbuf->create();

    scene.resourceUpdates = m_rhi->nextResourceUpdateBatch();
    scene.resourceUpdates->uploadStaticBuffer(scene.vbuf.get(), cube);

    scene.ubuf.reset(m_rhi->newBuffer(QRhiBuffer::Dynamic, QRhiBuffer::UniformBuffer, 64));
    scene.ubuf->create();

    scene.cubeTex.reset(m_rhi->newTexture(QRhiTexture::RGBA8, CUBE_TEX_SIZE));
    scene.cubeTex->create();

    scene.sampler.reset(m_rhi->newSampler(QRhiSampler::Linear, QRhiSampler::Linear, QRhiSampler::None,
                                               QRhiSampler::ClampToEdge, QRhiSampler::ClampToEdge));
    scene.sampler->create();

    scene.srb.reset(m_rhi->newShaderResourceBindings());
    scene.srb->setBindings({
        QRhiShaderResourceBinding::uniformBuffer(0, QRhiShaderResourceBinding::VertexStage, scene.ubuf.get()),
        QRhiShaderResourceBinding::sampledTexture(1, QRhiShaderResourceBinding::FragmentStage, scene.cubeTex.get(), scene.sampler.get())
    });
    scene.srb->create();

    scene.ps.reset(m_rhi->newGraphicsPipeline());
    scene.ps->setDepthTest(true);
    scene.ps->setDepthWrite(true);
    scene.ps->setCullMode(QRhiGraphicsPipeline::Back);
    scene.ps->setShaderStages({
        { QRhiShaderStage::Vertex, getShader(QLatin1String(":/shader_assets/texture.vert.qsb")) },
        { QRhiShaderStage::Fragment, getShader(QLatin1String(":/shader_assets/texture.frag.qsb")) }
    });
    QRhiVertexInputLayout inputLayout;
    // The cube is provided as non-interleaved sets of positions, UVs, normals.
    // Normals are not interesting here, only need the positions and UVs.
    inputLayout.setBindings({
        { 3 * sizeof(float) },
        { 2 * sizeof(float) }
    });
    inputLayout.setAttributes({
        { 0, 0, QRhiVertexInputAttribute::Float3, 0 },
        { 1, 1, QRhiVertexInputAttribute::Float2, 0 }
    });
    scene.ps->setSampleCount(m_sampleCount);
    scene.ps->setVertexInputLayout(inputLayout);
    scene.ps->setShaderResourceBindings(scene.srb.get());
    scene.ps->setRenderPassDescriptor(renderTarget()->renderPassDescriptor());
    scene.ps->create();

En la reimplementación de ` render()`, primero se comprueban los datos proporcionados por el usuario. Si el ` QSlider ` que controla la rotación ha proporcionado un nuevo valor, o si el ` QTextEdit ` con el texto del cubo ha cambiado su texto, se actualizan los recursos gráficos cuyo contenido depende de dichos datos.

A continuación, se registra una única pasada de renderizado con una sola llamada de dibujo. Los datos de la malla del cubo se proporcionan en un formato no intercalado, de ahí la necesidad de dos enlaces de entrada de vértices: uno para las posiciones (x, y, z) y otro para las coordenadas UV (u, v), con un desplazamiento inicial que corresponde a 36 pares de valores flotantes x-y-z.

void ExampleRhiWidget::render(QRhiCommandBuffer *cb)
{
    if (itemData.cubeRotationDirty) {
        itemData.cubeRotationDirty = false;
        updateMvp();
    }

    if (itemData.cubeTextDirty) {
        itemData.cubeTextDirty = false;
        updateCubeTexture();
    }

    QRhiResourceUpdateBatch *resourceUpdates = scene.resourceUpdates;
    if (resourceUpdates)
        scene.resourceUpdates = nullptr;

    const QColor clearColor = QColor::fromRgbF(0.4f, 0.7f, 0.0f, 1.0f);
    cb->beginPass(renderTarget(), clearColor, { 1.0f, 0 }, resourceUpdates);

    cb->setGraphicsPipeline(scene.ps.get());
    cb->setViewport(QRhiViewport(0, 0, m_pixelSize.width(), m_pixelSize.height()));
    cb->setShaderResources();
    const QRhiCommandBuffer::VertexInput vbufBindings[] = {
        { scene.vbuf.get(), 0 },
        { scene.vbuf.get(), quint32(36 * 3 * sizeof(float)) }
    };
    cb->setVertexInput(0, 2, vbufBindings);
    cb->draw(36);

    cb->endPass();
}

¿Cómo se envían los datos proporcionados por el usuario? Tomemos como ejemplo la rotación. La función `main()` se conecta a la señal ` valueChanged ` del ` QSlider`. Cuando se emite, la lambda conectada llama a `setCubeRotation()` en el `ExampleRhiWidget`. Aquí, si el valor es diferente al anterior, se almacena y se establece un indicador de cambio. A continuación, y lo más importante, se llama a update() en el ExampleRhiWidget. Esto es lo que desencadena el renderizado de un nuevo fotograma en la textura de fondo del QRhiWidget. Sin esto, el contenido del ExampleRhiWidget no se actualizaría al arrastrar el control deslizante.

    void setCubeTextureText(const QString &s)
    {
        if (itemData.cubeText == s)
            return;
        itemData.cubeText = s;
        itemData.cubeTextDirty = true;
        update();
    }

    void setCubeRotation(float r)
    {
        if (itemData.cubeRotation == r)
            return;
        itemData.cubeRotation = r;
        itemData.cubeRotationDirty = true;
        update();
    }

Proyecto de ejemplo en code.qt.io

Véase también QRhi, Ejemplo sencillo de widget RHI 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.