QCanvasPainter Class

 QRectF rect(40, 70, 120, 60);
 QRectF shadowRect = rect.translated(2, 4);
 // Paint shadow
 QCanvasBoxShadow shadow(shadowRect, 30, 15, "#60373F26");
 p->drawBoxShadow(shadow);
 // Paint rounded rect
 p->beginPath();
 p->roundRect(rect, 30);
 p->setFillStyle("#DBEB00");
 p->fill();
 // Paint text
 p->setTextAlign(QCanvasPainter::TextAlign::Center);
 p->setTextBaseline(QCanvasPainter::TextBaseline::Middle);
 QFont font("Titillium Web", 18);
 p->setFont(font);
 p->setFillStyle("#373F26");
 p->fillText("CLICK!", rect);

 // Paint grid
 QCanvasGridPattern grid(0, 0, 10, 10, "#404040", "#202020");
 p->setFillStyle(grid);
 p->fillRect(0, 0, width(), height());
 // Paint axis
 p->setFillStyle(QColorConstants::White);
 p->fillRect(0, 0.5 * height() - 1, width(), 2);
 p->fillRect(0.5 * width() - 1, 0, 2, height());
 // Paint shadowed graph
 p->beginPath();
 p->moveTo(20, height() * 0.8);
 p->bezierCurveTo(width() * 0.2, height() * 0.4,
                  width() * 0.5, height() * 0.8,
                  width() - 20, height() * 0.2);
 p->setAntialias(10);
 p->setLineWidth(12);
 p->setStrokeStyle("#D0000000");
 p->stroke();
 p->setAntialias(1);
 p->setLineWidth(6);
 QCanvasLinearGradient lg(0, 0, 0, height());
 lg.setStartColor(QColorConstants::Red);
 lg.setEndColor(QColorConstants::Green);
 p->setStrokeStyle(lg);
 p->stroke();

 p->setRenderHint(QCanvasPainter::RenderHint::DisableWindingEnforce);
 p->beginPath();
 // Outer shape, counterclockwise
 p->moveTo(20, 20);
 p->lineTo(100, 180);
 p->lineTo(180, 20);
 p->closePath();
 // Inner shape, clockwise
 p->moveTo(100, 40);
 p->lineTo(125, 90);
 p->lineTo(75, 90);
 p->closePath();
 p->fill();
 p->stroke();

 p->beginPath();
 p->roundRect(20, 20, 160, 160, 30);
 // Start painting holes
 p->beginHoleSubPath();
 p->roundRect(40, 40, 120, 120, 10);
 // Start painting solid
 p->beginSolidSubPath();
 p->rect(60, 60, 80, 20);
 p->circle(100, 120, 20);
 p->fill();
 p->stroke();

Member Function Documentation

[noexcept] QCanvasPainter::~QCanvasPainter()

Destroys the painter.

int QCanvasPainter::activeImageCount() const

Returns the number of active QCanvasImage objects registered with this QCanvasPainter. This also includes the internally created images for gradients.

QCanvasImage objects created by registering QCanvasOffscreenCanvas instances or externally managed textures are not taken into account by this function.

See also activeImageMemoryUsage(), addImage(), and removeImage().

int QCanvasPainter::activeImageMemoryUsage() const

Returns an approximation in kilobytes of the memory used by the image (pixel) data for all active QCanvasImage instances for this painter that were created by the addImage() overload taking a QImage. It also includes the data from internally created images for gradients.

QCanvasPainter does not keep copies of the CPU-side QImage data once addImage() has returned. Therefore, the result of this function is an approximation of the GPU memory that is used for textures.

Offscreen canvases and externally managed textures registered via the other addImage() overloads are not taken into account by this function.

For every valid QCanvasImage, the individual size in bytes can always be queried by calling sizeInBytes(). That function returns valid results also when the QCanvasImage was created from a QCanvasOffscreenCanvas or QRhiTexture, but it does not consider mipmap or multisample data.

See also activeImageCount(), addImage(), and removeImage().

QCanvasImage QCanvasPainter::addImage(const int &image, int flags = {})

Adds image with flags available for the painter as a texture. Returns QCanvasImage with the texture id and other information about the image. Returned QCanvasImage can then be used with drawImage and QCanvasImagePattern. After calling this method, image QImage does not need be kept in memory.

Calling with the same image is a cheap operation, since a cache hit is expected.

Care must be taken when optimizing to call addImage() only once. That is not always sufficient, depending on the application design. For example, if the underlying graphics resources are lost, e.g. because the painter is associated with a new QRhi under the hood due to moving a widget to a new top-level, then calling this function is essential in order to re-create the native graphics textures from image.

