Node

Base class for all scene graph nodes.

Node represents a transformable object in the scene hierarchy. It manages local and world transforms, parent–child relationships, and hooks for per-frame updates and input events. All renderable, camera, and light objects derive from this class and share the same hierarchical behavior.

The scene graph is a tree: each node can have zero or more children and at most one parent. Transforms always propagate downward, changing a parent updates the world-space transforms of all descendants. Input events propagate bottom-up through the scene graph: children receive the event before their parents, and any node can stop propagation by marking the event as handled.

Nodes can opt out of automatic transform updates via transform_auto_update when needed.

Construction

Constructors

Node()

Constructs a node.

Node::Node();

Factories preferred

Node::Create() std::unique_ptr<Node>

Creates an instance of Node.

static std::unique_ptr<Node> Node::Create();

Types

Node::Type enum

Enumerates all node categories.

Used by the engine and renderer to distinguish between cameras, meshes, lights, and generic nodes. Custom node types typically reuse one of the existing categories.

Value	Description
Billboard	Camera-facing quad.
Camera	Perspective or orthographic camera.
Default	Generic node without special behavior.
InstancedMesh	Node containing instanced meshes.
Light	Light source (directional, point, or spot).
Mesh	Single mesh with an associated material.
Renderable	Any node that can be rendered to the screen.
Scene	Root of a scene hierarchy.

Properties

transform Transform3

Local transform (position, rotation, scale) of this node.

Transform3 transform {};

transform_auto_update bool

When true the world transform is automatically updated each frame.

bool transform_auto_update {true};

up Vector3

Local up direction used by helpers such as LookAt.

Vector3 up {Vector3::UnitY()};

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 scene graph 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 scene graph.

T* Node::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> Node::Detach(T* node);

Parameter	Description
node	Direct child node to detach.

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 Node::Remove(Node* node);

Parameter	Description
node	Direct child node to remove.

RemoveAllChildren() void

Removes all children from this node.

Each child is detached from the scene graph, 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 Node::RemoveAllChildren();

UpdateTransformHierarchy() void

Recursively updates world transforms for this node and its descendants.

If transform_auto_update is enabled and 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 Node::UpdateTransformHierarchy();

GetCachedWorldTransform() const Matrix4&

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 Matrix4& Node::GetCachedWorldTransform() const;

GetWorldTransform() Matrix4

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. If transform_auto_update is disabled, returns the cached world transform as-is.

Matrix4 Node::GetWorldTransform() const;

GetWorldPosition() Vector3

Returns the node’s world-space position.

Computes the world transform via GetWorldTransform, then extracts the translation column of the matrix.

Vector3 Node::GetWorldPosition() const;

GetChildren() std::span<const std::unique_ptr< Node> >

Returns a view of this node’s direct children.

The returned span exposes read-only access to the owning node's std::unique_ptr<Node> objects for each child. Ownership is retained by the scene graph.

std::span<const std::unique_ptr< Node> > Node::GetChildren() const;

GetChild() Node*

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.

Node* Node::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 Node::IsChild(const Node* node) const;

Parameter	Description
node	Node to test for membership in the subtree. Must point to a live node or be nullptr.

GetParent() const Node*

Returns this node’s parent.

const Node* Node::GetParent() const;

GetScene() const Scene*

Returns the scene that owns this node.

Returns the scene this node is currently attached to or nullptr if the node is not attached to any scene.

const Scene* Node::GetScene() const;

LookAt() void virtual

Rotates the node so its forward direction points at the target.

virtual void Node::LookAt(const Vector3& target);

Parameter	Description
target	World-space point to look at.

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 Node::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 Node::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 Node::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 Node::OnGamepadEvent(GamepadEvent* event);

Parameter	Description
event	Gamepad event pointer.

GetNodeType() Node::Type virtual

Returns the node's type identifier.

Subclasses override this to report their specific type. The default is Node::Type::Default.

virtual Type vglx::Node::GetNodeType() const;

IsRenderable() bool virtual

Returns whether this node is renderable.

Renderable subclasses (such as Mesh and InstancedMesh) override this and return true. The base implementation always returns false.

virtual bool Node::IsRenderable() const;