#include <CUScene3.h>

Public Member Functions
	Scene3 ()

	~Scene3 ()

virtual 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)

virtual 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

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

	operator std::string () const

const Size	getSize () const

void	setSize (const Size size)

void	setSize (float width, float height)

void	setWidth (float width)

void	setHeight (float height)

const Rect	getBounds () const

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< SceneNode >	getChild (unsigned int pos)

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

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

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

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

std::shared_ptr< SceneNode >	getChildByName (const std::string name) const

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

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

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

virtual void	addChild (const std::shared_ptr< SceneNode > &child)

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

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

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

virtual void	removeChild (unsigned int pos)

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

void	removeChildByTag (unsigned int tag)

void	removeChildByName (const std::string name)

virtual void	removeAllChildren ()

bool	isActive () const

virtual void	setActive (bool value)

virtual void	update (float timestep)

virtual void	reset ()

virtual void	render ()

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

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

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

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

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

Protected Attributes
std::string	_name

std::shared_ptr< PerspectiveCamera >	_camera

std::shared_ptr< Scene3Pipeline >	_pipeline

cugl::Vec3	_light

std::vector< std::shared_ptr< SceneNode > >	_children

bool	_active

Friends
class	SceneNode

Detailed Description

This class provides the root node of a three-dimensional scene graph.

The Scene2 class is very similar to scene3::SceneNode and shares some methods in common. The major difference is that it has no parent and it has no position (so it cannot be transformed). Instead, the Scene2 is defined by an attached PerspectiveCamera.

Rendering a scene graph happens via a Scene3Pipeline. That pipeline uses depth testing to properly render the scene, but may perform sorting in order to preserve transparency and similar such affects.

Constructor & Destructor Documentation

◆ Scene3()

cugl::scene3::Scene3::Scene3 ( )

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.

◆ ~Scene3()

cugl::scene3::Scene3::~Scene3 ( )

inline

Deletes this scene, disposing all resources

Member Function Documentation

◆ addChild()

virtual void cugl::scene3::Scene3::addChild ( const std::shared_ptr< SceneNode > & child )

virtual

Adds a child to this scene.

Children are not necessarily enumerated in the order that they are added. Hence you should generally attempt to retrieve a child by tag or by name instead.

Parameters

child A child node.

◆ addChildWithName()

