QCanvasPainterWidget Class

成员函数文档

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

使用给定的parent 构建 QCanvasPainterWidget。

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

摧毁QCanvasPainterWidget.

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

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

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

以下来自QCanvasPainterWidget 子类的代码段展示了如何将屏幕外的画布渲染为图像或图像图案，然后在为 widget 绘制内容时将其用作图像或图像图案：

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() 函数。）

QColor QCanvasPainterWidget::fillColor() const

返回当前填充颜色。

另请参阅 setFillColor().

void QCanvasPainterWidget::grabCanvas(const QCanvasOffscreenCanvas &canvas, std::function<void (const QImage &)> callback)

为canvas 发出纹理回读请求。

callback 在函数返回之前或之后调用，具体取决于底层QRhi 和 3D API 实现。读回纹理内容可能涉及 GPU->CPU 复制，具体取决于 GPU 架构。

[virtual protected] void QCanvasPainterWidget::graphicsResourcesInvalidated()

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

这表明从 addImage() 返回的QCanvasImage 对象不再有效，需要再次调用 addImage()。如果paint() 的实现与此无关，例如不使用图像，或 addImage() 总是被调用，则无需采取任何措施。否则，建议切换一个标志或类似标志，并在下次调用paint() 时采取相应措施。

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

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

另请参阅 QRhiWidget::releaseResources()。

bool QCanvasPainterWidget::hasSharedPainter() const

如果此 widget 使用共享绘画器，则返回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() 填充 widget。

默认实现为空。

[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(const QColor &color)

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

另请参阅 fillColor() 。

void QCanvasPainterWidget::setSharedPainter(bool enable)

如果enable 是false ，则禁用画家共享。

如果启用了 Painter 共享，则同一QWindow 中的所有QCanvasPainterWidget 实例都将使用相同的QCanvasPainter 。该函数必须在派生类的构造函数中提前启动，且之后不得更改。

默认情况下已启用 "画家共享"。

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

另请参阅 hasSharedPainter 。