QCImage Class
QCImage is the image class for QCPainter. More...
| Header: | #include <QCImage> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS CanvasPainter)target_link_libraries(mytarget PRIVATE Qt6::CanvasPainter) |
| Since: | Qt 6.11 |
| Status: | Technical Preview |
Public Functions
| QCImage() | |
| QCImage(const QCImage &image) | |
| QCImage(QCImage &&other) | |
| ~QCImage() | |
| int | height() const |
| int | id() const |
| bool | isNull() const |
| void | setTintColor(const QColor &color) |
| int | size() const |
| void | swap(QCImage &other) |
| QColor | tintColor() const |
| int | width() const |
| QVariant | operator QVariant() const |
| bool | operator!=(const QCImage &image) const |
| QCImage & | operator=(QCImage &&other) |
| QCImage & | operator=(const QCImage &image) |
| bool | operator==(const QCImage &image) const |
Detailed Description
QCImage is the image class used by QCPainter. To be able to paint images, they fist need to be made available with e.g. QCPainter::addImage(). Then images can be painted as-is using QCPainter::drawImage() or used with QCImagePattern brush to fill / stroke.
Here is a simple example:
static QImage logoImage(":/qtlogo.png"); // Paint an image pattern. QCImage bg = painter.addImage(logoImage, QCPainter::ImageFlag::Repeat | QCPainter::ImageFlag::GenerateMipmaps); QCImagePattern ip(bg, 0, 0, 44, 32); painter.setFillStyle(ip); painter.fillRect(50, 50, 320, 230); // Paint a single image, with tint color. QCImage 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 QCImage variables as class members and calling QCPainter::addImage() e.g. in QQuickCPainterRenderer::initializeResources().
Similarly to QCBrush and QCOffscreenCanvas, QCImage is explicitly shared. See Implicit Data Sharing and QSharedDataPointer for details.
Note: A QCImage 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 QCPainter that handed out the QCImage via addImage().
A QCImage always belongs to the QCPainter 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
QCImage::QCImage()
Constructs a default image.
[noexcept] QCImage::QCImage(const QCImage &image)
Constructs an image that is a copy of the given image.
[constexpr noexcept] QCImage::QCImage(QCImage &&other)
Move-constructs a new QCImage from other.
[noexcept] QCImage::~QCImage()
Destroys the image.
int QCImage::height() const
Returns the height of this image.
int QCImage::id() const
Returns the texture id for this image. When the image has not been assigned yet, this returns 0.
See also isNull().
bool QCImage::isNull() const
Returns true if the image has not been assigned yet. See QCPainter::addImage() for details.
void QCImage::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().
int QCImage::size() const
Returns the size of this image in bytes.
[noexcept] void QCImage::swap(QCImage &other)
Swaps this image with other. This operation is very fast and never fails.
QColor QCImage::tintColor() const
Returns the tint color of the image. The default value is Qt::white.
See also setTintColor().
int QCImage::width() const
Returns the width of this image.
QVariant QCImage::operator QVariant() const
Returns the image as a QVariant.
bool QCImage::operator!=(const QCImage &image) const
Returns true if the image is different from the given image; otherwise false.
See also operator==().
[noexcept] QCImage &QCImage::operator=(QCImage &&other)
Move-assigns other to this QCImage instance.
[noexcept] QCImage &QCImage::operator=(const QCImage &image)
Assigns the given image to this image and returns a reference to this image.
bool QCImage::operator==(const QCImage &image) const
Returns true if the image is equal to the given image; otherwise false.
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.
