En esta página

QCanvasRhiPaintDriver Class

La clase QCanvasRhiPaintDriver gestiona los aspectos de bajo nivel del renderizado basado en QCanvasPainter para los destinos de renderizado de tipo « QRhi » y los lienzos fuera de pantalla. Más información...

Encabezado: #include <QCanvasRhiPaintDriver>
CMake: find_package(Qt6 REQUIRED COMPONENTS CanvasPainter)
target_link_libraries(mytarget PRIVATE Qt6::CanvasPainter)
Desde: Qt 6.11

Tipos públicos

enum class BeginPaintFlag { DepthTest }
flags BeginPaintFlags
enum class EndPaintFlag { DoNotRecordRenderPass }
flags EndPaintFlags

Funciones públicas

void beginPaint(QCanvasOffscreenCanvas &canvas, QRhiCommandBuffer *cb, QCanvasRhiPaintDriver::BeginPaintFlags flags = {})
void beginPaint(QRhiCommandBuffer *cb, QRhiRenderTarget *rt, const QMatrix4x4 &matrix, QCanvasRhiPaintDriver::BeginPaintFlags flags = {})
void beginPaint(QRhiCommandBuffer *cb, QRhiRenderTarget *rt, QColor fillColor = Qt::black, QSize logicalSize = QSize(), qreal dpr = 1.0, QCanvasRhiPaintDriver::BeginPaintFlags flags = {})
void endPaint(QCanvasRhiPaintDriver::EndPaintFlags flags = {})
void grabCanvas(const QCanvasOffscreenCanvas &canvas, const QObject *context, Functor &&callback)
void renderPaint()
void resetForNewFrame()

Descripción detallada

Las aplicaciones que deseen realizar el renderizado mediante un control de renderizado ( QCanvasPainter ) en un destino de renderizado basado en un objeto de tipo ` QRhi` —como, por ejemplo, en un ` QRhiTexture` o en el búfer de color de un ` QRhiSwapChain`— deben utilizar ` QCanvasPainterFactory ` para inicializar y recuperar un ` QCanvasPainter ` y un `QCanvasRhiPaintDriver` asociados al ` QRhi`. La API de dibujo la proporciona QCanvasPainter, mientras que los aspectos de bajo nivel del renderizado (cuál es el destino de renderizado, cuál es el búfer de comandos, etc.) los controla QCanvasRhiPaintDriver.

Nota: Esta clase solo es relevante cuando se trabaja con QCanvasPainter sin una clase de conveniencia como QCanvasPainterWidget o QCanvasPainterItem, ya que estas proporcionan una instancia de QCanvasPainter a la aplicación y gestionan su renderizado de forma implícita.

Las aplicaciones no crean por sí mismas instancias de `QCanvasRhiPaintDriver`. En su lugar, la obtienen de un ` initialized ` creado correctamente mediante ` QCanvasPainterFactory ` llamando a ` paintDriver()` ().

