#include <CUSceneNode.h>

Inheritance diagram for cugl::scene2::SceneNode:

Public Member Functions
	SceneNode ()

	~SceneNode ()

virtual void	dispose ()

virtual bool	init ()

virtual bool	initWithPosition (const Vec2 pos)

bool	initWithPosition (float x, float y)

virtual bool	initWithBounds (const Size size)

bool	initWithBounds (float width, float height)

virtual bool	initWithBounds (const Rect rect)

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

virtual bool	initWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data)

virtual SceneNode *	copy (SceneNode *dst)

unsigned int	getTag () const

void	setTag (unsigned int tag)

const std::string &	getName () const

void	setName (const std::string &name)

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)

Size	getSize () const

float	getWidth () const

float	getHeight () const

Rect	getBoundingBox () const

virtual void	setAnchor (const Vec2 anchor)

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

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 Mat4 &	getAlternateTransform ()

void	setAlternateTransform (const Mat4 &transform)

bool	withAlternateTransform ()

void	chooseAlternateTransform (bool active)

const Mat4 &	getNodeToParentTransform () const

Mat4	getParentToNodeTransform () const

Mat4	getNodeToWorldTransform () const

Mat4	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

void	setZOrder (int z)

int	getZOrder () const

bool	isZDirty () const

void	sortZOrder ()

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 (std::shared_ptr< SceneNode > child)

virtual void	addChild (const std::shared_ptr< SceneNode > &child, int zval)

void	addChildWithTag (const std::shared_ptr< SceneNode > &child, unsigned int tag)

void	addChildWithTag (const std::shared_ptr< SceneNode > &child, unsigned int tag, int zval)

void	addChildWithName (const std::shared_ptr< SceneNode > &child, const std::string &name)

void	addChildWithName (const std::shared_ptr< SceneNode > &child, const std::string &name, int zval)

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

virtual void	render (const std::shared_ptr< SpriteBatch > &batch, const Mat4 &transform, Color4 tint)

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

virtual void	draw (const std::shared_ptr< SpriteBatch > &batch, const Mat4 &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< SceneNode >	allocWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data)

Protected Attributes
Vec2	_position

Vec2	_anchor

Size	_contentSize

Color4	_tintColor

bool	_hasParentColor

bool	_isVisible

std::shared_ptr< Scissor >	_scissor

Vec2	_scale

float	_angle

Mat4	_transform

bool	_useTransform

Mat4	_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

int	_zOrder

bool	_zDirty

std::shared_ptr< JsonValue >	_json

Friends
class	cugl::Scene2

Detailed Description

This class provides a 2d scene graph node.

A base node is a rectangular space that can contain other (transformed) nodes. Each Node forms a its own coordinate space. All rendering takes place inside of this coordinate space. By default, a Node does not render anything, but it does provide rendering support for subclasses via the draw() method.

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.

Nodes 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 children are composed.

One of the important pitfalls of the Node class is that the position of a a Node does not necessarily define the position of its Node-space origin. That means that transforms applied to the Node do not necessarily leave the Node position unaffected.

That is why it is important to understand the difference between the anchor and the origin. Each Node is a rectangular bounding-box, and its origin is the bottom left corner. However, the anchor can be any point inside of the bounding box. The scale and angle are applied to the anchor point, NOT the Node origin. If you want to apply a traditional transform to the Node origin, you will need to use the setAlternateTransform() option.

In addition, when a Node is resized, the resizing takes place relative to the anchor point. That means that the position is unchanged, but the node origin may move. However, if the anchor is altered, the Node itself does not move while the position changes. While this may seem counter-intuitive, this is traditional sprite behavior, and scene graph nodes are just a generalization of a sprite.

Constructor & Destructor Documentation

◆ SceneNode()

cugl::scene2::SceneNode::SceneNode ( )

Creates an uninitialized node.

You must initialize this Node before use.

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

◆ ~SceneNode()

cugl::scene2::SceneNode::~SceneNode ( )

inline

Deletes this node, disposing all resources

Member Function Documentation

◆ addChild() [1/2]

virtual void cugl::scene2::SceneNode::addChild	(	const std::shared_ptr< SceneNode > &	child,
		int	zval
	)

virtual

Adds a child to this node 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.

Parameters

child	A child node.
zval	The (new) child z-order.

◆ addChild() [2/2]

void cugl::scene2::SceneNode::addChild ( std::shared_ptr< SceneNode > child )

inline

Adds a child to this node.

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

child A child node.

◆ addChildWithName() [1/2]

void cugl::scene2::SceneNode::addChildWithName	(	const std::shared_ptr< SceneNode > &	child,
		const std::string &	name
	)

inline

Adds a child to this node 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.

Parameters

child	A child node.
name	A string to identify the node.

◆ addChildWithName() [2/2]

void cugl::scene2::SceneNode::addChildWithName	(	const std::shared_ptr< SceneNode > &	child,
		const std::string &	name,
		int	zval
	)

inline

Adds a child to this node 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.

Parameters

child	A child node.
name	A string to identify the node.
zval	The (new) child z-order.

◆ addChildWithTag() [1/2]

void cugl::scene2::SceneNode::addChildWithTag	(	const std::shared_ptr< SceneNode > &	child,
		unsigned int	tag
	)

inline

Adds a child to this node 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.

Parameters

child	A child node.
tag	An integer to identify the node easily.

◆ addChildWithTag() [2/2]

void cugl::scene2::SceneNode::addChildWithTag	(	const std::shared_ptr< SceneNode > &	child,
		unsigned int	tag,
		int	zval
	)

inline

Adds a child to this node 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.

Parameters

child	A child node.
tag	An integer to identify the node easily.
zval	The (new) child z-order.

◆ alloc()

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

inlinestatic

Returns a newly allocated node at the world origin.

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

Returns: a newly allocated node at the world origin.

◆ allocWithBounds() [1/4]

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

inlinestatic

Returns a newly allocated 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 constructor for Nodes that will explicitly contain other Nodes.

Parameters

rect	The bounds of the node in parent space

Returns: a newly allocated node with the given bounds.

◆ allocWithBounds() [2/4]

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

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). Hence the node is anchored in the center and has position (width/2,height/2) in the parent space. The node origin is the (0,0) at the bottom left corner of the bounding box.

Parameters

size	The size of the node in parent space

Returns: a newly allocated node with the given size.

◆ allocWithBounds() [3/4]

static std::shared_ptr<SceneNode> cugl::scene2::SceneNode::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). Hence the node is anchored in the center and has position (width/2,height/2) in the parent space. The node origin is the (0,0) at the bottom left corner of the bounding box.

Parameters

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

◆ allocWithBounds() [4/4]

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

inlinestatic

Returns a newly allocated 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 constructor for Nodes that will explicitly contain other Nodes.

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<SceneNode> cugl::scene2::SceneNode::allocWithData	(	const Scene2Loader *	loader,
		const std::shared_ptr< JsonValue > &	data
	)