See also drawImage() and removeImage().

QCanvasImage QCanvasPainter::addImage(QRhiTexture *texture, int flags = {})

Adds texture with flags available for the painter as a texture. The flag NativeTexture is set implicitly. The returned QCanvasImage can be used with drawImage and QCanvasImagePattern.

See also drawImage() and removeImage().

QCanvasImage QCanvasPainter::addImage(const QCanvasOffscreenCanvas &canvas, int flags = {})

Registers canvas with flags to the painter so that it is available as an image. The returned QCanvasImage can be used with drawImage and QCanvasImagePattern.

See also drawImage() and removeImage().

void QCanvasPainter::arc(float centerX, float centerY, float radius, float a0, float a1, QCanvasPainter::PathWinding direction = PathWinding::ClockWise, QCanvasPainter::PathConnection connection = PathConnection::Connected)

Creates new circle arc shaped sub-path. The arc center is at centerX, centerY, with radius, and the arc is drawn from angle a0 to a1, and swept in direction (ClockWise or CounterClockWise). When connection is NotConnected, arc does not add a line from the previous path position to the start of the arc. Angles are specified in radians.

void QCanvasPainter::arc(int centerPoint, float radius, float a0, float a1, QCanvasPainter::PathWinding direction = PathWinding::ClockWise, QCanvasPainter::PathConnection connection = PathConnection::Connected)

Creates new circle arc shaped sub-path. The arc center is at centerPoint, with radius, and the arc is drawn from angle a0 to a1, and swept in direction (ClockWise or CounterClockWise). When connection is NotConnected, arc does not add a line from the previous path position to the start of the arc. Angles are specified in radians.

void QCanvasPainter::arcTo(float x1, float y1, float x2, float y2, float radius)

Adds an arc segment at the corner defined by the last path point, and two specified points (x1, y1 and x2, y2) with radius. The arc is automatically connected to the path's latest point with a straight line if necessary.

void QCanvasPainter::arcTo(int controlPoint1, int controlPoint2, float radius)

Adds an arc segment at the corner defined by the last path point, and two specified points (controlPoint1 and controlPoint2) with radius. The arc is automatically connected to the path's latest point with a straight line if necessary.

void QCanvasPainter::beginHoleSubPath()

Start a hole subpath. This is equivalent to setPathWinding(QCanvasPainter::PathWinding::ClockWise))

See also beginSolidSubPath().

void QCanvasPainter::beginPath()

Begins drawing a new path while clearing the current path.

void QCanvasPainter::beginSolidSubPath()

Start a solid subpath. This is equivalent to setPathWinding(QCanvasPainter::PathWinding::CounterClockWise))

See also beginHoleSubPath().

void QCanvasPainter::bezierCurveTo(float cp1X, float cp1Y, float cp2X, float cp2Y, float x, float y)

Adds cubic bezier segment from last point in the path via two control points (cp1X, cp1Y and cp2X, cp2Y) to the specified point (x, y).

void QCanvasPainter::bezierCurveTo(int controlPoint1, int controlPoint2, int endPoint)

Adds cubic bezier segment from last point in the path via two control points (controlPoint1 and controlPoint2) to the specified point endPoint.

void QCanvasPainter::circle(float centerX, float centerY, float radius)

Creates new circle shaped sub-path into ( centerX, centerY) with radius.

void QCanvasPainter::circle(int centerPoint, float radius)

Creates new circle shaped sub-path into centerPoint with radius.

void QCanvasPainter::cleanupResources()

Schedules dropping unused textures from the cache.

Additionally, other caches and pools may get shrunk upon calling this function, in order to minimize memory usage. This may potentially lead to more expensive drawing calls afterwards.

void QCanvasPainter::clearRect(float x, float y, float width, float height)

Erases the pixels in a rectangular area by filling the rectangle specified by x, y, width, height with transparent black. As clearing does not need blending, it can be faster than fillRect().

void QCanvasPainter::clearRect(const int &rect)

Erases the pixels in a rectangular area by filling the rectangle specified by rect with transparent black. This is an overloaded method using QRectF.

void QCanvasPainter::closePath()

Closes the current sub-path with a line segment. This is equivalent to lineTo([starting point]) as the last path element.

void QCanvasPainter::destroyCanvas(QCanvasOffscreenCanvas &canvas)

Destroys the resources backing canvas. canvas becomes a null canvas then.

The painter automatically does this upon its destruction. Therefore, calling this function is only necessary when releasing the associated resources is desired right away.

float QCanvasPainter::devicePixelRatio() const

Returns the ratio between physical pixels and device-independent pixels. The default value is 1.0.

void QCanvasPainter::drawBoxShadow(const QCanvasBoxShadow &shadow)

Draws a box shadow. The shadow will be painted with the position, size, color, blur etc. set in the shadow. Calling beginPath() before this method is not required.

See also QCanvasBoxShadow.

void QCanvasPainter::drawImage(const QCanvasImage &image, float x, float y)

Draw image into x, y, at its default size.

See also addImage().

void QCanvasPainter::drawImage(const QCanvasImage &image, const int &destinationRect)

Draw image into position and size of destinationRect.

See also addImage().

void QCanvasPainter::drawImage(const QCanvasImage &image, float x, float y, float width, float height)

Draw image into x, y, at given width and height.

See also addImage().

void QCanvasPainter::ellipse(float centerX, float centerY, float radiusX, float radiusY)

Creates new ellipse shaped sub-path into ( centerX, centerY) with radiusX and radiusY.

void QCanvasPainter::ellipse(const int &rect)

Creates new ellipse shaped sub-path into rect. This ellipse will cover the rect area.

void QCanvasPainter::ellipse(int centerPoint, float radiusX, float radiusY)

Creates new ellipse shaped sub-path into centerPoint with radiusX and radiusY.

void QCanvasPainter::fill()

Fills the current path with current fill style.

See also setFillStyle().

void QCanvasPainter::fill(const QCanvasPath &path, int pathGroup = 0)

Fills the path with current fill style and belonging into pathGroup. Painting through QCanvasPath is optimal when the path contains more commands is mostly static. By default, pathGroup is 0, so using the first group. When pathGroup is -1, the path will not be cached on GPU side. More information about using path cache groups in QCanvasPath documentation. Calling beginPath() before this method is not required.

See also setFillStyle().

void QCanvasPainter::fillRect(float x, float y, float width, float height)

Draws a filled rectangle into specified position ( x, y) at size width, height.

void QCanvasPainter::fillRect(const int &rect)

Draws a filled rectangle into rect. This is an overloaded method using QRectF.

void QCanvasPainter::fillText(const int &text, int point, float maxWidth = -1)

Draws text string at specified point, with current textAlign and textBaseline. To make the text wrap into multiple lines, set optional maxWidth parameter to preferred row width in pixels. White space is stripped at the beginning of the rows, the text is split at word boundaries or when new-line characters are encountered. Words longer than the max width are split at nearest character (i.e. no hyphenation).

This is an overloaded method using QPointF.

int QCanvasPainter::getTransform() const

Returns the current transform.

void QCanvasPainter::lineTo(float x, float y)

Adds line segment from the last point in the path to the ( x, y) point.

void QCanvasPainter::lineTo(int point)

Adds line segment from the last point in the path to the point.

[static] float QCanvasPainter::mmToPx(float mm)

Static helper method to convert millimeters mm into pixels. This allows doing resolution independent drawing. For example to set the line width to 2mm use:

painter->setLineWidth(QCanvasPainter::mmToPx(2));

void QCanvasPainter::moveTo(float x, float y)

Starts new sub-path with ( x, y) as first point.

void QCanvasPainter::moveTo(int point)

Starts new sub-path with point as first point.

[static] float QCanvasPainter::ptToPx(float pt)

Static helper method to convert points pt into pixels.

void QCanvasPainter::quadraticCurveTo(float cpX, float cpY, float x, float y)

Adds quadratic bezier segment from last point in the path via a control point (cpX, cpY) to the specified point (x, y).

void QCanvasPainter::quadraticCurveTo(int controlPoint, int endPoint)

Adds quadratic bezier segment from last point in the path via a controlPoint to the specified endPoint.

void QCanvasPainter::rect(float x, float y, float width, float height)

Creates new rectangle shaped sub-path in position x, y with size width, height.

void QCanvasPainter::rect(const int &rect)

Creates new rectangle shaped sub-path at rect. This is an overloaded method using QRectF.

void QCanvasPainter::removeImage(const QCanvasImage &image)

Releases the resources associated with image and removes the image from the painter.

See also addImage().

void QCanvasPainter::removePathGroup(int pathGroup)

Removes pathGroup from the painter cache. Calling fill() or stroke() for pathGroup after this, will regenerate the path into the group cache.

See also fill() and stroke().

int QCanvasPainter::renderHints() const

Returns a flag that specifies the rendering hints that are set for this painter.

