QCanvasPainterWidget Class

成员函数文档

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

使用给定的parent 实例化一个QCanvasPainterWidget。

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

销毁QCanvasPainterWidget 。

[protected] void QCanvasPainterWidget::beginCanvasPainting(QCanvasOffscreenCanvas &canvas)

开始录制针对canvas 的QCanvasPainter 绘制命令。

在从prePaint() 返回之前，必须始终在 beginCanvasPainting() 之后调用相应的endCanvasPainting()。

以下摘自QCanvasPainterWidget 子类的代码片段展示了如何将离屏画布渲染为图像或图像图案，并在绘制控件内容时将其用作图像或图像图案：

class MyWidget : public QCanvasPainterWidget
{
public:
    QCanvasOffscreenCanvas canvas;
    QCanvasImage canvasImage;

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

    void prePaint(QCanvasPainter *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, QCanvasPainter::ImageFlag::Repeat);
        }
    }

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

[protected] void QCanvasPainterWidget::endCanvasPainting()

表示结束针对beginCanvasPainting()中指定的画布进行的绘制操作。

beginCanvasPainting在从prePaint() 返回之前，() 之后必须始终跟上相应的 endCanvasPainting()。

[override virtual protected] bool QCanvasPainterWidget::event(QEvent *event)

重写了：QRhiWidget::event(QEvent *e)。

QColor QCanvasPainterWidget::fillColor() const

返回当前的填充颜色。

另请参阅 setFillColor()。

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

针对canvas 发出纹理读回请求，并将该请求与context 关联。

callback 该函数将在当前（主/GUI）线程上被调用，具体时间取决于底层的QRhi 和3D API实现，可能在函数返回之前，也可能在之后。根据GPU架构的不同，读回纹理内容可能涉及GPU→CPU的复制操作。该函数接受一个const QImage & 参数，该参数可以是任何函数对象，包括仅支持移动的函数对象。

如果context 在回读完成前被销毁，则抓取操作将被取消，且不会调用callback 。这使得回调函数可以安全地引用那些可能在待处理的回读操作完成前就已释放的对象。

例如，以下代码将把屏幕外画布的内容保存到 PNG 文件中：

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

[virtual protected] void QCanvasPainterWidget::graphicsResourcesInvalidated()

当底层图形资源（如纹理）丢失时调用此方法。

这表明由 addImage() 返回的QCanvasImage 对象已不再有效，需要重新调用 addImage()。如果paint() 的实现方式使得此情况无关紧要——例如因为未使用图像，或者总是会调用 addImage()——则无需采取任何行动。 否则，建议设置一个标志位（或类似机制），并在下次调用paint() 时据此采取相应措施。

这同样适用于由QCanvasPainter::createCanvas() 返回的QCanvasOffscreenCanvas 对象。当调用此函数时，下次调用paint() 时应创建新的画布并重绘其内容。

图形资源可能会丢失，例如当控件被移动到一个新的顶级窗口时，因为这意味着它将与一个新的QRhi 实例相关联。

另请参阅 QRhiWidget::releaseResources()。

bool QCanvasPainterWidget::hasSharedPainter() const

如果该控件使用共享绘制器，则返回true 。

另请参阅 setSharedPainter 。

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

重写了：QRhiWidget::initialize(QRhiCommandBuffer *cb)。

[virtual protected] void QCanvasPainterWidget::initializeResources(QCanvasPainter *painter)

重写此方法，以使用painter 初始化资源。通常，该方法会在首次调用prePaint()和paint()之前被调用一次。但当图形资源丢失时除外，详见graphicsResourcesInvalidated()。在这种情况下，该方法随后会再次被调用。

默认实现为空。

[virtual protected] void QCanvasPainterWidget::paint(QCanvasPainter *painter)

重写此方法，使用 `painter` 进行绘制。

首先使用 `fillColor()` 填充控件。

默认实现为空。

[virtual protected] void QCanvasPainterWidget::prePaint(QCanvasPainter *painter)

重写此函数，以便使用painter 向一个或多个离屏画布进行绘制。

默认实现为空。

另请参阅 beginCanvasPainting() 和endCanvasPainting()。

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

重写了：QRhiWidget::releaseResources()。

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

重写了：QRhiWidget::render(QRhiCommandBuffer *cb)。

void QCanvasPainterWidget::setFillColor(QColor color)

将填充颜色设置为color 。该颜色将用于绘制该项的背景。默认颜色为黑色。

另请参阅 fillColor()。

void QCanvasPainterWidget::setSharedPainter(bool enable)

如果enable 的值是false ，请禁用绘图器共享。

如果启用了绘图共享，同一QWindow 内的所有QCanvasPainterWidget 实例将使用相同的QCanvasPainter 。此函数必须在早期调用，例如在派生类的构造函数中，且此后不得更改。

绘图器共享默认处于启用状态。

如果两个小部件使用专用的、非共享的绘图器，则彼此的图形资源（例如支持QCanvasImage 或 QOffscreenCanvas 的资源）对它们来说将不可见。 而如果这些小部件位于同一个窗口中，并且启用了共享，它们就可以使用另一个小部件创建的图像或画布，因为它们都使用同一个QCanvasPainter 。

另请参阅 hasSharedPainter 。