Ejemplo de QQuickRenderControl RHI

Muestra cómo renderizar una escena de Qt Quick en un archivo QRhiTexture.

Cuadrícula de fotogramas renderizados con métricas de tiempo de la CPU y la GPU para cada fotograma

Este ejemplo muestra cómo configurar una escena de Qt Quick cuyo renderizado se redirige a un QRhiTexture. De este modo, la aplicación tiene libertad para hacer lo que desee con la textura resultante de cada fotograma. Este ejemplo es una aplicación basada en QWidget que realiza una lectura posterior de los datos de la imagen y, a continuación, muestra los renderizados recopilados por fotograma con información de tiempos basada en la CPU y la GPU para cada uno de ellos.

Al utilizar la abstracción de la API de gráficos 3D de Qt, este ejemplo no está vinculado a ninguna API gráfica en concreto. Al iniciarse, aparece un cuadro de diálogo con las API 3D que la plataforma podría admitir.

    QDialog apiSelect;
    QVBoxLayout *selLayout = new QVBoxLayout;
    selLayout->addWidget(new QLabel(QObject::tr("Select graphics API to use")));
    QListWidget *apiList = new QListWidget;
    QVarLengthArray<QSGRendererInterface::GraphicsApi, 5> apiValues;
#ifdef Q_OS_WIN
    apiList->addItem("Direct3D 11");
    apiValues.append(QSGRendererInterface::Direct3D11);
    apiList->addItem("Direct3D 12");
    apiValues.append(QSGRendererInterface::Direct3D12);
#endif
#if QT_CONFIG(metal)
    apiList->addItem("Metal");
    apiValues.append(QSGRendererInterface::Metal);
#endif
#if QT_CONFIG(vulkan)
    apiList->addItem("Vulkan");
    apiValues.append(QSGRendererInterface::Vulkan);
#endif
#if QT_CONFIG(opengl)
    apiList->addItem("OpenGL / OpenGL ES");
    apiValues.append(QSGRendererInterface::OpenGL);
#endif
    if (apiValues.isEmpty()) {
        QMessageBox::critical(nullptr, QObject::tr("No 3D graphics API"), QObject::tr("No 3D graphics APIs are supported in this Qt build"));
        return 1;
    }

Nota: Nose garantiza que todas las opciones seleccionadas funcionen en una plataforma determinada.

Una vez realizada la selección, se carga un archivo QML. Sin embargo, no nos limitaremos a crear una instancia de ` QQuickView ` y llamar a ` show()`. Más bien, el ` QQuickWindow ` que gestiona la escena ` Qt Quick ` nunca se muestra en pantalla. En su lugar, la aplicación controla cuándo y dónde se realiza el renderizado, mediante ` QQuickRenderControl`.