inlinestatic

Returns a newly allocated node with the given JSON specification.

This initializer is designed to receive the "data" object from the JSON passed to Scene2Loader. This JSON format supports the following attribute values:

 "position": A two-element number array
 "size":     A two-element number array
 "anchor":   A two-element number array representing the anchor point
 "color":    A four-element integer array.  Values should be 0..255
 "scale":    A two-element number array
 "angle":    A number, representing the rotation in DEGREES, not radians
 "visible":  A boolean value, representing if the node is visible

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 node with the given JSON specification.

◆ allocWithPosition() [1/2]

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

inlinestatic

Returns a newly allocated 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.

Parameters

pos	The origin of the node in parent space

Returns: a newly allocated node at the given position.

◆ allocWithPosition() [2/2]

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

inlinestatic

Returns a newly allocated 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.

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 node at the given position.

◆ chooseAlternateTransform()

void cugl::scene2::SceneNode::chooseAlternateTransform ( bool active )

inline

Set whether the Node is using the alternate transform.

Unlike the built-in scaling and rotation, the alternate transform is applied to the coordinate space of the Node (e.g. with the origin in the bottom left corner).

Scaling/rotation and the alternate transform do no play nice with each other. It does not make sense to stack them on top of one another in either direction. Hence, you should only use of of the two. This method determines whether the alternate transform is in use.

Parameters

active Whether the Node is using the alternate transform.

◆ copy()

virtual SceneNode* cugl::scene2::SceneNode::copy ( SceneNode * dst )

virtual

Performs a shallow copy of this Node into dst.

No children from this node are copied, and no children of dst are modified. In addition, the parents of both Nodes are unchanged. However, all other attributes of this node are copied.

Parameters

dst	The Node to copy into

Returns: A reference to dst for chaining.

◆ dispose()

virtual void cugl::scene2::SceneNode::dispose ( )

virtual

Disposes all of the resources used by this node.

A disposed Node 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 Node that is still currently inside of a scene graph.

Reimplemented in cugl::scene2::Label, cugl::scene2::Slider, cugl::scene2::TextField, cugl::scene2::Button, cugl::scene2::TexturedNode, cugl::scene2::NinePatch, and cugl::scene2::ProgressBar.

◆ doLayout()

virtual void cugl::scene2::SceneNode::doLayout ( )

virtual

Arranges the child of this node using the layout manager.

This process occurs recursively and top-down. A layout manager may end up resizing the children. That is why the parent must finish its layout before we can apply a layout manager to the children.

Reimplemented in cugl::scene2::Button.

◆ draw()

virtual void cugl::scene2::SceneNode::draw	(	const std::shared_ptr< SpriteBatch > &	batch,
		const Mat4 &	transform,
		Color4	tint
	)

inlinevirtual

Draws this Node via the given SpriteBatch.

This method only worries about drawing the current node. It does not attempt to render the children.

This is the method that you should override to implement your custom drawing code. You are welcome to use any OpenGL commands that you wish. You can even skip use of the SpriteBatch. However, if you do so, you must flush the SpriteBatch by calling end() at the start of the method. in addition, you should remember to call begin() at the start of the method.

This method provides the correct transformation matrix and tint color. You do not need to worry about whether the node uses relative color.
This method is called by render() and these values are guaranteed to be correct. In addition, this method does not need to check for visibility, as it is guaranteed to only be called when the node is visible.

Parameters

batch	The SpriteBatch to draw with.
transform	The global transformation matrix.
tint	The tint to blend with the Node color.

Reimplemented in cugl::scene2::TexturedNode, cugl::scene2::Label, cugl::scene2::PathNode, cugl::scene2::TextField, cugl::scene2::NinePatch, cugl::scene2::WireNode, and cugl::scene2::PolygonNode.

◆ getAbsoluteColor()

Color4 cugl::scene2::SceneNode::getAbsoluteColor ( )

Returns the absolute color tinting this node.

If hasRelativeColor() is true, this value is the base color multiplied by the absolute color of its parent. If hasRelativeColor() is false, it is the same as the tint color.

Returns: the absolute color tinting this node.

◆ getAlternateTransform()

const Mat4& cugl::scene2::SceneNode::getAlternateTransform ( )

inline

Returns the alternate transform of this node.

Unlike the built-in scaling and rotation, this transform is applied to the coordinate space of the Node (e.g. with the origin in the bottom left corner).

Scaling/rotation and the alternate transform do no play nice with each other. It does not make sense to stack them on top of one another in either direction. Hence, you should only use of of the two. See the method chooseAlternateTransform(bool) to choose.

Returns: the alternate transform of this node.

◆ getAnchor()

const Vec2 cugl::scene2::SceneNode::getAnchor ( ) const

inline

Returns the anchor point in percent.

The anchor point defines the relative origin of Node with respect to its parent. It is a "pin" where the Node is attached to its parent. In effect, the translation of a Node is defined by its position plus anchor point.

The anchorPoint is normalized, like a percentage. (0,0) means the bottom-left corner and (1,1) means the top-right corner. There are many anchor point constants defined in Vec2. However, there is nothing preventing an anchor point higher than (1,1) or lower than (0,0).

The default anchorPoint is (0.5,0.5), so it starts in the center of the node. Changing the anchor will not move the contents of the node in the parent space, but it will change the value of the Node position.

Returns: The anchor point in percent.

◆ getAnchorInPixels()

Vec2 cugl::scene2::SceneNode::getAnchorInPixels ( )

inline

Returns the anchor point in pixels.

The anchor point defines the relative origin of Node with respect to its parent. It is a "pin" where the Node is attached to its parent. In effect, the translation of a Node is defined by its position plus anchor point.

This version of the anchor point is multiplied by the size of the Node bounding box. Hence (0,0) means the bottom-left corner and (width,height) means the top-right corner.

Returns: The anchor point in percent.

◆ getAngle()

float cugl::scene2::SceneNode::getAngle ( )

inline

Returns the rotation angle of this node.

This value rotates the node about the anchor, with the anchor unmoved.
The angle is measured in radians , counter-clockwise from the x-axis. Rotation is applied after scaling.

Returns: the rotation angle of this node.

◆ getBoundingBox()

Rect cugl::scene2::SceneNode::getBoundingBox ( ) const

inline

Returns an AABB (axis-aligned bounding-box) in the parent's coordinates.

This method returns the minimal axis-aligned bounding box that contains the transformed node in its parents coordinate system. If the node is rotated, this may not be a perfect fit of the transformed contents.

Returns: An AABB (axis-aligned bounding-box) in the parent's coordinates.

◆ getChild() [1/3]

std::shared_ptr<SceneNode> cugl::scene2::SceneNode::getChild ( unsigned int pos )

Returns the child at the given position.

Children are not necessarily enumerated in the order that they are added. For example, they may be resorted by their z-order. Hence you should generally attempt to retrieve a child by tag or by name instead.

Parameters

pos	The child position.

Returns: the child at the given position.

