En esta página

Qt Canvas Painter: ejemplo de «Compact Health»

Muestra el uso de « QCanvasPainter » en « QWindow ».

Monitor de pacientes con lecturas de pulso, SpO₂, respiración y temperatura, junto a trazados de ondas en verde y amarillo

Este ejemplo muestra cómo utilizar Qt Canvas Painter en una aplicación « QWindow » pura. El Qt Quick y Qt Widgets no se utilizan.

La aplicación representa todo el contenido a través de los backends de QRhi con QCanvasPainter. La representación y la integración de QCanvasPainter con QRhi se gestionan a través de QCanvasRhiPaintDriver. Esto significa que se utiliza la aceleración por hardware siempre que esté disponible para el backend seleccionado.

Nota: QRhi forma parte de Qt GUI Private. Como tal, ofrece garantías de compatibilidad limitadas. No hay garantías de compatibilidad ni a nivel de código fuente ni de binarios para estas clases, lo que significa que solo se garantiza que la API funcione con la versión de Qt con la que se desarrolló la aplicación.

Qué muestra este ejemplo

  • Cómo renderizar una interfaz de usuario totalmente personalizada en una cadena de intercambio ( QWindow).
  • Creación y gestión de un ` QRhi`, una cadena de intercambio (swapchain) y recursos de profundidad y plantilla (depth-stencil).
  • Grabar comandos de dibujo mediante ` QCanvasPainter ` y ` QCanvasRhiPaintDriver`.
  • Ejecución de una animación continua con ` QWindow::requestUpdate()`.

Guía paso a paso

Por defecto, la aplicación elige una API de renderizado en función de la plataforma. También puedes solicitar un backend específico mediante argumentos de línea de comandos:

  • --null
  • --opengl
  • --vulkan
  • --d3d11
  • --d3d12
  • --metal

Si falla la creación del backend, el ejemplo intenta recurrir a OpenGL ES 2 cuando esté disponible.

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);
    app.setAttribute(Qt::AA_SynthesizeTouchForUnhandledMouseEvents);

    QRhi::Implementation graphicsApi;
#if defined(Q_OS_WIN)
    graphicsApi = QRhi::D3D11;
#elif QT_CONFIG(metal)
    graphicsApi = QRhi::Metal;
#elif QT_CONFIG(vulkan)
    graphicsApi = QRhi::Vulkan;
#else
    graphicsApi = QRhi::OpenGLES2;
#endif

    QCommandLineParser cmdLineParser;
    cmdLineParser.addHelpOption();
    QCommandLineOption nullOption({ "n", "null" }, QLatin1String("Null"));
    cmdLineParser.addOption(nullOption);
    QCommandLineOption glOption({ "g", "opengl" }, QLatin1String("OpenGL"));
    cmdLineParser.addOption(glOption);
    QCommandLineOption vkOption({ "v", "vulkan" }, QLatin1String("Vulkan"));
    cmdLineParser.addOption(vkOption);
    QCommandLineOption d3d11Option({ "d", "d3d11" }, QLatin1String("Direct3D 11"));
    cmdLineParser.addOption(d3d11Option);
    QCommandLineOption d3d12Option({ "D", "d3d12" }, QLatin1String("Direct3D 12"));
    cmdLineParser.addOption(d3d12Option);
    QCommandLineOption mtlOption({ "m", "metal" }, QLatin1String("Metal"));
    cmdLineParser.addOption(mtlOption);

    cmdLineParser.process(app);

   if (cmdLineParser.isSet(nullOption))
        graphicsApi = QRhi::Null;
    if (cmdLineParser.isSet(glOption))
        graphicsApi = QRhi::OpenGLES2;
    si (cmdLineParser.isSet(vkOption))
        graphicsApi = QRhi::Vulkan;
    if (cmdLineParser.isSet(d3d11Option))
        graphicsApi = QRhi::D3D11;
    si (cmdLineParser.isSet(d3d12Option))
        graphicsApi = QRhi::D3D12;
    if (cmdLineParser.isSet(mtlOption))
        graphicsApi = QRhi::Metal;

#if QT_CONFIG(opengl)
    QSurfaceFormat fmt;
    fmt.setDepthBufferSize(24);
    fmt.setStencilBufferSize(8);
#  ifdef Q_OS_MACOS
    fmt.setVersion(4, 1);
    fmt.setProfile(QSurfaceFormat::CoreProfile);
#  endif
    QSurfaceFormat::setDefaultFormat(fmt);
#endif

#if QT_CONFIG(vulkan)
    QVulkanInstance vulkanInstance;
    if (graphicsApi== QRhi::Vulkan) {
        vulkanInstance.setExtensions(QRhiVulkanInitParams::preferredInstanceExtensions());
        if (!vulkanInstance.create()) {
#if QT_CONFIG(opengl)
            qWarning("Vulkan is not usable, falling back to OpenGL");
            graphicsApi = QRhi::OpenGLES2;
#else
            qWarning("Vulkan is not usable, falling back to the null backend");
            graphicsApi = QRhi::Null;
#endif
        }
    }
#endif

    MainWindow window(graphicsApi);

#if QT_CONFIG(vulkan)
    if (graphicsApi== QRhi::Vulkan)
        window.setVulkanInstance(&vulkanInstance);
#endif

    window.resize(1920 / 2, 1080 / 2);
    window.show();

    return app.exec();
}

