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 |
Public Functions
| QCanvasImage() | |
| QCanvasImage(const QCanvasImage &image) | |
| QCanvasImage(QCanvasImage &&other) | |
| ~QCanvasImage() | |
| 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.
int QCanvasImage::height() const
Returns the height of this image.
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.
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.
QCanvasImage::operator QVariant() const
Returns the image as a QVariant.
[noexcept] QCanvasImage &QCanvasImage::operator=(QCanvasImage &&other)
Move-assigns other to this QCanvasImage instance.
[noexcept] 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!=().
© 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.
