Scene

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.