◆ getChild() [2/3]

const std::shared_ptr<SceneNode>& cugl::scene2::SceneNode::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.

Parameters

pos	The child position.

Returns: the child at the given position.

◆ getChild() [3/3]

template<typename T >

std::shared_ptr<T> cugl::scene2::SceneNode::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. For example, they may be resorted by their z-order. Hence you should generally attempt to retrieve a child by tag or by name instead.

Parameters

pos	The child position.

Returns: the child at the given position, typecast to a shared T pointer.

◆ getChildByName() [1/2]

std::shared_ptr<SceneNode> cugl::scene2::SceneNode::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. For the base Node class, children are always enumerated in the order that they are added. However, this is not guaranteed for subclasses of Node. Hence it is very important that names be unique.

Parameters

name	An identifier to find the child node.

Returns: the (first) child with the given name.

◆ getChildByName() [2/2]

template<typename T >

std::shared_ptr<T> cugl::scene2::SceneNode::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. For the base Node class, children are always enumerated in the order that they are added. However, this is not guaranteed for subclasses of Node. Hence it is very important that names be unique.

Parameters

name	An identifier to find the child node.

Returns: the (first) child with the given name, typecast to a shared T pointer.

◆ getChildByTag() [1/2]

std::shared_ptr<SceneNode> cugl::scene2::SceneNode::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. For the base Node class, children are always enumerated in the order that they are added. However, this is not guaranteed for subclasses of Node. Hence it is very important that tags be unique.

Parameters

tag	An identifier to find the child node.

Returns: the (first) child with the given tag.

◆ getChildByTag() [2/2]

template<typename T >

std::shared_ptr<T> cugl::scene2::SceneNode::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. For the base Node class, children are always enumerated in the order that they are added. However, this is not guaranteed for subclasses of Node. Hence it is very important that tags be unique.

Parameters

tag	An identifier to find the child node.

Returns: the (first) child with the given tag, typecast to a shared T pointer.

◆ getChildCount()

size_t cugl::scene2::SceneNode::getChildCount ( ) const

inline

Returns the number of children of this node.

Returns: The number of children of this node.

◆ getChildren() [1/2]

std::vector<std::shared_ptr<SceneNode> > cugl::scene2::SceneNode::getChildren ( )

inline

Returns the list of the node's children.

Returns: the list of the node's children.

◆ getChildren() [2/2]

const std::vector<std::shared_ptr<SceneNode> >& cugl::scene2::SceneNode::getChildren ( ) const

inline

Returns the list of the node's children.

Returns: the list of the node's children.

◆ getColor()

Color4 cugl::scene2::SceneNode::getColor ( ) const

inline

Returns the color tinting this node.

This color will be multiplied with the parent (this node on top) if hasRelativeColor() is true.

The default color is white, which means that all children have their natural color.

Returns: the color tinting this node.

◆ getContentHeight()

float cugl::scene2::SceneNode::getContentHeight ( ) const

inline

Returns the untransformed height of the node.

The content height remains the same no matter how the node is scaled or rotated. All nodes must have a height, though it may be degenerate (0).

Returns: the untransformed height of the node.

◆ getContentSize()

const Size cugl::scene2::SceneNode::getContentSize ( ) const

inline

Returns the untransformed size of the node.

The content size remains the same no matter how the node is scaled or rotated. All nodes must have a size, though it may be degenerate (0,0).

Returns: the untransformed size of the node.

◆ getContentWidth()

float cugl::scene2::SceneNode::getContentWidth ( ) const

inline

Returns the untransformed width of the node.

The content width remains the same no matter how the node is scaled or rotated. All nodes must have a width, though it may be degenerate (0).

Returns: the untransformed width of the node.

◆ getHeight()

float cugl::scene2::SceneNode::getHeight ( ) const

inline

Returns the transformed height of the node.

This method returns the height of the axis-aligned bounding box that contains the transformed node in its parents coordinate system. If the node is rotated, this may not be a perfect fit of the transformed contents.

Returns: the transformed height of the node.

◆ getLayout()

const std::shared_ptr<Layout>& cugl::scene2::SceneNode::getLayout ( ) const

inline

Returns the layout manager for this node

We had originally intended to completely decouple layout managers from nodes. However, nodes (including layout assignemnts) are typically built bottom-up, while layout must happen top down to correctly resize elements. Therefore, we do allow the addition of an optional layout manager.

Returns: the layout manager for this node

◆ getName()

const std::string& cugl::scene2::SceneNode::getName ( ) const

inline

Returns a string that is used to identify the node.

This name is used to access a child node, since child position may change. In addition, the name is useful for debugging. To work properly, a name should be unique within a scene graph. It is empty if undefined.

Returns: a string that is used to identify the node.

◆ getNodeToParentTransform()

const Mat4& cugl::scene2::SceneNode::getNodeToParentTransform ( ) const

inline

Returns the matrix transforming node space to parent space.

This value is the node's transform. It is either computed from the scale and rotation about the anchor, or the alternate transform, as determined by defined by chooseAlternateTransform(bool).

Returns: the matrix transforming node space to parent space.

◆ getNodeToWorldTransform()

Mat4 cugl::scene2::SceneNode::getNodeToWorldTransform ( ) const

Returns the matrix transforming node space to world space.

This matrix is used to convert node coordinates into OpenGL coordinates. It is the recursive (left-multiplied) node-to-parent transforms of all of its ancestors.

Returns: the matrix transforming node space to world space.

◆ getParent() [1/2]

SceneNode* cugl::scene2::SceneNode::getParent ( )

inline

Returns a (weak) pointer to the parent node.

The purpose of this pointer is to climb back up the scene graph tree. No child asserts ownership of its parent.

Returns: a (weak) pointer to the parent node.

◆ getParent() [2/2]

const SceneNode* cugl::scene2::SceneNode::getParent ( ) const

inline

Returns a (weak) pointer to the parent node.

The purpose of this pointer is to climb back up the scene graph tree. No child asserts ownership of its parent.

Returns: a (weak) pointer to the parent node.

◆ getParentToNodeTransform()

Mat4 cugl::scene2::SceneNode::getParentToNodeTransform ( ) const

inline

Returns the matrix transforming parent space to node space.

This value is the inverse that node's transform. It is either computed from the scale and rotation about the anchor, or the alternate transform, as determined by defined by chooseAlternateTransform(bool).

Returns: the matrix transforming parent space to node space.

◆ getPosition()

const Vec2 cugl::scene2::SceneNode::getPosition ( ) const

inline

Returns the position of the node in its parent's coordinate system.

The node position is not necessarily the origin of the Node coordinate system. The relationship between the position and Node space is determined by the anchor point. See getAnchor() for more details.

Returns: the position of the node in its parent's coordinate system.

◆ getPositionX()

float cugl::scene2::SceneNode::getPositionX ( void ) const

inline

Returns the x-coordinate of the node in its parent's coordinate system.