See also setRenderHints() and setRenderHint().

void QCanvasPainter::reset()

Resets the current painter state to default values.

See also save() and restore().

void QCanvasPainter::resetClipping()

Resets and disables clipping.

See also setClipRect().

void QCanvasPainter::resetTransform()

Resets current transform to a identity matrix.

void QCanvasPainter::restore()

Pops and restores current render state. So previously saved state will be restored. If save() has not been called and the state stack is empty, calling this does nothing.

See also save().

void QCanvasPainter::rotate(float angle)

Rotates current coordinate system clockwise by angle.

The angle is specified in radians. Use qDegreesToRadians() to convert from degrees to radians.

void QCanvasPainter::roundRect(float x, float y, float width, float height, float radius)

Creates new rounded rectangle shaped sub-path in position x, y with size width, height. Corners rounding will be radius.

void QCanvasPainter::roundRect(const int &rect, float radius)

Creates new rounded rectangle shaped sub-path at rect with radius corners. This is an overloaded method using QRectF.

void QCanvasPainter::roundRect(const int &rect, float radiusTopLeft, float radiusTopRight, float radiusBottomRight, float radiusBottomLeft)

Creates new rounded rectangle shaped sub-path at rect. Corners rounding can be varying per-corner, with radiusTopLeft, radiusTopRight, radiusBottomRight, radiusBottomLeft.

void QCanvasPainter::roundRect(float x, float y, float width, float height, float radiusTopLeft, float radiusTopRight, float radiusBottomRight, float radiusBottomLeft)

Creates new rounded rectangle shaped sub-path in position x, y with size width, height. Corners rounding can be varying per-corner, with radiusTopLeft, radiusTopRight, radiusBottomRight, radiusBottomLeft.

void QCanvasPainter::scale(float scale)

Scales the current coordinat system by scale. Both x and y coordinates are scaled evenly.

void QCanvasPainter::scale(float scaleX, float scaleY)

Scales the current coordinat system by scaleX and scaleY.

void QCanvasPainter::setAntialias(float antialias)

Set the current antialiasing amount to antialias in pixels. More antialias means smoother painting. This only affects fill and stroke painting, not images or texts. The default value is 1.0 and the maximum value is 10.0.

Antialiasing can be modified per-path so it can be set before each stroke/fill. To disable antialiasing from the whole canvas painter, use QCanvasPainter::RenderHint::Antialiasing render hint.

See also setRenderHints() and setTextAntialias().

void QCanvasPainter::setClipRect(float x, float y, float width, float height)

Sets the current scissor rectangle to (x, y, width, height). The scissor rectangle is transformed by the current transform.

See also resetClipping().

void QCanvasPainter::setClipRect(const int &rect)

Sets the current scissor rectangle to rect. The scissor rectangle is transformed by the current transform.

See also resetClipping().

void QCanvasPainter::setFillStyle(const class QCanvasBrush &brush)

Sets the fill style to brush. The default fill style is solid black color (0, 0, 0, 1).

void QCanvasPainter::setFont(const int &font)

Sets the font as currently active font.

void QCanvasPainter::setGlobalAlpha(float alpha)

Sets the global alpha (transparency) value to alpha. This alpha value is applied to all rendered shapes. Already transparent paths will get proportionally more transparent as well. Alpha should be between 0.0 (fully transparent) and 1.0 (fully opaque). By default alpha is 1.0.

void QCanvasPainter::setGlobalBrightness(float value)

Sets the global brightness to value. This brightess is applied to all rendered shapes. A value of 0 will cause painting to be completely black. Value can also be bigger than 1.0, to increase the brightness. By default, brightness is 1.0.

void QCanvasPainter::setGlobalCompositeOperation(QCanvasPainter::CompositeOperation operation)

Sets the global composite operation mode to operation. This mode is applied to all painting operations. The default mode is QCanvasPainter::CompositeOperation::SourceOver.

void QCanvasPainter::setGlobalContrast(float value)

Sets the global contrast to value. This contrast is applied to all rendered shapes. A value of 0 will cause painting to be completely gray (0.5, 0.5, 0.5). Value can also be bigger than 1.0, to increase the contrast. By default, contrast is 1.0.

void QCanvasPainter::setGlobalSaturate(float value)

Sets the global saturations to value. This saturations is applied to all rendered shapes. A value of 0 will disable saturation and cause painting to be completely grayscale. Value can also be bigger than 1.0, to increase the saturation. By default, saturation is 1.0.

