Back to Qt.io
Contact Us Blog Download Qt
本页内容

QCanvasOffscreenCanvas Class

QCanvasOffscreenCanvas 表示一个QCanvasPainter 可以定位的离屏画布。更多内容...

头文件： #include <QCanvasOffscreenCanvas>
CMake： find_package(Qt6 REQUIRED COMPONENTS CanvasPainter)
target_link_libraries(mytarget PRIVATE Qt6::CanvasPainter)
自： Qt 6.11

公共类型

enum class Flag { PreserveContents, MipMaps }
flags Flags

公共函数

QCanvasOffscreenCanvas(const QCanvasOffscreenCanvas &canvas)
QCanvasOffscreenCanvas(QCanvasOffscreenCanvas &&other)
~QCanvasOffscreenCanvas()
QColor fillColor() const
QCanvasOffscreenCanvas::Flags flags() const
int height() const
bool isNull() const
void setFillColor(QColor color)
QSize size() const
QRhiTexture *texture() const
int width() const
QCanvasOffscreenCanvas &operator=(const QCanvasOffscreenCanvas &canvas)
bool operator!=(const QCanvasOffscreenCanvas &lhs, const QCanvasOffscreenCanvas &rhs)
bool operator==(const QCanvasOffscreenCanvas &lhs, const QCanvasOffscreenCanvas &rhs)

详细说明

离屏画布本质上是一个颜色缓冲区（QRhiTexture ），可能还包含其他相关的图形资源。将内容渲染到画布的颜色缓冲区后，可以通过registered 将画布传递给绘图器，以获取QCanvasImage ，该资源随后可用于drawImage()调用，或作为image pattern 。

要创建一个离屏画布，请调用QCanvasPainter::createCanvas()。若要通过绘制命令针对离屏画布进行操作，在使用底层 API 时请调用相应的QCanvasRhiPaintDriver::beginPaint() 重载方法；若使用便捷控件或Qt Quick 项类，则请调用QCanvasPainterWidget::beginCanvasPainting() 或QCanvasPainterItemRenderer::beginCanvasPainting()。

与QCanvasImage 和QCanvasBrush 类似，QCanvasOffscreenCanvas是显式共享的。详情请参阅“隐式数据共享”和QSharedDataPointer 。

注意： 与QCanvasImage一样， QCanvasOffscreenCanvas可被视为仅包含句柄的对象。即使发生脱离，实际资源（例如底层纹理及其中的图像数据）也绝不会被复制或复制。 任何实际图形资源（例如QRhiTexture ）的真正所有者，是通过createCanvas()方法分发该QCanvasOffscreenCanvas的QCanvasPainter 。

画布始终属于创建它的QCanvasPainter 。若需手动销毁画布，请调用destroyCanvas()。但在大多数情况下，这并不必要，因为绘制器会在自身销毁时自动销毁所有画布。

成员类型文档

enum class QCanvasOffscreenCanvas::Flag
flags QCanvasOffscreenCanvas::Flags

指定画布的标志。

常量值说明
QCanvasOffscreenCanvas::Flag::PreserveContents0x01表示在向画布绘制时，画布的内容将被保留。这可能会对性能产生负面影响，具体取决于 GPU 架构。详情请参阅QRhiTextureRenderTarget::PreserveColorContents 。当采样数大于 1 时，不支持设置此标志。
QCanvasOffscreenCanvas::Flag::MipMaps0x02表示画布的底层纹理应启用米普映射。当采样数大于 1 时，不支持设置此标志。请注意，当调用addImage() 并设置了GenerateMipmaps 标志时，会生成米普映射序列。 这意味着每次画布内容发生变化后，都必须调用 addImage()，以便重新生成 Mipmap 链。频繁生成 Mipmap 可能会对性能产生负面影响。

Flags 类型是QFlags<Flag> 的 typedef。它存储 Flag 值的按“或”运算组合。

成员函数文档

QCanvasOffscreenCanvas::QCanvasOffscreenCanvas(const QCanvasOffscreenCanvas &canvas)

复制构造函数。

[constexpr noexcept default] QCanvasOffscreenCanvas::QCanvasOffscreenCanvas(QCanvasOffscreenCanvas &&other)

通过`Move`构造一个QCanvasOffscreenCanvas 的实例。

[noexcept] QCanvasOffscreenCanvas::~QCanvasOffscreenCanvas()

析构函数。

QColor QCanvasOffscreenCanvas::fillColor() const

返回当前的填充颜色。

另请参阅 ` setFillColor()`。

QCanvasOffscreenCanvas::Flags QCanvasOffscreenCanvas::flags() const

返回创建画布时使用的标志。

这些标志是不可变的，画布创建后无法更改。

int QCanvasOffscreenCanvas::height() const

返回此画布的高度（以像素为单位）。

另请参阅 width() 和size()。

bool QCanvasOffscreenCanvas::isNull() const

如果该画布包含有效数据，则返回 true。

通常情况下，该值始终为 true。

另请参阅 texture()。

void QCanvasOffscreenCanvas::setFillColor(QColor color)

将填充（透明）颜色设置为color 。

默认情况下，该值与传递给 `createCanvas()` 的参数相同。

另请参阅 fillColor()。

QSize QCanvasOffscreenCanvas::size() const

返回此画布的大小（宽度和高度），单位为像素。

另请参阅 ` width()` 和 `height()`。

QRhiTexture *QCanvasOffscreenCanvas::texture() const

返回此离屏画布所基于的纹理。

另请参阅 isNull()。

int QCanvasOffscreenCanvas::width() const

返回此画布的宽度（以像素为单位）。

另请参阅 height() 和size()。

QCanvasOffscreenCanvas &QCanvasOffscreenCanvas::operator=(const QCanvasOffscreenCanvas &canvas)

将给定的canvas 的浅拷贝分配给此画布，并返回对此画布的引用。有关浅拷贝的更多信息，请参阅隐式数据共享文档。

注意： 底层资源（例如QRhiTexture 等图形资源）绝不会被复制或重复创建。

相关的非成员

[noexcept] bool operator!=(const QCanvasOffscreenCanvas &lhs, const QCanvasOffscreenCanvas &rhs)

如果画布句柄lhs 与rhs 不一致，则返回true ；否则返回false 。

另请参阅 operator==()。

[noexcept] bool operator==(const QCanvasOffscreenCanvas &lhs, const QCanvasOffscreenCanvas &rhs)

如果画布句柄lhs 与rhs 相等，则返回true ；否则返回false 。

注意：相等性 是指这两个画布对象的填充颜色相同，且它们引用的是相同的图形资源。内容（像素数据）不会被比较。

另请参阅 operator!=()。

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