The node position is not necessarily the origin of the Node coordinate system. The relationship between the position and Node space is determined by the anchor point. See getAnchor() for more details.

Returns: the x-coordinate of the node in its parent's coordinate system.

◆ getPositionY()

float cugl::scene2::SceneNode::getPositionY ( void ) const

inline

Returns the y-coordinate of the node in its parent's coordinate system.

The node position is not necessarily the origin of the Node coordinate system. The relationship between the position and Node space is determined by the anchor point. See getAnchor() for more details.

Returns: the y-coordinate of the node in its parent's coordinate system.

◆ getScale()

const Vec2 cugl::scene2::SceneNode::getScale ( ) const

inline

Returns the non-uniform scaling factor for this node about the anchor.

This factor scales the node about the anchor (with the anchor unmoved). Hence this is not the same as a scale applied to Node space, as the origin is in the bottom left corner. Scaling is first, before any other transforms.

Returns: the non-uniform scaling factor for this node about the anchor

◆ getScaleX()

float cugl::scene2::SceneNode::getScaleX ( ) const

inline

Returns the x-axis scaling factor for this node.

This factor scales the node about the anchor (with the anchor unmoved). Hence this is not the same as a scale applied to Node space, as the origin is in the bottom left corner. Scaling is first, before any other transforms.

Returns: the x-axis scaling factor for this node.

◆ getScaleY()

float cugl::scene2::SceneNode::getScaleY ( ) const

inline

Returns the y-axis scaling factor for this node.

This factor scales the node about the anchor (with the anchor unmoved). Hence this is not the same as a scale applied to Node space, as the origin is in the bottom left corner. Scaling is first, before any other transforms.

Returns: the y-axis scaling factor for this node.

◆ getScene() [1/2]

Scene2* cugl::scene2::SceneNode::getScene ( )

inline

Returns a (weak) pointer to the scene graph.

The purpose of this pointer is to climb back up to the root of the scene graph tree. No node asserts ownership of its scene.

Returns: a (weak) pointer to the scene graph.

◆ getScene() [2/2]

const Scene2* cugl::scene2::SceneNode::getScene ( ) const

inline

Returns a (weak) pointer to the scene graph.

The purpose of this pointer is to climb back up to the root of the scene graph tree. No node asserts ownership of its scene.

Returns: a (weak) pointer to the scene graph.

◆ getScissor()

std::shared_ptr<Scissor> cugl::scene2::SceneNode::getScissor ( ) const

inline

Returns the scissor associated with this node.

SceneNodes are just coordinate spaces. Any child outside of the content area is still drawn; the content area value is primarily used for anchor placement. If you want to obscure (parts of) children that are outside the content area, you will need to set a scissor.

The scissor does not need to be set to the content area. It can by any scissor, and that scissor will be applied to the coordinate system of this node. To create a scissor that will restrict to the node content area, simply construct

Scissor::alloc(getContentSize())

It is possible for the children of a node to have a scissor as well. When that happens, the children will be rendered with the intersection of the two scissors. However, if the child is rotated, then its scissor will be oriented to be aligned with the parent scissor, as we can only intersect two rectangles of the same orientation. The rule for this intersection will be the same as Scissor#intersect.

Returns: the scissor associated with this node.

◆ getSize()

Size cugl::scene2::SceneNode::getSize ( ) const

Returns the transformed size of the node.

This method returns the size of the axis-aligned bounding box that contains the transformed node in its parents coordinate system. If the node is rotated, this may not be a perfect fit of the transformed contents.

Returns: the transformed size of the node.

◆ getTag()

unsigned int cugl::scene2::SceneNode::getTag ( ) const

inline

Returns a tag that is used to identify the node easily.

This tag is used to quickly access a child node, since child position may change. To work properly, a tag should be unique within a scene graph. It is 0 if undefined.

Returns: a tag that is used to identify the node easily.

◆ getWidth()

float cugl::scene2::SceneNode::getWidth ( ) const

inline

Returns the transformed width of the node.

This method returns the width of the axis-aligned bounding box that contains the transformed node in its parents coordinate system. If the node is rotated, this may not be a perfect fit of the transformed contents.

Returns: the transformed width of the node.

◆ getWorldPosition()

Vec2 cugl::scene2::SceneNode::getWorldPosition ( ) const

inline

Returns the position of the anchor point node in OpenGL space.

Note that this is the position of the anchor point. This is not the same as the location of the node origin in world space.

Returns: the position of this node in OpenGL space.

◆ getWorldToNodeTransform()

Mat4 cugl::scene2::SceneNode::getWorldToNodeTransform ( ) const

inline

Returns the matrix transforming node space to world space.

This matrix is used to convert OpenGL coordinates into node coordinates. This method is useful for converting global positions like touches or mouse clicks. It is the recursive (right-multiplied) parent-to-node transforms of all of its ancestors.

Returns: the matrix transforming node space to world space.

◆ getZOrder()

int cugl::scene2::SceneNode::getZOrder ( ) const

inline

Returns the value used to 'sort' a node relative to its siblings.

The z-order determines the drawing order of the children. If two nodes have the same z-order, they are drawn in the order that they were added to their parent.

The z-order is not an actual z-value. Attempting to interpret it other wise would result in an interleaving of children, which is not what we want in a scene graph.

Sorting does not happen automatically (except within a Scene2). It is the responsibility of a user to sort the z-order before a call to render. Otherwise, render order will be in the unsorted order.

Returns: the value used to 'sort' a node relative to its siblings.

◆ hasRelativeColor()

bool cugl::scene2::SceneNode::hasRelativeColor ( )

inline

Returns true if this node is tinted by its parent.

If this value is true, the base color is multiplied with the absolute color of its parent when rendering happens. Otherwise, the base color is used alone.

Returns: true if this node is tinted by its parent.

◆ init()

virtual bool cugl::scene2::SceneNode::init ( )

inlinevirtual

Initializes a node at the world origin.

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

Returns: true if initialization was successful.

Reimplemented in cugl::scene2::Label, cugl::scene2::Slider, cugl::scene2::Button, cugl::scene2::TexturedNode, cugl::scene2::NinePatch, and cugl::scene2::ProgressBar.

◆ initWithBounds() [1/4]

virtual bool cugl::scene2::SceneNode::initWithBounds ( const Rect rect )

virtual

Initializes a 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

rect	The bounds of the node in parent space

Returns: true if initialization was successful.

◆ initWithBounds() [2/4]

virtual bool cugl::scene2::SceneNode::initWithBounds ( const Size size )

virtual

Initializes a node with the given size.

The size defines the content size. The bounding box of the node is (0,0,width,height). Hence the node is anchored in the center and has position (width/2,height/2) in the parent space. The node origin is the (0,0) at the bottom left corner of the bounding box.

Parameters

size	The size of the node in parent space

Returns: true if initialization was successful.

◆ initWithBounds() [3/4]

bool cugl::scene2::SceneNode::initWithBounds	(	float	width,
		float	height
	)

inline

Initializes a node with the given size.

