#include <CUScene.h>

Public Member Functions
	Scene ()

	~Scene ()

void	dispose ()

bool	init (const Size &size)

bool	init (float width, float height)

bool	init (const Rect &rect)

bool	init (const Vec2 &origin, const Size &size)

bool	init (float x, float y, float width, float height)

const std::string &	getName () const

void	setName (const std::string &name)

std::shared_ptr< Camera >	getCamera ()

const std::shared_ptr< Camera >	getCamera () const

Color4	getColor ()

void	setColor (Color4 color)

virtual std::string	toString (bool verbose=false) const

	operator std::string () const

void	setSize (const Size &size)

void	setSize (float width, float height)

void	setWidth (float width)

void	setHeight (float height)

void	setBounds (const Rect &rect)

void	setBounds (const Vec2 &origin, const Size &size)

void	setBounds (float x, float y, float width, float height)

void	setOffset (const Vec2 &origin)

Vec3	screenToWorldCoords (const Vec2 &screenCoords) const

Vec2	worldToScreenCoords (const Vec3 &worldCoords) const

size_t	getChildCount () const

std::shared_ptr< Node >	getChild (unsigned int pos)

const std::shared_ptr< Node > &	getChild (unsigned int pos) const

template<typename T >
std::shared_ptr< T >	getChild (unsigned int pos) const

std::shared_ptr< Node >	getChildByTag (unsigned int tag) const

template<typename T >
std::shared_ptr< T >	getChildByTag (unsigned int tag) const

std::shared_ptr< Node >	getChildByName (const std::string &name) const

template<typename T >
std::shared_ptr< T >	getChildByName (const std::string &name) const

std::vector< std::shared_ptr< Node > >	getChildren ()

const std::vector< std::shared_ptr< Node > > &	getChildren () const

void	addChild (std::shared_ptr< Node > child)

virtual void	addChild (const std::shared_ptr< Node > &child, int zval)

void	addChildWithTag (const std::shared_ptr< Node > &child, unsigned int tag)

void	addChildWithTag (const std::shared_ptr< Node > &child, unsigned int tag, int zval)

void	addChildWithName (const std::shared_ptr< Node > &child, const std::string &name)

void	addChildWithName (const std::shared_ptr< Node > &child, const std::string &name, int zval)

void	swapChild (const std::shared_ptr< Node > &child1, const std::shared_ptr< Node > &child2, bool inherit=false)

virtual void	removeChild (unsigned int pos)

void	removeChild (const std::shared_ptr< Node > &child)

void	removeChildByTag (unsigned int tag)

void	removeChildByName (const std::string &name)

virtual void	removeAllChildren ()

bool	isZAutoSort ()

void	setZAutoSort (bool value)

bool	isZDirty () const

void	sortZOrder ()

void	render (const std::shared_ptr< SpriteBatch > &batch)

Static Public Member Functions
static std::shared_ptr< Scene >	alloc (const Size &size)

static std::shared_ptr< Scene >	alloc (float width, float height)

static std::shared_ptr< Scene >	alloc (const Rect &rect)

static std::shared_ptr< Scene >	alloc (const Vec2 &origin, const Size &size)

static std::shared_ptr< Scene >	alloc (float x, float y, float width, float height)

Protected Attributes
std::string	_name

std::shared_ptr< OrthographicCamera >	_camera

std::vector< std::shared_ptr< Node > >	_children

Color4	_color

bool	_zDirty

bool	_zSort

Friends
class	Node

Detailed Description

This class provides the root node of a scene graph.

The Scene class is very similar to Node and shares many methods in common. The major differences are that it has no parent and it has no position (so it cannot be transformed). Instead, the Scene is defined by an attached OrthographicCamera.

