# ThorVG: Canvas

Canvas
ThorVG

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

Inheritance diagram for Canvas:
[legend]

## 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