thorvg_python.canvas¶

class thorvg_python.canvas.Canvas(engine: Engine, canvas: CanvasStruct)¶

Bases: object

Common Canvas API

A module for managing and drawing graphical elements.

A canvas is an entity responsible for drawing the target. It sets up the drawing engine and the buffer, which can be drawn on the screen. It also manages given Paint objects.

Note

A Canvas behavior depends on the raster engine though the final content of the buffer is expected to be identical.

Warning

The Paint objects belonging to one Canvas can’t be shared among multiple Canvases.

This is base Canvas class. Please instantiate SwCanvas, GlCanvas or WgCanvas instead

clear(free: bool) → Result¶

Sets the total number of the paints pushed into the canvas to be zero. PaintStruct objects stored in the canvas are released if free is set to true, otherwise the memory is not deallocated and all paints should be released manually in order to avoid memory leaks.

Parameters:¶

free : bool¶

If true the memory occupied by paints is deallocated, otherwise it is not.

Returns:¶

INVALID_ARGUMENT An invalid CanvasStruct pointer.

Return type:¶

Result

See also

Canvas.destroy()

destroy() → Result¶

Clears the canvas internal data, releases all paints stored by the canvas and destroys the canvas object itself.

Returns:¶

INVALID_ARGUMENT An invalid pointer to the CanvasStruct object is passed.

Return type:¶

Result

Note

If the paints from the canvas should not be released, the tvg_canvas_clear() with a free argument value set to false should be called. Please be aware that in such a case TVG is not responsible for the paints release anymore and it has to be done manually in order to avoid memory leaks.

See also

Paint.del(), Canvas.clear()

draw() → Result¶

Requests the canvas to draw the PaintStruct objects.

All paints from the given canvas will be rasterized to the buffer.

Returns:¶

INVALID_ARGUMENT An invalid CanvasStruct pointer.

Return type:¶

Result

Note

Drawing can be asynchronous based on the assigned thread number. To guarantee the drawing is done, call Canvas.sync() afterwards.

See also

Canvas.sync()

push(paint: Paint) → Result¶

Inserts a drawing element into the canvas using a PaintStruct object.

Parameters:¶

paint : Paint¶

The Paint object to be drawn.

Only the paints pushed into the canvas will be drawing targets. They are retained by the canvas until you call tvg_canvas_clear().

Returns:¶

• INVALID_ARGUMENT In case a nullptr is passed as the argument.

• INSUFFICIENT_CONDITION An internal error.

Return type:¶

Result

Note

The rendering order of the paints is the same as the order as they were pushed. Consider sorting the paints before pushing them if you intend to use layering.

See also

Canvas.clear()

reserve(n: int) → Result¶

Reserves a memory block where the objects pushed into a canvas are stored.

If the number of PaintStructs to be stored in a canvas is known in advance, calling this function reduces the multiple memory allocations thus improves the performance.

Parameters:¶

n : int¶

The number of objects for which the memory is to be reserved.

Returns:¶

INVALID_ARGUMENT An invalid CanvasStruct pointer.

Return type:¶

Result

Deprecated since version 0.10.

Note

Malfunctional

set_viewport(x: int, y: int, w: int, h: int) → Result¶

Sets the drawing region in the canvas.

This function defines the rectangular area of the canvas that will be used for drawing operations. The specified viewport is used to clip the rendering output to the boundaries of the rectangle.

Parameters:¶

x : int¶

The x-coordinate of the upper-left corner of the rectangle.

y : int¶

The y-coordinate of the upper-left corner of the rectangle.

w : int¶

The width of the rectangle.

h : int¶

The height of the rectangle.

Returns:¶

Result enumeration.

Return type:¶

Result

Warning

It’s not allowed to change the viewport during tvg_canvas_update() - tvg_canvas_sync() or tvg_canvas_push() - tvg_canvas_sync().

Note

When resetting the target, the viewport will also be reset to the target size.

See also

SwCanvas.set_target()

Added in version 0.15.

sync() → Result¶

Guarantees that the drawing process is finished.

Since the canvas rendering can be performed asynchronously, it should be called after the Canvas.draw().

Returns:¶

• INVALID_ARGUMENT An invalid CanvasStruct pointer.

• INSUFFICIENT_CONDITION canvas is either already in sync condition or in a damaged condition (a draw is required before syncing).

Return type:¶

Result

See also

Canvas.draw()

update() → Result¶

Updates all paints in a canvas.

Should be called before drawing in order to prepare paints for the rendering.

Returns:¶

INVALID_ARGUMENT An invalid CanvasStruct pointer.

Return type:¶

Result

See also

Canvas.update_paint()

update_paint(paint: Paint) → Result¶

Updates the given PaintStruct object from the canvas before the rendering.

If a client application using the TVG library does not update the entire canvas with Canvas.update() in the frame rendering process, PaintStruct objects previously added to the canvas should be updated manually with this function.

Parameters:¶

paint : PaintStruct¶

The PaintStruct object to be updated.

Returns:¶

INVALID_ARGUMENT In case a nullptr is passed as the argument.

Return type:¶

Result

See also

Canvas.update()