QCanvasOffscreenCanvas Class
QCanvasOffscreenCanvas represents an offscreen canvas that QCanvasPainter can target. More...
| Header: | #include <QCanvasOffscreenCanvas> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS CanvasPainter)target_link_libraries(mytarget PRIVATE Qt6::CanvasPainter) |
| Since: | Qt 6.11 |
Public Types
Public Functions
| QCanvasOffscreenCanvas(const QCanvasOffscreenCanvas &canvas) | |
| QCanvasOffscreenCanvas(QCanvasOffscreenCanvas &&other) | |
| ~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) |
Related Non-Members
| bool | operator!=(const QCanvasOffscreenCanvas &lhs, const QCanvasOffscreenCanvas &rhs) |
| bool | operator==(const QCanvasOffscreenCanvas &lhs, const QCanvasOffscreenCanvas &rhs) |
Detailed Description
An offscreen canvas is essentially a color buffer (a QRhiTexture), and possibly other associated graphics resources. After content has been rendered into the canvas's color buffer, the canvas can be registered to the painter to retrieve a QCanvasImage that can then be used in drawImage() calls or as an image pattern.
To create an offscreen canvas, call QCanvasPainter::createCanvas(). To target an offscreen canvas with with draw commands, call the appropriate QCanvasRhiPaintDriver::beginPaint() overload when working with the lower level API, or QCanvasPainterWidget::beginCanvasPainting() or QCanvasPainterItemRenderer::beginCanvasPainting() when using the convenience widget or Qt Quick item classes.
Similarly to QCanvasImage and QCanvasBrush, QCanvasOffscreenCanvas is explicitly shared. See Implicit Data Sharing and QSharedDataPointer for details.
Note: As with QCanvasImage, a QCanvasOffscreenCanvas can be seen as an object merely containing handles. Even when a detach occurs, the actual resources, e.g. the underlying texture and the image data in it, are never actually copied or duplicated. The actual owner of any real graphics resources (e.g., a QRhiTexture) is the QCanvasPainter that handed out the QCanvasOffscreenCanvas via createCanvas().
A canvas always belongs to the QCanvasPainter that created it. Manually destroying canvases is done by calling destroyCanvas(). In most cases this will not be necessary, however, since the painter will automatically destroy any canvases during its own destruction.
Member Type Documentation
enum class QCanvasOffscreenCanvas::Flag
flags QCanvasOffscreenCanvas::Flags
Specifies the flags for the canvas.
| Constant | Value | Description |
|---|---|---|
QCanvasOffscreenCanvas::Flag::PreserveContents | 0x01 | Indicates that the contents of the canvas is preserved when painting to it. This can have a negative effect on performance, depending on the GPU architecture. See QRhiTextureRenderTarget::PreserveColorContents for details. Setting this flag is not supported when the sample count is greater than 1. |
QCanvasOffscreenCanvas::Flag::MipMaps | 0x02 | Indicates that the canvas' backing texture should have mipmapping enabled. Setting this flag is not supported when the sample count is greater than 1. Note that the mipmap sequence is generated when calling addImage() with the GenerateMipmaps flag set. This implies that addImage() must be called every time after the canvas' content changes, so that the mipmap chain is regenerated. Frequent mipmap generation can have a negative effect on performance. |
The Flags type is a typedef for QFlags<Flag>. It stores an OR combination of Flag values.
Member Function Documentation
QCanvasOffscreenCanvas::QCanvasOffscreenCanvas(const QCanvasOffscreenCanvas &canvas)
Copy constructor.
[constexpr noexcept default] QCanvasOffscreenCanvas::QCanvasOffscreenCanvas(QCanvasOffscreenCanvas &&other)
Move-constructs an instance of QCanvasOffscreenCanvas.
[noexcept] QCanvasOffscreenCanvas::~QCanvasOffscreenCanvas()
Destructor.
void QCanvasOffscreenCanvas::detach()
If multiple canvases share common data, this image makes a copy of the data and detaches itself from the sharing mechanism, making sure that this image is the only one referring to the data.
Nothing is done if there is just a single reference.
Note: The canvas only contains handles to the underlying graphics resources, and data such as the fill color. The graphics resources themselves, such as the QRhiTexture, are never copied or duplicated.
QColor QCanvasOffscreenCanvas::fillColor() const
Returns the current fill color.
See also setFillColor().
QCanvasOffscreenCanvas::Flags QCanvasOffscreenCanvas::flags() const
Returns the flags with which the canvas was created.
The flags are immutable and cannot be changed once the canvas has been created.
bool QCanvasOffscreenCanvas::isNull() const
Returns true if this canvas has valid data.
Normally this will always be true.
See also texture().
void QCanvasOffscreenCanvas::setFillColor(const QColor &color)
Sets the fill (clear) color to color.
By default this is set to the value passed to createCanvas().
See also fillColor().
QRhiTexture *QCanvasOffscreenCanvas::texture() const
Returns the texture backing this offscreen canvas.
See also isNull().
[noexcept] QCanvasOffscreenCanvas &QCanvasOffscreenCanvas::operator=(const QCanvasOffscreenCanvas &canvas)
Assigns a shallow copy of the given canvas to this canvas and returns a reference to this canvas. For more information about shallow copies, see the implicit data sharing documentation.
Note: The underlying resources, the graphics resources such as the QRhiTexture, are never copied or duplicated.
Related Non-Members
[noexcept] bool operator!=(const QCanvasOffscreenCanvas &lhs, const QCanvasOffscreenCanvas &rhs)
Returns true if the canvas handle lhs is different from rhs; false otherwise.
See also operator==().
[noexcept] bool operator==(const QCanvasOffscreenCanvas &lhs, const QCanvasOffscreenCanvas &rhs)
Returns true if the canvas handle lhs is equal to rhs; false otherwise.
Note: Equality means that the two canvas objects' fill colors are the same and they reference the same graphics resources. The contents (pixel data) is not compared.
See also 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.
