CUGL 2.1
Cornell University Game Library
Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
cugl::scene2::OrderedNode Class Reference

#include <CUOrderedNode.h>

Inheritance diagram for cugl::scene2::OrderedNode:
cugl::scene2::SceneNode

Classes

class  Context
 

Public Types

enum  Order {
  PRE_ORDER, POST_ORDER, ASCEND, DESCEND,
  PRE_ASCEND, PRE_DESCEND, POST_ASCEND, POST_DESCEND
}
 

Public Member Functions

 OrderedNode ()
 
 ~OrderedNode ()
 
virtual void dispose () override
 
bool initWithOrder (Order order)
 
bool initWithOrder (Order order, Vec2 pos)
 
bool initWithOrder (Order order, Rect bounds)
 
virtual bool initWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data) override
 
Order getOrder () const
 
void setOrder (Order order)
 
void render (const std::shared_ptr< SpriteBatch > &batch, const Affine2 &transform, Color4 tint) override
 
virtual void render (const std::shared_ptr< SpriteBatch > &batch) override
 
 CU_DISALLOW_COPY_AND_ASSIGN (OrderedNode)
 
- Public Member Functions inherited from cugl::scene2::SceneNode
 SceneNode ()
 
 ~SceneNode ()
 
virtual bool init ()
 
virtual bool initWithPosition (const Vec2 pos)
 
bool initWithPosition (float x, float y)
 
virtual bool initWithBounds (const Size size)
 
virtual bool initWithBounds (float width, float height)
 
virtual bool initWithBounds (const Rect rect)
 
virtual bool initWithBounds (float x, float y, float width, float height)
 
virtual std::shared_ptr< SceneNodecopy (const std::shared_ptr< SceneNode > &dst) const
 
unsigned int getTag () const
 
void setTag (unsigned int tag)
 
const std::string getName () const
 
void setName (const std::string name)
 
const std::string getClassName () const
 
virtual std::string toString (bool verbose=false) const
 
 operator std::string () const
 
const Vec2 getPosition () const
 
void setPosition (const Vec2 &position)
 
void setPosition (float x, float y)
 
float getPositionX (void) const
 
void setPositionX (float x)
 
float getPositionY (void) const
 
void setPositionY (float y)
 
Vec2 getWorldPosition () const
 
const Size getContentSize () const
 
virtual void setContentSize (const Size size)
 
virtual void setContentSize (float width, float height)
 
float getContentWidth () const
 
void setContentWidth (float width)
 
float getContentHeight () const
 
void setContentHeight (float height)
 
virtual Rect getLayoutBounds () const
 
Size getSize () const
 
float getWidth () const
 
float getHeight () const
 
Rect getBoundingBox () const
 
virtual void setAnchor (const Vec2 anchor)
 
virtual void setAnchor (float x, float y)
 
const Vec2 getAnchor () const
 
Vec2 getAnchorInPixels ()
 
Color4 getColor () const
 
virtual void setColor (Color4 color)
 
Color4 getAbsoluteColor ()
 
bool isVisible () const
 
void setVisible (bool visible)
 
bool hasRelativeColor () const
 
void setRelativeColor (bool flag)
 
std::shared_ptr< ScissorgetScissor () const
 
void setScissor (const std::shared_ptr< Scissor > &scissor)
 
void setScissor ()
 
const Vec2 getScale () const
 
float getScaleX () const
 
float getScaleY () const
 
void setScale (float scale)
 
void setScale (const Vec2 vec)
 
void setScale (float sx, float sy)
 
float getAngle ()
 
void setAngle (float angle)
 
const Affine2getTransform () const
 
const Affine2getAlternateTransform () const
 
void setAlternateTransform (const Affine2 &transform)
 
bool withAlternateTransform ()
 
void chooseAlternateTransform (bool active)
 
const Affine2getNodeToParentTransform () const
 
Affine2 getParentToNodeTransform () const
 
