PySide6.QtCanvasPainter.QCanvasPath

class QCanvasPath

QCanvasPath is the native path format of QCanvasPainter . More…

Synopsis

Methods

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description

A painter path is an object composed of a number of graphical building blocks, such as rectangles, ellipses, lines, and curves. QCanvasPath API matches to QCanvasPainter path painting, making it easy to adjust code between paintind directly or painting into a path. The main reason use QCanvasPath is to avoid recreating the (static) paths and be able to cache the paths GPU buffers.

Compared to QPainterPath, QCanvasPath is more optimized for rendering with fewer features for comparing or adjusting the paths. In particular:

  • There are no methods for intersection or subtraction between two paths.

  • There is no method for translating the path.

  • There is no method for adding text.

  • The fill rule is always WindingFill (nonzero), OddEvenFill is not supported.

From a functionality point of view, QCanvasPath is more similar to HTML Canvas Path2D , with some additions and the API matching to QCanvasPainter .

Painting paths through QCanvasPath allows the engine to cache the path geometry (vertices). This improves the performance of static paths, while potentially increasing GPU memory consumption.

When painting paths using fill() or stroke() that take QCanvasPath as a parameter, it is possible to set a pathGroup as a second parameter. This defines the GPU buffer where the path is cached. By default, pathGroup is 0, meaning that the first buffer is used. Setting the pathGroup to -1 means that the path does not allocate its own buffer, and the same dynamic buffer is used as with direct painting using beginPath() followed by commands and fill/stroke.

Arranging paths into path groups allows efficient optimization of the rendering performance and the GPU memory usage. Paths that belong together and often change at the same time should be in the same group for optimal buffer usage.

When the path changes, its geometry (vertex buffer) is automatically updated. Things that cause a geometry update of the path group are:

Note that changing the state transform ( transform() , rotate() etc.) does not invalidate the path, so moving/scaling/rotating a cached path is very efficient.

In cases where the path does not need to be painted anymore, or the application should release GPU memory, the cache can be released by calling removePathGroup() . This isn’t usually needed, as the cached paths are automatically released during the painter destructor.

__init__()

Constructs an empty path.

__init__(path)
Parameters:

path – QCanvasPath

Constructs a path that is a copy of the given path.

__init__(commandsSize[, commandsDataSize=-1])
Parameters:

  • commandsSize – int

  • commandsDataSize – int

Constructs an empty path, allocating space for commandsSize amount of commands and optionally commandsDataSize amount of data. If commandsDataSize parameter is not given, space is automatically reserved for 2 * commandsSize amount of data, which is optimal amount when the path commands are straight lines ( moveTo() , lineTo() , rect() ).

Reserving correct space is an optimization for path creation and memory usage. It isn’t mandatory as sufficient space will automatically be ensured while adding commands to the path.

See also

reserve()

addPath(path[, transform=QTransform()])
Parameters:

Adds path into this path, optionally using transform to alter the path points. When transform is not provided (or it is identity matrix), this operation is very fast as it reuses the path data.

addPath(path, start, count[, transform=QTransform()])
Parameters:

Adds path into the current path, starting from the command at start and including count amount of commands. Optionally using transform to alter the path points. The range of start and count is checked, so that commands are not accessed more than commandsSize() . In case the path shouldn’t continue from the current path position, call first moveTo() with path.positionAt(start - 1).

arc(centerPoint, radius, a0, a1[, direction=QCanvasPainter.PathWinding.ClockWise[, connection=QCanvasPainter.PathConnection.Connected]])
Parameters:

Creates an arc centered on centerPoint with the given radius, starting at an angle of a0 radians and ending at a1 radians. The arc spans the given direction. When connection is NotConnected , the previous path is closed and a new sub-path is started.

arc(centerX, centerY, radius, a0, a1[, direction=QCanvasPainter.PathWinding.ClockWise[, connection=QCanvasPainter.PathConnection.Connected]])
Parameters:

  • centerX – float

  • centerY – float

  • radius – float

  • a0 – float

  • a1 – float

  • direction – PathWinding

  • connection – PathConnection

Creates an arc centered on QPointF(centerX, centerY) with the given radius, starting at an angle of a0 radians and ending at a1 radians. The arc spans the given direction. When connection is NotConnected , the previous path is closed and a new sub-path is started.