A continuación se muestra una aplicación de consola independiente y casi completa que dibuja un círculo en un QRhiTexture, lee el resultado y lo guarda en un archivo PNG:

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    // std::unique_ptr<QRhi> rhi(QRhi::create(...));

    std::unique_ptr<QRhiTexture> tex(rhi->newTexture(QRhiTexture::RGBA8, QSize(1280, 720), 1,
                                     QRhiTexture::RenderTarget | QRhiTexture::UsedAsTransferSource));
    tex->create();
    std::unique_ptr<QRhiRenderBuffer> ds(rhi->newRenderBuffer(QRhiRenderBuffer::DepthStencil, QSize(1280, 720)));
    ds->create();
    QRhiTextureRenderTargetDescription rtDesc;
    rtDesc.setColorAttachments({ tex.get() });
    rtDesc.setDepthStencilBuffer(ds.get());
    std::unique_ptr<QRhiTextureRenderTarget> rt(rhi->newTextureRenderTarget(rtDesc));
    std::unique_ptr<QRhiRenderPassDescriptor> rp(rt->newCompatibleRenderPassDescriptor());
    rt->setRenderPassDescriptor(rp.get());
    rt->create();

    std::unique_ptr<QCanvasPainterFactory> factory(new QCanvasPainterFactory);
    QCanvasPainter *painter = factory->create(rhi.get());
    QCanvasRhiPaintDriver *pd = factory->paintDriver();

    QRhiCommandBuffer *cb;
    QRhiReadbackResult readbackResult;

    rhi->beginOffscreenFrame(&cb);
    pd->resetForNewFrame();

    {
        pd->beginPaint(cb, rt.get());

        painter->beginPath();
        painter->circle(640, 360, 180);
        painter->setFillStyle(Qt::red);
        painter->fill();

        pd->endPaint();

        QRhiResourceUpdateBatch *u = rhi->nextResourceUpdateBatch();
        u->readBackTexture({ tex.get() }, &readbackResult);
        cb->resourceUpdate(u);
    }

    rhi->endOffscreenFrame();

    QImage image(reinterpret_cast<const uchar *>(readbackResult.data.constData()),
                    readbackResult.pixelSize.width(),
                    readbackResult.pixelSize.height(),
                    QImage::Format_RGBA8888);
    if (rhi->isYUpInFramebuffer())
        image.flip();

    image.save("result.png");

    return 0;
}

Documentación sobre los tipos de miembros

enum class QCanvasRhiPaintDriver::BeginPaintFlag
flags QCanvasRhiPaintDriver::BeginPaintFlags

Especifica los parámetros para ` beginPaint()`.

ConstanteValorDescripción
QCanvasRhiPaintDriver::BeginPaintFlag::DepthTest0x01Indica que se debe habilitar la comprobación de profundidad durante el renderizado. Normalmente, ` QCanvasPainter ` no escribe ni comprueba el búfer de profundidad. Si es necesario comparar con valores escritos por otro renderizador, active esta bandera. La función de comparación de profundidad utilizada es ` Less`.

El tipo `BeginPaintFlags` es un `typedef` para ` QFlags<BeginPaintFlag>`. Almacena una combinación OR de valores de `BeginPaintFlag`.

enum class QCanvasRhiPaintDriver::EndPaintFlag
flags QCanvasRhiPaintDriver::EndPaintFlags

Especifica los parámetros para la función ` endPaint()`.

ConstanteValorDescripción
QCanvasRhiPaintDriver::EndPaintFlag::DoNotRecordRenderPass0x01Indica que no se desea vaciar los comandos generados por ` QCanvasPainter` ni registrar la pasada de renderizado ` QRhi `, ya que posteriormente se realizará una llamada explícita a ` renderPaint()`.

El tipo EndPaintFlags es un typedef de QFlags<EndPaintFlag>. Almacena una combinación OR de valores de EndPaintFlag.

Documentación de las funciones miembro

void QCanvasRhiPaintDriver::beginPaint(QCanvasOffscreenCanvas &canvas, QRhiCommandBuffer *cb, QCanvasRhiPaintDriver::BeginPaintFlags flags = {})

Comienza a pintar en el « canvas » fuera de pantalla especificado, registrando los comandos de renderizado en el búfer de comandos « cb ».

Nota: Una llamada a beginPaint() debe ir siempre seguida de una llamada a endPaint(). Actualmente no se admite el anidamiento.

El borrado se realiza mediante fill color set on the canvas, a menos que se active el indicador QCanvasOffscreenCanvas::Flag::PreserveContents, en cuyo caso no se produce ningún borrado y se conserva el contenido del lienzo (con posibles implicaciones para el rendimiento, dependiendo de la arquitectura de la GPU subyacente).

Nota: El ` QRhi ` asociado debe estar grabando un fotograma (se debe haber llamado a `QRhi::beginFrame()` o ` QRhi::beginOffscreenFrame()`), pero no debe encontrarse en estado de grabación de pasada de renderizado cuando se llame a esta función.