Affine2 getNodeToWorldTransform () const
 
Affine2 getWorldToNodeTransform () const
 
Vec2 screenToNodeCoords (const Vec2 screenPoint) const
 
Vec2 worldToNodeCoords (const Vec2 worldPoint) const
 
Vec2 nodeToScreenCoords (const Vec2 nodePoint) const
 
Vec2 nodeToWorldCoords (const Vec2 nodePoint) const
 
Vec2 parentToNodeCoords (const Vec2 parentPoint) const
 
Vec2 nodeToParentCoords (const Vec2 nodePoint) const
 
size_t getChildCount () const
 
std::shared_ptr< SceneNodegetChild (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< SceneNodegetChildByTag (unsigned int tag) const
 
template<typename T >
std::shared_ptr< T > getChildByTag (unsigned int tag) const
 
std::shared_ptr< SceneNodegetChildByName (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
 
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)
 
SceneNodegetParent ()
 
const SceneNodegetParent () const
 
Scene2getScene ()
 
const Scene2getScene () const
 
void removeFromParent ()
 
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 ()
 
void setPriority (float priority)
 
float getPriority ()
 
virtual void draw (const std::shared_ptr< SpriteBatch > &batch, const Affine2 &transform, Color4 tint)
 
const std::shared_ptr< Layout > & getLayout () const
 
void setLayout (const std::shared_ptr< Layout > &layout)
 
virtual void doLayout ()
 

Static Public Member Functions

static std::shared_ptr< SceneNodealloc ()
 
static std::shared_ptr< SceneNodeallocWithPosition (const Vec2 pos)
 
static std::shared_ptr< SceneNodeallocWithPosition (float x, float y)
 
static std::shared_ptr< SceneNodeallocWithBounds (const Size size)
 
static std::shared_ptr< SceneNodeallocWithBounds (float width, float height)
 
static std::shared_ptr< SceneNodeallocWithBounds (const Rect rect)
 
static std::shared_ptr< SceneNodeallocWithBounds (float x, float y, float width, float height)
 
static std::shared_ptr< OrderedNodeallocWithOrder (Order order)
 
static std::shared_ptr< OrderedNodeallocWithOrder (Order order, Vec2 pos)
 
static std::shared_ptr< OrderedNodeallocWithOrder (Order order, Rect bounds)
 
static std::shared_ptr< OrderedNodeallocWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data)
 
- Static Public Member Functions inherited from cugl::scene2::SceneNode
static std::shared_ptr< SceneNodealloc ()
 
static std::shared_ptr< SceneNodeallocWithPosition (const Vec2 pos)
 
static std::shared_ptr< SceneNodeallocWithPosition (float x, float y)
 
static std::shared_ptr< SceneNodeallocWithBounds (const Size size)
 
static std::shared_ptr< SceneNodeallocWithBounds (float width, float height)
 
static std::shared_ptr< SceneNodeallocWithBounds (const Rect rect)
 
static std::shared_ptr< SceneNodeallocWithBounds (float x, float y, float width, float height)
 
static std::shared_ptr< SceneNodeallocWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data)
 

Protected Member Functions

void visit (const std::shared_ptr< SceneNode > &node, const Affine2 &transform, Color4 tint)
 

Protected Attributes

std::deque< Context * > _entries
 
std::shared_ptr< Scissor_viewport
 
Order _order
 
- Protected Attributes inherited from cugl::scene2::SceneNode
Vec2 _position
 
Vec2 _anchor
 
Size _contentSize
 
Color4 _tintColor
 
bool _hasParentColor
 
bool _isVisible
 
std::shared_ptr< Scissor_scissor
 
Vec2 _scale
 
float _angle
 
Affine2 _transform
 
bool _useTransform
 
Affine2 _combined
 
std::vector< std::shared_ptr< SceneNode > > _children
 
SceneNode_parent
 
Scene2_graph
 
std::shared_ptr< Layout_layout
 
