Canvas

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

Inheritance diagram for Canvas:

Public Member Functions
std::list< Paint * > &	paints () noexcept
	Returns the list of the paints that currently held by the Canvas. More...
virtual Result	push (std::unique_ptr< Paint > paint) noexcept
	Passes drawing elements to the Canvas using Paint objects. More...
virtual Result	clear (bool free=true) noexcept
	Clear the internal canvas resources that used for the drawing. More...
virtual Result	update (Paint *paint=nullptr) noexcept
	Request the canvas to update the paint objects. More...
virtual Result	draw () noexcept
	Requests the canvas to draw the Paint objects. More...
virtual Result	viewport (int32_t x, int32_t y, int32_t w, int32_t h) noexcept
	Sets the drawing region in the canvas. More...
virtual Result	sync () noexcept
	Guarantees that drawing task is finished. More...

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

clear()

virtual Result clear ( bool  free = true )

virtualnoexcept

Clear the internal canvas resources that used for the drawing.

This API sets the total number of paints pushed into the canvas to zero. Depending on the value of the free argument, the paints are either freed or retained. So if you need to update paint properties while maintaining the existing scene structure, you can set free = false.

Parameters

[in]

free

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

See also

Canvas::push()

Canvas::paints()

draw()

virtual Result draw ( )

virtualnoexcept

Requests the canvas to draw the Paint objects.

Note

Drawing can be asynchronous if the assigned thread number is greater than zero. To guarantee the drawing is done, call sync() afterwards.

See also

Canvas::sync()

paints()

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

noexcept

Returns the list of the paints that currently held by the Canvas.

This function provides the list of paint nodes, allowing users a direct opportunity to modify the scene tree.

Warning

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

See also

Canvas::sync()

Note

Experimental API

push()

virtual Result push ( std::unique_ptr< Paint >  paint )

virtualnoexcept

Passes drawing elements to the Canvas using Paint objects.

Only pushed paints in the canvas will be drawing targets. They are retained by the canvas until you call Canvas::clear().

Parameters

[in]

paint

A Paint object to be drawn.

Return values

Result::MemoryCorruption

In case a nullptr is passed as the argument.

Note

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

See also

Canvas::paints()

Canvas::clear()

sync()

virtual Result sync ( )

virtualnoexcept

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.

Return values

Result::InsufficientCondition

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

See also

Canvas::draw()

update()

virtual Result update ( Paint *  paint = nullptr )

virtualnoexcept

Request the canvas to update the paint objects.

If a nullptr is passed all paint objects retained by the Canvas are updated, otherwise only the paint to which the given paint points.

Parameters

[in]

paint

A pointer to the Paint object or nullptr.

Note

The Update behavior can be asynchronous if the assigned thread number is greater than zero.

viewport()

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

virtualnoexcept

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

[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.

See also

SwCanvas::target()

GlCanvas::target()

WgCanvas::target()

Warning

It's not allowed to change the viewport during Canvas::push() - Canvas::sync() or Canvas::update() - Canvas::sync().

Note

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

Since

0.15