MainWindow es una subclase de ` PainterWindow`, que a su vez es una subclase de ` QWindow`. ` PainterWindow ` implementa una ventana que muestra contenido renderizado a través de ` QRhi`, la abstracción gráfica de Qt. Inicializa una instancia de ` QRhi ` cuando se expone la ventana, gestiona una cadena de intercambio y un búfer de profundidad-estencil, maneja eventos de redimensionamiento e invoca una función virtual ` paint() ` implementada por ` MainWindow`.

Para comprender mejor la implementación de ` PainterWindow `, se recomienda consultar el ejemplo de ventana RHI, ya que, en esencia, es muy similar a la clase ` RhiWindow ` de dicho ejemplo.

Un paso específico de QCanvasPainter consiste en recuperar una instancia de QCanvasPainterFactory una vez que se haya inicializado QRhi:

if (!m_factory) {
    m_factory = new QCanvasPainterFactory;
    m_factory->create(m_rhi.get());
}

La representación de un nuevo fotograma se lleva a cabo en la función ` render() `, que se invoca cuando se muestra la ventana, se cambia su tamaño y en respuesta a las solicitudes de actualización programadas mediante ` requestUpdate()`.

A diferencia del ejemplo de ventana RHI, no crearemos búferes de vértices y uniformes ni canalizaciones gráficas a través de la API de QRhi, ni emitiremos llamadas de dibujo directamente. En su lugar, se utiliza QCanvasRhiPaintDriver para registrar una pasada de renderizado con el renderizado generado por QCanvasPainter.

void PainterWindow::render()
{
    if (!m_factory|| !m_factory->isValid()|| !m_rhi|| !m_sc)
        return;

    if (!m_hasSwapChain|| m_notExposed)
        return;

   if (m_sc->currentPixelSize() != m_sc->surfacePixelSize()|| m_newlyExposed) {
        resizeSwapChain();
       si (!m_hasSwapChain)
            return;
        m_newlyExposed = false;
    }

    QRhi::FrameOpResult r = m_rhi->beginFrame(m_sc.get());
    if (r== QRhi::FrameOpSwapChainOutOfDate) {
        resizeSwapChain();
        if (!m_hasSwapChain)
            return;
        r = m_rhi->beginFrame(m_sc.get());
    }
    if (r != QRhi::FrameOpSuccess) {
        qDebug("beginFrame failed with %d, retry", r);
        requestUpdate();
        return;
    }

    QRhiCommandBuffer*cb = m_sc->currentFrameCommandBuffer();
    QRhiRenderTarget*rt = m_sc->currentFrameRenderTarget();

    QCanvasRhiPaintDriver*pd = m_factory->paintDriver();
    QCanvasPainter*painter = m_factory->painter();

    pd->resetForNewFrame();
    pd->beginPaint(cb, rt, m_fillColor, size(), float(devicePixelRatio()));
    paint(painter);
    pd->endPaint();

    m_rhi->endFrame(m_sc.get());
}

La implementación de ` paint() ` de `MainWindow` utiliza la API de ` QCanvasPainter ` y no necesita gestionar directamente los detalles de bajo nivel de ` QRhi `.

En primer lugar, carga y registra las imágenes si aún no lo ha hecho:

void MainWindow::paint(QCanvasPainter *p)
{
    if (!m_initialized) {
        auto flags = QCanvasPainter::ImageFlag::GenerateMipmaps;
        m_b1ImageLight = p->addImage(QImage(":/images/icon_random_light.png"), flags);
        m_b1ImageDark = p->addImage(QImage(":/images/icon_random_dark.png"), flags);
        m_b2ImageLight = p->addImage(QImage(":/images/icon_theme_light.png"), flags);
        m_b2ImageDark = p->addImage(QImage(":/images/icon_theme_dark.png"), flags);
        m_b3ImageLight = p->addImage(QImage(":/images/icon_settings_light.png"), flags);
        m_b3ImageDark = p->addImage(QImage(":/images/icon_settings_dark.png"), flags);
        m_sImageLight = p->addImage(QImage(":/images/icon_run_light.png"), flags);
        m_sImageDark = p->addImage(QImage(":/images/icon_run_dark.png"), flags);
        m_initialized = true;
    }

A continuación, se lleva a cabo el dibujo propiamente dicho, que incluye el relleno y el trazo de las rutas, la representación de texto y el dibujo de imágenes. Por ejemplo:

// Highlight pressed button
if (m_selectedButton) {
    p->beginPath();
    p->roundRect(m_views[m_selectedButton].rect, viewRadius);
    p->setLineWidth(2.0f * m_px);
    p->setStrokeStyle(m_theme.highlight());
    p->stroke();
}

QCanvasPainter Los comandos de dibujo preparan la geometría, el estado y el trabajo de dibujo « QRhi » de forma interna. El flujo de comandos se vacía cuando se llama a ` endPaint()` en ` PainterWindow::render()`. Es ahí donde se registra una pasada de renderizado en el ` QRhiCommandBuffer` asociado.

Antes de regresar, MainWindow::paint() llama a requestUpdate(), una función de QWindow que solicita un nuevo fotograma sincronizado con la frecuencia de actualización de la pantalla. Esto garantiza que el contenido se actualice continuamente para la animación.

Consulta el código fuente completo del ejemplo para conocer los detalles de la implementación.

Proyecto de ejemplo en code.qt.io

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