int _childOffset
 
unsigned int _tag
 
std::string _name
 
size_t _hashOfName
 
std::string _classname
 
float _priority
 
std::shared_ptr< JsonValue_json
 

Detailed Description

This is a scene graph node to arbitrary render orders

One of the drawbacks of a scene graph is that it must always render with a pre-order traversal. This is the natural traversal for UI elements, but it is not convenient for character animation (where child components may need to be layered differently).

This node is introduced to solve this problem. For the most part, this node operates just like SceneNode. However, it allows you to resort the render order of the descendents of this node. Simply choose any one of the OrderedNode#Order values available. These orders are applied to the SceneNode#getPriority value of each node in the scene graph.

Any order other than a pre-order traversal comes as a cost, as we must cache the scene graph transform and color context of each node (these values are computed naturally from the recursive calls of a pre-order traversal). In addition, we must call std::sort (currently IntroSort) on all of the descendants every single render pass. However, as long as the number of children of this node is reasonably sized, this should not be an issue.

An OrderedNode is a render barrier. This means that if one OrderedNode (the first node) is a descendant of another OrderedNode (the second node), the first node will be rendered as a unit with the priority of that node. So it is impossible to interleave other descendants of the second node with descendants of the first node. This is necessary as the two OrderedNodes may have incompatible orderings.

Member Enumeration Documentation

◆ Order

This enum represents the possible render orders.

The default render order is PRE_ORDER. When this is set, this node will act like a normal SceneNode. Other orders will create a list of render contexts that will be sorted before rendering. This will incur additional overhead, particularly if the number of descendant nodes is large.

Enumerator
PRE_ORDER 

Render the nodes with a pre-order traversal (DEFAULT)

In a pre-order traversal, the parent is rendered first and then the children. Children are rendered in the order that they are stored in the node.

POST_ORDER 

Render the nodes with a post-order traversal

In a post-order traversal, the children are rendered first and then the parent. Children are rendered in the order that they are stored in the node.

ASCEND 

Render the nodes in ascending order by priority

Children with lower priorities will appear at the back of the scene.

The algorithm for std::sort is an unstable sorting algorithm and does not handle ties well. Hence all ties are broken by the pre-order traveral value.

DESCEND 

Render the nodes in descending order by priority

Children with higher priorities will appear at the back of the scene.

The algorithm for std::sort is an unstable sorting algorithm and does not handle ties well. Hence all ties are broken by the pre-order traveral value.

PRE_ASCEND 

Render the nodes in a pre-order traversal, sorted on ascending priority

This order is still a pre-order traversal where the parent is rendered first and then the children. However, children are sorted with respect to their priority. Children with the lowest priority are drawn first.

PRE_DESCEND 

Render the nodes in a pre-order traversal, sorted on descending priority

This order is still a pre-order traversal where the parent is rendered first and then the children. However, children are sorted with respect to their priority. Children with the highest priority are drawn first.

POST_ASCEND 

Render the nodes in a post-order traversal, sorted on ascending priority

This order is still a pre-order traversal where the children are rendered first and then the parent. However, children are sorted with respect to their priority. Children with the lowest priority are drawn first.

POST_DESCEND 

Render the nodes in a post-order traversal, sorted on descending priority

This order is still a pre-order traversal where the children are rendered first and then the parent. However, children are sorted with respect to their priority. Children with the highest priority are drawn first.

Constructor & Destructor Documentation

◆ OrderedNode()

cugl::scene2::OrderedNode::OrderedNode ( )

Creates an uninitialized ordered node.

You must initialize this OrderedNode before use.

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

◆ ~OrderedNode()

cugl::scene2::OrderedNode::~OrderedNode ( )
inline

Deletes this node, disposing all resources

Member Function Documentation

◆ alloc()

static std::shared_ptr<SceneNode> cugl::scene2::OrderedNode::alloc ( )
inlinestatic

Returns a newly allocated ordered node at the world origin.

