- Qt 6.11
- Qt Canvas Painter
- C++ Classes
- QtCanvasPainter (Technical Preview)
- QCanvasOffscreenCanvas
- Qt Canvas Painter | Commercial or GPLv3

# 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
Status: | Technical Preview

- List of all members, including inherited members

## Public Types

enum class | Flag { PreserveContents, MipMaps }
flags | Flags

## Public Functions

| 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)

## 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.

### `[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().

### 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!=().