Scene

A class to composite children paints. More...

Inheritance diagram for Scene:

Collaboration diagram for Scene:

Public Member Functions
Result	push (std::unique_ptr< Paint > paint) noexcept
	Passes drawing elements to the Scene using Paint objects. More...
TVG_DEPRECATED Result	reserve (uint32_t size) noexcept
	Sets the size of the container, where all the paints pushed into the Scene are stored. More...
std::list< Paint * > &	paints () noexcept
	Returns the list of the paints that currently held by the Scene. More...
Result	clear (bool free=true) noexcept
	Sets the total number of the paints pushed into the scene to be zero. Depending on the value of the free argument, the paints are freed or not. More...
Public Member Functions inherited from Paint
Result	rotate (float degree) noexcept
	Sets the angle by which the object is rotated. More...
Result	scale (float factor) noexcept
	Sets the scale value of the object. More...
Result	translate (float x, float y) noexcept
	Sets the values by which the object is moved in a two-dimensional space. More...
Result	transform (const Matrix &m) noexcept
	Sets the matrix of the affine transformation for the object. More...
Matrix	transform () noexcept
	Gets the matrix of the affine transformation of the object. More...
Result	opacity (uint8_t o) noexcept
	Sets the opacity of the object. More...
Result	composite (std::unique_ptr< Paint > target, CompositeMethod method) noexcept
	Sets the composition target object and the composition method. More...
Result	blend (BlendMethod method) const noexcept
	Sets the blending method for the paint object. More...
TVG_DEPRECATED Result	bounds (float *x, float *y, float *w, float *h) const noexcept
	Gets the bounding box of the paint object before any transformation. More...
Result	bounds (float *x, float *y, float *w, float *h, bool transformed) const noexcept
	Gets the axis-aligned bounding box of the paint object. More...
Paint *	duplicate () const noexcept
	Duplicates the object. More...
uint8_t	opacity () const noexcept
	Gets the opacity value of the object. More...
CompositeMethod	composite (const Paint **target) const noexcept
	Gets the composition target object and the composition method. More...
BlendMethod	blend () const noexcept
	Gets the blending method of the object. More...
uint32_t	identifier () const noexcept
	Return the unique id value of the paint instance. More...

Static Public Member Functions
static std::unique_ptr< Scene >	gen () noexcept
	Creates a new Scene object. More...
static uint32_t	identifier () noexcept
	Return the unique id value of this class. More...

Detailed Description

A class to composite children paints.

As the traditional graphics rendering method, TVG also enables scene-graph mechanism. This feature supports an array function for managing the multiple paints as one group paint.

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

Member Function Documentation

clear()

Result clear ( bool  free = true )

noexcept

Sets the total number of the paints pushed into the scene 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

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.

Since

0.2

gen()

static std::unique_ptr<Scene> gen ( )

staticnoexcept

Creates a new Scene object.

Returns

A new Scene object.

identifier()

static uint32_t identifier ( )

staticnoexcept

Return the unique id value of this class.

This method can be referred for identifying the Scene class type.

Returns

The type id of the Scene class.

paints()

std::list<Paint*>& paints ( )

noexcept

Returns the list of the paints that currently held by the Scene.

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 Scene update/draw. You can access them after calling Canvas::sync().

See also

Canvas::sync()

Scene::push()

Scene::clear()

@BETA_API

push()

Result push ( std::unique_ptr< Paint >  paint )

noexcept

Passes drawing elements to the Scene using Paint objects.

Only the paints pushed into the scene will be the drawn targets. The paints are retained by the scene until Scene::clear() is called.

Parameters

[in]

paint

A Paint object to be drawn.

Returns

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

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

Scene::paints()

Scene::clear()

reserve()

TVG_DEPRECATED Result reserve ( uint32_t  size )

noexcept

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]

size

The number of objects for which the memory is to be reserved.

Returns

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