arcTo(controlPoint1, controlPoint2, radius)
Parameters:

  • controlPoint1 – QPointF

  • controlPoint2 – QPointF

  • radius – float

Creates an arc using the points point1 and point2 with the given radius.

arcTo(c1x, c1y, c2x, c2y, radius)
Parameters:

  • c1x – float

  • c1y – float

  • c2x – float

  • c2y – float

  • radius – float

Creates an arc using the points QPointF(x1, y1) and QPointF(x2, y2) with the given radius.

beginHoleSubPath()

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

beginSolidSubPath()

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

bezierCurveTo(controlPoint1, controlPoint2, endPoint)
Parameters:

Adds a cubic Bezier curve between the current position and the given endPoint using the control points specified by controlPoint1, and controlPoint2.

After the curve is added, the current position is updated to be at the end point of the curve.

bezierCurveTo(c1x, c1y, c2x, c2y, x, y)
Parameters:

  • c1x – float

  • c1y – float

  • c2x – float

  • c2y – float

  • x – float

  • y – float

Adds a cubic Bezier curve between the current position and the end point specified by x and y, using the control points specified by cp1X, cp1Y, cp2X, and cp2Y.

After the curve is added, the current position is updated to be at the end point of the curve.

circle(centerPoint, radius)
Parameters:

  • centerPoint – QPointF

  • radius – float

Adds a circle with center at centerPoint and the given radius to the path.

circle(x, y, radius)
Parameters:

  • x – float

  • y – float

  • radius – float

Adds a circle with center at QPointF(x, y) and the given radius to the path.

clear()

Clears the path commands and data.

Call this when the path commands change to recreate the path. This does not affect the memory usage, use reserve() and squeeze() for that.

See also

reserve() squeeze()

closePath()

Closes the current subpath by drawing a line to the beginning of the subpath, automatically starting a new path.

commandsCapacity()
Return type:

int

Returns the capacity of commands in the path.

commandsDataCapacity()
Return type:

int

Returns the capacity of commands data in the path.

commandsDataSize()
Return type:

int

Returns the amount of commands data in the path.

Commands data basically means the points required by the commands.

Note

Some path elements require several data points. For example closePath requires 0, moveTo and lineTo require 2, bezierCurveTo requires 6 and roundRect requires 34 data points.

commandsSize()
Return type:

int

Returns the amount of commands in the path.

Note

Some path elements require several commands. For example moveTo and lineTo require 1 command, bezierCurveTo requires 6 commands and roundRect 10 commands.

currentPosition()
Return type:

QPointF

Returns the current position of the path. This means position where previous path command ( moveTo , lineTo , bezierCurveTo etc.) has ended. When the path is empty, returns (0.0, 0.0).

ellipse(rect)
Parameters:

rect – QRectF

Creates an ellipse within the rectangle rect and adds it to the path as a closed subpath.

ellipse(x, y, radiusX, radiusY)
Parameters:

  • x – float

  • y – float

  • radiusX – float

  • radiusY – float

Creates an ellipse centered at (x, y), with radii defined by radiusX, radiusY and adds it to the path as a closed subpath.

isEmpty()
Return type:

bool

Returns true when the path is empty.

See also

clear

lineTo(point)
Parameters:

point – QPointF

Adds a straight line from the current position to the given point. After the line is drawn, the current position is updated to be at the end point of the line.

lineTo(x, y)
Parameters:

  • x – float

  • y – float

Draws a line from the current position to the point (x, y).

moveTo(point)
Parameters:

point – QPointF

Moves the current point to the given point, implicitly starting a new subpath and closing the previous one.

moveTo(x, y)
Parameters:

  • x – float

  • y – float

Moves the current position to (x, y) and starts a new subpath, implicitly closing the previous path.

__ne__(rhs)
Parameters:

rhs – QCanvasPath

Return type:

bool

__eq__(rhs)
Parameters:

rhs – QCanvasPath

Return type:

bool

positionAt(index)
Parameters:

index – int

Return type:

QPointF