The node has both position and size (0,0).

The node will use a pre-order traversal, unless the order is changed with setOrder.

Returns
a newly allocated ordered node at the world origin.

◆ allocWithBounds() [1/4]

static std::shared_ptr<SceneNode> cugl::scene2::OrderedNode::allocWithBounds ( const Rect  rect)
inlinestatic

Returns a newly allocated ordered node with the given bounds.

The rectangle origin is the bottom left corner of the node in parent space, and corresponds to the origin of the Node space. The size defines its content width and height in node space. The node anchor is placed in the bottom left corner.

Because the bounding box is explicit, this is the preferred constructor for nodes that will explicitly contain other nodes.

The node will use a pre-order traversal, unless the order is changed with setOrder.

Parameters
rectThe bounds of the node in parent space
Returns
a newly allocated ordered node with the given bounds.

◆ allocWithBounds() [2/4]

static std::shared_ptr<SceneNode> cugl::scene2::OrderedNode::allocWithBounds ( const Size  size)
inlinestatic

Returns a newly allocated ordered node with the given size.

The size defines the content size. The bounding box of the node is (0,0,width,height) and is anchored in the bottom left corner (0,0). The node is positioned at the origin in parent space.

The node will use a pre-order traversal, unless the order is changed with setOrder.

Parameters
sizeThe size of the node in parent space
Returns
a newly allocated ordered node with the given size.

◆ allocWithBounds() [3/4]

static std::shared_ptr<SceneNode> cugl::scene2::OrderedNode::allocWithBounds ( float  width,
float  height 
)
inlinestatic

Returns a newly allocated node with the given size.

The size defines the content size. The bounding box of the node is (0,0,width,height) and is anchored in the bottom left corner (0,0). The node is positioned at the origin in parent space.

The node will use a pre-order traversal, unless the order is changed with setOrder.

Parameters
widthThe width of the node in parent space
heightThe height of the node in parent space
Returns
a newly allocated ordered node with the given size.

◆ allocWithBounds() [4/4]

static std::shared_ptr<SceneNode> cugl::scene2::OrderedNode::allocWithBounds ( float  x,
float  y,
float  width,
float  height 
)
inlinestatic

Returns a newly allocated ordered node with the given bounds.

The rectangle origin is the bottom left corner of the node in parent space, and corresponds to the origin of the Node space. The size defines its content width and height in node space. The node anchor is placed in the bottom left corner.

Because the bounding box is explicit, this is the preferred constructor for Nodes that will explicitly contain other Nodes.

The node will use a pre-order traversal, unless the order is changed with setOrder.

Parameters
xThe x-coordinate of the node origin in parent space
yThe y-coordinate of the node origin in parent space
widthThe width of the node in parent space
heightThe height of the node in parent space
Returns
a newly allocated node with the given bounds.

◆ allocWithData()

static std::shared_ptr<OrderedNode> cugl::scene2::OrderedNode::allocWithData ( const Scene2Loader loader,
const std::shared_ptr< JsonValue > &  data 
)
inlinestatic

Returns a newly allocated ordered node with the given JSON specificaton.

This initializer is designed to receive the "data" object from the JSON passed to Scene2Loader. This JSON format supports all of the attribute values of its parent class. In addition, it supports the following additional attributes:

 "order":    The sort order of this node.

Sort orders are specified as lower case strings representing the names of the enum with dashes in place of underscores (e.g. "pre-order", "post-ascend"). All attributes are optional. There are no required attributes.

Parameters
loaderThe scene loader passing this JSON file
dataThe JSON object specifying the node
Returns
a newly allocated ordered node with the given JSON specificaton.

◆ allocWithOrder() [1/3]

static std::shared_ptr<OrderedNode> cugl::scene2::OrderedNode::allocWithOrder ( Order  order)
inlinestatic

Returns a newly allocated ordered node at the world origin with the given order.

The node has both position and size (0,0).