The size defines the content size. The bounding box of the node is (0,0,width,height). Hence the node is anchored in the center and has position (width/2,height/2) in the parent space. The node origin is the (0,0) at the bottom left corner of the bounding box.

Parameters

width	The width of the node in parent space
height	The height of the node in parent space

Returns: true if initialization was successful.

◆ initWithBounds() [4/4]

bool cugl::scene2::SceneNode::initWithBounds	(	float	x,
		float	y,
		float	width,
		float	height
	)

inline

Initializes a 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

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: true if initialization was successful.

◆ initWithData()

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

virtual

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 the following attribute values:

 "position": A two-element number array
 "size":     A two-element number array
 "anchor":   A two-element number array representing the anchor point
 "color":    A four-element integer array.  Values should be 0..255
 "scale":    Either a two-element number array or a single number
 "angle":    A number, representing the rotation in DEGREES, not radians
 "visible":  A boolean value, representing if the node is visible

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 in cugl::scene2::Label, cugl::scene2::TexturedNode, cugl::scene2::ProgressBar, cugl::scene2::Slider, cugl::scene2::Button, cugl::scene2::PathNode, cugl::scene2::NinePatch, cugl::scene2::WireNode, and cugl::scene2::AnimationNode.

◆ initWithPosition() [1/2]

virtual bool cugl::scene2::SceneNode::initWithPosition ( const Vec2 pos )

virtual

Initializes a 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.

Parameters

pos	The origin of the node in parent space

Returns: true if initialization was successful.

◆ initWithPosition() [2/2]

bool cugl::scene2::SceneNode::initWithPosition	(	float	x,
		float	y
	)

inline

Initializes a 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.

Parameters

x	The x-coordinate of the node in parent space
y	The y-coordinate of the node in parent space

Returns: true if initialization was successful.

◆ isVisible()

bool cugl::scene2::SceneNode::isVisible ( ) const

inline

Returns true if the node is visible.

If a node is not visible, then it is not drawn. This means that its children are not visible as well, regardless of their visibility settings. The default value is true, making the node visible.

Returns: true if the node is visible.

◆ isZDirty()

bool cugl::scene2::SceneNode::isZDirty ( ) const

inline

Returns whether the children of this node needs resorting.

The children of a node 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 any associated Scene2). Our methods guarantee this invariant, so that the method isZDirty() always returns the correct value.

Sorting does not happen automatically (except within a Scene2). It is the responsibility of a user to sort the z-order before a call to render. Otherwise, render order will be in the unsorted order.

Returns: whether the children of this node needs resorting.

◆ nodeToParentCoords()

Vec2 cugl::scene2::SceneNode::nodeToParentCoords ( const Vec2 nodePoint ) const

inline

Converts an node (local) space position to parent coordinates.

See getNodeToParentTransform() for how this conversion takes place. That method should be used instead if there are many points to convert, as this method will recompute the transform matrix each time.

Parameters

nodePoint A local position.

Returns: A point in parent space coordinates.

◆ nodeToScreenCoords()

Vec2 cugl::scene2::SceneNode::nodeToScreenCoords ( const Vec2 nodePoint ) const

Converts an node (local) position to screen coordinates.

This method is useful for converting back to global positions like touches or mouse clicks, which are represented in screen coordinates. Screen coordinates typically have the origin in the top left.

The screen coordinate system is defined by the scene's camera. The method converts the node point into world space, and then uses the camera to convert into screen space.

This method returns the original point if there is no active scene.

Parameters

nodePoint A local position.

Returns: A point in screen coordinates.

◆ nodeToWorldCoords()

Vec2 cugl::scene2::SceneNode::nodeToWorldCoords ( const Vec2 nodePoint ) const

inline

Converts an node (local) position to OpenGL coordinates.

See getNodeToWorldTransform() for how this conversion takes place. That method should be used instead if there are many points to convert, as this method will recompute the transform matrix each time.

Parameters

nodePoint A local position.

Returns: A point in OpenGL coordinates.

◆ operator std::string()

cugl::scene2::SceneNode::operator std::string ( ) const

inline

Cast from a Node to a string.

◆ parentToNodeCoords()

Vec2 cugl::scene2::SceneNode::parentToNodeCoords ( const Vec2 parentPoint ) const

inline

Converts an parent space position to node (local) space coordinates.

See getParentToNodeTransform() for how this conversion takes place. That method should be used instead if there are many points to convert, as this method will recompute the transform matrix each time.

Parameters

parentPoint A parent position.

Returns: A point in node (local) space coordinates.

◆ removeAllChildren()

virtual void cugl::scene2::SceneNode::removeAllChildren ( )

virtual

Removes all children from this Node.

◆ removeChild() [1/2]

void cugl::scene2::SceneNode::removeChild ( const std::shared_ptr< SceneNode > & child )

Removes a child from this Node.

Removing a child alters the position of every child after it. Hence it is unsafe to cache child positions.

If the child is not in this node, nothing happens.

Parameters

child The child node which will be removed.

◆ removeChild() [2/2]

virtual void cugl::scene2::SceneNode::removeChild ( unsigned int pos )

virtual

Removes the child at the given position from this Node.

Removing a child alters the position of every child after it. Hence it is unsafe to cache child positions.

Parameters

pos	The position of the child node which will be removed.

◆ removeChildByName()

void cugl::scene2::SceneNode::removeChildByName ( const std::string name )

Removes a child from the Node by name.

If there is more than one child of the given name, it removes the first one that is found. For the base Node class, children are always enumerated in the order that they are added. However, this is not guaranteed for subclasses of Node. Hence it is very important that names be unique.

Parameters

name	A string to identify the node.

◆ removeChildByTag()

void cugl::scene2::SceneNode::removeChildByTag ( unsigned int tag )

Removes a child from the Node by tag value.

If there is more than one child of the given tag, it removes the first one that is found. For the base Node class, children are always enumerated in the order that they are added. However, this is not guaranteed for subclasses of Node. Hence it is very important that tags be unique.

Parameters

tag	An integer to identify the node easily.

◆ removeFromParent()

void cugl::scene2::SceneNode::removeFromParent ( )

inline

Removes this node from its parent node.

If the node has no parent, nothing happens.

◆ render() [1/2]

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

inlinevirtual

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

You almost never need to override this method. You should override the method draw(shared_ptr<SpriteBatch>,const Mat4&,Color4) if you need to define custom drawing code.

Parameters

batch The SpriteBatch to draw with.

◆ render() [2/2]

virtual void cugl::scene2::SceneNode::render	(	const std::shared_ptr< SpriteBatch > &	batch,
		const Mat4 &	transform,
		Color4	tint
	)

virtual

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

You almost never need to override this method. You should override the method draw(shared_ptr<SpriteBatch>,const Mat4&,Color4) if you need to define custom drawing code.

Parameters

batch	The SpriteBatch to draw with.
transform	The global transformation matrix.
tint	The tint to blend with the Node color.

◆ screenToNodeCoords()

Vec2 cugl::scene2::SceneNode::screenToNodeCoords ( const Vec2 screenPoint ) const

Converts a screen position to node (local) space coordinates.

This method is useful for converting global positions like touches or mouse clicks, which are represented in screen coordinates. Screen coordinates typically have the origin in the top left.

The screen coordinate system is defined by the scene's camera. The method uses the camera to convert into world space, and then converts from world space into not (local) space.

This method returns the original point if there is no active scene.

Parameters

screenPoint An position on the screen

Returns: A point in node (local) space coordinates.

◆ setAlternateTransform()

void cugl::scene2::SceneNode::setAlternateTransform ( const Mat4 & transform )

inline

Sets the alternate transform of this node.

Unlike the built-in scaling and rotation, this transform is applied to the coordinate space of the Node (e.g. with the origin in the bottom left corner).

Scaling/rotation and the alternate transform do no play nice with each other. It does not make sense to stack them on top of one another in either direction. Hence, you should only use of of the two. See the method chooseAlternateTransform(bool) to choose.

Parameters

transform the alternate transform of this node.

◆ setAnchor() [1/2]

virtual void cugl::scene2::SceneNode::setAnchor ( const Vec2 anchor )

virtual

Sets the anchor point in percentages.

The anchor point defines the relative origin of Node with respect to its parent. It is a "pin" where the Node is attached to its parent. In effect, the translation of a Node is defined by its position plus anchor point.

The anchorPoint is normalized, like a percentage. (0,0) means the bottom-left corner and (1,1) means the top-right corner. There are many anchor point constants defined in Vec2. However, there is nothing preventing an anchor point higher than (1,1) or lower than (0,0).

The default anchorPoint is (0.5,0.5), so it starts in the center of the node. Changing the anchor will not move the contents of the node in the parent space, but it will change the value of the Node position.

Parameters

anchor The anchor point of node.

Reimplemented in cugl::scene2::TexturedNode.

◆ setAnchor() [2/2]

void cugl::scene2::SceneNode::setAnchor	(	float	x,
		float	y
	)

inline

Sets the anchor point in percentages.

The anchor point defines the relative origin of Node with respect to its parent. It is a "pin" where the Node is attached to its parent. In effect, the translation of a Node is defined by its position plus anchor point.

The anchorPoint is normalized, like a percentage. (0,0) means the bottom-left corner and (1,1) means the top-right corner. There are many anchor point constants defined in Vec2. However, there is nothing preventing an anchor point higher than (1,1) or lower than (0,0).

The default anchorPoint is (0.5,0.5), so it starts in the center of the node. Changing the anchor will not move the contents of the node in the parent space, but it will change the value of the Node position.

Parameters

x	The horizontal anchor percentage.
y	The vertical anchor percentage.

◆ setAngle()

void cugl::scene2::SceneNode::setAngle ( float angle )

inline

Sets the rotation angle of this node.

This value rotates the node about the anchor, with the anchor unmoved. The angle is measured in radians , counter-clockwise from the x-axis. Rotation is applied after scaling.

Parameters

angle the rotation angle of this node.

◆ setColor()

virtual void cugl::scene2::SceneNode::setColor ( Color4 color )

inlinevirtual

Sets the color tinting this node.

This color will be multiplied with the parent (this node on top) if hasRelativeColor() is true.

The default color is white, which means that all children have their natural color.

Parameters

color the color tinting this node.

Reimplemented in cugl::scene2::Button.

◆ setContentHeight()

void cugl::scene2::SceneNode::setContentHeight ( float height )

inline

Sets the untransformed height of the node.

The content height remains the same no matter how the node is scaled or rotated. All nodes must have a height, though it may be degenerate (0).

Changing the size of a rectangle will not change the position of the node. However, if the anchor is not the bottom-left corner, it will change the origin. The Node will grow out from an anchor on an edge, and equidistant from an anchor in the center.

Parameters

height The untransformed height of the node.

◆ setContentSize() [1/2]

virtual void cugl::scene2::SceneNode::setContentSize ( const Size size )

virtual

Sets the untransformed size of the node.

The content size remains the same no matter how the node is scaled or rotated. All nodes must have a size, though it may be degenerate (0,0).

Changing the size of a rectangle will not change the position of the node. However, if the anchor is not the bottom-left corner, it will change the origin. The Node will grow out from an anchor on an edge, and equidistant from an anchor in the center.

Parameters

size	The untransformed size of the node.

Reimplemented in cugl::scene2::Label, cugl::scene2::TexturedNode, and cugl::scene2::NinePatch.

◆ setContentSize() [2/2]

virtual void cugl::scene2::SceneNode::setContentSize	(	float	width,
		float	height
	)

inlinevirtual

Sets the untransformed size of the node.

The content size remains the same no matter how the node is scaled or rotated. All nodes must have a size, though it may be degenerate (0,0).

Changing the size of a rectangle will not change the position of the node. However, if the anchor is not the bottom-left corner, it will change the origin. The Node will grow out from an anchor on an edge, and equidistant from an anchor in the center.

Parameters

width	The untransformed width of the node.
height	The untransformed height of the node.

Reimplemented in cugl::scene2::Label, and cugl::scene2::TexturedNode.

◆ setContentWidth()

void cugl::scene2::SceneNode::setContentWidth ( float width )

inline

Sets the untransformed width of the node.

The content width remains the same no matter how the node is scaled or rotated. All nodes must have a width, though it may be degenerate (0).

Changing the size of a rectangle will not change the position of the node. However, if the anchor is not the bottom-left corner, it will change the origin. The Node will grow out from an anchor on an edge, and equidistant from an anchor in the center.

Parameters

width The untransformed width of the node.

◆ setLayout()

void cugl::scene2::SceneNode::setLayout ( const std::shared_ptr< Layout > & layout )

inline

Sets the layout manager for this node

We had originally intended to completely decouple layout managers from nodes. However, nodes (including layout assignemnts) are typically built bottom-up, while layout must happen top down to correctly resize elements. Therefore, we do allow the addition of an optional layout manager.

Changing the layout manager does not reperform layout. You must call doLayout() to do this.

Parameters

layout The layout manager for this node

◆ setName()

void cugl::scene2::SceneNode::setName ( const std::string & name )

inline

Sets a string that is used to identify the node.

This name is used to access a child node, since child position may change. In addition, the name is useful for debugging. To work properly, a name should be unique within a scene graph. It is empty if undefined.

Parameters

name	A string that is used to identify the node.

◆ setPosition() [1/2]

void cugl::scene2::SceneNode::setPosition ( const Vec2 & position )

inline

Sets the position of the node in its parent's coordinate system.

The node position is not necessarily the origin of the Node coordinate system. The relationship between the position and Node space is determined by the anchor point. See getAnchor() for more details.

Parameters

position The position of the node in its parent's coordinate system.

◆ setPosition() [2/2]

void cugl::scene2::SceneNode::setPosition	(	float	x,
		float	y
	)

