Canvas
ThorVG

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

Inheritance diagram for Canvas:
[legend]

## 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) noexcept
| Request the canvas to update the paint objects. More...
virtual Result | draw () noexcept
| Request 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

Request 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 the 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() should be called after the draw().

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

See also
  Canvas::draw()

## update()

virtual Result update | ( | Paint * | paint | ) |

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.