QCPainterWidget Class

Member Function Documentation

[explicit] QCPainterWidget::QCPainterWidget(QWidget *parent = nullptr)

Constructs a QCPainterWidget with the given parent.

[override virtual noexcept] QCPainterWidget::~QCPainterWidget()

Destroys the QCPainterWidget.

[protected] void QCPainterWidget::beginCanvasPainting(QCOffscreenCanvas &canvas)

Starts recording QCPainter draw commands targeting canvas.

beginCanvasPainting() must always be followed by corresponding endCanvasPainting() before returning from prePaint().

The following snippet from a QCPainterWidget subclass shows how an offscreen canvas could be rendered into and then used as an image or image pattern when drawing the contents for the widget:

class MyWidget : public QCPainterWidget
{
public:
    QCOffscreenCanvas canvas;
    QCImage canvasImage;

    void graphicsResourcesInvalidated() override
    {
        canvas = {}; // so that the next prePaint() will recreate and redraw the canvas
    }

    void prePaint(QCPainter *p) override
    {
        if (canvas.isNull()) {
            canvas = p->createCanvas(QSize(320, 240));
            beginCanvasPainting(canvas);
            p->beginPath();
            p->circle(160, 120, 20);
            p->setFillStyle(Qt::red);
            p->fill();
            endCanvasPainting();
            canvasImage = p->addImage(canvas, QCPainter::ImageFlag::Repeat);
        }
    }

    void paint(QCPainter *p) override
    {
        // use canvasImage as a brush or with drawImage()
    }
};

[protected] void QCPainterWidget::endCanvasPainting()

Indicates the end of the drawing targeting the canvas specified in beginCanvasPainting().

beginCanvasPainting() must always be followed by corresponding endCanvasPainting() before returning from prePaint().

QColor QCPainterWidget::fillColor() const

Returns the current fill color.

See also setFillColor().

void QCPainterWidget::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.

[virtual protected] void QCPainterWidget::graphicsResourcesInvalidated()

Called when underlying graphics resources, such as textures, are lost.

This indicates that QCImage objects returned from addImage() are no longer valid, and addImage() needs to be called again. If the paint() implementation is such that this does not matter, for example because images are not used, or addImage() is always called, then no action is necessary. Otherwise, it is recommended to toggle a flag, or similar, and act accordingly in the next invocation of paint().

The same applies to QCOffscreenCanvas objects returned from QCPainter::createCanvas(). When this function is called, the next invocation of paint() should create new canvases and redraw their contents.

Graphics resources can be lost, for example, when the widget is moved to a new top-level window, because that implies being associated with a new QRhi instance.

See also QRhiWidget::releaseResources().

bool QCPainterWidget::hasSharedPainter() const

Returns true if this widget uses a shared painter.

See also setSharedPainter.

[override virtual protected] void QCPainterWidget::initialize(QRhiCommandBuffer *cb)

Reimplements: QRhiWidget::initialize(QRhiCommandBuffer *cb).

[virtual protected] void QCPainterWidget::initializeResources(QCPainter *painter)

Reimplement this method to initialize resources using painter. Generally, this will be called once before the first prePaint() and paint(). An exception is when graphics resources are lost, see graphicsResourcesInvalidated(). In that case, this method will get invoked again afterwards.

The default implementation is empty.

[virtual protected] void QCPainterWidget::paint(QCPainter *painter)

Reimplement this method to paint using painter.

The widget is first filled with fillColor().

The default implementation is empty.

[virtual protected] void QCPainterWidget::prePaint(QCPainter *painter)

Reimplement this function to perform drawing into one or more offscreen canvases using painter.

The default implementation is empty.

See also beginCanvasPainting() and endCanvasPainting().

[override virtual protected] void QCPainterWidget::releaseResources()

Reimplements: QRhiWidget::releaseResources().

[override virtual protected] void QCPainterWidget::render(QRhiCommandBuffer *cb)

Reimplements: QRhiWidget::render(QRhiCommandBuffer *cb).

void QCPainterWidget::setFillColor(const QColor &color)

Set the fill color to color. This color will be used to draw the background of the item. The default color is black.

See also fillColor().

void QCPainterWidget::setSharedPainter(bool enable)

Disable painter sharing if enable is false.

If painter sharing is enabled, all QCPainterWidget instances inside the same QWindow will use the same QCPainter. This function must be early, e.g. from the derived class' constructor, and must not be changed afterwards.

Painter sharing is enabled by default.

If two widgets use dedicated, non-shared painters, each other's graphics resources, such as the ones backing QCImage or QOffscreenCanvas, will not be visible to them. Whereas if the widgets are in the same window, and sharing is enabled, they can use images or canvases created by the other widget, because they both use the same QCPainter.

See also hasSharedPainter.