Canvas

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

Inheritance diagram for Canvas:

Public Member Functions
TVG_DEPRECATED Result	reserve (uint32_t n) noexcept
	Sets the size of the container, where all the paints pushed into the Canvas are stored. More...
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	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.

Return values

Result::Success

when succeed, Result::InsufficientCondition otherwise.

See also

Canvas::push()

Canvas::paints()

draw()

virtual Result draw ( )

virtualnoexcept

Requests the canvas to draw the Paint objects.

Return values

Result::Success

when succeed, Result::InsufficientCondition otherwise.

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::Success	When succeed.
Result::MemoryCorruption	In case a nullptr is passed as the argument.
Result::InsufficientCondition	An internal error.

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()

reserve()

TVG_DEPRECATED Result reserve ( uint32_t  n )

noexcept

Sets the size of the container, where all the paints pushed into the Canvas are stored.

If the number of objects pushed into the Canvas is known in advance, calling the function prevents multiple memory reallocation, thus improving the performance.

Parameters

[in]

n

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

Returns

Result::Success when succeed.

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::Success

when succeed, Result::InsufficientCondition otherwise.

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.

Return values

Result::Success

when succeed, Result::InsufficientCondition otherwise.

Note

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