Sets the position of the node in its parent's coordinate system.

The node position is not necessarily the origin of the Node coordinate system. The relationship between the position and Node space is determined by the anchor point. See getAnchor() for more details.

Parameters

x	The x-coordinate of the node in its parent's coordinate system.
y	The x-coordinate of the node in its parent's coordinate system.

◆ setPositionX()

void cugl::scene2::SceneNode::setPositionX ( float x )

inline

Sets the x-coordinate of the node in its parent's coordinate system.

The node position is not necessarily the origin of the Node coordinate system. The relationship between the position and Node space is determined by the anchor point. See getAnchor() for more details.

Parameters

x	The x-coordinate of the node in its parent's coordinate system.

◆ setPositionY()

void cugl::scene2::SceneNode::setPositionY ( float y )

inline

Sets the y-coordinate of the node in its parent's coordinate system.

The node position is not necessarily the origin of the Node coordinate system. The relationship between the position and Node space is determined by the anchor point. See getAnchor() for more details.

Parameters

y	The y-coordinate of the node in its parent's coordinate system.

◆ setRelativeColor()

void cugl::scene2::SceneNode::setRelativeColor ( bool flag )

inline

Sets whether this node is tinted by its parent.

If this value is true, the base color is multiplied with the absolute color of its parent when rendering happens. Otherwise, the base color is used alone.

Parameters

flag	Whether this node is tinted by its parent.

◆ setScale() [1/3]

void cugl::scene2::SceneNode::setScale ( const Vec2 vec )

inline

Sets the non-uniform scaling factor for this node.

This factor scales the node about the anchor (with the anchor unmoved). Hence this is not the same as a scale applied to Node space, as the origin is in the bottom left corner. Scaling is first, before any other transforms.

Parameters

vec	the non-uniform scaling factor.

◆ setScale() [2/3]

void cugl::scene2::SceneNode::setScale ( float scale )

inline

Sets the uniform scaling factor for this node.

This factor scales the node about the anchor (with the anchor unmoved). Hence this is not the same as a scale applied to Node space, as the origin is in the bottom left corner. Scaling is first, before any other transforms.

Parameters

scale the uniform scaling factor.

◆ setScale() [3/3]

void cugl::scene2::SceneNode::setScale	(	float	sx,
		float	sy
	)

inline

Sets the non-uniform scaling factor for this node.

This factor scales the node about the anchor (with the anchor unmoved). Hence this is not the same as a scale applied to Node space, as the origin is in the bottom left corner. Scaling is first, before any other transforms.

Parameters

sx	the x-axis scaling factor.
sy	the y-axis scaling factor.

◆ setScissor() [1/2]

void cugl::scene2::SceneNode::setScissor ( )

inline

Sets a content-bounded scissor associated with this node.

SceneNodes are just coordinate spaces. Any child outside of the content area is still drawn; the content area value is primarily used for anchor placement. If you want to obscure (parts of) children that are outside the content area, you will need to set a scissor.

The scissor set by this method is guaranteed to fit the content bounds ({

See also: getContentSize()}) of this node. However, it will not be updated if the content bounds of the node are changed. In that case, this method should be called again.

It is possible for the children of a node to have a scissor as well. When that happens, the children will be rendered with the intersection of the two scissors. However, if the child is rotated, then its scissor will be oriented to be aligned with the parent scissor, as we can only intersect two rectangles of the same orientation. The rule for this intersection will be the same as Scissor#intersect.

◆ setScissor() [2/2]

void cugl::scene2::SceneNode::setScissor ( const std::shared_ptr< Scissor > & scissor )

inline

Sets the scissor associated with this node.

SceneNodes are just coordinate spaces. Any child outside of the content area is still drawn; the content area value is primarily used for anchor placement. If you want to obscure (parts of) children that are outside the content area, you will need to set a scissor.

The scissor does not need to be set to the content area. It can by any scissor, and that scissor will be applied to the coordinate system of this node. To create a scissor that will restrict to the node content area, simply construct

Scissor::alloc(getContentSize())

It is possible for the children of a node to have a scissor as well. When that happens, the children will be rendered with the intersection of the two scissors. However, if the child is rotated, then its scissor will be oriented to be aligned with the parent scissor, as we can only intersect two rectangles of the same orientation. The rule for this intersection will be the same as Scissor#intersect.

Parameters

scissor The scissor associated with this node.

◆ setTag()

void cugl::scene2::SceneNode::setTag ( unsigned int tag )

inline

Sets a tag that is used to identify the node easily.

This tag is used to quickly access a child node, since child position may change. To work properly, a tag should be unique within a scene graph. It is 0 if undefined.

Parameters

tag	A tag that is used to identify the node easily.

◆ setVisible()

void cugl::scene2::SceneNode::setVisible ( bool visible )

inline

Sets whether the node is visible.

If a node is not visible, then it is not drawn. This means that its children are not visible as well, regardless of their visibility settings. The default value is true, making the node visible.

Parameters

visible true if the node is visible.

◆ setZOrder()

void cugl::scene2::SceneNode::setZOrder ( int z )

Sets the value used to 'sort' a node relative to its siblings.

The z-order determines the drawing order of the children. If two nodes have the same z-order, they are drawn in the order that they were added to their parent.

The z-order is not an actual z-value. Attempting to interpret it other wise would result in an interleaving of children, which is not what we want in a scene graph.

Sorting does not happen automatically (except within a Scene2). It is the responsibility of a user to sort the z-order before a call to render. Otherwise, render order will be in the unsorted order.

Parameters

z	The local Z order value.

◆ sortZOrder()

void cugl::scene2::SceneNode::sortZOrder ( )

Resorts the children of this node 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 any associated Scene2).

Sorting does not happen automatically (except within a Scene2). It is the responsibility of a user to call this method before rendering. Otherwise, render order will be in the unsorted order.

◆ swapChild()

void cugl::scene2::SceneNode::swapChild	(	const std::shared_ptr< SceneNode > &	child1,
		const std::shared_ptr< SceneNode > &	child2,
		bool	inherit = `false`
	)

Swaps the current child child1 with the new child child2.

If inherit is true, the children of child1 are assigned to child2 after the swap; this value is false by default. The purpose of this value is to allow transition nodes in the middle of the scene graph.

This method is undefined if child1 is not a child of this node.

Parameters

child1	The current child of this node
child2	The child to swap it with.
inherit	Whether the new child should inherit the children of child1.

◆ toString()

virtual std::string cugl::scene2::SceneNode::toString ( bool verbose = false ) const

virtual

Returns a string representation of this node for debugging purposes.

If verbose is true, the string will include class information. This allows us to unambiguously identify the class.

Parameters

verbose Whether to include class information

Returns: a string representation of this node for debuggging purposes.

Reimplemented in cugl::scene2::TexturedNode, and cugl::scene2::NinePatch.

◆ withAlternateTransform()

bool cugl::scene2::SceneNode::withAlternateTransform ( )

