QCOffscreenCanvas Class
QCOffscreenCanvas represents an offscreen canvas that QCPainter can target. More...
| Header: | #include <QCOffscreenCanvas> |
Public Types
Public Functions
| QCOffscreenCanvas(const QCOffscreenCanvas &canvas) | |
| ~QCOffscreenCanvas() | |
| void | detach() |
| QColor | fillColor() const |
| QCOffscreenCanvas::Flags | flags() const |
| bool | isNull() const |
| void | setFillColor(const QColor &color) |
| QRhiTexture * | texture() const |
| QCOffscreenCanvas & | operator=(const QCOffscreenCanvas &canvas) |
| bool | operator==(const QCOffscreenCanvas &other) const |
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 QCImage that can then be used in drawImage() calls or as an image pattern.
To create an offscreen canvas, call QCPainter::createCanvas(). To target an offscreen canvas with with draw commands, call the appropriate QCRhiPaintDriver::beginPaint() overload when working with the lower level API, or QCPainterWidget::beginCanvasPainting() or QQuickCPainterRenderer::beginCanvasPainting() when using the convenience widget or Qt Quick item classes.
Similarly to QCImage and QCBrush, QCOffscreenCanvas is explicitly shared. See Implicit Data Sharing and QSharedDataPointer for details. As with QCImage, a QCOffscreenCanvas object can be seen as containing handles to graphics resources. Even when a detach occurs, the actual resources, i.e. the image data in the underlying texture, are never actually copied or duplicated.
A canvas always belongs to the QCPainter 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 QCOffscreenCanvas::Flag
flags QCOffscreenCanvas::Flags
Specifies the flags for the canvas.
| Constant | Value | Description |
|---|---|---|
QCOffscreenCanvas::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. Settings this flag is not supported when the sample count is greater than 1. |
The Flags type is a typedef for QFlags<Flag>. It stores an OR combination of Flag values.
Member Function Documentation
[noexcept] QCOffscreenCanvas::QCOffscreenCanvas(const QCOffscreenCanvas &canvas)
Copy constructor.
[noexcept] QCOffscreenCanvas::~QCOffscreenCanvas()
Destructor.
void QCOffscreenCanvas::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 QCOffscreenCanvas::fillColor() const
Returns the current fill color.
See also setFillColor().
QCOffscreenCanvas::Flags QCOffscreenCanvas::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 QCOffscreenCanvas::isNull() const
Returns true if this canvas has valid data.
Normally this will always be true.
See also texture().
void QCOffscreenCanvas::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 *QCOffscreenCanvas::texture() const
Returns the texture backing this offscreen canvas.
See also isNull().
[noexcept] QCOffscreenCanvas &QCOffscreenCanvas::operator=(const QCOffscreenCanvas &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.
bool QCOffscreenCanvas::operator==(const QCOffscreenCanvas &other) const
Returns true if this and the other canvas are the same, meaning their fill colors are the same and they reference the same graphics resources.
© 2025 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.
