#include <CUScene3.h>

Inheritance diagram for cugl::scene3::Scene3:

Public Member Functions
	Scene3 ()

	~Scene3 ()

virtual void	dispose () override

virtual bool	init () override

bool	initWithViewport (const Size &size)

bool	initWithViewport (float width, float height)

bool	initWithViewport (const Rect &rect)

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

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

bool	initWithFOV (float fov)

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

	operator std::string () 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 ()

std::shared_ptr< Scene3Pipeline >	getPipeline () const

void	setPipeline (const std::shared_ptr< Scene3Pipeline > &pipeline)

const std::shared_ptr< graphics::FrameBuffer > &	getFrameBuffer () const

void	setFrameBuffer (const std::shared_ptr< graphics::FrameBuffer > &buffer)

virtual void	render () override

Public Member Functions inherited from cugl::Scene
	Scene ()

	~Scene ()

virtual void	dispose ()

virtual bool	init ()

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

const Rect	getBounds () const

Vec3	screenToWorldCoords (const Vec2 &screenCoords) const

Vec2	worldToScreenCoords (const Vec3 &worldCoords) const

bool	isActive () const

virtual void	setActive (bool value)

virtual void	update (float dt)

virtual void	reset ()

virtual void	render ()

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

static std::shared_ptr< Scene3 >	allocWithViewport (const Size &size)

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

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

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

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

static std::shared_ptr< Scene3 >	allocWithFOV (float fov)

Protected Attributes
std::shared_ptr< Scene3Pipeline >	_pipeline

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

std::shared_ptr< graphics::FrameBuffer >	_framebuffer

Protected Attributes inherited from cugl::Scene
std::shared_ptr< Camera >	_camera

std::string	_name

Size	_size

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

static std::shared_ptr< Scene3 > cugl::scene3::Scene3::alloc ( )

inlinestatic

Returns a newly allocated scene with the default FOV.

This scene will have a viewport that matches the display and a perspective camera with a FOV of 67 degrees. The camera will be pointed at the origin.

The scene will not have an attached pipeline. You must add one with setPipeline.

Returns: a newly allocated scene with the default FOV.

◆ allocWithFOV()

static std::shared_ptr< Scene3 > cugl::scene3::Scene3::allocWithFOV ( float fov )

inlinestatic

Returns a newly allocated scene with the given field of view.

The viewport will match the size of the display. The field of view given is for the height, and is measured in degrees.

The scene will not have an attached pipeline. You must add one with setPipeline.

Parameters

fov	The field of view

Returns: a newly allocated scene with the given field of view.

◆ allocWithViewport() [1/5]

static std::shared_ptr< Scene3 > cugl::scene3::Scene3::allocWithViewport ( const Rect & rect )

inlinestatic

Returns a newly allocated scene for the given viewport.

The viewport is used to define a perspective camera on the display. The camera will be pointed at the origin with a FOV of 67 degrees.

The viewport origin only affects the coordinate conversion methods Camera#project() and Camera#unproject() which are used to convert from the scene graph to a display. It is intended to represent the offset of the viewport in a larger canvas.

The scene will not have an attached pipeline. You must add one with setPipeline.

Parameters

rect	The viewport bounding box

Returns: a newly allocated Scene for the given viewport.

◆ allocWithViewport() [2/5]

static std::shared_ptr< Scene3 > cugl::scene3::Scene3::allocWithViewport ( const Size & size )

inlinestatic

Returns a newly allocated scene for the given viewport.

The viewport is used to define a perspective camera on the display. The camera will be pointed at the origin with a FOV of 67 degrees.

The scene will not have an attached pipeline. You must add one with setPipeline.

Parameters

size	The viewport size

Returns: a newly allocated Scene for the given viewport.

◆ allocWithViewport() [3/5]

static std::shared_ptr< Scene3 > cugl::scene3::Scene3::allocWithViewport	(	const Vec2 &	origin,
		const Size &	size
	)

inlinestatic

Returns a newly allocated scene for the given viewport.

The viewport is used to define a perspective camera on the display. The camera will be pointed at the origin with a FOV of 67 degrees.

The viewport origin only affects the coordinate conversion methods Camera#project() and Camera#unproject() which are used to convert from the scene graph to a display. It is intended to represent the offset of the viewport in a larger canvas.

