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 or disable visibility tests using frustum_culled 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
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.
Sprite	Billboarded sprite.

Properties

frustum_culled bool

When true this node participates in view frustum culling.

bool frustum_culled {true};

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::Up()};

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 world transform is dirty, it is recomputed from the parent’s world transform (or from the local transform if this node is a root). The world transform is then marked clean for this update cycle. The method then recurses into each child.

This is the primary mechanism used by the renderer and scene step to update transform propagation across the entire hierarchy.

void Node::UpdateTransformHierarchy();

UpdateWorldTransform() void

Ensures this node’s world transform is up to date.

If the parent’s world transform may be outdated, the method updates the parent first. Then, if this node's transform is dirty, the world transform is recomputed without affecting siblings or children. This method does not recurse into children, unlike UpdateTransformHierarchy.

This is typically used when querying world-space properties on a single node.

void Node::UpdateWorldTransform();

Children() 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::Children() const;

IsChild() bool

Checks whether the given node exists anywhere in this node’s subtree.

The search is breadth-first. All descendants are examined.

bool Node::IsChild(const Node* node) const;

Parameter	Description
node	Node to test for membership in the subtree.

GetParent() constNode*

Returns this node’s parent.

const Node* Node::GetParent() const;

GetScene() constScene*

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;

ShouldUpdateWorldTransform() bool

Returns whether this node’s world transform must be recomputed.

A world transform is considered dirty if either the local transform has been modified, or if the parent’s world transform was updated during the current update cycle.

bool Node::ShouldUpdateWorldTransform() const;

GetWorldPosition() Vector3

Returns the node’s world-space position.

Ensures the world transform is current via UpdateWorldTransform, then extracts the translation column of the world matrix.

Vector3 Node::GetWorldPosition();

GetWorldTransform() Matrix4

Returns the node’s world transform matrix.

If transform auto-updates are enabled, calls UpdateTransformHierarchy to refresh this node and all descendants. Otherwise, returns the cached world transform as-is.

Matrix4 Node::GetWorldTransform();

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.

TranslateX() void

Translates the node along its local X axis.

void Node::TranslateX(float value);

Parameter	Description
value	Offset in local X.

TranslateY() void

Translates the node along its local Y axis.

void Node::TranslateY(float value);

Parameter	Description
value	Offset in local Y.

TranslateZ() void

Translates the node along its local Z axis.

void Node::TranslateZ(float value);

Parameter	Description
value	Offset in local Z.

RotateX() void

Rotates the node around its local X axis.

void Node::RotateX(float angle);

Parameter	Description
angle	Angle in radians.

RotateY() void

Rotates the node around its local Y axis.

void Node::RotateY(float angle);

Parameter	Description
angle	Angle in radians.

RotateZ() void

Rotates the node around its local Z axis.

void Node::RotateZ(float angle);

Parameter	Description
angle	Angle in radians.

SetScale() void

Sets the local scale of the node.

void Node::SetScale(const Vector3& value);

Parameter	Description
value	New scale vector.

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.

OnAttached() void virtual

Called when the node is attached to a scene context.

Override this to perform initialization that depends on the application's shared context.

virtual void Node::OnAttached(SharedContextPointer context);

Parameter	Description
context	Shared engine context.

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.

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;