Parameters
orderThe render order
Returns
a newly allocated ordered node at the world origin with the given order.

◆ allocWithOrder() [2/3]

static std::shared_ptr<OrderedNode> cugl::scene2::OrderedNode::allocWithOrder ( Order  order,
Rect  bounds 
)
inlinestatic

Returns a newly allocated ordered node with the given bounds.

The rectangle origin is the bottom left corner of the node in parent space, and corresponds to the origin of the Node space. The size defines its content width and height. The node is anchored in the center and has position origin-(width/2,height/2) in parent space.

Because the bounding box is explicit, this is the preferred initializer for Nodes that will explicitly contain other Nodes.

Parameters
orderThe render order
boundsThe bounds of the node in parent space
Returns
a newly allocated ordered node with the given bounds.

◆ allocWithOrder() [3/3]

static std::shared_ptr<OrderedNode> cugl::scene2::OrderedNode::allocWithOrder ( Order  order,
Vec2  pos 
)
inlinestatic

Returns a newly allocated ordered node with the given position and order.

The node has size (0,0). As a result, the position is identified with the origin of the node space.

Parameters
orderThe render order
posThe origin of the node in parent space
Returns
a newly allocated ordered node with the given position and order.

◆ allocWithPosition() [1/2]

static std::shared_ptr<SceneNode> cugl::scene2::OrderedNode::allocWithPosition ( const Vec2  pos)
inlinestatic

Returns a newly allocated ordered node at the given position.

The node has size (0,0). As a result, the position is identified with the origin of the node space.

The node will use a pre-order traversal, unless the order is changed with setOrder.

Parameters
posThe origin of the node in parent space
Returns
a newly allocated ordered node at the given position.

◆ allocWithPosition() [2/2]

static std::shared_ptr<SceneNode> cugl::scene2::OrderedNode::allocWithPosition ( float  x,
float  y 
)
inlinestatic

Returns a newly allocated ordered node at the given position.

The node has size (0,0). As a result, the position is identified with the origin of the node space.

The node will use a pre-order traversal, unless the order is changed with setOrder.

Parameters
xThe x-coordinate of the node in parent space
yThe y-coordinate of the node in parent space
Returns
a newly allocated ordered node at the given position.

◆ CU_DISALLOW_COPY_AND_ASSIGN()

cugl::scene2::OrderedNode::CU_DISALLOW_COPY_AND_ASSIGN ( OrderedNode  )

This macro disables the copy constructor (not allowed on scene graphs)

◆ dispose()

virtual void cugl::scene2::OrderedNode::dispose ( )
overridevirtual

Disposes all of the resources used by this node.

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

It is unsafe to call this on a OrderedNode that is still currently inside of a scene graph.

Reimplemented from cugl::scene2::SceneNode.

◆ getOrder()

Order cugl::scene2::OrderedNode::getOrder ( ) const
inline

Returns the render order of this node

This render order will be applied to all descendants of this node. However, other instances of OrderedNode constitute a render boundary. While the ordered nodes themselves will be resorted, their children will not.

The default value of Order#PRE_ORDER will default to the normal render algorithm and is therefore the most efficient.

Returns
the render order of this node

◆ initWithData()

virtual bool cugl::scene2::OrderedNode::initWithData ( const Scene2Loader loader,
const std::shared_ptr< JsonValue > &  data 
)
overridevirtual

Initializes a node with the given JSON specificaton.

This initializer is designed to receive the "data" object from the JSON passed to Scene2Loader. This JSON format supports all of the attribute values of its parent class. In addition, it supports the following additional attributes:

 "order":    The sort order of this node.

Sort orders are specified as lower case strings representing the names of the enum with dashes in place of underscores (e.g. "pre-order", "post-ascend"). All attributes are optional. There are no required attributes.

Parameters
loaderThe scene loader passing this JSON file
dataThe JSON object specifying the node
Returns
true if initialization was successful.

