| ThorVG v0.8

Functions
Scene
ThorVG_CAPI

A module managing the multiple paints as one group paint. More...

Collaboration diagram for Scene:

## Functions
TVG_EXPORT Tvg_Paint * | tvg_scene_new ()
| Creates a new scene object. More...
TVG_EXPORT Tvg_Result | tvg_scene_reserve (Tvg_Paint *scene, uint32_t size)
| Sets the size of the container, where all the paints pushed into the scene are stored. More...
TVG_EXPORT Tvg_Result | tvg_scene_push (Tvg_Paint *scene, Tvg_Paint *paint)
| Passes drawing elements to the scene using Tvg_Paint objects. More...
TVG_EXPORT Tvg_Result | tvg_scene_clear (Tvg_Paint *scene, bool free)
| Clears a Tvg_Scene objects from pushed paints. More...

## Detailed Description

A module managing the multiple paints as one group paint.

As a group, scene can be transformed, translucent, composited with other target paints, its children will be affected by the scene world.

## Function Documentation

## ◆ tvg_scene_clear()

TVG_EXPORT Tvg_Result tvg_scene_clear | ( | Tvg_Paint * | scene,
|  | bool | free
| ) |  |

Clears a Tvg_Scene objects from pushed paints.

Tvg_Paint objects stored in the scene are released if `free` is set to `true`, otherwise the memory is not deallocated and all paints should be released manually in order to avoid memory leaks.

Parameters

  [in] | scene | The Tvg_Scene object to be cleared.
  [in] | free | If `true` the memory occupied by paints is deallocated, otherwise it is not.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | An invalid Tvg_Canvas pointer.

Warning
  Please use the `free` argument only when you know how it works, otherwise it's not recommended.

## ◆ tvg_scene_new()

TVG_EXPORT Tvg_Paint* tvg_scene_new | ( |  | ) |

Creates a new scene object.

A scene object is used to group many paints into one object, which can be manipulated using TVG APIs.

Returns
  A new scene object.

## ◆ tvg_scene_push()

TVG_EXPORT Tvg_Result tvg_scene_push | ( | Tvg_Paint * | scene,
|  | Tvg_Paint * | paint
| ) |  |

Passes drawing elements to the scene using Tvg_Paint objects.

Only the paints pushed into the scene will be the drawn targets. The paints are retained by the scene until the tvg_scene_clear() is called. If you know the number of pushed objects in advance, please call tvg_scene_reserve().

Parameters

  [in] | scene | A Tvg_Paint pointer to the scene object.
  [in] | paint | A graphical object to be drawn.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_INVALID_ARGUMENT | A `nullptr` passed as the argument.
  TVG_RESULT_MEMORY_CORRUPTION | An internal error.

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

See also
  tvg_scene_reserve()

## ◆ tvg_scene_reserve()

TVG_EXPORT Tvg_Result tvg_scene_reserve | ( | Tvg_Paint * | scene,
|  | uint32_t | size
| ) |  |

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

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

Parameters

  [in] | scene | A Tvg_Paint pointer to the scene object.
  [in] | size | The number of objects for which the memory is to be reserved.

Returns
  Tvg_Result enumeration.

Return values

  TVG_RESULT_SUCCESS | Succeed.
  TVG_RESULT_FAILED_ALLOCATION | An internal error with a memory allocation.
  TVG_RESULT_INVALID_ARGUMENT | An invalid Tvg_Paint pointer.