#include <CUOrderedNode.h>

Inheritance diagram for cugl::scene2::OrderedNode:

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< SceneNode >	copy (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< Scissor >	getScissor () 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 Affine2 &	getTransform () const

const Affine2 &	getAlternateTransform () const

void	setAlternateTransform (const Affine2 &transform)

bool	withAlternateTransform ()

void	chooseAlternateTransform (bool active)

const Affine2 &	getNodeToParentTransform () 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< 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

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)

SceneNode *	getParent ()

const SceneNode *	getParent () const

Scene2 *	getScene ()

const Scene2 *	getScene () 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< SceneNode >	alloc ()

static std::shared_ptr< SceneNode >	allocWithPosition (const Vec2 pos)

static std::shared_ptr< SceneNode >	allocWithPosition (float x, float y)

static std::shared_ptr< SceneNode >	allocWithBounds (const Size size)

static std::shared_ptr< SceneNode >	allocWithBounds (float width, float height)

static std::shared_ptr< SceneNode >	allocWithBounds (const Rect rect)

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

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

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

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

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

Static Public Member Functions inherited from cugl::scene2::SceneNode
static std::shared_ptr< SceneNode >	alloc ()

static std::shared_ptr< SceneNode >	allocWithPosition (const Vec2 pos)

static std::shared_ptr< SceneNode >	allocWithPosition (float x, float y)

static std::shared_ptr< SceneNode >	allocWithBounds (const Size size)

static std::shared_ptr< SceneNode >	allocWithBounds (float width, float height)

static std::shared_ptr< SceneNode >	allocWithBounds (const Rect rect)

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

static std::shared_ptr< SceneNode >	allocWithData (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

enum cugl::scene2::OrderedNode::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

rect	The 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

size	The 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

width	The width of the node in parent space
height	The 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

x	The x-coordinate of the node origin in parent space
y	The y-coordinate of the node origin in parent space
width	The width of the node in parent space
height	The 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

loader	The scene loader passing this JSON file
data	The 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

order The 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

order	The render order
bounds	The 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

order	The render order
pos	The 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

pos	The 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

x	The x-coordinate of the node in parent space
y	The 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

loader	The scene loader passing this JSON file
data	The 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

order The 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

order	The render order
bounds	The 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

order	The render order
pos	The 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

batch The 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

batch	The SpriteBatch to draw with.
transform	The global transformation matrix.
tint	The 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

order The 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

node	The descendant node to render.
transform	The global transformation matrix.
tint	The 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:

include/cugl/scene2/graph/CUOrderedNode.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ Order

Constructor & Destructor Documentation

◆ OrderedNode()

◆ ~OrderedNode()

Member Function Documentation

◆ alloc()

◆ allocWithBounds() [1/4]

◆ allocWithBounds() [2/4]

◆ allocWithBounds() [3/4]

◆ allocWithBounds() [4/4]

◆ allocWithData()

◆ allocWithOrder() [1/3]

◆ allocWithOrder() [2/3]

◆ allocWithOrder() [3/3]

◆ allocWithPosition() [1/2]

◆ allocWithPosition() [2/2]

◆ CU_DISALLOW_COPY_AND_ASSIGN()

◆ dispose()

◆ getOrder()

◆ initWithData()

◆ initWithOrder() [1/3]

◆ initWithOrder() [2/3]

◆ initWithOrder() [3/3]

◆ render() [1/2]

◆ render() [2/2]

◆ setOrder()

◆ visit()

Member Data Documentation

◆ _entries

◆ _order

◆ _viewport