Returns the position of the path at index. This means position where path command ( moveTo , lineTo , bezierCurveTo etc.) is at index. The index need to be between 0 and commandsSize() - 1. When the path is empty, returns (0.0, 0.0).

quadraticCurveTo(controlPoint, endPoint)
Parameters:

Adds a quadratic Bezier curve between the current position and the given endPoint with the control point specified by controlPoint.

quadraticCurveTo(cx, cy, x, y)
Parameters:

  • cx – float

  • cy – float

  • x – float

  • y – float

Adds a quadratic Bezier curve between the current point and the endpoint (x, y) with the control point specified by (cpX, cpY).

rect(rect)
Parameters:

rect – QRectF

Creates a rectangle specified by rect

rect(x, y, width, height)
Parameters:

  • x – float

  • y – float

  • width – float

  • height – float

Creates a rectangle positioned at QPointF(x, y) with the given width and height.

reserve(commandsSize)
Parameters:

commandsSize – int

Reserves a given amounts of space in QCanvasPath ‘s internal memory.

Attempts to allocate memory for at least commandsSize commands. Some path elements require multiple commands, see commandsSize() and commandsDataSize() .

Space is automatically reserved for 2 * commandsSize amount of data, which is optimal amount when the path commands are straight lines ( moveTo() , lineTo() , rect() ).

Reserving correct space is an optimization for path creation and memory usage. It isn’t mandatory as sufficient space will automatically be ensured while adding commands into the path.

reserve(commandsSize, commandsDataSize)
Parameters:

  • commandsSize – int

  • commandsDataSize – int

Reserves a given amounts of space in QCanvasPath ‘s internal memory.

Attempts to allocate memory for at least commandsSize commands and commandsDataSize data points. Some path elements require multiple commands, see commandsSize() and commandsDataSize() .

Reserving correct space is an optimization for path creation and memory usage. It isn’t mandatory as sufficient space will automatically be ensured while adding commands into the path.

roundRect(rect, radius)
Parameters:

  • rect – QRectF

  • radius – float

Adds the given rectangle rect with rounded corners to the path. The corners are quarter circles with the given radius.

roundRect(rect, radiusTopLeft, radiusTopRight, radiusBottomRight, radiusBottomLeft)
Parameters:

  • rect – QRectF

  • radiusTopLeft – float

  • radiusTopRight – float

  • radiusBottomRight – float

  • radiusBottomLeft – float

Adds the rectangle rect with rounded corners to the path. The corners are quarter circles with radius radiusTopLeft, radiusTopRight radiusBottomRight and radiusBottomLeft, respectively.

roundRect(x, y, width, height, radius)
Parameters:

  • x – float

  • y – float

  • width – float

  • height – float

  • radius – float

Adds the given rectangle x, y, width, height with rounded corners to the path. The corners are quarter circles with the given radius.

roundRect(x, y, width, height, radiusTopLeft, radiusTopRight, radiusBottomRight, radiusBottomLeft)
Parameters:

  • x – float

  • y – float

  • width – float

  • height – float

  • radiusTopLeft – float

  • radiusTopRight – float

  • radiusBottomRight – float

  • radiusBottomLeft – float

Adds the rectangle x, y, width, height with rounded corners to the path. The corners are quarter circles with radius radiusTopLeft, radiusTopRight radiusBottomRight and radiusBottomLeft, respectively.

setPathWinding(winding)
Parameters:

winding – PathWinding

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

sliced(start, count[, transform=QTransform()])
Parameters:

  • start – int

  • count – int

  • transform – QTransform

Return type:

QCanvasPath

Returns a new path containing the commands from this path, starting from the command at start and including count amount of commands, optionally using transform to alter the path points.

The range of start and count is checked, so that commands are not accessed more than commandsSize() . In case the command at start is not MoveTo, the first command will be replaced with MoveTo so that this slice is an individual path.

squeeze()

Releases any memory not required to store the path commands and data. This can be used to reduce the memory usage after calling the reserve() .

Normally this is not needed to be used, but it can be useful when the path size has been big due to reserving or adding many elements ( lineTo , bezierCurveTo etc.) and then size is expected to be much smaller in future so calling first reserve() and then squeeze(), will release some memory.

See also

reserve()

swap(other)
Parameters:

other – QCanvasPath

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