void QCanvasPainter::setLineCap(QCanvasPainter::LineCap cap)

Sets the end of the line of stoke to cap. The default line cap is QCanvasPainter::LineCap::Butt.

void QCanvasPainter::setLineJoin(QCanvasPainter::LineJoin join)

Sets the line join of stroke to join. The default line join is QCanvasPainter::LineJoin::Miter.

See also setMiterLimit().

void QCanvasPainter::setLineWidth(float width)

Sets the line width of stroke to width in pixels. The default line width is 1.0. When the antialiasing is enabled, the line widths under a single pixel automatically fade the opacity, creating a smooth output.

See also stroke().

void QCanvasPainter::setMiterLimit(float limit)

Sets the miter limit to limit. Miter limit controls when a sharp corner is beveled. When the corner length would become longer than this limit, QCanvasPainter::LineJoin::Bevel will be applied between the lines instead. This has only effect with the QCanvasPainter::LineJoin::Miter line join. The default limit is 10.0.

See also setLineJoin().

void QCanvasPainter::setPathWinding(QCanvasPainter::PathWinding winding)

Sets the current sub-path winding to either CounterClockWise (default) or ClockWise. CounterClockWise draws solid subpaths while ClockWise draws holes.

See also beginHoleSubPath() and beginSolidSubPath().

void QCanvasPainter::setRenderHint(int hint, bool on = true)

Sets the given render hint on the painter if on is true; otherwise clears the render hint.

See also setRenderHints() and renderHints().

void QCanvasPainter::setRenderHints(int hints, bool on = true)

Sets the given render hints on the painter if on is true; otherwise clears the render hints.

See also setRenderHint() and renderHints().

void QCanvasPainter::setStrokeStyle(const class QCanvasBrush &brush)

Sets the stroke style to brush. The default stroke style is solid black color (0, 0, 0, 1).

void QCanvasPainter::setTextAlign(QCanvasPainter::TextAlign align)

Sets the horizontal alignment of text to align. The default alignment is QCanvasPainter::TextAlign::Start.

See also setTextBaseline().

void QCanvasPainter::setTextAntialias(float antialias)

Set the current text antialiasing amount. The value antialias is multiplier to normal antialiasing, meaning that 0.0 disables antialiasing and 2.0 doubles it. The default value is 1.0.

void QCanvasPainter::setTextBaseline(QCanvasPainter::TextBaseline baseline)

Sets the vertical alignment (baseline) of text to baseline. The default alignment is QCanvasPainter::TextBaseline::Alphabetic.

See also setTextAlign().

void QCanvasPainter::setTextDirection(QCanvasPainter::TextDirection direction)

Sets the direction of text to direction. The default direction is QCanvasPainter::TextDirection::Inherit.

void QCanvasPainter::setTextLineHeight(float height)

Sets the line height adjustment in pixels to height for wrapped text. The default line height is 0.

void QCanvasPainter::setTextWrapMode(QCanvasPainter::WrapMode wrapMode)

Sets the text wrap mode to wrapMode. The default wrap mode is QCanvasPainter::WrapMode::NoWrap.

void QCanvasPainter::skew(float angleX, float angleY = 0.0f)

Skews (shears) the current coordinate system along X axis by angleX and along Y axis by angleY. Angles are specifid in radians.

void QCanvasPainter::stroke()

Strokes the current path with current stroke style.

See also setStrokeStyle().

void QCanvasPainter::stroke(const QCanvasPath &path, int pathGroup = 0)

Strokes the path with current stroke style and belonging into pathGroup. Painting through QCanvasPath is optimal when the path contains more commands is mostly static. By default, pathGroup is 0, so using the first group. When pathGroup is -1, the path will not be cached on GPU side. More information about using path cache groups in QCanvasPath documentation. Calling beginPath() before this method is not required.

See also setStrokeStyle().

void QCanvasPainter::strokeRect(float x, float y, float width, float height)

Draws a stoked rectangle into specified position ( x, y) at size width, height.

void QCanvasPainter::strokeRect(const int &rect)

Draws a stoked rectangle into rect. This is an overloaded method using QRectF.

int QCanvasPainter::textBoundingBox(const int &text, int point, float maxWidth = -1)

Measures bounding box of a text string at point. To measure multi-line text, set optional maxWidth parameter to preferred row width in pixels. Returns QRectF with values [xmin, ymin, width, height]. Measured values are returned in local coordinate space.

void QCanvasPainter::translate(float x, float y)

Translates current coordinate system by x and y.

void QCanvasPainter::translate(int point)

Translates current coordinate system by point.