QCRhiPaintDriver Class

Member Function Documentation

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

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

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

flags specifies the optional flags that control rendering.

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

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

This overload takes a custom matrix, which is used to transform the vertices. The matrix must be suitable to deal with vertices where the coordinates are given in pixels. A common use case is to pass in Qt Quick's modelview-projection matrix when implementing QCPainter-pased rendering within a QSGRenderNode subclass.

The viewport size and device pixel ratio are taken from the render target.

This overload does not take a fill color since in practice it is expected to be followed by an endPaint() with the flag EndPaintFlag::DoNotRecordRenderPass set.

flags specifies the optional flags that control rendering.

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

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. This value is ignored when the flags for endPaint() contain EndPaintFlag::DoNotRecordRenderPass.

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.

flags specifies the optional flags that control rendering.

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().