Back to Doc.qt.io
Contact Us Blog Download Qt
On this page

QCRhiPaintDriver Class

The QCRhiPaintDriver class manages the lower level aspects of QCPainter-based rendering for QRhi render targets and offscreen canvases. More...

Header: #include <QCRhiPaintDriver>

Public Types

enum class EndPaintFlag { DoNotRecordRenderPass }
flags EndPaintFlags

Public Functions

void beginPaint(QCOffscreenCanvas &canvas, QRhiCommandBuffer *cb)
void beginPaint(QRhiCommandBuffer *cb, QRhiRenderTarget *rt, const QColor &fillColor = Qt::black, QSize logicalSize = QSize(), float dpr = 1.0f)
void endPaint(QCRhiPaintDriver::EndPaintFlags flags = {})
void grabCanvas(const QCOffscreenCanvas &canvas, std::function<void (const QImage &)> callback)
void renderPaint()
void resetForNewFrame()

Detailed Description

Applications wishing to render with QCPainter onto a QRhi-based render target, such as into a QRhiTexture, or to the color buffer of a QRhiSwapChain, use QCPainterFactory to initialize and retrieve a QCPainter and QCRhiPaintDriver associated with the QRhi. The drawing API is provided by QCPainter, while the low-level aspects of rendering (what is the render target, what is the command buffer, etc.) are controlled by QCRhiPaintDriver.

Note: This class is relevant only when working with QCPainter without a convenience class such as QCPainterWidget or QQuickCPainterItem, because those provide a QCPainter instance to the application and manage its rendering implicitly.

Applications do not create instances of QCRhiPaintDriver themselves. Rather, retrieve it from a successfully initialized QCPainterFactory by calling paintDriver().

The following is an almost complete, standalone console application that draws a circle into a QRhiTexture, reads back the result, and saves it into a PNG file:

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<QCPainterFactory> factory(new QCPainterFactory);
    QCPainter *painter = factory->create(rhi.get());
    QCRhiPaintDriver *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;
}

Member Type Documentation

enum class QCRhiPaintDriver::EndPaintFlag
flags QCRhiPaintDriver::EndPaintFlags

Specifies the flags for endPaint().

ConstantValueDescription
QCRhiPaintDriver::EndPaintFlag::DoNotRecordRenderPass0x01Indicates that flushing the QCPainter's generated commands and recording the QRhi render pass is not desired, because there will be an explicit call to renderPaint() afterwards.

The EndPaintFlags type is a typedef for QFlags<EndPaintFlag>. It stores an OR combination of EndPaintFlag values.

Member Function Documentation

void QCRhiPaintDriver::beginPaint(QCOffscreenCanvas &canvas, QRhiCommandBuffer *cb)

Begins painting onto the specified offscreen canvas, recording rendering commands to the command buffer cb.

Note: A beginPaint() must always be followed by an endPaint(). Nesting is not currently supported.

Clearing happens with the fill color set on the canvas, unless the QCOffscreenCanvas::Flag::PreserveContents flag is set, in which case there is no clear and the canvas contents is preserved (with potential implications for performance, depending on the underlying GPU architecture).

Note: The associated QRhi must be recording a frame (QRhi::beginFrame() or QRhi::beginOffscreenFrame() must have been called), but it should not be in render pass recording state when this function is called.

This is an overloaded function.

void QCRhiPaintDriver::beginPaint(QRhiCommandBuffer *cb, QRhiRenderTarget *rt, const QColor &fillColor = Qt::black, QSize logicalSize = QSize(), float dpr = 1.0f)

Begins painting onto the render target rt, recording rendering commands to the command buffer cb.

fillColor specifies the color used for clearing the color buffer.

Note: A beginPaint() must always be followed by an endPaint(). Nesting is not currently supported.

Note: rt is expected to have both a color and depth-stencil attachment. QCPainter requires the presence of a depth buffer. In case there are multiple color attachments, only the color buffer for attachment 0 is written.

logicalSize is optional. When non-empty, it specifies the viewport size in logical units. dpr must then specify the scale factor (device pixel ratio) so that logicalSize can be converted to pixels internally. In practice this will rarely be needed, since the render target's size is used automatically by default.

Note: The associated QRhi must be recording a frame (QRhi::beginFrame() or QRhi::beginOffscreenFrame() must have been called), but it should not be in render pass recording state when this function is called.

This is an overloaded function.

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

Flushes and records all QRhi rendering generated by the QCPainter drawing commands.

By default, this function records a full render pass, meaning it will internally call QRhiCommandBuffer::beginPass() and QRhiCommandBuffer::endPass(). The clear color is specified by the fillColor argument of beginPaint(), or the offscreen canvas's fill color.

flags can be used to control the recording of a render pass, since in some cases it will not be desirable to let endPaint() issue an entire beginPass() - endPass() sequence.

The following two snippets are identical when it comes to the results, but the sceond offers more flexibility, in case the application wants to do more within the same render pass:

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

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

See also beginPaint() and renderPaint().

void QCRhiPaintDriver::grabCanvas(const QCOffscreenCanvas &canvas, std::function<void (const QImage &)> callback)

Issues a texture readback request for canvas.

callback is invoked either before the function returns, or later, depending on the underlying QRhi and 3D API implementation. Reading back texture contents may involve a GPU->CPU copy, depending on the GPU architecture.

This function can be called both within a beginPaint() - endPaint() block, and outside. When called outside, it will internally invoke QRhi::beginOffscreenFrame() etc., allowing grabs to be performed at any time.

void QCRhiPaintDriver::renderPaint()

Records all QRhi rendering generated by the QCPainter drawing commands. Call this function only when endPaint() was invoked with DoNotRecordRenderPass. It must not be called otherwise.

The associated QRhi must be recording a render pass when this function is invoked.

See also endPaint().

void QCRhiPaintDriver::resetForNewFrame()

Resets the painter engine state. This function is expected to be called once when starting a whole new frame, typically after QRhi::beginFrame() or QRhi::beginOffscreenFrame().

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