flags Especifica los indicadores opcionales que controlan el renderizado.

Se trata de una función sobrecargada.

void QCanvasRhiPaintDriver::beginPaint(QRhiCommandBuffer *cb, QRhiRenderTarget *rt, const QMatrix4x4 &matrix, QCanvasRhiPaintDriver::BeginPaintFlags flags = {})

Comienza a pintar en el destino de renderizado rt, registrando los comandos de renderizado en el búfer de comandos cb.

Esta sobrecarga toma una matriz personalizada matrix, que se utiliza para transformar los vértices. La matriz debe ser adecuada para tratar vértices cuyas coordenadas se expresan en píxeles. Un caso de uso habitual es pasar la matriz de proyección modelview de Qt Quick al implementar el renderizado basado en QCanvasPainter dentro de una subclase de QSGRenderNode.

El tamaño de la ventana de visualización y la relación de píxeles del dispositivo se obtienen del destino de renderizado.

Esta sobrecarga no admite un color de relleno, ya que, en la práctica, se espera que vaya seguida de una llamada a endPaint() con el indicador EndPaintFlag::DoNotRecordRenderPass activado.

Nota: La compatibilidad con el recorte es limitada cuando se utiliza una matriz personalizada. Se admiten recortes rectangulares no transformados cuando la matriz especifica una proyección ortográfica sin escalado ni rotación añadidos. En general, se recomienda evitar dibujar basándose en el recorte en este modo.

Nota: Una llamada a ` beginPaint()` debe ir siempre seguida de una llamada a ` endPaint()`. Actualmente no se admite el anidamiento.

Nota: Se espera que` rt ` tenga tanto un anexo de color como uno de profundidad-plantilla. En caso de que haya varios anexos de color, solo se escribe el búfer de color del anexo 0. ` QCanvasPainter ` requiere la presencia de un búfer de profundidad-plantilla. Actualmente solo se utiliza la plantilla; las pruebas de profundidad y la escritura están siempre desactivadas.

Nota: El ` QRhi ` asociado debe estar grabando un fotograma (se debe haber llamado a `QRhi::beginFrame()` o a ` QRhi::beginOffscreenFrame()`), pero no debe encontrarse en estado de grabación de pasada de renderizado cuando se llame a esta función.

flags Especifica los indicadores opcionales que controlan el renderizado.

Esta es una función sobrecargada.

void QCanvasRhiPaintDriver::beginPaint(QRhiCommandBuffer *cb, QRhiRenderTarget *rt, QColor fillColor = Qt::black, QSize logicalSize = QSize(), qreal dpr = 1.0, QCanvasRhiPaintDriver::BeginPaintFlags flags = {})

Comienza a pintar sobre el destino de renderizado rt, registrando los comandos de renderizado en el búfer de comandos cb.

fillColor Especifica el color utilizado para borrar el búfer de color. Este valor se ignora cuando los indicadores de endPaint() contienen EndPaintFlag::DoNotRecordRenderPass.

Nota: Una llamada a ` beginPaint()` debe ir siempre seguida de una llamada a ` endPaint()`. Actualmente no se admite el anidamiento.

Nota: Se espera que` rt ` tenga tanto un anexo de color como uno de profundidad-plantilla. En caso de que haya varios anexos de color, solo se escribe el búfer de color del anexo 0. ` QCanvasPainter ` requiere la presencia de un búfer de profundidad-plantilla. Actualmente solo se utiliza la plantilla; la comprobación de profundidad y la escritura están siempre desactivadas.

logicalSize es opcional. Cuando no está vacío, especifica el tamaño de la ventana de visualización en unidades lógicas. dpr debe entonces especificar el factor de escala (relación de píxeles del dispositivo) para que logicalSize pueda convertirse a píxeles internamente. En la práctica, esto rara vez será necesario, ya que el tamaño del destino de renderizado se utiliza automáticamente por defecto.

