- Qt 6.12
- Qt Canvas Painter
- C++ Classes
- QCanvasImage
- Qt Canvas Painter | Commercial or GPLv3

# QCanvasImage Class

QCanvasImage is the image class for QCanvasPainter. More...

Header: | `#include <QCanvasImage>`
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 Functions

| QCanvasImage()
| QCanvasImage(const QCanvasImage &image)
| QCanvasImage(QCanvasImage &&other)
| ~QCanvasImage()
qreal | devicePixelRatio() const
int | height() const
int | id() const
bool | isNull() const
void | setTintColor(const QColor &color)
QSize | size() const
qsizetype | sizeInBytes() const
void | swap(QCanvasImage &other)
QColor | tintColor() const
int | width() const
| operator QVariant() const
QCanvasImage & | operator=(QCanvasImage &&other)
QCanvasImage & | operator=(const QCanvasImage &image)

## Related Non-Members

bool | operator!=(const QCanvasImage &lhs, const QCanvasImage &rhs)
bool | operator==(const QCanvasImage &lhs, const QCanvasImage &rhs)

## Detailed Description

QCanvasImage is the image class used by QCanvasPainter. To be able to paint images, they fist need to be made available with e.g. QCanvasPainter::addImage(). Then images can be painted as-is using QCanvasPainter::drawImage() or used with QCanvasImagePattern brush to fill / stroke.

Here is a simple example:

     static QImage logoImage(":/qtlogo.png");
     // Paint an image pattern.
     QCanvasImage bg = painter.addImage(logoImage,
                  QCanvasPainter::ImageFlag::Repeat |
                  QCanvasPainter::ImageFlag::GenerateMipmaps);
     QCanvasImagePattern ip(bg, 0, 0, 44, 32);
     painter.setFillStyle(ip);
     painter.fillRect(50, 50, 320, 230);
     // Paint a single image, with tint color.
     QCanvasImage logo = painter.addImage(logoImage);
     logo.setTintColor("#2cde85");
     painter.drawImage(logo, 100, 80);

In the above example the QImage is static and addImage() is called on every repaint. This is not a problem as when the image and flags remain the same, addImage() fetches the image from cache instead of uploads it again as a texture. But a more common approac is having QCanvasImage variables as class members and calling QCanvasPainter::addImage() e.g. in QCanvasPainterItemRenderer::initializeResources().

Similarly to QCanvasBrush and QCanvasOffscreenCanvas, QCanvasImage is explicitly shared. See Implicit Data Sharing and QSharedDataPointer for details.

Note: A QCanvasImage object contains only a handle to a graphics resource, such as a texture. Even when a detach occurs, the actual resource, i.e. the underlying texture and the image data in it, is never actually copied or duplicated. The actual owner of the real graphics resource (e.g., a QRhiTexture) is the QCanvasPainter that handed out the QCanvasImage via addImage().

A QCanvasImage always belongs to the QCanvasPainter that created it. Manually removing images is done by calling removeImage(). In most cases this will not be necessary, however, since the painter will automatically destroy any images during its own destruction.

## Member Function Documentation

### QCanvasImage::QCanvasImage()

Constructs a default image.

### QCanvasImage::QCanvasImage(const QCanvasImage &image)

Constructs an image that is a copy of the given image.

### `[constexpr noexcept default]` QCanvasImage::QCanvasImage(QCanvasImage &&other)

Move-constructs a new QCanvasImage from other.

### `[noexcept]` QCanvasImage::~QCanvasImage()

Destroys the image.

### qreal QCanvasImage::devicePixelRatio() const

Returns the device pixel ratio for the image. This is the ratio between device pixels and device independent pixels.

A QCanvasImage with a greater than 1 device pixel ratio applies that scale factor when using the image. For example, `drawImage(image, 0, 0)` is then equivalent to `drawImage(image, 0, 0, image.width() / image.devicePixelRatio(), image.height() / image.devicePixelRatio())`.

The default value is 1.0.

The value is carried over from the QImage the QCanvasImage is created from. A QCanvasImage created from a texture or offscreen canvas always has a device pixel ratio of 1.

See also QImage.

### int QCanvasImage::height() const

Returns the height of this image in pixels;

### int QCanvasImage::id() const

Returns the texture id for this image. When the image has not been assigned yet, this returns 0.

See also isNull().

### bool QCanvasImage::isNull() const

Returns true if the image has not been assigned yet. See QCanvasPainter::addImage() for details.

### void QCanvasImage::setTintColor(const QColor &color)

Set the tint color of the image. This color will be multiplied with the image color to colorize the image. This can be used for example to highlight icons or to adjust images becase on the theme.

See also tintColor().

### QSize QCanvasImage::size() const

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

### qsizetype QCanvasImage::sizeInBytes() const

Returns the size of this image in bytes.

QCanvasPainter does not keep copies of the CPU-side QImage data once addImage() has returned. If the source is a offscreen canvas, then there is no CPU-side image data in the first place. Therefore, the result of this function is an approximation of the GPU memory that is used for the underlying texture.

Note: The value is only an estimate based on the image format and dimensions. Qt has no knowledge of how the data for textures is stored and laid out in memory on the GPU side.

Note: This function does not take mipmap or multisample data into consideration.

### `[noexcept]` void QCanvasImage::swap(QCanvasImage &other)

Swaps this image with other. This operation is very fast and never fails.

### QColor QCanvasImage::tintColor() const

Returns the tint color of the image. The default value is Qt::white.

See also setTintColor().

### int QCanvasImage::width() const

Returns the width of this image in pixels.

### QCanvasImage::operator QVariant() const

Returns the image as a QVariant.

### `[noexcept]` QCanvasImage &QCanvasImage::operator=(QCanvasImage &&other)

Move-assigns other to this QCanvasImage instance.

### QCanvasImage &QCanvasImage::operator=(const QCanvasImage &image)

Assigns the given image to this image and returns a reference to this image.

## Related Non-Members

### `[noexcept]` bool operator!=(const QCanvasImage &lhs, const QCanvasImage &rhs)

Returns `true` if the image handle lhs is different from rhs; `false` otherwise.

See also operator==().

### `[noexcept]` bool operator==(const QCanvasImage &lhs, const QCanvasImage &rhs)

Returns `true` if the image handle lhs is equal to rhs; `false` otherwise.

Note: Equality means that the two image objects reference the same graphics resources and the tint colors are the same. The contents (pixel data) is not compared.

See also operator!=().