The scene will not have an attached pipeline. You must add one with setPipeline.

Parameters

origin	The viewport offset
size	The viewport size

Returns: a newly allocated Scene for the given viewport.

◆ allocWithViewport() [4/5]

static std::shared_ptr< Scene3 > cugl::scene3::Scene3::allocWithViewport	(	float	width,
		float	height
	)

inlinestatic

Returns a newly allocated scene for the given viewport.

The viewport is used to define a perspective camera on the display. The camera will be pointed at the origin with a FOV of 67 degrees.

The scene will not have an attached pipeline. You must add one with setPipeline.

Parameters

width	The viewport width
height	The viewport height

Returns: a newly allocated Scene for the given viewport.

◆ allocWithViewport() [5/5]

static std::shared_ptr< Scene3 > cugl::scene3::Scene3::allocWithViewport	(	float	x,
		float	y,
		float	width,
		float	height
	)

inlinestatic

Returns a newly allocated scene for the given viewport.

The viewport is used to define a perspective camera on the display. The camera will be pointed at the origin with a FOV of 67 degrees.

The viewport origin only affects the coordinate conversion methods Camera#project() and Camera#unproject() which are used to convert from the scene graph to a display. It is intended to represent the offset of the viewport in a larger canvas.

The scene will not have an attached pipeline. You must add one with setPipeline.

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

overridevirtual

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.

Reimplemented from cugl::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.

◆ getFrameBuffer()

const std::shared_ptr< graphics::FrameBuffer > & cugl::scene3::Scene3::getFrameBuffer ( ) const

inline

Returns the offscreen framebuffer associated with this scene.

If this value is nullptr (the default), then this scene will be rendered to the primary display. Otherwise, it will be rendered to the given framebuffer. The framebuffer must be compatible with a sprite batch. However, we do not require that the framebuffer be the same size as the display.

Returns: the offscreen framebuffer associated with this scene.

◆ getPipeline()

std::shared_ptr< Scene3Pipeline > cugl::scene3::Scene3::getPipeline ( ) const

inline

Returns the pipeline for rendering this scene.

Scene3 nodes are typically rendered with a Scene3Pipeline object. In particular the method render traverses the scene graph and sends those nodes to pipeline (though this behavior can be overridden).

As graphics pipelines are fairly heavy-weight pipelines, we do not construct a pipeline for each scene. Instead a pipeline has to be assigned to the scene. If no pipeline is assigned, nothing is drawn.

Returns: the pipeline for rendering this scene.

◆ init()

virtual bool cugl::scene3::Scene3::init ( )

overridevirtual

Initializes a Scene with the default FOV.

This scene will have a viewport that matches the display and a perspective camera with a FOV of 67 degrees. The camera will be pointed at the origin.

The scene will not have an attached pipeline. You must add one with setPipeline.

Returns: true if initialization was successful.

Reimplemented from cugl::Scene.

◆ initWithFOV()

bool cugl::scene3::Scene3::initWithFOV ( float fov )

Initializes a scene with the given field of view.

The viewport will match the size of the display. The field of view given is for the height, and is measured in degrees.

The scene will not have an attached pipeline. You must add one with setPipeline.

Parameters

fov	The field of view

Returns: true if initialization was successful.

◆ initWithViewport() [1/5]

bool cugl::scene3::Scene3::initWithViewport ( const Rect & rect )

inline

Initializes a scene with the given viewport.

The viewport is used to define a perspective camera on the display. The camera will be pointed at the origin with a FOV of 67 degrees.

The viewport origin only affects the coordinate conversion methods Camera#project() and Camera#unproject() which are used to convert from the scene graph to a display. It is intended to represent the offset of the viewport in a larger canvas.

The scene will not have an attached pipeline. You must add one with setPipeline.

Parameters

rect	The viewport bounding box

Returns: true if initialization was successful.

◆ initWithViewport() [2/5]

bool cugl::scene3::Scene3::initWithViewport ( const Size & size )

inline

Initializes a scene with the given viewport.

The viewport is used to define a perspective camera on the display. The camera will be pointed at the origin with a FOV of 67 degrees.