void cugl::scene3::Scene3::addChildWithName	(	const std::shared_ptr< SceneNode > &	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. 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.

◆ addChildWithTag()

void cugl::scene3::Scene3::addChildWithTag	(	const std::shared_ptr< SceneNode > &	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. 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.

◆ alloc() [1/5]

static std::shared_ptr< Scene3 > cugl::scene3::Scene3::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.

◆ alloc() [2/5]

static std::shared_ptr< Scene3 > cugl::scene3::Scene3::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.

◆ alloc() [3/5]

static std::shared_ptr< Scene3 > cugl::scene3::Scene3::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.

◆ alloc() [4/5]

static std::shared_ptr< Scene3 > cugl::scene3::Scene3::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.

◆ alloc() [5/5]

static std::shared_ptr< Scene3 > cugl::scene3::Scene3::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.

◆ dispose()

virtual void cugl::scene3::Scene3::dispose ( )

virtual

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.

◆ getBounds()

const Rect cugl::scene3::Scene3::getBounds ( ) const

inline

Returns the viewport of this Scene2.

Returns: the viewport of this Scene2.

◆ getCamera() [1/2]

std::shared_ptr< Camera > cugl::scene3::Scene3::getCamera ( )

Returns the camera for this scene.

Returns: the camera for this scene.

◆ getCamera() [2/2]

const std::shared_ptr< Camera > cugl::scene3::Scene3::getCamera ( ) const

Returns the camera for this scene.

Returns: the camera for this scene.

◆ getChild() [1/3]

std::shared_ptr< SceneNode > cugl::scene3::Scene3::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.

◆ getChild() [2/3]

const std::shared_ptr< SceneNode > & cugl::scene3::Scene3::getChild ( unsigned int pos ) const

Returns the child at the given position.

Children are not necessarily enumerated in the order that they are added. 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.

◆ getChild() [3/3]

template<typename T >

std::shared_ptr< T > cugl::scene3::Scene3::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. 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.

◆ getChildByName() [1/2]

std::shared_ptr< SceneNode > cugl::scene3::Scene3::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. 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.

◆ getChildByName() [2/2]

template<typename T >

std::shared_ptr< T > cugl::scene3::Scene3::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. 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.

◆ getChildByTag() [1/2]

std::shared_ptr< SceneNode > cugl::scene3::Scene3::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. 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.

◆ getChildByTag() [2/2]

template<typename T >

std::shared_ptr< T > cugl::scene3::Scene3::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. 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.

◆ getChildCount()

size_t cugl::scene3::Scene3::getChildCount ( ) const

inline

Returns the number of immediate children of this scene.

Returns: The number of immediate children of this scene.

◆ getChildren() [1/2]

std::vector< std::shared_ptr< SceneNode > > cugl::scene3::Scene3::getChildren ( )

inline

Returns the list of the scene's immediate children.

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

◆ getChildren() [2/2]

const std::vector< std::shared_ptr< SceneNode > > & cugl::scene3::Scene3::getChildren ( ) const

inline

Returns the list of the scene's immediate children.

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

◆ getName()

const std::string cugl::scene3::Scene3::getName ( ) const

inline

Returns a string that is used to identify the scene.

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

◆ getSize()

const Size cugl::scene3::Scene3::getSize ( ) const

inline

Returns the viewport size of this Scene2.

Returns: the viewport size of this Scene2.

◆ init() [1/5]

bool cugl::scene3::Scene3::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.

◆ init() [2/5]

bool cugl::scene3::Scene3::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.

◆ init() [3/5]

bool cugl::scene3::Scene3::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.

◆ init() [4/5]

bool cugl::scene3::Scene3::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.

◆ init() [5/5]

virtual bool cugl::scene3::Scene3::init	(	float	x,
		float	y,
		float	width,
		float	height
	)

virtual

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.

◆ isActive()

bool cugl::scene3::Scene3::isActive ( ) const

inline

Returns true if the scene is currently active

Returns: true if the scene is currently active

◆ operator std::string()

cugl::scene3::Scene3::operator std::string ( ) const

inline

Cast from a Scene to a string.

◆ removeAllChildren()

virtual void cugl::scene3::Scene3::removeAllChildren ( )

virtual

Removes all children from this Node.

◆ removeChild() [1/2]

void cugl::scene3::Scene3::removeChild ( const std::shared_ptr< SceneNode > & 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.

◆ removeChild() [2/2]

virtual void cugl::scene3::Scene3::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.

◆ removeChildByName()

void cugl::scene3::Scene3::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. Hence it is very important that names be unique.

Parameters

name	A string to identify the node.

◆ removeChildByTag()

void cugl::scene3::Scene3::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. Hence it is very important that tags be unique.

Parameters

tag	An integer to identify the node easily.

◆ render()

virtual void cugl::scene3::Scene3::render ( )

virtual

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

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 children.

◆ reset()

virtual void cugl::scene3::Scene3::reset ( )

inlinevirtual

Resets the status of the scene to its original configuration.

◆ screenToWorldCoords()

Vec3 cugl::scene3::Scene3::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.

◆ setActive()

virtual void cugl::scene3::Scene3::setActive ( bool value )

inlinevirtual

Sets whether the scene is currently active

Parameters

value whether the scene is currently active

◆ setBounds() [1/3]

void cugl::scene3::Scene3::setBounds ( const Rect rect )

inline

Sets this Scene2 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

◆ setBounds() [2/3]

void cugl::scene3::Scene3::setBounds	(	const Vec2	origin,
		const Size	size
	)

inline

Sets this Scene2 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

◆ setBounds() [3/3]

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

inline

Sets this Scene2 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

◆ setHeight()

void cugl::scene3::Scene3::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

◆ setName()

void cugl::scene3::Scene3::setName ( const std::string name )

inline

Sets the string that is used to identify the scene.

Parameters

name	A string that is used to identify the scene.

◆ setOffset()

void cugl::scene3::Scene3::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

◆ setSize() [1/2]

void cugl::scene3::Scene3::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

◆ setSize() [2/2]

void cugl::scene3::Scene3::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

◆ setWidth()

void cugl::scene3::Scene3::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

◆ swapChild()

void cugl::scene3::Scene3::swapChild	(	const std::shared_ptr< SceneNode > &	child1,
		const std::shared_ptr< SceneNode > &	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.

◆ toString()

virtual std::string cugl::scene3::Scene3::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.

◆ update()

virtual void cugl::scene3::Scene3::update ( float timestep )

inlinevirtual

The method called to update the scene.

This method should be overridden with the specific scene logic.

Parameters

timestep The amount of time (in seconds) since the last frame

◆ worldToScreenCoords()

Vec2 cugl::scene3::Scene3::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

◆ _active

bool cugl::scene3::Scene3::_active

protected

Whether or note this scene is still active

◆ _camera

std::shared_ptr<PerspectiveCamera> cugl::scene3::Scene3::_camera

protected

The camera for this scene

◆ _children

std::vector<std::shared_ptr<SceneNode> > cugl::scene3::Scene3::_children

protected

The array of internal nodes

◆ _light

cugl::Vec3 cugl::scene3::Scene3::_light

protected

The light source position

◆ _name

std::string cugl::scene3::Scene3::_name

protected

The name of this scene

◆ _pipeline

std::shared_ptr<Scene3Pipeline> cugl::scene3::Scene3::_pipeline

protected

The camera for this scene

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

/Users/wmwhite/Developer/CUGL/include/cugl/scene3/CUScene3.h

Public Member Functions

Static Public Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Scene3()

◆ ~Scene3()

Member Function Documentation

◆ addChild()

◆ addChildWithName()

◆ addChildWithTag()

◆ alloc() [1/5]

◆ alloc() [2/5]

◆ alloc() [3/5]

◆ alloc() [4/5]

◆ alloc() [5/5]

◆ dispose()

◆ getBounds()

◆ getCamera() [1/2]

◆ getCamera() [2/2]

◆ getChild() [1/3]

◆ getChild() [2/3]

◆ getChild() [3/3]

◆ getChildByName() [1/2]

◆ getChildByName() [2/2]

◆ getChildByTag() [1/2]

◆ getChildByTag() [2/2]

◆ getChildCount()

◆ getChildren() [1/2]

◆ getChildren() [2/2]

◆ getName()

◆ getSize()

◆ init() [1/5]

◆ init() [2/5]

◆ init() [3/5]

◆ init() [4/5]

◆ init() [5/5]

◆ isActive()

◆ operator std::string()

◆ removeAllChildren()

◆ removeChild() [1/2]

◆ removeChild() [2/2]

◆ removeChildByName()

◆ removeChildByTag()

◆ render()

◆ reset()

◆ screenToWorldCoords()

◆ setActive()

◆ setBounds() [1/3]

◆ setBounds() [2/3]

◆ setBounds() [3/3]

◆ setHeight()

◆ setName()

◆ setOffset()

◆ setSize() [1/2]

◆ setSize() [2/2]

◆ setWidth()

◆ swapChild()

◆ toString()

◆ update()

◆ worldToScreenCoords()

Member Data Documentation

◆ _active

◆ _camera

◆ _children

◆ _light

◆ _name

◆ _pipeline