CUGL 2.1
Cornell University Game Library
Public Member Functions | Static Public Member Functions | Protected Attributes | Friends | List of all members
cugl::Scene2 Class Reference

#include <CUScene2.h>

Inheritance diagram for cugl::Scene2:
cugl::Scene2Texture

Public Member Functions

 Scene2 ()
 
 ~Scene2 ()
 
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< CameragetCamera ()
 
const std::shared_ptr< CameragetCamera () const
 
Color4 getColor ()
 
void setColor (Color4 color)
 
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< scene2::SceneNodegetChild (unsigned int pos)
 
const std::shared_ptr< scene2::SceneNode > & getChild (unsigned int pos) const
 
template<typename T >
std::shared_ptr< TgetChild (unsigned int pos) const
 
std::shared_ptr< scene2::SceneNodegetChildByTag (unsigned int tag) const
 
template<typename T >
std::shared_ptr< TgetChildByTag (unsigned int tag) const
 
std::shared_ptr< scene2::SceneNodegetChildByName (const std::string name) const
 
template<typename T >
std::shared_ptr< TgetChildByName (const std::string name) const
 
std::vector< std::shared_ptr< scene2::SceneNode > > getChildren ()
 
const std::vector< std::shared_ptr< scene2::SceneNode > > & getChildren () const
 
virtual void addChild (const std::shared_ptr< scene2::SceneNode > &child)
 
void addChildWithTag (const std::shared_ptr< scene2::SceneNode > &child, unsigned int tag)
 
void addChildWithName (const std::shared_ptr< scene2::SceneNode > &child, const std::string name)
 
void swapChild (const std::shared_ptr< scene2::SceneNode > &child1, const std::shared_ptr< scene2::SceneNode > &child2, bool inherit=false)
 
virtual void removeChild (unsigned int pos)
 