inline

Returns true if the Node is using the alternate transform.

Unlike the built-in scaling and rotation, the alternate transform is applied to the coordinate space of the Node (e.g. with the origin in the bottom left corner).

Scaling/rotation and the alternate transform do no play nice with each other. It does not make sense to stack them on top of one another in either direction. Hence, you should only use of of the two. This method returns true if the alternate transform is in use.

Returns: true if the Node is using the alternate transform.

◆ worldToNodeCoords()

Vec2 cugl::scene2::SceneNode::worldToNodeCoords ( const Vec2 worldPoint ) const

inline

Converts an OpenGL position to node (local) space coordinates.

See getWorldtoNodeTransform() for how this conversion takes place. That method should be used instead if there are many points to convert, as this method will recompute the transform matrix each time.

Parameters

worldPoint An OpenGL position.

Returns: A point in node (local) space coordinates.

Member Data Documentation

◆ _anchor

Vec2 cugl::scene2::SceneNode::_anchor

protected

The anchor point of the node.

The anchor point is a percentage of the node bounding box. Together with the position, it species the origin of the node space.

◆ _angle

float cugl::scene2::SceneNode::_angle

protected

The rotation angle of this node.

The angle is measured in degrees and is counter-clockwise from the x-axis. The rotation is about the anchor point, not the node origin. It is applied after the scale, but before the post-transform. The node coordinate space is unchanged.

◆ _childOffset

int cugl::scene2::SceneNode::_childOffset

protected

The (current) child offset of this node (-1 if root)

◆ _children

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

protected

The array of children nodes

◆ _combined

Mat4 cugl::scene2::SceneNode::_combined

protected

The cached local transform matrix.

This matrix specifes the transform from node space to parent space. Depending on the settings, it is either the scale and rotation or the alternate transform.

◆ _contentSize

Size cugl::scene2::SceneNode::_contentSize

protected

The (untransformed) size of this node.

◆ _graph

Scene2* cugl::scene2::SceneNode::_graph

protected

A weaker pointer to the scene (or null if not in a scene)

◆ _hashOfName

size_t cugl::scene2::SceneNode::_hashOfName

protected

A cached has value of _name.

This value is used to speed up look-ups by string.

◆ _hasParentColor

bool cugl::scene2::SceneNode::_hasParentColor

protected

Whether to blend our color with that of our parent.

◆ _isVisible

bool cugl::scene2::SceneNode::_isVisible

protected

Whether this node is visible

◆ _json

std::shared_ptr<JsonValue> cugl::scene2::SceneNode::_json

protected

The defining JSON data for this node (if any)

◆ _layout

std::shared_ptr<Layout> cugl::scene2::SceneNode::_layout

protected

A layout manager for complex scene graphs

◆ _name

std::string cugl::scene2::SceneNode::_name

protected

A descriptive identifying tag.

Like tag, this value is used to quickly identify the child of a node. However, it is more descriptive, and so is useful in debugging.

◆ _parent

SceneNode* cugl::scene2::SceneNode::_parent

protected

A weaker pointer to the parent (or null if root)

◆ _position

Vec2 cugl::scene2::SceneNode::_position

protected

The position of the node.

This position is specified in the coordinate system defined by the parent. Together with the anchor point, it species the origin of the node space.

◆ _scale

Vec2 cugl::scene2::SceneNode::_scale

protected

The scale of this node.

The scale determines the transform from node space about the anchor. It is applied before any rotation. The node coordinate space is unchanged.

◆ _scissor

std::shared_ptr<Scissor> cugl::scene2::SceneNode::_scissor

protected

An optional scissor value

◆ _tag

unsigned int cugl::scene2::SceneNode::_tag

protected

An identifying tag.

This value is used to quickly identify the child of a node. To work properly, a tag should be unique within a scene graph. It is 0 if undefined.

◆ _tintColor

Color4 cugl::scene2::SceneNode::_tintColor

protected

The color to tint this node. This color is white by default.

◆ _transform

Mat4 cugl::scene2::SceneNode::_transform

protected

The alternate transform of this node.

This value allows you to perform more arbitrary transformations of the node in parent space. Unlike scaling and rotation, this transform is applied to the node space directly (not with respect to the anchor). Hence this transform is applied before any other ones.

◆ _useTransform

bool cugl::scene2::SceneNode::_useTransform

protected

Whether or not to use the alternate transform

◆ _zDirty

bool cugl::scene2::SceneNode::_zDirty

protected

Indicates whether or not the z-order is currently violated

◆ _zOrder

int cugl::scene2::SceneNode::_zOrder

protected

The z-order of this node

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

include/cugl/scene2/graph/CUSceneNode.h

Public Member Functions

Static Public Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ SceneNode()

◆ ~SceneNode()

Member Function Documentation

◆ addChild() [1/2]

◆ addChild() [2/2]

◆ addChildWithName() [1/2]

◆ addChildWithName() [2/2]

◆ addChildWithTag() [1/2]

◆ addChildWithTag() [2/2]

◆ alloc()

◆ allocWithBounds() [1/4]

◆ allocWithBounds() [2/4]

◆ allocWithBounds() [3/4]

◆ allocWithBounds() [4/4]

◆ allocWithData()

◆ allocWithPosition() [1/2]

◆ allocWithPosition() [2/2]

◆ chooseAlternateTransform()

◆ copy()

◆ dispose()

◆ doLayout()

◆ draw()

◆ getAbsoluteColor()

◆ getAlternateTransform()

◆ getAnchor()

◆ getAnchorInPixels()

◆ getAngle()

◆ getBoundingBox()

◆ getChild() [1/3]

◆ getChild() [2/3]

◆ getChild() [3/3]

◆ getChildByName() [1/2]

◆ getChildByName() [2/2]

◆ getChildByTag() [1/2]

◆ getChildByTag() [2/2]

◆ getChildCount()

◆ getChildren() [1/2]

◆ getChildren() [2/2]

◆ getColor()

◆ getContentHeight()

◆ getContentSize()

◆ getContentWidth()

◆ getHeight()

◆ getLayout()

◆ getName()

◆ getNodeToParentTransform()

◆ getNodeToWorldTransform()

◆ getParent() [1/2]

◆ getParent() [2/2]

◆ getParentToNodeTransform()

◆ getPosition()

◆ getPositionX()

◆ getPositionY()

◆ getScale()

◆ getScaleX()

◆ getScaleY()

◆ getScene() [1/2]

◆ getScene() [2/2]

◆ getScissor()

◆ getSize()

◆ getTag()

◆ getWidth()

◆ getWorldPosition()

◆ getWorldToNodeTransform()

◆ getZOrder()

◆ hasRelativeColor()

◆ init()

◆ initWithBounds() [1/4]

◆ initWithBounds() [2/4]

◆ initWithBounds() [3/4]

◆ initWithBounds() [4/4]

◆ initWithData()

◆ initWithPosition() [1/2]

◆ initWithPosition() [2/2]