![]() |
CUGL 2.3
Cornell University Game Library
|
#include <CUSceneNode.h>
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) |
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 bool | initWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data) |
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 | render (const std::shared_ptr< SpriteBatch > &batch, const Affine2 &transform, Color4 tint) |
virtual void | render (const std::shared_ptr< SpriteBatch > &batch) |
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< 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 |
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 |
Friends | |
class | cugl::Scene2 |
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. To get around this restriction, you must use the OrderedNode
subclass.
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.
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.
|
inline |
Deletes this node, disposing all resources
void cugl::scene2::SceneNode::addChild | ( | const std::shared_ptr< SceneNode > & | child | ) |
Adds a child to this node.
Children are enumerated in the order that they are added. However, it is still best to For example, they may be resorted by their z-order. Hence you should generally attempt to retrieve a child by tag or by name instead.
child | A child node. |
|
inline |
Adds a child to this node with the given name.
For the base SceneNode class, children are always enumerated in the order that they are added. However, this is not guaranteed for all subclasses of SceneNode. Hence it is generally best to retrieve a child using either a tag or a name instead.
child | A child node. |
name | A string to identify the node. |
|
inline |
Adds a child to this node with the given tag.
For the base SceneNode class, children are always enumerated in the order that they are added. However, this is not guaranteed for all subclasses of SceneNode. Hence it is generally best to retrieve a child using either a tag or a name instead.
child | A child node. |
tag | An integer to identify the node easily. |
|
inlinestatic |
Returns a newly allocated node at the world origin.
The node has both position and size (0,0).
|
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 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.
rect | The bounds of the node in parent space |
|
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.
size | The size of the node in parent space |
|
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.
width | The width of the node in parent space |
height | The height of the node in parent space |
|
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 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.
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 |
|
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": Either a four-element integer array (values 0..255) or a string. Any string should be a web color or a Tkinter color name. "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.
loader | The scene loader passing this JSON file |
data | The JSON object specifying the node |
|
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.
pos | The origin of the node in parent space |
|
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.
x | The x-coordinate of the node in parent space |
y | The y-coordinate of the node in parent space |
|
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.
active | Whether the Node is using the alternate transform. |
|
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.
dst | The Node to copy into |
Reimplemented in cugl::scene2::PathNode, cugl::scene2::PolygonNode, cugl::scene2::SpriteNode, cugl::scene2::TexturedNode, and cugl::scene2::WireNode.
|
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::CanvasNode, cugl::scene2::OrderedNode, cugl::scene2::TexturedNode, cugl::scene2::Button, cugl::scene2::Label, cugl::scene2::NinePatch, cugl::scene2::ProgressBar, cugl::scene2::ScrollPane, cugl::scene2::Slider, and cugl::scene2::TextField.
|
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.
|
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.
batch | The SpriteBatch to draw with. |
transform | The global transformation matrix. |
tint | The tint to blend with the Node color. |
Reimplemented in cugl::scene2::CanvasNode, cugl::scene2::PathNode, cugl::scene2::PolygonNode, cugl::scene2::WireNode, cugl::scene2::Label, cugl::scene2::NinePatch, cugl::scene2::TextField, and cugl::scene2::TexturedNode.
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.
|
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 not 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.
|
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.
|
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.
|
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.
|
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.
std::shared_ptr< SceneNode > cugl::scene2::SceneNode::getChild | ( | unsigned int | pos | ) |
Returns the child at the given position.
For the base SceneNode class, children are always enumerated in the order that they are added. However, this is not guaranteed for all subclasses of SceneNode. Hence it is generally best to retrieve a child using either a tag or a name instead.
pos | The child position. |
const std::shared_ptr< SceneNode > & cugl::scene2::SceneNode::getChild | ( | unsigned int | pos | ) | const |
Returns the child at the given position.
For the base SceneNode class, children are always enumerated in the order that they are added. However, this is not guaranteed for all subclasses of SceneNode. Hence it is generally best to retrieve a child using either a tag or a name instead.
pos | The child position. |
|
inline |
Returns the child at the given position, typecast to a shared T pointer.
This method is provided to simplify the polymorphism of a scene graph. While all children are a subclass of type Node, you may want to access them by their specific subclass. If the child is not an instance of type T (or a subclass), this method returns nullptr.
For the base SceneNode class, children are always enumerated in the order that they are added. However, this is not guaranteed for all subclasses of SceneNode. Hence it is generally best to retrieve a child using either a tag or a name instead.
pos | The child position. |
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 SceneNode class, children are always enumerated in the order that they are added. However, this is not guaranteed for all subclasses of SceneNode. Hence it is very important that names be unique.
name | An identifier to find the child node. |
|
inline |
Returns the (first) child with the given name, typecast to a shared T pointer.
This method is provided to simplify the polymorphism of a scene graph. While all children are a subclass of type Node, you may want to access them by their specific subclass. If the child is not an instance of type T (or a subclass), this method returns nullptr.
If there is more than one child of the given name, it returns the first one that is found. For the base SceneNode class, children are always enumerated in the order that they are added. However, this is not guaranteed for all subclasses of SceneNode. Hence it is very important that names be unique.
name | An identifier to find the child node. |
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 SceneNode class, children are always enumerated in the order that they are added. However, this is not guaranteed for all subclasses of SceneNode. Hence it is very important that tags be unique.
tag | An identifier to find the child node. |
|
inline |
Returns the (first) child with the given tag, typecast to a shared T pointer.
This method is provided to simplify the polymorphism of a scene graph. While all children are a subclass of type Node, you may want to access them by their specific subclass. If the child is not an instance of type T (or a subclass), this method returns nullptr.
If there is more than one child of the given tag, it returns the first one that is found. For the base SceneNode class, children are always enumerated in the order that they are added. However, this is not guaranteed for all subclasses of SceneNode. Hence it is very important that tags be unique.
tag | An identifier to find the child node. |
|
inline |
Returns the number of children of this node.
|
inline |
Returns the list of the node's children.
|
inline |
Returns the list of the node's children.
|
inline |
Returns the class name of this node.
This method is to help us speed up subclass-based polymorphism on the scene graphs.
|
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.
|
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). It is possible for children of this node to be outside of the content size bounds. The concept of content size is primarily for the purpose of anchoring and registering touch input.
|
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). It is possible for children of this node to be outside of the content size bounds. The concept of content size is primarily for the purpose of anchoring and registering touch input.
|
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). It is possible for children of this node to be outside of the content size bounds. The concept of content size is primarily for the purpose of anchoring and registering touch input.
|
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.
|
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.
|
inlinevirtual |
Returns the untransformed bounds of this node for layout purposes.
The layout bounds are used by the layout managers to place children in this node. For example, an anchored layout will put a child with anchors "top" and "right" at the top right corners of these bounds.
In this class, the layout bounds start at the origin of the node and extend to the getContentSize
. This value can be overridden in subclasses to decouple the layout bounds from the content size (such as nodes that do not show all available content).
Reimplemented in cugl::scene2::ScrollPane.
|
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.
|
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)
.
Affine2 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.
|
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.
|
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.
|
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)
.
|
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.
|
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.
|
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.
|
inline |
Returns the render priority of this node
Normally the nodes in a scene graph are rendered using a pre-order traversal, as this is the natural way to present UI elements. However, for character animation, it may be preferred to render elements in order independent of the scene graph hierarchy.
That is the purpose of the priority value. The priority assigns a (potentially global) rendering priority. To use the priority, this node must be the descendant of a root OrderedNode
. In that case the priority is the rendering priority of this node with respect to all of the other descendants of that root node. {
|
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.
|
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.
|
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.
|
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.
|
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.
|
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
.
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.
|
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.
|
inline |
Returns the standard transform of this node.
This transform includes the scaling and rotational operations that you have applied to this node. It is the transform that is use to draw the node contents unless chooseAlternateTransform(bool)
is set to true.
|
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.
|
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.
|
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.
|
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.
|
inlinevirtual |
Initializes a node at the world origin.
The node has both position and size (0,0).
Reimplemented in cugl::scene2::CanvasNode, cugl::scene2::TexturedNode, cugl::scene2::Button, cugl::scene2::NinePatch, cugl::scene2::ProgressBar, and cugl::scene2::Slider.
|
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 in node space. The node anchor is placed in the bottom left corner.
Because the bounding box is explicit, this is the preferred initializer for Nodes that will explicitly contain other Nodes.
rect | The bounds of the node in parent space |
Reimplemented in cugl::scene2::CanvasNode, cugl::scene2::Label, and cugl::scene2::ScrollPane.
|
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) and is anchored in the bottom left corner (0,0). The node is positioned at the origin in parent space.
size | The size of the node in parent space |
Reimplemented in cugl::scene2::CanvasNode, cugl::scene2::Label, and cugl::scene2::ScrollPane.
|
inlinevirtual |
Initializes a 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.
width | The width of the node in parent space |
height | The height of the node in parent space |
Reimplemented in cugl::scene2::CanvasNode, cugl::scene2::Label, and cugl::scene2::ScrollPane.
|
inlinevirtual |
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 in node space. The node anchor is placed in the bottom left corner.
Because the bounding box is explicit, this is the preferred initializer for Nodes that will explicitly contain other Nodes.
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 |
Reimplemented in cugl::scene2::CanvasNode, cugl::scene2::Label, and cugl::scene2::ScrollPane.
|
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": Either a four-element integer array (values 0..255) or a string. Any string should be a web color or a Tkinter color name. "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.
loader | The scene loader passing this JSON file |
data | The JSON object specifying the node |
Reimplemented in cugl::scene2::CanvasNode, cugl::scene2::OrderedNode, cugl::scene2::PathNode, cugl::scene2::PolygonNode, cugl::scene2::SpriteNode, cugl::scene2::TexturedNode, cugl::scene2::WireNode, cugl::scene2::Button, cugl::scene2::Label, cugl::scene2::NinePatch, cugl::scene2::ProgressBar, cugl::scene2::ScrollPane, cugl::scene2::Slider, and cugl::scene2::TextField.
|
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.
pos | The origin of the node in parent space |
Reimplemented in cugl::scene2::Label.
|
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.
x | The x-coordinate of the node in parent space |
y | The y-coordinate of the node in parent space |
|
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.
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.
nodePoint | A local position. |
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.
nodePoint | A local position. |
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.
nodePoint | A local position. |
|
inline |
Cast from a Node to a string.
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.
parentPoint | A parent position. |
|
virtual |
Removes all children from this Node.
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.
child | The child node which will be removed. |
|
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.
pos | The position of the child node which will be removed. |
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 SceneNode class, children are always enumerated in the order that they are added. However, this is not guaranteed for subclasses of SceneNode. Hence it is very important that names be unique.
name | A string to identify the node. |
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 SceneNode class, children are always enumerated in the order that they are added. However, this is not guaranteed for subclasses of SceneNode. Hence it is very important that tags be unique.
tag | An integer to identify the node easily. |
|
inline |
Removes this node from its parent node.
If the node has no parent, nothing happens.
|
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 Affine2&,Color4) if you need to define custom drawing code. In fact, overriding this method can break the functionality of OrderedNode
.
batch | The SpriteBatch to draw with. |
Reimplemented in cugl::scene2::OrderedNode, and cugl::scene2::ScrollPane.
|
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 Affine2&,Color4) if you need to define custom drawing code. In fact, overriding this method can break the functionality of OrderedNode
.
batch | The SpriteBatch to draw with. |
transform | The global transformation matrix. |
tint | The tint to blend with the Node color. |
Reimplemented in cugl::scene2::OrderedNode, and cugl::scene2::ScrollPane.
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.
screenPoint | An position on the screen |
|
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.
transform | the alternate transform of this node. |
|
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.
anchor | The anchor point of node. |
Reimplemented in cugl::scene2::TexturedNode.
|
inlinevirtual |
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.
x | The horizontal anchor percentage. |
y | The vertical anchor percentage. |
Reimplemented in cugl::scene2::TexturedNode.
|
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.
angle | the rotation angle of this node. |
|
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.
color | the color tinting this node. |
Reimplemented in cugl::scene2::Button.
|
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). It is possible for children of this node to be outside of the content size bounds. The concept of content size is primarily for the purpose of anchoring and registering touch input.
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.
height | The untransformed height of the node. |
|
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). It is possible for children of this node to be outside of the content size bounds. The concept of content size is primarily for the purpose of anchoring and registering touch input.
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.
size | The untransformed size of the node. |
Reimplemented in cugl::scene2::TexturedNode, cugl::scene2::Label, and cugl::scene2::NinePatch.
|
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). It is possible for children of this node to be outside of the content size bounds. The concept of content size is primarily for the purpose of anchoring and registering touch input.
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.
width | The untransformed width of the node. |
height | The untransformed height of the node. |
Reimplemented in cugl::scene2::TexturedNode, and cugl::scene2::Label.
|
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). It is possible for children of this node to be outside of the content size bounds. The concept of content size is primarily for the purpose of anchoring and registering touch input.
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.
width | The untransformed width of the node. |
|
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.
layout | The layout manager for this node |
|
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.
name | A string that is used to identify the node. |
|
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.
position | The position of the node in its parent's coordinate system. |
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.
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. |
|
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.
x | The x-coordinate of the node in its parent's coordinate system. |
|
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.
y | The y-coordinate of the node in its parent's coordinate system. |
|
inline |
Sets the render priority of this node
Normally the nodes in a scene graph are rendered using a pre-order traversal, as this is the natural way to present UI elements. However, for character animation, it may be preferred to render elements in order independent of the scene graph hierarchy.
That is the purpose of the priority value. The priority assigns a (potentially global) rendering priority. To use the priority, this node must be the descendant of a root OrderedNode
. In that case the priority is the rendering priority of this node with respect to all of the other descendants of that root node. {
priority | The render priority of this node |
|
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.
flag | Whether this node is tinted by its parent. |
|
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.
vec | the non-uniform scaling factor. |
|
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.
scale | the uniform scaling factor. |
|
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.
sx | the x-axis scaling factor. |
sy | the y-axis scaling factor. |
|
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 ({
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
.
|
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
.
scissor | The scissor associated with this node. |
|
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.
tag | A tag that is used to identify the node easily. |
|
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.
visible | true if the node is visible. |
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.
child1 | The current child of this node |
child2 | The child to swap it with. |
inherit | Whether the new child should inherit the children of child1. |
|
virtual |
Returns a string representation of this node for debugging purposes.
If verbose is true, the string will include class information. This allows us to unambiguously identify the class.
verbose | Whether to include class information |
Reimplemented in cugl::scene2::TexturedNode, and cugl::scene2::NinePatch.
|
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.
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.
worldPoint | An OpenGL position. |
|
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.
|
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.
|
protected |
The (current) child offset of this node (-1 if root)
|
protected |
The array of children nodes
|
protected |
The class name for the specific subclass
|
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.
|
protected |
The (untransformed) size of this node.
|
protected |
A weaker pointer to the scene (or null if not in a scene)
|
protected |
A cached has value of _name.
This value is used to speed up look-ups by string.
|
protected |
Whether to blend our color with that of our parent.
|
protected |
Whether this node is visible
|
protected |
The defining JSON data for this node (if any)
|
protected |
A layout manager for complex scene graphs
|
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.
|
protected |
A weaker pointer to the parent (or null if root)
|
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.
|
protected |
The rendering priority; used by OrderedNode
|
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.
|
protected |
An optional scissor value
|
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.
|
protected |
The color to tint this node. This color is white by default.
|
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.
|
protected |
Whether or not to use the alternate transform