void removeChild (const std::shared_ptr< scene2::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 (const std::shared_ptr< SpriteBatch > &batch)
 

Static Public Member Functions

static std::shared_ptr< Scene2alloc (const Size size)
 
static std::shared_ptr< Scene2alloc (float width, float height)
 
static std::shared_ptr< Scene2alloc (const Rect rect)
 
static std::shared_ptr< Scene2alloc (const Vec2 origin, const Size size)
 
static std::shared_ptr< Scene2alloc (float x, float y, float width, float height)
 

Protected Attributes

std::string _name
 
std::shared_ptr< OrthographicCamera_camera
 
std::vector< std::shared_ptr< scene2::SceneNode > > _children
 
Color4 _color
 
GLenum _blendEquation
 
GLenum _srcFactor
 
GLenum _dstFactor
 
bool _active
 

Friends

class scene2::SceneNode
 

Detailed Description

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

The Scene2 class is very similar to scene2::SceneNode 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 Scene2 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 sequentially.

Scenes do support optional z-ordering. This is not a true depth value, as depth filtering is incompatible with alpha compositing. However, it does provide a way to dynamically reorder how siblings are composed.

Constructor & Destructor Documentation

◆ Scene2()

cugl::Scene2::Scene2 ( )

Creates a new degenerate Scene2 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.

◆ ~Scene2()

cugl::Scene2::~Scene2 ( )
inline

Deletes this scene, disposing all resources

Member Function Documentation

◆ addChild()

virtual void cugl::Scene2::addChild ( const std::shared_ptr< scene2::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
childA child node.

◆ addChildWithName()

void cugl::Scene2::addChildWithName ( const std::shared_ptr< scene2::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
childA child node.
nameA string to identify the node.

◆ addChildWithTag()

void cugl::Scene2::addChildWithTag ( const std::shared_ptr< scene2::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
childA child node.
tagAn integer to identify the node easily.

◆ alloc() [1/5]

static std::shared_ptr<Scene2> cugl::Scene2::alloc ( const Rect  rect)
inlinestatic

Returns a newly allocated Scene2 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
rectThe viewport bounding box
Returns
a newly allocated Scene for the given viewport.

◆ alloc() [2/5]

static std::shared_ptr<Scene2> cugl::Scene2::alloc ( const Size  size)
inlinestatic

Returns a newly allocated Scene2 for the given viewport.

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

Parameters
sizeThe viewport size
Returns
a newly allocated Scene for the given viewport.

◆ alloc() [3/5]

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

Returns a newly allocated Scene2 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
originThe viewport offset
sizeThe viewport size
Returns
a newly allocated Scene for the given viewport.

◆ alloc() [4/5]

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

Returns a newly allocated Scene2 for the given viewport.

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

Parameters
widthThe viewport width
heightThe viewport height
Returns
a newly allocated Scene for the given viewport.

◆ alloc() [5/5]

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

Returns a newly allocated Scene2 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
xThe viewport x offset
yThe viewport y offset
widthThe viewport width
heightThe viewport height
Returns
a newly allocated Scene for the given viewport.

◆ dispose()

virtual void cugl::Scene2::dispose ( )
virtual

Disposes all of the resources used by this scene.

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

Reimplemented in cugl::Scene2Texture.

◆ getBounds()

const Rect cugl::Scene2::getBounds ( ) const
inline

Returns the viewport of this Scene2.

Returns
the viewport of this Scene2.

◆ getCamera() [1/2]

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

Returns the camera for this scene.

Returns
the camera for this scene.

◆ getCamera() [2/2]

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

Returns the camera for this scene.

Returns
the camera for this scene.

◆ getChild() [1/3]

std::shared_ptr<scene2::SceneNode> cugl::Scene2::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
posThe child position.
Returns
the child at the given position.

◆ getChild() [2/3]

const std::shared_ptr<scene2::SceneNode>& cugl::Scene2::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
posThe child position.
Returns
the child at the given position.

◆ getChild() [3/3]

template<typename T >
std::shared_ptr<T> cugl::Scene2::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
posThe child position.
Returns
the child at the given position, typecast to a shared T pointer.

◆ getChildByName() [1/2]

std::shared_ptr<scene2::SceneNode> cugl::Scene2::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
nameAn 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::Scene2::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
nameAn 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<scene2::SceneNode> cugl::Scene2::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
tagAn 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::Scene2::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
tagAn identifier to find the child node.
Returns
the (first) child with the given tag, typecast to a shared T pointer.

◆ getChildCount()

size_t cugl::Scene2::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<scene2::SceneNode> > cugl::Scene2::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<scene2::SceneNode> >& cugl::Scene2::getChildren ( ) const
inline

Returns the list of the scene's immediate children.

Returns
the list of the scene's immediate children.

◆ getColor()

Color4 cugl::Scene2::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.

◆ getName()

const std::string& cugl::Scene2::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::Scene2::getSize ( ) const
inline

Returns the viewport size of this Scene2.

Returns
the viewport size of this Scene2.

◆ init() [1/5]

bool cugl::Scene2::init ( const Rect  rect)
inline

Initializes a Scene2 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
rectThe viewport bounding box
Returns
true if initialization was successful.

◆ init() [2/5]

bool cugl::Scene2::init ( const Size  size)
inline

Initializes a Scene2 with the given viewport.

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

Parameters
sizeThe viewport size
Returns
true if initialization was successful.

◆ init() [3/5]

bool cugl::Scene2::init ( const Vec2  origin,
const Size  size 
)
inline

Initializes a Scene2 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
originThe viewport offset
sizeThe viewport size
Returns
true if initialization was successful.

◆ init() [4/5]

bool cugl::Scene2::init ( float  width,
float  height 
)
inline

Initializes a Scene2 with the given viewport.

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

Parameters
widthThe viewport width
heightThe viewport height
Returns
true if initialization was successful.

◆ init() [5/5]

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

Initializes a Scene2 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
xThe viewport x offset
yThe viewport y offset
widthThe viewport width
heightThe viewport height
Returns
true if initialization was successful.

Reimplemented in cugl::Scene2Texture.

◆ isActive()

bool cugl::Scene2::isActive ( ) const
inline

Returns true if the scene is currently active

Returns
true if the scene is currently active

◆ operator std::string()

cugl::Scene2::operator std::string ( ) const
inline

Cast from a Scene to a string.

◆ removeAllChildren()

virtual void cugl::Scene2::removeAllChildren ( )
virtual

Removes all children from this Node.

◆ removeChild() [1/2]

void cugl::Scene2::removeChild ( const std::shared_ptr< scene2::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
childThe child node which will be removed.

◆ removeChild() [2/2]

virtual void cugl::Scene2::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
posThe position of the child node which will be removed.

◆ removeChildByName()

void cugl::Scene2::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
nameA string to identify the node.

◆ removeChildByTag()

void cugl::Scene2::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
tagAn integer to identify the node easily.

◆ render()

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

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). To override this draw order, you should place an scene2::OrderedNode in the scene graph to specify an alternative order.

Parameters
batchThe SpriteBatch to draw with.

Reimplemented in cugl::Scene2Texture.

◆ reset()

virtual void cugl::Scene2::reset ( )
inlinevirtual

Resets the status of the scene to its original configuration.

◆ screenToWorldCoords()

Vec3 cugl::Scene2::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
screenCoordsThe point in screen coordinates
Returns
the world space equivalent of a point in screen coordinates.

◆ setActive()

virtual void cugl::Scene2::setActive ( bool  value)
inlinevirtual

Sets whether the scene is currently active

Parameters
valuewhether the scene is currently active

◆ setBounds() [1/3]

void cugl::Scene2::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
rectThe viewport bounding box

◆ setBounds() [2/3]

void cugl::Scene2::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
originThe viewport offset
sizeThe viewport size

◆ setBounds() [3/3]

void cugl::Scene2::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
xThe viewport x offset
yThe viewport y offset
widthThe viewport width
heightThe viewport height

◆ setColor()

void cugl::Scene2::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.

Parameters
colorThe tint color for this scene.

◆ setHeight()

void cugl::Scene2::setHeight ( float  height)
inline

Sets this Scene2 to have the given viewport height.

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

Parameters
heightThe viewport height

◆ setName()

void cugl::Scene2::setName ( const std::string &  name)
inline

Returns the string that is used to identify the scene.

Parameters
nameA string that is used to identify the scene.

◆ setOffset()

void cugl::Scene2::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
originThe offset of the viewport origin

◆ setSize() [1/2]

void cugl::Scene2::setSize ( const Size  size)
inline

Sets this Scene2 to have the given viewport.

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

Parameters
sizeThe viewport size

◆ setSize() [2/2]

void cugl::Scene2::setSize ( float  width,
float  height 
)
inline

Sets this Scene2 to have the given viewport.

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

Parameters
widthThe viewport width
heightThe viewport height

◆ setWidth()

void cugl::Scene2::setWidth ( float  width)
inline

Sets this Scene2 to have the given viewport width.

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

Parameters
widthThe viewport width

◆ swapChild()

void cugl::Scene2::swapChild ( const std::shared_ptr< scene2::SceneNode > &  child1,
const std::shared_ptr< scene2::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
child1The current child of this node
child2The child to swap it with.
inheritWhether the new child should inherit the children of child1.

◆ toString()

virtual std::string cugl::Scene2::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
verboseWhether to include class information
Returns
a string representation of this scene for debuggging purposes.

◆ update()

virtual void cugl::Scene2::update ( float  timestep)
inlinevirtual

The method called to update the scene.

This method should be overridden with the specific scene logic.

Parameters
timestepThe amount of time (in seconds) since the last frame

◆ worldToScreenCoords()

Vec2 cugl::Scene2::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
worldCoordsThe point in wprld coordinates
Returns
the screen space equivalent of a point in world coordinates.

Member Data Documentation

◆ _active

bool cugl::Scene2::_active
protected

Whether or note this scene is still active

◆ _blendEquation

GLenum cugl::Scene2::_blendEquation
protected

The blending equation for this scene

◆ _camera

std::shared_ptr<OrthographicCamera> cugl::Scene2::_camera
protected

The camera for this scene

◆ _children

std::vector<std::shared_ptr<scene2::SceneNode> > cugl::Scene2::_children
protected

The array of internal nodes

◆ _color

Color4 cugl::Scene2::_color
protected

The default tint for this scene

◆ _dstFactor

GLenum cugl::Scene2::_dstFactor
protected

The destination factor for the blend function

◆ _name

std::string cugl::Scene2::_name
protected

The name of this scene

◆ _srcFactor

GLenum cugl::Scene2::_srcFactor
protected

The source factor for the blend function


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