QCanvasImage Class

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.

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.