void MainWindow::load(const QString&filename)
{
    reset();

    m_renderControl.reset(new QQuickRenderControl);
    m_scene.reset(new QQuickWindow(m_renderControl.get()));

    // habilita lastCompletedGpuTime() en QRhiCommandBuffer, si lo admite la API 3D subyacente
    QQuickGraphicsConfiguration config;
    config.setTimestamps(true);
    m_scene->setGraphicsConfiguration(config);

#if QT_CONFIG(vulkan)
    if (m_scene->graphicsApi()== QSGRendererInterface::Vulkan)
        m_scene->setVulkanInstance(m_vulkanInstance);
#endif

    m_qmlEngine.reset(new QQmlEngine);
    m_qmlComponent.reset(new QQmlComponent(m_qmlEngine.get(), QUrl::fromLocalFile(filename)));
    if (m_qmlComponent->isError()) {
        for (const QQmlError&error: m_qmlComponent->errors())
            qWarning() << error.url() << error.line() << error;
        QMessageBox::critical(this, tr("No se puede cargar la escena QML"), tr("Error al cargar %1").arg(filename));
        reset();
        return;
    }

Una vez instanciado el árbol de objetos, se consulta el elemento raíz (un Rectangle), se comprueba que su tamaño sea válido y, a continuación, se propaga.

Nota: No se admitenlas escenas que utilizan el elemento Window dentro del árbol de objetos.

    QObject*rootObject = m_qmlComponent->create();
    if (m_qmlComponent->isError()) {
        for (const QQmlError&error: m_qmlComponent->errors())
            qWarning() << error.url() << error.line() << error;
        QMessageBox::critical(this, tr("No se puede cargar la escena QML"), tr("Error al crear el componente"));
        reset();
        return;
    }

    QQuickItem*rootItem = qobject_cast<QQuickItem*>(rootObject);
    if (!rootItem) {
        // Eliminar la ventana en pantalla, si el objeto raíz era una ventana
        if (QQuickWindow*w = qobject_cast<QQuickWindow*>(rootObject))
            delete w;
        QMessageBox::critical(this,
                              tr("Elemento raíz no válido en la escena QML"),
                              tr("El objeto raíz no es un QQuickItem. Si se trata de una escena que contiene una ventana, ten en cuenta que este tipo de escenas no son compatibles."));
        reset();
        return;
    }

    if (rootItem->size().width() < 16)
        rootItem->setSize(QSizeF(640, 360));

    m_scene->contentItem()->setSize(rootItem->size());
    m_scene->setGeometry(0, 0, rootItem->width(), rootItem->height());

    rootItem->setParentItem(m_scene->contentItem());

    m_statusMsg->setText(tr("Escena QML cargada"));

En este punto aún no se han inicializado recursos de renderizado, es decir, todavía no se ha hecho nada con la API nativa de gráficos 3D. Un ` QRhi ` se instancia únicamente en el siguiente paso, y eso es lo que desencadena la configuración del sistema de renderizado (Vulkan, Metal, Direct 3D, etc.) en segundo plano.

    const bool initSuccess = m_renderControl->initialize();
    if (!initSuccess) {
        QMessageBox::critical(this, tr("Cannot initialize renderer"), tr("QQuickRenderControl::initialize() failed"));
        reset();
        return;
    }

    const QSGRendererInterface::GraphicsApi api = m_scene->rendererInterface()->graphicsApi();
    switch (api) {
    case QSGRendererInterface::OpenGL:
        m_apiMsg->setText(tr("OpenGL"));
        break;
    case QSGRendererInterface::Direct3D11:
        m_apiMsg->setText(tr("D3D11"));
        break;
    case QSGRendererInterface::Direct3D12:
        m_apiMsg->setText(tr("D3D12"));
        break;
    case QSGRendererInterface::Vulkan:
        m_apiMsg->setText(tr("Vulkan"));
        break;
    case QSGRendererInterface::Metal:
        m_apiMsg->setText(tr("Metal"));
        break;
    default:
        m_apiMsg->setText(tr("Unknown 3D API"));
        break;
    }

    QRhi *rhi = m_renderControl->rhi();
    if (!rhi) {
        QMessageBox::critical(this, tr("Cannot render"), tr("No QRhi from QQuickRenderControl"));
        reset();
        return;
    }

    m_driverInfoMsg->setText(QString::fromUtf8(rhi->driverInfo().deviceName));

Nota: Esta aplicación utiliza un modelo en el que Qt crea una instancia de ` QRhi`. Este no es el único enfoque posible: si la aplicación mantiene su propio ` QRhi ` (y, por tanto, un contexto OpenGL, un dispositivo Vulkan, etc.), se puede solicitar a ` Qt Quick ` que adopte y utilice ese ` QRhi` ya existente. Esto se hace pasando un ` QQuickGraphicsDevice ` creado mediante ` QQuickGraphicsDevice::fromRhi()` a ` QQuickWindow`, de forma similar a como se establece ` QQuickGraphicsConfiguration ` en el fragmento de código anterior. Consideremos, por ejemplo, el caso en el que se desee utilizar las texturas renderizadas por ` Qt Quick ` en un ` QRhiWidget`: en ese caso, habrá que pasar el ` QRhi ` de ` QRhiWidget` a ` Qt Quick`, en lugar de dejar que ` Qt Quick ` cree el suyo propio.

Una vez que QQuickRenderControl::initialize() se ejecuta con éxito, el renderizador está activo y listo para funcionar. Para ello, necesitamos un búfer de color en el que renderizar.

QQuickRenderTarget es una clase ligera y de uso compartido implícito que contiene (aunque no es propietaria de ellos) diversos conjuntos de objetos nativos o de tipo ` QRhi ` que describen texturas, destinos de renderizado o elementos similares. Llamar a ` setRenderTarget()` sobre el ` QQuickWindow ` (recuerda que tenemos un ` QQuickWindow ` que no es visible en pantalla) es lo que desencadena el redireccionamiento del renderizado del grafo de escena de ` Qt Quick ` hacia la textura proporcionada por la aplicación. Al trabajar con QRhi (y no con objetos nativos de la API 3D, como los identificadores de textura de OpenGL o los objetos VkImage), la aplicación debe configurar un QRhiTextureRenderTarget y, a continuación, pasarlo a Qt Quick mediante QQuickRenderTarget::fromRhiRenderTarget().

    const QSize pixelSize = rootItem->size().toSize(); // no scaling, i.e. the item size is in pixels

    m_texture.reset(rhi->newTexture(QRhiTexture::RGBA8, pixelSize, 1,
                                    QRhiTexture::RenderTarget | QRhiTexture::UsedAsTransferSource));
    if (!m_texture->create()) {
        QMessageBox::critical(this, tr("Cannot render"), tr("Cannot create texture object"));
        reset();
        return;
    }

    m_ds.reset(rhi->newRenderBuffer(QRhiRenderBuffer::DepthStencil, pixelSize, 1));
    if (!m_ds->create()) {
        QMessageBox::critical(this, tr("Cannot render"), tr("Cannot create depth-stencil buffer"));
        reset();
        return;
    }

    QRhiTextureRenderTargetDescription rtDesc(QRhiColorAttachment(m_texture.get()));
    rtDesc.setDepthStencilBuffer(m_ds.get());
    m_rt.reset(rhi->newTextureRenderTarget(rtDesc));
    m_rpDesc.reset(m_rt->newCompatibleRenderPassDescriptor());
    m_rt->setRenderPassDescriptor(m_rpDesc.get());
    if (!m_rt->create()) {
        QMessageBox::critical(this, tr("Cannot render"), tr("Cannot create render target"));
        reset();
        return;
    }

    m_scene->setRenderTarget(QQuickRenderTarget::fromRhiRenderTarget(m_rt.get()));

Nota: Proporcionesiempre un búfer de profundidad-estencil para Qt Quick, ya que tanto estos búferes como las pruebas de profundidad y estencil pueden ser utilizados por el grafo de escena de Qt Quick durante el renderizado.

El bucle de renderizado principal es el siguiente. Aquí también se muestra cómo realizar lecturas de imágenes de la GPU a la CPU. Una vez que hay un « QImage » disponible, la interfaz de usuario basada en « QWidget » se actualiza en consecuencia. Omitiremos aquí entrar en detalles al respecto.

El ejemplo también muestra una forma sencilla de medir el coste de renderizar un fotograma en la CPU y en la GPU. Los fotogramas renderizados fuera de pantalla son muy adecuados para ello debido a cierto comportamiento interno de ` QRhi `, lo que implica que las operaciones que, de otro modo, serían asíncronas (en el sentido de que solo se completan al renderizar un fotograma posterior), tienen garantizado que estarán listas una vez que ` QRhi::endOffscreenFrame()` (es decir, ` QQuickRenderControl::endFrame()`) devuelva un resultado. Aprovechamos este conocimiento al volver a leer la textura, y esto también se aplica a las marcas de tiempo de la GPU. Por eso la aplicación puede mostrar la hora de la GPU para cada fotograma, al tiempo que garantiza que la hora se refiere realmente a ese fotograma concreto (y no a uno anterior). Véase lastCompletedGpuTime() para obtener más detalles sobre los tiempos de la GPU. Los tiempos del lado de la CPU se obtienen mediante QElapsedTimer.

    QElapsedTimer cpuTimer;
    cpuTimer.start();

    m_renderControl->polishItems();

    m_renderControl->beginFrame();

    m_renderControl->sync();
    m_renderControl->render();

    QRhi *rhi = m_renderControl->rhi();
    QRhiReadbackResult readResult;
    QRhiResourceUpdateBatch *readbackBatch = rhi->nextResourceUpdateBatch();
    readbackBatch->readBackTexture(m_texture.get(), &readResult);
    m_renderControl->commandBuffer()->resourceUpdate(readbackBatch);

    m_renderControl->endFrame();

    const double gpuRenderTimeMs = m_renderControl->commandBuffer()->lastCompletedGpuTime() * 1000.0;
    const double cpuRenderTimeMs = cpuTimer.nsecsElapsed() / 1000000.0;

    // m_renderControl->begin/endFrame() is based on QRhi's
    // begin/endOffscreenFrame() under the hood, meaning it does not do
    // pipelining, unlike swapchain-based frames, and therefore the readback is
    // guaranteed to complete once endFrame() returns.
    QImage wrapperImage(reinterpret_cast<const uchar *>(readResult.data.constData()),
                    readResult.pixelSize.width(), readResult.pixelSize.height(),
                    QImage::Format_RGBA8888_Premultiplied);
    QImage result;
    if (rhi->isYUpInFramebuffer())
        result = wrapperImage.flipped();
    else
        result = wrapperImage.copy();

Un aspecto importante es el avance de las animaciones Qt Quick. Dado que no disponemos de una ventana en pantalla que pueda controlar el sistema de animación, ya sea midiendo el tiempo transcurrido, mediante un temporizador convencional o mediante una regulación basada en la frecuencia de presentación, el redireccionamiento del renderizado Qt Quick a menudo implica que la aplicación debe hacerse cargo del control de las animaciones. De lo contrario, las animaciones funcionan basándose en un simple temporizador del sistema, pero el tiempo transcurrido real a menudo no tendrá nada que ver con lo que se espera que perciba la escena renderizada fuera de pantalla. Imaginemos que se renderizan 5 fotogramas seguidos, en un bucle muy ajustado. El movimiento de las animaciones en esos 5 fotogramas depende de la velocidad a la que la CPU ejecute las iteraciones del bucle. Eso casi nunca es lo ideal. Para garantizar animaciones coherentes, instala un QAnimationDriver personalizado. Aunque se trata de una API no documentada (pero pública) destinada a usuarios avanzados, el ejemplo que se muestra aquí ofrece una demostración sencilla de cómo utilizarla.

class AnimationDriver : public QAnimationDriver
{
public:
    AnimationDriver(QObject *parent = nullptr)
        : QAnimationDriver(parent),
          m_step(16)
    {
    }

    void setStep(int milliseconds)
    {
        m_step = milliseconds;
    }

    void advance() override
    {
        m_elapsed += m_step;
        advanceAnimation();
    }

    qint64 elapsed() const override
    {
        return m_elapsed;
    }

private:
    int m_step;
    qint64 m_elapsed = 0;
};

La aplicación cuenta con un control « QSlider » que se puede utilizar para cambiar el valor del paso de animación, que por defecto es de 16 milisegundos, por otro valor. Fíjate en la llamada a la función setStep() de nuestra subclase de QAnimationDriver.

    QSlider *animSlider = new QSlider;
    animSlider->setOrientation(Qt::Horizontal);
    animSlider->setMinimum(1);
    animSlider->setMaximum(1000);
    QLabel *animLabel = new QLabel;
    QObject::connect(animSlider, &QSlider::valueChanged, animSlider, [this, animLabel, animSlider] {
        if (m_animationDriver)
            m_animationDriver->setStep(animSlider->value());
        animLabel->setText(tr("Simulated elapsed time per frame: %1 ms").arg(animSlider->value()));
    });
    animSlider->setValue(16);
    QCheckBox *animCheckBox = new QCheckBox(tr("Custom animation driver"));
    animCheckBox->setToolTip(tr("Note: Installing the custom animation driver makes widget drawing unreliable, depending on the platform.\n"
                                "This is due to widgets themselves relying on QPropertyAnimation and similar, which are driven by the same QAnimationDriver.\n"
                                "In any case, the functionality of the widgets are not affected, just the rendering may lag behind.\n"
                                "When not checked, Qt Quick animations advance based on the system time, i.e. the time elapsed since the last press of the Next button."));
    QObject::connect(animCheckBox, &QCheckBox::checkStateChanged, animCheckBox, [this, animCheckBox, animSlider, animLabel] {
        if (animCheckBox->isChecked()) {
            animSlider->setEnabled(true);
            animLabel->setEnabled(true);
            m_animationDriver = new AnimationDriver(this);
            m_animationDriver->install();
            m_animationDriver->setStep(animSlider->value());
        } else {
            animSlider->setEnabled(false);
            animLabel->setEnabled(false);
            delete m_animationDriver;
            m_animationDriver = nullptr;
        }
    });
    animSlider->setEnabled(false);
    animLabel->setEnabled(false);
    controlLayout->addWidget(animCheckBox);
    controlLayout->addWidget(animLabel);
    controlLayout->addWidget(animSlider);

Nota: La instalación del controlador de animación personalizado es opcional gracias a la casilla de verificación « animCheckBox ». Esto permite comparar el efecto de tener o no instalado un controlador de animación personalizado. Además, en algunas plataformas (y quizá dependiendo del tema), tener el controlador personalizado activado puede provocar retrasos en el dibujo de los widgets. Esto es lo esperado, ya que si alguna animación de un widget (por ejemplo, el resaltado de un « QPushButton » o un « QCheckBox ») se gestiona mediante « QPropertyAnimation » y similares, dichas animaciones son controladas por el mismo «QAnimationDriver», y este no avanza hasta que se solicita un nuevo fotograma al hacer clic en los botones.

El avance de las animaciones se realiza antes de cada fotograma (es decir, antes de la llamada a QQuickRenderControl::beginFrame()) simplemente llamando a advance():

void MainWindow::stepAnimations()
{
    if (m_animationDriver) {
        // Now the Qt Quick scene will think that <slider value> milliseconds have
        // elapsed and update animations accordingly when doing the next frame.
        m_animationDriver->advance();
    }
}

Proyecto de ejemplo en code.qt.io

Véase también QRhi, QQuickRenderControl y QQuickWindow.

© 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.