Nota: El QRhi asociado debe estar grabando un fotograma (se debe haber llamado aQRhi::beginFrame() o QRhi::beginOffscreenFrame()), pero no debe encontrarse en estado de grabación de pasada de renderizado cuando se llame a esta función.

flags Especifica los indicadores opcionales que controlan el renderizado.

Esta es una función sobrecargada.

void QCanvasRhiPaintDriver::endPaint(QCanvasRhiPaintDriver::EndPaintFlags flags = {})

Vacíe y registre todo el renderizado de QRhi generado por los comandos de dibujo de QCanvasPainter.

Por defecto, esta función graba una pasada de renderizado completa, lo que significa que llamará internamente a QRhiCommandBuffer::beginPass() y QRhiCommandBuffer::endPass(). El color de borrado viene determinado por el argumento fillColor de beginPaint(), o por el color de relleno del lienzo fuera de pantalla.

flags Se puede utilizar para controlar la grabación de una pasada de renderizado, ya que en algunos casos no será conveniente permitir que endPaint() ejecute una secuencia completa de beginPass() - endPass().

Los dos fragmentos de código siguientes son idénticos en cuanto a los resultados, pero el segundo ofrece mayor flexibilidad, en caso de que la aplicación quiera realizar más operaciones dentro del mismo paso de renderizado:

pd->beginPaint(cb, rt, Qt::black);
// painter->...
pd->endPaint();
pd->beginPaint(cb, rt);
// painter->...
pd->endPaint(QCanvasRhiPaintDriver::EndPaintFlag::DoNotRecordRenderPass);

cb->beginPass(rt, Qt::black, { 1.0f, 0 });
pd->renderPaint();
cb->endPass();

Véase también beginPaint() y renderPaint().

template <typename Functor> void QCanvasRhiPaintDriver::grabCanvas(const QCanvasOffscreenCanvas &canvas, const QObject *context, Functor &&callback)

Envía una solicitud de lectura de textura para ` canvas`, asociándola a ` context`.

callback Se invoca antes de que la función devuelva un valor, o más tarde, dependiendo de la implementación subyacente de ` QRhi ` y de la API 3D. La lectura del contenido de la textura puede implicar una copia de la GPU a la CPU, dependiendo de la arquitectura de la GPU. Admite un único argumento ` const QImage & ` y puede ser cualquier functor, incluidos los de solo movimiento.

Si context se destruye antes de que finalice la lectura, la captura se cancela y no se invoca callback. Esto hace que sea seguro que la llamada de retorno haga referencia a objetos que quizá no sobrevivan a la lectura pendiente.

Esta función se puede invocar tanto dentro de un bloque ` beginPaint()` - ` endPaint()` como fuera de él. Cuando se invoca fuera, invocará internamente ` QRhi::beginOffscreenFrame()`, etc., lo que permite realizar capturas en cualquier momento.

Por ejemplo, el siguiente código guardaría el contenido de un lienzo fuera de pantalla en un archivo PNG:

grabCanvas(offscreenCanvas, qGuiApp, [](const QImage &image) {
    image.save("result.png");
});

void QCanvasRhiPaintDriver::renderPaint()

Registra todo el renderizado de « QRhi » generado por los comandos de dibujo « QCanvasPainter ». Llama a esta función únicamente cuando se haya invocado « endPaint()» con « DoNotRecordRenderPass ». No debe llamarse en ningún otro caso.

El QRhi asociado debe estar registrando una pasada de renderizado cuando se invoque esta función.

Véase también endPaint().

void QCanvasRhiPaintDriver::resetForNewFrame()

Restablece el estado del motor de dibujo. Se espera que esta función se llame una vez al iniciar un fotograma completamente nuevo, normalmente después de QRhi::beginFrame() o QRhi::beginOffscreenFrame().

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