QCanvasOffscreenCanvas Class
QCanvasOffscreenCanvas 表示离屏画布，QCanvasPainter 。更多
| Header： | #include <QCanvasOffscreenCanvas> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS CanvasPainter)target_link_libraries(mytarget PRIVATE Qt6::CanvasPainter) |
| 自 | Qt 6.11 |
| 状态 | 技术预览版 |
公共类型
公共函数
| QCanvasOffscreenCanvas(const QCanvasOffscreenCanvas &canvas) | |
| ~QCanvasOffscreenCanvas() | |
| void | detach() |
| QColor | fillColor() const |
| QCanvasOffscreenCanvas::Flags | flags() const |
| bool | isNull() const |
| void | setFillColor(const QColor &color) |
| QRhiTexture * | texture() 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() 重载，在使用方便的 widget 或Qt Quick item 类时可调用QCanvasPainterWidget::beginCanvasPainting() 或QCanvasPainterItemRenderer::beginCanvasPainting()。
与QCanvasImage 和QCanvasBrush 类似，QCanvasOffscreenCanvas 也是显式共享的。详见隐式数据共享和QSharedDataPointer 。
注意： 与QCanvasImage 一样，QCanvasOffscreenCanvas 可被视为仅包含句柄的对象。即使发生分离，实际资源（如底层纹理和其中的图像数据）也不会被实际复制或重复。任何实际图形资源（如QRhiTexture ）的实际所有者是通过createCanvas() 发送 QCanvasOffscreenCanvas 的QCanvasPainter 。
画布始终属于创建它的QCanvasPainter 。手动销毁画布的方法是调用destroyCanvas() 。不过，在大多数情况下并不需要这样做，因为画图器在销毁自己的画布时会自动销毁任何画布。
成员类型文档
枚举类 QCanvasOffscreenCanvas::Flag
flags QCanvasOffscreenCanvas::Flags
指定画布的标志。
| 常量 | 值 | 说明 |
|---|---|---|
QCanvasOffscreenCanvas::Flag::PreserveContents | 0x01 | 表示在画布上绘制时保留画布的内容。这可能会对性能产生负面影响，具体取决于 GPU 架构。详情请参阅QRhiTextureRenderTarget::PreserveColorContents 。当采样计数大于 1 时，不支持设置此标记。 |
QCanvasOffscreenCanvas::Flag::MipMaps | 0x02 | 表示画布的背景纹理应启用 mipmapping。当采样计数大于 1 时，不支持设置此标记。请注意，当调用addImage() 并设置GenerateMipmaps 标记时，会生成 mipmap 序列。这意味着每次画布内容更改后都必须调用 addImage()，以便重新生成 mipmap 链。频繁生成 mipmap 会对性能产生负面影响。 |
Flags 类型是QFlags<Flag> 的类型定义。它存储 Flag 值的 OR 组合。
成员函数文档
QCanvasOffscreenCanvas::QCanvasOffscreenCanvas(const QCanvasOffscreenCanvas &canvas)
复制构造函数。
[noexcept] QCanvasOffscreenCanvas::~QCanvasOffscreenCanvas()
毁灭者
void QCanvasOffscreenCanvas::detach()
如果多个画布共享共同的数据，该图像会复制数据并从共享机制中分离出来，确保该图像是唯一引用数据的图像。
如果只有一个引用，则不会执行任何操作。
注意： 画布只包含指向底层图形资源的句柄以及填充颜色等数据。图形资源本身（如QRhiTexture ）永远不会被复制或重复。
QColor QCanvasOffscreenCanvas::fillColor() const
返回当前填充颜色。
另请参阅 setFillColor().
QCanvasOffscreenCanvas::Flags QCanvasOffscreenCanvas::flags() const
返回创建画布时使用的标记。
标记是不可变的，画布创建后就不能更改。
bool QCanvasOffscreenCanvas::isNull() const
如果该画布有有效数据，则返回 true。
通常情况下，返回值总是 true。
另请参阅 texture()。
void QCanvasOffscreenCanvas::setFillColor(const QColor &color)
将填充（透明）颜色设置为color 。
默认情况下，该值设置为传递给createCanvas() 的值。
另请参阅 fillColor()。
QRhiTexture *QCanvasOffscreenCanvas::texture() const
返回屏幕外画布的纹理。
另请参阅 isNull()。
QCanvasOffscreenCanvas &QCanvasOffscreenCanvas::operator=(const QCanvasOffscreenCanvas &canvas)
将给定canvas 的浅层副本分配给此 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.
