CUGL 1.3
Cornell University Game Library
|
#include <CUScene.h>
Public Member Functions | |
Scene () | |
~Scene () | |
virtual void | dispose () |
virtual bool | init (const Size &size) |
bool | init (float width, float height) |
virtual bool | init (const Rect &rect) |
virtual 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 () |
bool | isActive () const |
virtual void | setActive (bool value) |
virtual void | update (float timestep) |
virtual void | reset () |
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 |
GLenum | _blendEquation |
GLenum | _srcFactor |
GLenum | _dstFactor |
bool | _active |
Friends | |
class | Node |
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).
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.
|
inline |
Deletes this scene, disposing all resources
|
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.
child | A child node. |
zval | The (new) child z-order. |
|
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.
child | A child node. |
|
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.
child | A child node. |
name | A string to identify the node. |
|
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.
child | A child node. |
name | A string to identify the node. |
zval | The (new) child z-order. |
|
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.
child | A child node. |
tag | An integer to identify the node easily. |
|
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.
child | A child node. |
tag | An integer to identify the node easily. |
zval | The (new) child z-order. |
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
rect | The viewport bounding box |
|
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
origin | The viewport offset |
size | The viewport size |
|
inlinestatic |
|
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
x | The viewport x offset |
y | The viewport y offset |
width | The viewport width |
height | The viewport height |
|
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.
std::shared_ptr<Camera> cugl::Scene::getCamera | ( | ) |
Returns the camera for this scene.
const std::shared_ptr<Camera> cugl::Scene::getCamera | ( | ) | const |
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.
pos | The child 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.
pos | The child position. |
|
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.
pos | The child position. |
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.
name | An identifier to find the child node. |
|
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.
name | An identifier to find the child node. |
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.
tag | An identifier to find the child node. |
|
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.
tag | An identifier to find the child node. |
|
inline |
Returns the number of immediate children of this scene.
|
inline |
Returns the list of the scene's immediate children.
|
inline |
Returns the list of the scene's immediate children.
|
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.
|
inline |
Returns a string that is used to identify the scene.
|
inlinevirtual |
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.
rect | The viewport bounding box |
|
inlinevirtual |
Initializes a Scene with the given viewport.
The viewport origin is assumed to be (0,0).
size | The viewport size |
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.
origin | The viewport offset |
size | The viewport size |
|
inline |
Initializes a Scene with the given viewport.
The viewport origin is assumed to be (0,0).
width | The viewport width |
height | The viewport height |
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.
x | The viewport x offset |
y | The viewport y offset |
width | The viewport width |
height | The viewport height |
|
inline |
Returns true if the scene is currently active
|
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.
|
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.
|
inline |
Cast from a Scene to a string.
|
virtual |
Removes all children from this Node.
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.
child | The child node which will be removed. |
|
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.
pos | The position of 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.
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.
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).
batch | The SpriteBatch to draw with. |
|
inlinevirtual |
Resets the status of the scene to its original configuration.
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.
screenCoords | The point in screen coordinates |
|
inlinevirtual |
Sets whether the scene is currently active
value | whether the scene is currently active |
|
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
rect | The viewport bounding box |
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
origin | The viewport offset |
size | The viewport 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
x | The viewport x offset |
y | The viewport y offset |
width | The viewport width |
height | The viewport height |
|
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. |
|
inline |
Sets this Scene to have the given viewport height.
The viewport origin is assumed to be (0,0).
height | The viewport height |
|
inline |
Returns the string that is used to identify the scene.
name | A string that is used to identify the scene. |
|
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
origin | The offset of the viewport origin |
|
inline |
Sets this Scene to have the given viewport.
The viewport origin is assumed to be (0,0).
size | The viewport size |
|
inline |
Sets this Scene to have the given viewport.
The viewport origin is assumed to be (0,0).
width | The viewport width |
height | The viewport height |
|
inline |
Sets this Scene to have the given viewport width.
The viewport origin is assumed to be (0,0).
width | The viewport width |
|
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.
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 |
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.
verbose | Whether to include class information |
|
inlinevirtual |
The method called to update the scene.
This method should be overridden with the specific scene logic.
timestep | The amount of time (in seconds) since the last frame |
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).
worldCoords | The point in wprld coordinates |
|
protected |
Whether or note this scene is still active
|
protected |
The blending equation for this scene
|
protected |
The camera for this scene
|
protected |
The array of internal nodes
|
protected |
The default tint for this scene
|
protected |
The destination factor for the blend function
|
protected |
The name of this scene
|
protected |
The source factor for the blend function
|
protected |
Indicates whether the z-order is currently violated
|
protected |
Indicates whether auto-sorting is active