The scene will not have an attached pipeline. You must add one with setPipeline.

Parameters

size	The viewport size

Returns: true if initialization was successful.

◆ initWithViewport() [3/5]

bool cugl::scene3::Scene3::initWithViewport	(	const Vec2 &	origin,
		const Size &	size
	)

inline

Initializes a scene with the given viewport.

The viewport is used to define a perspective camera on the display. The camera will be pointed at the origin with a FOV of 67 degrees.

The viewport origin only affects the coordinate conversion methods Camera#project() and Camera#unproject() which are used to convert from the scene graph to a display. It is intended to represent the offset of the viewport in a larger canvas.

The scene will not have an attached pipeline. You must add one with setPipeline.

Parameters

origin	The viewport offset
size	The viewport size

Returns: true if initialization was successful.

◆ initWithViewport() [4/5]

bool cugl::scene3::Scene3::initWithViewport	(	float	width,
		float	height
	)

inline

Initializes a scene with the given viewport.

The viewport is used to define a perspective camera on the display. The camera will be pointed at the origin with a FOV of 67 degrees.

The scene will not have an attached pipeline. You must add one with setPipeline.

Parameters

width	The viewport width
height	The viewport height

Returns: true if initialization was successful.

◆ initWithViewport() [5/5]

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

Initializes a scene with the given viewport.

The viewport is used to define a perspective camera on the display. The camera will be pointed at the origin with a FOV of 67 degrees.

The viewport origin only affects the coordinate conversion methods Camera#project() and Camera#unproject() which are used to convert from the scene graph to a display. It is intended to represent the offset of the viewport in a larger canvas.

The scene will not have an attached pipeline. You must add one with setPipeline.

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.

◆ 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 ( )

overridevirtual

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.

Reimplemented from cugl::Scene.

◆ setFrameBuffer()

void cugl::scene3::Scene3::setFrameBuffer ( const std::shared_ptr< graphics::FrameBuffer > & buffer )

inline

Sets the offscreen framebuffer associated with this scene.

If this value is nullptr (the default), then this scene will be rendered to the primary display. Otherwise, it will be rendered to the given framebuffer. The framebuffer must be compatible with a sprite batch. However, we do not require that the framebuffer be the same size as the display.

Parameters

buffer The offscreen framebuffer for this scene (or nullptr)

◆ setPipeline()

void cugl::scene3::Scene3::setPipeline ( const std::shared_ptr< Scene3Pipeline > & pipeline )

inline

Sets the pipeline for rendering this scene.

Scene3 nodes are typically rendered with a Scene3Pipeline object. In particular the method render traverses the scene graph and sends those nodes to pipeline (though this behavior can be overridden).

As graphics pipelines are fairly heavy-weight pipelines, we do not construct a pipeline for each scene. Instead a pipeline has to be assigned to the scene. If no pipeline is assigned, nothing is drawn.

Parameters

pipeline The pipeline for rendering this scene.

◆ 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

overridevirtual

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.

Reimplemented from cugl::Scene.

Member Data Documentation

◆ _children

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

protected

The array of internal nodes

◆ _framebuffer

std::shared_ptr<graphics::FrameBuffer> cugl::scene3::Scene3::_framebuffer

protected

An (optional) offscreen buffer for rendering the 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()

◆ allocWithFOV()

◆ allocWithViewport() [1/5]

◆ allocWithViewport() [2/5]

◆ allocWithViewport() [3/5]

◆ allocWithViewport() [4/5]

◆ allocWithViewport() [5/5]

◆ dispose()

◆ 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]

◆ getFrameBuffer()

◆ getPipeline()

◆ init()

◆ initWithFOV()

◆ initWithViewport() [1/5]

◆ initWithViewport() [2/5]

◆ initWithViewport() [3/5]

◆ initWithViewport() [4/5]

◆ initWithViewport() [5/5]

◆ operator std::string()

◆ removeAllChildren()

◆ removeChild() [1/2]

◆ removeChild() [2/2]

◆ removeChildByName()

◆ removeChildByTag()

◆ render()

◆ setFrameBuffer()

◆ setPipeline()

◆ swapChild()

◆ toString()

Member Data Documentation

◆ _children

◆ _framebuffer

◆ _pipeline