- Qt 6.12
- Qt Canvas Painter
- C++ Classes
- 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

- List of all members, including inherited members

## Public Types

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

## Public Functions

| QCanvasOffscreenCanvas(const QCanvasOffscreenCanvas &canvas)
| QCanvasOffscreenCanvas(QCanvasOffscreenCanvas &&other)
| ~QCanvasOffscreenCanvas()
QColor | fillColor() const
QCanvasOffscreenCanvas::Flags | flags() const
int | height() const
bool | isNull() const
void | setFillColor(const QColor &color)
QSize | size() const
QRhiTexture * | texture() const
int | width() 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.

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

### int QCanvasOffscreenCanvas::height() const

Returns the height of this canvas in pixels.

See also width() and size().

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

### QSize QCanvasOffscreenCanvas::size() const

Returns the size (width and height) of this canvas in pixels.

See also width() and height().

### QRhiTexture *QCanvasOffscreenCanvas::texture() const

Returns the texture backing this offscreen canvas.

See also isNull().

### int QCanvasOffscreenCanvas::width() const

Returns the width of this canvas in pixels.

See also height() and size().

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