Node2D
Node2D represents a transformable object in a canvas hierarchy. It manages local and world transforms, parent–child relationships, and hooks for per-frame updates and input events. All 2D drawable objects, such as sprites and text, derive from this class and share the same hierarchical behavior.
The canvas is a tree rooted at a Canvas node: each node can have zero or more children and at most one parent. Transforms propagate downward, changing a parent updates the world-space transforms of all descendants. Opacity is inherited the same way, and hiding a node hides its entire subtree. Nodes are drawn in tree order: parents before children, siblings in insertion order. Input events propagate bottom-up through the hierarchy: children receive the event before their parents, and any node can stop propagation by marking the event as handled.
Construction
Constructors
Node2D()
Constructs a node.
Node2D::Node2D();Factories preferred
Creates an instance of Node2D.
static std::unique_ptr<Node2D> Node2D::Create();Types
Node2D::Type enum
Enumerates all node categories.
Used by the engine and renderer to distinguish between drawable nodes, the canvas root, and generic nodes. Custom node types typically reuse one of the existing categories.
| Value | Description |
|---|---|
| Default | Generic node without special behavior. |
| Canvas | Root of a canvas hierarchy. |
| Renderable | Any node that can be drawn to the canvas. |
| Sprite | Textured quad drawn in canvas space. |
| Text | Glyph quads laid out from a bitmap font. |
Properties
opacity float
Opacity of this node, where 1.0 is fully opaque.
Multiplied by the opacity of every ancestor at draw time so fading a parent fades its whole subtree. see GetWorldOpacity. Does not affect updates or input.
float opacity {1.0f};transform Transform2
Local transform (position, rotation, scale, center) of this node.
Transform2 transform {};visible bool
When true this node and its descendants are drawn.
Hidden nodes are skipped by the renderer along with their entire subtree, but still receive OnUpdate calls.
bool visible {true};Functions
Add() T*
Adds a child node to this node and returns a non-owning reference.
This overload transfers ownership of a node into this node’s children list. The canvas is the sole owner of all nodes. The returned pointer is a non-owning reference that remains valid only while the node is attached to the canvas.
T* Node2D::Add(std::unique_ptr<T> node);| Parameter | Description |
|---|---|
| node | Node to attach. Ownership is transferred. |
Detach() std::unique_ptr<T>
Detaches a direct child node from this node and returns ownership.
Removes a node from this node’s children list without destroying it and returns the owned subtree as a std::unique_ptr. The detached node’s parent pointer is cleared, its attached state is reset, and its transform is marked dirty.
std::unique_ptr<T> Node2D::Detach(T* node);| Parameter | Description |
|---|---|
| node | Direct child node to detach. |
UpdateTransformHierarchy() void
Recursively updates world transforms for this node and its descendants.
If the node’s local transform is dirty, or an ancestor was recomputed during this pass, the world transform is recomputed from the parent’s world transform (or from the local transform if this node is a root) and the local transform is marked clean. The method then recurses into each child.
This is the primary mechanism used by the renderer to update transform propagation across the entire hierarchy once per frame.
void Node2D::UpdateTransformHierarchy();Returns the world transform cached by the last hierarchy update.
Reflects the state as of the most recent call to UpdateTransformHierarchy and may be stale if a transform changed since. Intended for the renderer, which reads it after the per-frame update. Use GetWorldTransform for an always-current result.
const Matrix3& Node2D::GetCachedWorldTransform() const;Returns the node’s world transform matrix.
Composes the local transforms along the parent chain without modifying any cached state, so the result is current regardless of when the hierarchy was last updated. The cost is proportional to the node’s depth.
Matrix3 Node2D::GetWorldTransform() const;Returns the node’s world-space position.
Computes the world transform via GetWorldTransform, then extracts the translation column of the matrix.
Vector2 Node2D::GetWorldPosition() const;GetWorldOpacity() float
Returns the node’s effective opacity.
Multiplies opacity by the opacity of every ancestor up to the root. Like GetWorldTransform, the result is computed on demand and is always current.
float Node2D::GetWorldOpacity() const;Remove() void
Removes a direct child node from this node and destroys it.
If the node exists in the children list it is detached and destroyed.
void Node2D::Remove(Node2D* node);| Parameter | Description |
|---|---|
| node | Direct child node to remove. |
RemoveAllChildren() void
Removes all children from this node.
Each child is detached from the canvas, has its parent pointer cleared, its attached state reset, and its transform marked dirty. After all children are processed, the children list is emptied.
void Node2D::RemoveAllChildren();Returns a view of this node’s direct children.
The returned span exposes read-only access to the owning node's std::unique_ptr<Node2D> objects for each child. Ownership is retained by the canvas.
std::span<const std::unique_ptr< Node2D> > Node2D::GetChildren() const;Returns a direct child node with the given name.
Searches only this node's immediate children for a node whose name matches the specified identifier. If no matching child is found, returns nullptr.
This function does not search descendants. Use GetChildren to implement recursive searches when needed.
Node2D* Node2D::GetChild(std::string_view name) const;| Parameter | Description |
|---|---|
| name | Name of the child node to retrieve. |
IsChild() bool
Checks whether the given node exists anywhere in this node’s subtree.
bool Node2D::IsChild(const Node2D* node) const;| Parameter | Description |
|---|---|
| node | Node to test for membership in the subtree. |
Returns the canvas that owns this node.
Returns the canvas this node is currently attached to or nullptr if the node is not attached to any canvas.
const Canvas* Node2D::GetCanvas() const;OnUpdate() void virtual
Per-frame update callback.
Called once per frame with the elapsed time since the last frame in seconds. Override this to implement node behavior.
virtual void Node2D::OnUpdate(float delta);| Parameter | Description |
|---|---|
| delta | Time step in seconds. |
OnKeyboardEvent() void virtual
Keyboard event handler.
Override this to react to keyboard events. Events can be marked as handled to stop propagation.
virtual void Node2D::OnKeyboardEvent(KeyboardEvent* event);| Parameter | Description |
|---|---|
| event | Keyboard event pointer. |
OnMouseEvent() void virtual
Mouse event handler.
Override this to react to cursor, button, or scroll events. Events can be marked as handled to stop propagation.
virtual void Node2D::OnMouseEvent(MouseEvent* event);| Parameter | Description |
|---|---|
| event | Mouse event pointer. |
OnGamepadEvent() void virtual
Gamepad event handler.
Override this to react to gamepad connection, button, or axis events. Events can be marked as handled to stop propagation.
virtual void Node2D::OnGamepadEvent(GamepadEvent* event);| Parameter | Description |
|---|---|
| event | Gamepad event pointer. |
GetNodeType() Node2D::Type virtual
Returns the node's type identifier.
Subclasses override this to report their specific type. The default is Node2D::Type::Default.
virtual Type vglx::Node2D::GetNodeType() const;IsRenderable() bool virtual
Returns whether this node is renderable.
Drawable nodes derive from Renderable2D which overrides this and returns true. The renderer draws any node reporting true through that interface. The base implementation always returns false.
virtual bool Node2D::IsRenderable() const;