Rendering happens by traversing the the scene graph using an "Pre-Order" tree traversal algorithm ( https://en.wikipedia.org/wiki/Tree_traversal#Pre-order ). That means that parents are always draw before (and behind children). The children of each sub tree are ordered by z-value (or by the order added).

Constructor & Destructor Documentation

cugl::Scene::Scene ( )

Creates a new degenerate Scene on the stack.

The scene has no camera and must be initialized.

NEVER USE A CONSTRUCTOR WITH NEW. If you want to allocate an object on the heap, use one of the static constructors instead.

cugl::Scene::~Scene ( )

inline

Deletes this scene, disposing all resources

Member Function Documentation

void cugl::Scene::addChild ( std::shared_ptr< Node > child )

inline

Adds a child to this scene.

Children are not necessarily enumerated in the order that they are added. For example, they may be resorted by their z-order. Hence you should generally attempt to retrieve a child by tag or by name instead.

Parameters

child A child node.

virtual void cugl::Scene::addChild	(	const std::shared_ptr< Node > &	child,
		int	zval
	)

virtual

Adds a child to this scene with the given z-order.

Children are not necessarily enumerated in the order that they are added. For example, they may be resorted by their z-order. Hence you should generally attempt to retrieve a child by tag or by name instead.

The z-order overrides what z-value was previously in the child node.

Parameters

child	A child node.
zval	The (new) child z-order.

void cugl::Scene::addChildWithName	(	const std::shared_ptr< Node > &	child,
		const std::string &	name
	)

inline

Adds a child to this scene with the given name.

Children are not necessarily enumerated in the order that they are added. For example, they may be resorted by their z-order. Hence you should generally attempt to retrieve a child by tag or by name instead.

Parameters

child	A child node.
name	A string to identify the node.

void cugl::Scene::addChildWithName	(	const std::shared_ptr< Node > &	child,
		const std::string &	name,
		int	zval
	)

inline

Adds a child to this scene with the given name and z-order

Children are not necessarily enumerated in the order that they are added. For example, they may be resorted by their z-order. Hence you should generally attempt to retrieve a child by tag or by name instead.

The z-order overrides what z-value was previously in the child node.

Parameters

child	A child node.
name	A string to identify the node.
zval	The (new) child z-order.

void cugl::Scene::addChildWithTag	(	const std::shared_ptr< Node > &	child,
		unsigned int	tag
	)

inline

Adds a child to this scene with the given tag.

Children are not necessarily enumerated in the order that they are added. For example, they may be resorted by their z-order. Hence you should generally attempt to retrieve a child by tag or by name instead.

Parameters

child	A child node.
tag	An integer to identify the node easily.

void cugl::Scene::addChildWithTag	(	const std::shared_ptr< Node > &	child,
		unsigned int	tag,
		int	zval
	)

inline

Adds a child to this scene with the given tag and z-order

Children are not necessarily enumerated in the order that they are added. For example, they may be resorted by their z-order. Hence you should generally attempt to retrieve a child by tag or by name instead.

The z-order overrides what z-value was previously in the child node.

Parameters

child	A child node.
tag	An integer to identify the node easily.
zval	The (new) child z-order.

static std::shared_ptr<Scene> cugl::Scene::alloc ( const Size & size )

inlinestatic

Returns a newly allocated Scene for the given viewport.

The viewport origin is assumed to be (0,0).

Parameters

size	The viewport size

Returns: a newly allocated Scene for the given viewport.

static std::shared_ptr<Scene> cugl::Scene::alloc	(	float	width,
		float	height
	)

inlinestatic

Returns a newly allocated Scene for the given viewport.

The viewport origin is assumed to be (0,0).

Parameters

width	The viewport width
height	The viewport height

Returns: a newly allocated Scene for the given viewport.

static std::shared_ptr<Scene> cugl::Scene::alloc ( const Rect & rect )

inlinestatic

Returns a newly allocated Scene for the given viewport.

Offseting the viewport origin has little affect on the Scene in general. It only affects the coordinate conversion methods Camera#project() and Camera#unproject(). It is supposed to represent the offset

Parameters

rect	The viewport bounding box

Returns: a newly allocated Scene for the given viewport.

static std::shared_ptr<Scene> cugl::Scene::alloc	(	const Vec2 &	origin,
		const Size &	size
	)

inlinestatic

Returns a newly allocated Scene for the given viewport.

Offseting the viewport origin has little affect on the Scene in general. It only affects the coordinate conversion methods Camera#project() and Camera#unproject(). It is supposed to represent the offset

Parameters

origin	The viewport offset
size	The viewport size

Returns: a newly allocated Scene for the given viewport.

static std::shared_ptr<Scene> cugl::Scene::alloc	(	float	x,
		float	y,
		float	width,
		float	height
	)

inlinestatic

Returns a newly allocated Scene for the given viewport.

Offseting the viewport origin has little affect on the Scene in general. It only affects the coordinate conversion methods Camera#project() and Camera#unproject(). It is supposed to represent the offset

Parameters

x	The viewport x offset
y	The viewport y offset
width	The viewport width
height	The viewport height

Returns: a newly allocated Scene for the given viewport.

void cugl::Scene::dispose ( )

Disposes all of the resources used by this scene.

A disposed Scene can be safely reinitialized. Any children owned by this scene will be released. They will be deleted if no other object owns them.

std::shared_ptr<Camera> cugl::Scene::getCamera ( )

Returns the camera for this scene.

Returns: the camera for this scene.

const std::shared_ptr<Camera> cugl::Scene::getCamera ( ) const

Returns the camera for this scene.

Returns: the camera for this scene.

std::shared_ptr<Node> cugl::Scene::getChild ( unsigned int pos )

Returns the child at the given position.

Children are not necessarily enumerated in the order that they are added. For example, they may be resorted by their z-order. Hence you should generally attempt to retrieve a child by tag or by name instead.

Parameters

pos	The child position.

Returns: the child at the given position.

const std::shared_ptr<Node>& cugl::Scene::getChild ( unsigned int pos ) const

Returns the child at the given position.

Children are not necessarily enumerated in the order that they are added. For example, they may be resorted by their z-order. Hence you should generally attempt to retrieve a child by tag or by name instead.

Parameters

pos	The child position.

Returns: the child at the given position.

template<typename T >

std::shared_ptr<T> cugl::Scene::getChild ( unsigned int pos ) const

inline

Returns the child at the given position, typecast to a shared T pointer.

This method is provided to simplify the polymorphism of a scene graph. While all children are a subclass of type Node, you may want to access them by their specific subclass. If the child is not an instance of type T (or a subclass), this method returns nullptr.

Children are not necessarily enumerated in the order that they are added. For example, they may be resorted by their z-order. Hence you should generally attempt to retrieve a child by tag or by name instead.

Parameters

pos	The child position.

Returns: the child at the given position, typecast to a shared T pointer.

std::shared_ptr<Node> cugl::Scene::getChildByName ( const std::string & name ) const

Returns the (first) child with the given name.

If there is more than one child of the given name, it returns the first one that is found. Children are not necessarily enumerated in the order that they are added. For example, they may be resorted by their z-order. Hence it is very important that names be unique.

Parameters

name	An identifier to find the child node.

Returns: the (first) child with the given name.

template<typename T >

std::shared_ptr<T> cugl::Scene::getChildByName ( const std::string & name ) const

inline

Returns the (first) child with the given name, typecast to a shared T pointer.

This method is provided to simplify the polymorphism of a scene graph. While all children are a subclass of type Node, you may want to access them by their specific subclass. If the child is not an instance of type T (or a subclass), this method returns nullptr.

If there is more than one child of the given name, it returns the first one that is found. Children are not necessarily enumerated in the order that they are added. For example, they may be resorted by their z-order. Hence it is very important that names be unique.

Parameters

name	An identifier to find the child node.

Returns: the (first) child with the given name, typecast to a shared T pointer.

std::shared_ptr<Node> cugl::Scene::getChildByTag ( unsigned int tag ) const

Returns the (first) child with the given tag.

If there is more than one child of the given tag, it returns the first one that is found. Children are not necessarily enumerated in the order that they are added. For example, they may be resorted by their z-order. Hence it is very important that tags be unique.

Parameters

tag	An identifier to find the child node.

Returns: the (first) child with the given tag.

template<typename T >

std::shared_ptr<T> cugl::Scene::getChildByTag ( unsigned int tag ) const

inline

Returns the (first) child with the given tag, typecast to a shared T pointer.

This method is provided to simplify the polymorphism of a scene graph. While all children are a subclass of type Node, you may want to access them by their specific subclass. If the child is not an instance of type T (or a subclass), this method returns nullptr.

If there is more than one child of the given tag, it returns the first one that is found. Children are not necessarily enumerated in the order that they are added. For example, they may be resorted by their z-order. Hence it is very important that tags be unique.

Parameters

tag	An identifier to find the child node.

Returns: the (first) child with the given tag, typecast to a shared T pointer.

size_t cugl::Scene::getChildCount ( ) const

inline

Returns the number of immediate children of this scene.

Returns: The number of immediate children of this scene.

std::vector<std::shared_ptr<Node> > cugl::Scene::getChildren ( )

inline

Returns the list of the scene's immediate children.

Returns: the list of the scene's immediate children.

const std::vector<std::shared_ptr<Node> >& cugl::Scene::getChildren ( ) const

inline

Returns the list of the scene's immediate children.

Returns: the list of the scene's immediate children.

Color4 cugl::Scene::getColor ( )

inline

Returns the tint color for this scene.

During the render phase, this color will be applied to any child for which hasRelativeColor() is true.

Returns: the tint color for this scene.

const std::string& cugl::Scene::getName ( ) const

inline

Returns a string that is used to identify the scene.

Returns: a string that is used to identify the scene.

bool cugl::Scene::init ( const Size & size )

inline

Initializes a Scene with the given viewport.

The viewport origin is assumed to be (0,0).

Parameters

size	The viewport size

Returns: true if initialization was successful.

bool cugl::Scene::init	(	float	width,
		float	height
	)

inline

Initializes a Scene with the given viewport.

The viewport origin is assumed to be (0,0).

Parameters

width	The viewport width
height	The viewport height

Returns: true if initialization was successful.

bool cugl::Scene::init ( const Rect & rect )

inline

Initializes a Scene with the given viewport.

Offseting the viewport origin has little affect on the Scene in general. It only affects the coordinate conversion methods Camera#project() and Camera#unproject(). It is supposed to represent the offset of the viewport in a larger canvas.

Parameters

rect	The viewport bounding box

Returns: true if initialization was successful.

bool cugl::Scene::init	(	const Vec2 &	origin,
		const Size &	size
	)

inline

Initializes a Scene with the given viewport.

Offseting the viewport origin has little affect on the Scene in general. It only affects the coordinate conversion methods Camera#project() and Camera#unproject(). It is supposed to represent the offset of the viewport in a larger canvas.

Parameters

origin	The viewport offset
size	The viewport size

Returns: true if initialization was successful.

bool cugl::Scene::init	(	float	x,
		float	y,
		float	width,
		float	height
	)

Initializes a Scene with the given viewport.

Offseting the viewport origin has little affect on the Scene in general. It only affects the coordinate conversion methods Camera#project() and Camera#unproject(). It is supposed to represent the offset of the viewport in a larger canvas.

Parameters

x	The viewport x offset
y	The viewport y offset
width	The viewport width
height	The viewport height

Returns: true if initialization was successful.

bool cugl::Scene::isZAutoSort ( )

inline

Returns true if this scene automatically sorts children by z-value.

If this value is true, the scene graph will be resorted every time that render() is called. Because of our invariant with dirty nodes, sorting will be avoided if it is not necessary.

Sorting only happens automatically is this value it true. Otherwise, you will need to call sortZOrder() if you wish to guarantee that the sceen graph is in z-order.

Returns: true if this scene automatically sorts children by z-value.

bool cugl::Scene::isZDirty ( ) const

inline

Returns whether the children of this Scene needs resorting.

The children of a scene may need to be resorted whenever a child is added, or whenever the z-value of a child is changed.

This value satisfies the following invariant: if a Node is dirty and needs resorting, then so are all of its ancestors (including this associated Scene). Our methods guarantee this invariant, so that the method isZDirty() always returns the correct value.

Sorting only happens automatically is isZAutoSort() it true. Otherwise, you will need to call sortZOrder() if you wish to guarantee that the sceen graph is in z-order.

Returns: whether the children of this node needs resorting.

cugl::Scene::operator std::string ( ) const

inline

Cast from a Scene to a string.

virtual void cugl::Scene::removeAllChildren ( )

virtual

Removes all children from this Node.

virtual void cugl::Scene::removeChild ( unsigned int pos )

virtual

Removes the child at the given position from this Scene.

Removing a child alters the position of every child after it. Hence it is unsafe to cache child positions.

Parameters

pos	The position of the child node which will be removed.

void cugl::Scene::removeChild ( const std::shared_ptr< Node > & child )

Removes a child from this Scene.

Removing a child alters the position of every child after it. Hence it is unsafe to cache child positions.

If the child is not in this node, nothing happens.

Parameters

child The child node which will be removed.

void cugl::Scene::removeChildByName ( const std::string & name )

Removes a child from the Scene by name.

If there is more than one child of the given name, it removes the first one that is found. Children are not necessarily enumerated in the order that they are added. For example, they may be resorted by their z-order. Hence it is very important that names be unique.

Parameters

name	A string to identify the node.

void cugl::Scene::removeChildByTag ( unsigned int tag )

Removes a child from the Scene by tag value.

If there is more than one child of the given tag, it removes the first one that is found. Children are not necessarily enumerated in the order that they are added. For example, they may be resorted by their z-order. Hence it is very important that tags be unique.

Parameters

tag	An integer to identify the node easily.

void cugl::Scene::render ( const std::shared_ptr< SpriteBatch > & batch )

Draws all of the children in this scene with the given SpriteBatch.

This method assumes that the sprite batch is not actively drawing. It will call both begin() and end().

Rendering happens by traversing the the scene graph using an "Pre-Order" tree traversal algorithm ( https://en.wikipedia.org/wiki/Tree_traversal#Pre-order ). That means that parents are always draw before (and behind children). The children of each sub tree are ordered by z-value (or by the order added).

Parameters

batch The SpriteBatch to draw with.

Vec3 cugl::Scene::screenToWorldCoords ( const Vec2 & screenCoords ) const

inline

Returns the world space equivalent of a point in screen coordinates.

Ideally, window space and screen space would be the same space. They are both defined by the viewport and have the same offset and dimension. However, screen coordinates have the origin in the top left while window coordinates have the origin in the bottom left.

In computing the world space coordinates, this method assumes that the z-value of the original vector is the same as near, which is the closest it can be the screen.

This method is important for converting event coordinates (such as a mouse click) to world coordinates.

Parameters

screenCoords The point in screen coordinates

Returns: the world space equivalent of a point in screen coordinates.

void cugl::Scene::setBounds ( const Rect & rect )

inline

Sets this Scene to have the given viewport.

Offseting the viewport origin has little affect on the Scene in general. It only affects the coordinate conversion methods Camera#project() and Camera#unproject(). It is supposed to represent the offset

Parameters

rect	The viewport bounding box

void cugl::Scene::setBounds	(	const Vec2 &	origin,
		const Size &	size
	)

inline

Sets this Scene to have the given viewport.

Offseting the viewport origin has little affect on the Scene in general. It only affects the coordinate conversion methods Camera#project() and Camera#unproject(). It is supposed to represent the offset

Parameters

origin	The viewport offset
size	The viewport size
yDown	Whether to put the origin in the top left corner

void cugl::Scene::setBounds	(	float	x,
		float	y,
		float	width,
		float	height
	)

inline

Sets this Scene to have the given viewport.

Offseting the viewport origin has little affect on the Scene in general. It only affects the coordinate conversion methods Camera#project() and Camera#unproject(). It is supposed to represent the offset

Parameters

x	The viewport x offset
y	The viewport y offset
width	The viewport width
height	The viewport height

void cugl::Scene::setColor ( Color4 color )

inline

Sets the tint color for this scene.

During the render phase, this color will be applied to any child for which hasRelativeColor() is true.

color The tint color for this scene.

void cugl::Scene::setHeight ( float height )

inline

Sets this Scene to have the given viewport height.

The viewport origin is assumed to be (0,0).

Parameters

height The viewport height

void cugl::Scene::setName ( const std::string & name )

inline

Returns the string that is used to identify the scene.

Parameters

name	A string that is used to identify the scene.

void cugl::Scene::setOffset ( const Vec2 & origin )

inline

Offsets the viewport origin by the given amount.

Offseting the viewport origin has little affect on the Scene in general. It only affects the coordinate conversion methods Camera#project() and Camera#unproject(). It is supposed to represent the offset

Parameters

origin The offset of the viewport origin

void cugl::Scene::setSize ( const Size & size )

inline

Sets this Scene to have the given viewport.

The viewport origin is assumed to be (0,0).

Parameters

size	The viewport size

void cugl::Scene::setSize	(	float	width,
		float	height
	)

inline

Sets this Scene to have the given viewport.

The viewport origin is assumed to be (0,0).

Parameters

width	The viewport width
height	The viewport height

void cugl::Scene::setWidth ( float width )

inline

Sets this Scene to have the given viewport width.

The viewport origin is assumed to be (0,0).

Parameters

width The viewport width

void cugl::Scene::setZAutoSort ( bool value )

inline

Sets whether this scene automatically sorts children by z-value.

If this value is true, the scene graph will be resorted every time that render() is called. Because of our invariant with dirty nodes, sorting will be avoided if it is not necessary.

Sorting only happens automatically is this value it true. Otherwise, you will need to call sortZOrder() if you wish to guarantee that the sceen graph is in z-order.

value Whether this scene automatically sorts children by z-value.

void cugl::Scene::sortZOrder ( )

Resorts the children of this Scene according to z-value.

If two children have the same z-value, their relative order is preserved to what it was before the sort. This method should be called before rendering.

Resorting is done recursively down a tree for each child that is dirty and needs resorting. We guarantee that Nodes will not be resorted unless necessary, because of the following invariant: if a Node is dirty and needs resorting, then so are all of its ancestors (including this associated Scene).

Sorting only happens automatically is isZAutoSort() it true. Otherwise, you will need to call sortZOrder() if you wish to guarantee that the sceen graph is in z-order.

void cugl::Scene::swapChild	(	const std::shared_ptr< Node > &	child1,
		const std::shared_ptr< Node > &	child2,
		bool	inherit = `false`
	)

Swaps the current child child1 with the new child child2.

If inherit is true, the children of child1 are assigned to child2 after the swap; this value is false by default. The purpose of this value is to allow transitions in the scene graph.

This method is undefined if child1 is not a child of this scene.

Parameters

child1	The current child of this node
child2	The child to swap it with.
inherit	Whether the new child should inherit the children of child1.

virtual std::string cugl::Scene::toString ( bool verbose = false ) const

virtual

Returns a string representation of this scene for debugging purposes.

If verbose is true, the string will include class information. This allows us to unambiguously identify the class.

Parameters

verbose Whether to include class information

Returns: a string representation of this scene for debuggging purposes.

Vec2 cugl::Scene::worldToScreenCoords ( const Vec3 & worldCoords ) const

inline

Returns the screen space equivalent of a point in world coordinates.

Ideally, window space and screen space would be the same space. They are both defined by the viewport and have the same offset and dimension. However, screen coordinates have the origin in the top left while window coordinates have the origin in the bottom left.

This method is important for converting world coordinates to event coordinates (such as a mouse click).

Parameters

worldCoords The point in wprld coordinates

Returns: the screen space equivalent of a point in world coordinates.

Member Data Documentation

std::shared_ptr<OrthographicCamera> cugl::Scene::_camera

protected

The camera for this scene

std::vector<std::shared_ptr<Node> > cugl::Scene::_children

protected

The array of internal nodes

Color4 cugl::Scene::_color

protected

The default tint for this scene

std::string cugl::Scene::_name

protected

The name of this scene

bool cugl::Scene::_zDirty

protected

Indicates whether the z-order is currently violated

bool cugl::Scene::_zSort

protected

Indicates whether auto-sorting is active

The documentation for this class was generated from the following file:

2d/CUScene.h

Public Member Functions

Static Public Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation