Canvas

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

Inheritance diagram for Canvas:

Public Member Functions
Result	reserve (uint32_t n) noexcept
	Sets the size of the container, where all the paints pushed into the Canvas are stored. 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
	Sets the total number of the paints pushed into the canvas to be zero. Depending on the value of the free argument, the paints are freed or not. 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

Sets the total number of the paints pushed into the canvas to be zero. Depending on the value of the free argument, the paints are freed or not.

Parameters

[in]

free

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

Returns

Result::Success when succeed, Result::InsufficientCondition otherwise.

Warning

If you don't free the paints they become dangled. They are supposed to be reused, otherwise you are responsible for their lives. Thus please use the free argument only when you know how it works, otherwise it's not recommended.

draw()

virtual Result draw ( )

virtualnoexcept

Requests the canvas to draw the Paint objects.

Returns

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

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(). If you know the number of the pushed objects in advance, please call Canvas::reserve().

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

Canvas::clear()

reserve()

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.

Returns

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.

Returns

Result::Success when succeed, Result::InsufficientCondition otherwise.

Note

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