Reimplemented from cugl::scene2::SceneNode.

◆ initWithOrder() [1/3]

bool cugl::scene2::OrderedNode::initWithOrder ( Order  order)

Initializes an ordered node at the world origin with the given order.

The node has both position and size (0,0).

Parameters
orderThe render order
Returns
true if initialization was successful.

◆ initWithOrder() [2/3]

bool cugl::scene2::OrderedNode::initWithOrder ( Order  order,
Rect  bounds 
)

Initializes an ordered node with the given bounds.

The rectangle origin is the bottom left corner of the node in parent space, and corresponds to the origin of the Node space. The size defines its content width and height. The node is anchored in the center and has position origin-(width/2,height/2) in parent space.

Because the bounding box is explicit, this is the preferred initializer for Nodes that will explicitly contain other Nodes.

Parameters
orderThe render order
boundsThe bounds of the node in parent space
Returns
true if initialization was successful.

◆ initWithOrder() [3/3]

bool cugl::scene2::OrderedNode::initWithOrder ( Order  order,
Vec2  pos 
)

Initializes an ordered node with the given position and order.

The node has size (0,0). As a result, the position is identified with the origin of the node space.

Parameters
orderThe render order
posThe origin of the node in parent space
Returns
true if initialization was successful.

◆ render() [1/2]

virtual void cugl::scene2::OrderedNode::render ( const std::shared_ptr< SpriteBatch > &  batch)
inlineoverridevirtual

Draws this node and all of its children with the given SpriteBatch.

By default, this will revert to the render method of SceneNode. However if the order is anything other than Order#PRE_ORDER, it will construct a render queue of all children. This render queue will bypass all calls to SceneNode#render and instead call SceneNode#draw. This is why it is important for all custom subclasses of SceneNode to override draw instead of render.

Parameters
batchThe SpriteBatch to draw with.

Reimplemented from cugl::scene2::SceneNode.

◆ render() [2/2]

void cugl::scene2::OrderedNode::render ( const std::shared_ptr< SpriteBatch > &  batch,
const Affine2 transform,
Color4  tint 
)
overridevirtual

Draws this node and all of its children with the given SpriteBatch.

By default, this will revert to the render method of SceneNode. However if the order is anything other than Order#PRE_ORDER, it will construct a render queue of all children. This render queue will bypass all calls to SceneNode#render and instead call SceneNode#draw. This is why it is important for all custom subclasses of SceneNode to override draw instead of render.

Parameters
batchThe SpriteBatch to draw with.
transformThe global transformation matrix.
tintThe tint to blend with the node color.

Reimplemented from cugl::scene2::SceneNode.

◆ setOrder()

void cugl::scene2::OrderedNode::setOrder ( Order  order)
inline

Sets the render order of this node

This render order will be applied to all descendants of this node. However, other instances of OrderedNode constitute a render boundary. While the ordered nodes themselves will be resorted, their children will not.

The default value of Order#PRE_ORDER will default to the normal render algorithm and is therefore the most efficient.

Parameters
orderThe render order of this node

◆ visit()

void cugl::scene2::OrderedNode::visit ( const std::shared_ptr< SceneNode > &  node,
const Affine2 transform,
Color4  tint 
)
protected

Adds the given node ot the render queue.

This method replaces render to provide a delayed render command (via a queue of Context objects). This method is recursive. However, it will stop when it encounters any other OrderedNode objects.

Parameters
nodeThe descendant node to render.
transformThe global transformation matrix.
tintThe tint to blend with the node color.

Member Data Documentation

◆ _entries

std::deque<Context*> cugl::scene2::OrderedNode::_entries
protected

The render queue (always use a deque for this functionality)

◆ _order

Order cugl::scene2::OrderedNode::_order
protected

The current render order

◆ _viewport

std::shared_ptr<Scissor> cugl::scene2::OrderedNode::_viewport
protected

The global scissor context (necessary as sprite batches manage this normally)


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