An abstract class for drawing graphical elements. More...

#include <thorvg.h>

Inheritance diagram for Canvas:

[legend]

Public Member Functions
const std::list< Paint * > &	paints () const noexcept
	Returns the list of paints currently held by the Canvas.

Result	push (Paint target, Paint at=nullptr) noexcept
	Adds a paint object to the root scene.

Result	remove (Paint *paint=nullptr) noexcept
	Removes a paint object or all paint objects from the root scene.

Result	update () noexcept
	Requests the canvas to update modified paint objects in preparation for rendering.

Result	draw (bool clear=false) noexcept
	Requests the canvas to render the Paint objects.

Result	viewport (int32_t x, int32_t y, int32_t w, int32_t h) noexcept
	Sets the drawing region of the canvas.

Result	sync () noexcept
	Guarantees that drawing task is finished.

Detailed Description

An abstract class for 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.

Member Function Documentation

◆ draw()

Result draw ( bool clear = false )

noexcept

Requests the canvas to render the Paint objects.

Parameters

[in] clear If true, clears the target buffer to zero before drawing.

Return values

Result::InsufficientCondition The canvas is not properly prepared. This may occur if Canvas::target() has not been set or if draw() is called multiple times without calling Canvas::sync() in between.

Note: Clearing the buffer is unnecessary if the canvas will be fully covered with opaque content. Skipping the clear can improve performance.; Drawing may be performed asynchronously if the thread count is greater than zero. To ensure the drawing process is complete, call sync() afterwards.; If the canvas has not been updated prior to Canvas::draw(), it may implicitly perform Canvas::update().

See also: Canvas::sync(); Canvas::update()

◆ paints()

const std::list< Paint * > & paints ( ) const

noexcept

Returns the list of paints currently held by the Canvas.

This function provides a list of paint nodes, allowing users to access scene-graph information.

Warning: Please avoid accessing the paints during Canvas update/draw. You can access them after calling sync().

See also: Canvas::push(); Canvas::remove()

Warning: This is read-only. Do not modify the list.

Note: 1.0

◆ push()

Result push	(	Paint *	target,
		Paint *	at = `nullptr`
	)

noexcept

Adds a paint object to the root scene.

This function appends a paint object to root scene of the canvas. If the optional at is provided, the new paint object will be inserted immediately before the specified paint object in the root scene. If at is nullptr, the paint object will be added to the end of the root scene.

Parameters

[in]	target	A pointer to the Paint object to be added into the root scene. This parameter must not be `nullptr`.
[in]	at	A pointer to an existing Paint object in the root scene before which the new paint object will be added. If `nullptr`, the new paint object is added to the end of the root scene. The default is `nullptr`.

Note: The ownership of the paint object is transferred to the canvas upon addition.; 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::paints(); Canvas::remove()

◆ remove()

Result remove ( Paint * paint = nullptr )

noexcept

Removes a paint object or all paint objects from the root scene.

This function removes a specified paint object from the root scene. If no paint object is specified (i.e., the default nullptr is used), the function performs to clear all paints from the root scene.

Parameters

[in] paint A pointer to the Paint object to be removed from the root scene. If nullptr, remove all the paints from the root scene.

See also: Canvas::push(); Canvas::paints()

Since: 1.0

◆ sync()

Result sync ( )

noexcept

Guarantees that drawing task is finished.

The Canvas rendering can be performed asynchronously. To make sure that rendering is finished, the sync() must be called after the draw() regardless of threading.

See also: Canvas::draw()

◆ update()

Result update ( )

noexcept

Requests the canvas to update modified paint objects in preparation for rendering.

This function triggers an internal update for all paint instances that have been modified since the last update. It ensures that the canvas state is ready for accurate rendering.

Return values

Result::InsufficientCondition The canvas is not properly prepared. This may occur if the canvas target has not been set or if the update is called during drawing. Call Canvas::sync() before trying.

Note: Only paint objects that have been changed will be processed.; If the canvas is configured with multiple threads, the update may be performed asynchronously.

See also: Canvas::sync()

◆ viewport()

Result viewport	(	int32_t	x,
		int32_t	y,
		int32_t	w,
		int32_t	h
	)

noexcept

Sets the drawing region of the canvas.

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

Please note that changing the viewport is only allowed at the beginning of the rendering sequence—that is, after calling Canvas::sync().

Parameters

[in]	x	The x-coordinate of the upper-left corner of the rectangle.
[in]	y	The y-coordinate of the upper-left corner of the rectangle.
[in]	w	The width of the rectangle.
[in]	h	The height of the rectangle.

Return values

Result::InsufficientCondition If the canvas is not in a synced state.

See also: Canvas::sync(); SwCanvas::target(); GlCanvas::target(); WgCanvas::target()

Warning: Changing the viewport is not allowed after calling Canvas::push(), Canvas::remove(), Canvas::update(), or Canvas::draw().

Note: When the target is reset, the viewport will also be reset to match the target size.

Since: 0.15

Public Member Functions

Detailed Description

Member Function Documentation

◆ draw()

◆ paints()

◆ push()

◆ remove()

◆ sync()

◆ update()

◆ viewport()