The SceneSystem, a singleton System, responsible for tracking all objects in the scene, computing their Transforms, and maintaining hierarchical relationships between scene nodes. More...

#include <scene_system.hpp>

Inheritance diagram for ToyMaker::SceneSystem:

Classes
struct	getNodeByID_Helper
	Helper struct for retrieving nodes based on their UniversalEntityIDs. More...

struct	getNodeByID_Helper< TSceneNode, typename std::enable_if_t< std::is_base_of< SceneNodeCore, TSceneNode >::value > >

class	SceneSubworld
	A subsystem of the SceneSystem which tracks, per world, which objects have had their Placement components updated. More...

Public Member Functions
	SceneSystem (std::weak_ptr< ECSWorld > world)
	Constructs a new SceneSystem object.

bool	isSingleton () const override
	Informs this System's ECSWorld that the SceneSystem is a singleton, i.e., there should not be more than one instance of it in the entire project, regardless of how many ECSWorlds are present.

template<typename TObject = std::shared_ptr<SceneNode>>
TObject	getByPath (const std::string &where)
	Gets an object of a specific type based on a valid path to that object belonging to the scene system from its root node.

template<typename TSceneNode>
std::shared_ptr< TSceneNode >	getNodeByID (const UniversalEntityID &universalEntityID)
	Gets a scene node by its world-entity ID pair.

std::vector< std::shared_ptr< SceneNodeCore > >	getNodesByID (const std::vector< UniversalEntityID > &universalEntityIDs)
	Gets nodes by their world-entity ID pair.

std::shared_ptr< SceneNodeCore >	getNode (const std::string &where)
	Gets a node by its scene node path.

std::shared_ptr< SceneNodeCore >	removeNode (const std::string &where)
	Removes a node present at the path specified in the call.

void	addNode (std::shared_ptr< SceneNodeCore > node, const std::string &where)
	Adds a node to the SceneSystem's scene tree as a child of the node specified by its path.

std::weak_ptr< ECSWorld >	getRootWorld () const
	Gets the world associated with the root ViewportNode of the scene system.

ViewportNode &	getRootViewport () const
	Gets a reference to the root viewport of the SceneSystem, usually used to adjust its rendering configuration.

void	onApplicationInitialize (const ViewportNode::RenderConfiguration &rootViewportRenderConfiguration)
	A method intended to be used at the start of the application to configure the SceneSystem's root viewport.

void	onApplicationStart ()
	Method to be called by main to initialize the SceneSystem as a whole.

void	onApplicationEnd ()
	Clean up tasks the SceneSystem should perform before the application is terminated.

void	simulationStep (uint32_t simStepMillis, std::vector< std::pair< ActionDefinition, ActionData > > triggeredActions={})
	Runs a single step for the root viewport and its descendants, propagating any actions generated by the InputManager up until this point.

void	variableStep (float simulationProgress, uint32_t simulationLagMillis, uint32_t variableStepMillis, std::vector< std::pair< ActionDefinition, ActionData > > triggeredActions={})
	Runs the variable step for the SceneSystem's root viewport and its descendants.

void	updateTransforms ()
	Updates transforms of objects in the scene per changes in those object's Placement component.

uint32_t	render (float simulationProgress, uint32_t variableStep)
	Runs the render step for the SceneSystem's root viewport and its descendants.

Static Public Member Functions
static std::string	getSystemTypeName ()
	The system type string associated with the SceneSystem.

Private Member Functions
bool	isActive (std::shared_ptr< const SceneNodeCore > sceneNode) const
	Returns whether a particular scene node is an active member of the SceneSystem's scene tree.

bool	isActive (UniversalEntityID UniversalEntityID) const
	Returns whether a particular scene node is an active member of the SceneSystem's scene tree.

bool	inScene (std::shared_ptr< const SceneNodeCore > sceneNode) const
	Returns whether a particular scene node is in the SceneSystem's scene tree, even if it is inactive.

bool	inScene (UniversalEntityID UniversalEntityID) const
	Returns whether a particular scene node is in the SceneSystem's scene tree, even if it is inactive.

void	markDirty (UniversalEntityID UniversalEntityID)
	Marks a node as in need of a transform update based on its universal entity id.

std::vector< std::shared_ptr< ViewportNode > >	getActiveViewports ()
	Returns a list of active viewports including the root viewport of the scene tree.

std::vector< std::weak_ptr< ECSWorld > >	getActiveWorlds ()
	Returns the ECSWorlds owned by ViewportNodes active in the scene tree.

Transform	getLocalTransform (std::shared_ptr< const SceneNodeCore > sceneNode) const
	Gets the transform of a node solely based on its Placement component and independent of its position in the scene hierarchy.

Transform	getCachedWorldTransform (std::shared_ptr< const SceneNodeCore > sceneNode) const
	Returns the Transform of a node based on both its local Placement and its hierarchical transforms.

void	updateHierarchyDataInsertion (std::shared_ptr< SceneNodeCore > insertedNode)
	Updates a node's scene hierarchy data per its location in the scene tree.

void	updateHierarchyDataRemoval (std::shared_ptr< SceneNodeCore > removedNode)
	Removes a node's scene hierarchy data before it's removed from the hierarchy.

void	nodeAdded (std::shared_ptr< SceneNodeCore > sceneNode)
	Plays any side effects associated with a node being added to the SceneSystem's scene tree.

void	nodeRemoved (std::shared_ptr< SceneNodeCore > sceneNode)
	Plays any side effects related to a node being removed from the SceneSystem's scene tree.

void	nodeActivationChanged (std::shared_ptr< SceneNodeCore > sceneNode, bool state)
	"Activates" or deactivates a node and its descendants on various ECS systems, per the node's system mask.

void	activateSubtree (std::shared_ptr< SceneNodeCore > sceneNode)
	Activates this node and its descendants.

void	deactivateSubtree (std::shared_ptr< SceneNodeCore > sceneNode)
	Deactivates this node and its descendants.

void	onWorldEntityUpdate (UniversalEntityID UniversalEntityID)
	A callback used by this system's subsystem to notify the SceneSystem that an entity has been updated.

std::shared_ptr< SceneNodeCore >	getNodeByID (const UniversalEntityID &universalEntityID)
	Gets the scene node associated with an entity of a world-entity ID pair.

Private Attributes
std::shared_ptr< ViewportNode >	mRootNode { nullptr }
	The root node of the SceneSystem, alive and active throughout the lifetime of the application.

std::map< UniversalEntityID, std::weak_ptr< SceneNodeCore >, std::less< UniversalEntityID > >	mEntityToNode {}
	A mapping from the world-entity IDs of active nodes in the SceneSystem to the nodes themselves.

std::set< UniversalEntityID, std::less< UniversalEntityID > >	mActiveEntities {}
	A list of world-entity IDs associated with all the active nodes known by the SceneSystem.

std::set< UniversalEntityID, std::less< UniversalEntityID > >	mComputeTransformQueue {}
	Nodes which were updated during this variable or simulation step scheduled for a Transform update.

Friends
class	SceneNodeCore

Detailed Description

The SceneSystem, a singleton System, responsible for tracking all objects in the scene, computing their Transforms, and maintaining hierarchical relationships between scene nodes.

In many ways this is the primary interface through which a game developer will manipulate and query the game world. The scene tree is to games what a DOM tree is to browsers.

Constructor & Destructor Documentation

◆ SceneSystem()

ToyMaker::SceneSystem::SceneSystem ( std::weak_ptr< ECSWorld > world )

inlineexplicit

Constructs a new SceneSystem object.

Parameters

world The world this SceneSystem will belong to, which is always the prototype ECSWorld.

Member Function Documentation

◆ activateSubtree()

void SceneSystem::activateSubtree ( std::shared_ptr< SceneNodeCore > sceneNode )

private

Activates this node and its descendants.

Parameters

sceneNode The node being activated.

◆ addNode()

void SceneSystem::addNode	(	std::shared_ptr< SceneNodeCore >	node,
		const std::string &	where )

Adds a node to the SceneSystem's scene tree as a child of the node specified by its path.

Parameters

node	The node being added to the SceneSystem's scene tree.
where	The location of the to-be parent to the new node.

◆ deactivateSubtree()

void SceneSystem::deactivateSubtree ( std::shared_ptr< SceneNodeCore > sceneNode )

private

Deactivates this node and its descendants.

Parameters

sceneNode The node being deactivated.

◆ getActiveViewports()

std::vector< std::shared_ptr< ViewportNode > > SceneSystem::getActiveViewports ( )

private

Returns a list of active viewports including the root viewport of the scene tree.

Returns: std::vector<std::shared_ptr<ViewportNode>> A list of active viewports in the SceneSystem's scene tree.

◆ getActiveWorlds()

std::vector< std::weak_ptr< ECSWorld > > SceneSystem::getActiveWorlds ( )

private

Returns the ECSWorlds owned by ViewportNodes active in the scene tree.

Returns: std::vector<std::weak_ptr<ECSWorld>> A list of active ECSWorlds known by the scene system.

◆ getByPath()

template<typename TObject>

TObject ToyMaker::SceneSystem::getByPath ( const std::string & where )

Gets an object of a specific type based on a valid path to that object belonging to the scene system from its root node.

Template Parameters

TObject The object being retrieved, by default shared pointers to SceneNodes.

Parameters

where The path to the object being retrieved.

Returns: TObject The object retrieved via this method.

◆ getCachedWorldTransform()

Transform SceneSystem::getCachedWorldTransform ( std::shared_ptr< const SceneNodeCore > sceneNode ) const

private

Returns the Transform of a node based on both its local Placement and its hierarchical transforms.

Parameters

sceneNode The node whose Transform is being retrieved.

Returns: Transform The computed Transform.

◆ getLocalTransform()

Transform SceneSystem::getLocalTransform ( std::shared_ptr< const SceneNodeCore > sceneNode ) const

private

Gets the transform of a node solely based on its Placement component and independent of its position in the scene hierarchy.

Parameters

sceneNode The node whose Transform is being computed.

Returns: Transform The computed Transform.

◆ getNode()

std::shared_ptr< SceneNodeCore > SceneSystem::getNode ( const std::string & where )

Gets a node by its scene node path.

Parameters

where The path at which the node may be found relative to the SceneSystem's root node.

Returns: std::shared_ptr<SceneNodeCore> A pointer to the retrieved node.

◆ getNodeByID() [1/2]

template<typename TSceneNode>

std::shared_ptr< TSceneNode > ToyMaker::SceneSystem::getNodeByID ( const UniversalEntityID & universalEntityID )

inline

Gets a scene node by its world-entity ID pair.

Template Parameters

TSceneNode The type of scene node reference deesired.

Parameters

universalEntityID The world-entity ID pair of the node being retrieved.

Returns: std::shared_ptr<TSceneNode> The retrieved node.

◆ getNodeByID() [2/2]

std::shared_ptr< SceneNodeCore > SceneSystem::getNodeByID ( const UniversalEntityID & universalEntityID )

private

Gets the scene node associated with an entity of a world-entity ID pair.

Parameters

universalEntityID The world-entity id pair associated with a note.

Returns: std::shared_ptr<SceneNodeCore> The node associated with the ID passed as argument.

◆ getNodesByID()

std::vector< std::shared_ptr< SceneNodeCore > > SceneSystem::getNodesByID ( const std::vector< UniversalEntityID > & universalEntityIDs )

Gets nodes by their world-entity ID pair.

Parameters

universalEntityIDs A list of world-entity ID pairs for which nodes are desired.

Returns: std::vector<std::shared_ptr<SceneNodeCore>> A list of nodes retrieved.

◆ getRootViewport()

ViewportNode & SceneSystem::getRootViewport ( ) const

Gets a reference to the root viewport of the SceneSystem, usually used to adjust its rendering configuration.

Returns: ViewportNode& A reference to the root viewport of the SceneSystem.

◆ getRootWorld()

std::weak_ptr< ECSWorld > SceneSystem::getRootWorld ( ) const

Gets the world associated with the root ViewportNode of the scene system.

Returns: std::weak_ptr<ECSWorld> A reference to the root node's ECSWorld.

◆ getSystemTypeName()

static std::string ToyMaker::SceneSystem::getSystemTypeName ( )

inlinestatic

The system type string associated with the SceneSystem.

Returns: std::string This system's system type string.

◆ inScene() [1/2]

bool SceneSystem::inScene ( std::shared_ptr< const SceneNodeCore > sceneNode ) const

private

Returns whether a particular scene node is in the SceneSystem's scene tree, even if it is inactive.

Parameters

sceneNode The scene node whose membership in the scene tree is being tested.

Return values

true	The scene node is a member of the SceneSystem's scene tree.
false	The scene node is not a member of the SceneSystem's scene tree.

◆ inScene() [2/2]

bool SceneSystem::inScene ( UniversalEntityID UniversalEntityID ) const

private

Returns whether a particular scene node is in the SceneSystem's scene tree, even if it is inactive.

Parameters

UniversalEntityID The ID of the entity of the node whose membership in the scene tree is being tested.

Return values

true	The scene node is a member of the SceneSystem's scene tree.
false	The scene node is not a member of the SceneSystem's scene tree.

◆ isActive() [1/2]

bool SceneSystem::isActive ( std::shared_ptr< const SceneNodeCore > sceneNode ) const

private

Returns whether a particular scene node is an active member of the SceneSystem's scene tree.

Parameters

sceneNode The scene node whose activity is being queried.

Return values

true	The scene node is active.
false	The scene node is inactive.

◆ isActive() [2/2]

bool SceneSystem::isActive ( UniversalEntityID UniversalEntityID ) const

private

Returns whether a particular scene node is an active member of the SceneSystem's scene tree.

Parameters

UniversalEntityID The id of the entity of the scene node whose activity is being queried.

Return values

true	The scene node is active.
false	The scene node is not active.

◆ isSingleton()

bool ToyMaker::SceneSystem::isSingleton ( ) const

inlineoverride

Informs this System's ECSWorld that the SceneSystem is a singleton, i.e., there should not be more than one instance of it in the entire project, regardless of how many ECSWorlds are present.

Return values

true	The SceneSystem is a singleton System;

Todo: This is obviously stupid and I should do something about it.

◆ markDirty()

void SceneSystem::markDirty ( UniversalEntityID UniversalEntityID )

private

Marks a node as in need of a transform update based on its universal entity id.

Parameters

UniversalEntityID The ID of the node needing a Transform update.

◆ nodeActivationChanged()

void SceneSystem::nodeActivationChanged	(	std::shared_ptr< SceneNodeCore >	sceneNode,
		bool	state )

private

"Activates" or deactivates a node and its descendants on various ECS systems, per the node's system mask.

Parameters

sceneNode	The node whose activation is changing.
state	Whether the node is active or not.

◆ nodeAdded()

void SceneSystem::nodeAdded ( std::shared_ptr< SceneNodeCore > sceneNode )

private

Plays any side effects associated with a node being added to the SceneSystem's scene tree.

Parameters

sceneNode The node that was added.

◆ nodeRemoved()

void SceneSystem::nodeRemoved ( std::shared_ptr< SceneNodeCore > sceneNode )

private

Plays any side effects related to a node being removed from the SceneSystem's scene tree.

Parameters

sceneNode The node that was removed.

◆ onApplicationInitialize()

void SceneSystem::onApplicationInitialize ( const ViewportNode::RenderConfiguration & rootViewportRenderConfiguration )

A method intended to be used at the start of the application to configure the SceneSystem's root viewport.

Parameters

rootViewportRenderConfiguration The render configuration for the SceneSystem's root ViewportNode.

◆ onWorldEntityUpdate()

void SceneSystem::onWorldEntityUpdate ( UniversalEntityID UniversalEntityID )

private

A callback used by this system's subsystem to notify the SceneSystem that an entity has been updated.

Parameters

UniversalEntityID The world-entity id pair associated with the updated active scene node.

◆ removeNode()

std::shared_ptr< SceneNodeCore > SceneSystem::removeNode ( const std::string & where )

Removes a node present at the path specified in the call.

Parameters

where The path to the node being removed.

Returns: std::shared_ptr<SceneNodeCore> A reference to the removed node.

◆ render()

uint32_t SceneSystem::render	(	float	simulationProgress,
		uint32_t	variableStep )

Runs the render step for the SceneSystem's root viewport and its descendants.

Parameters

simulationProgress	Progress to the start of the next simulation step after the end of the previous one, as a number between 0 and 1.
variableStep	The time since the last simulation step.

Returns: uint32_t The time to the next render execution, in milliseconds, based on the SceneSystem's root ViewportNode's configuration.

◆ simulationStep()

void SceneSystem::simulationStep	(	uint32_t	simStepMillis,
		std::vector< std::pair< ActionDefinition, ActionData > >	triggeredActions = {} )

Runs a single step for the root viewport and its descendants, propagating any actions generated by the InputManager up until this point.

Parameters

simStepMillis	The time by which the simulation should be advanced.
triggeredActions	Actions triggered up until the current point in the simulation.

◆ updateHierarchyDataInsertion()

void SceneSystem::updateHierarchyDataInsertion ( std::shared_ptr< SceneNodeCore > insertedNode )

private

Updates a node's scene hierarchy data per its location in the scene tree.

Parameters

insertedNode The node just inserted into the SceneSystem's scene tree.

◆ updateHierarchyDataRemoval()

void SceneSystem::updateHierarchyDataRemoval ( std::shared_ptr< SceneNodeCore > removedNode )

private

Removes a node's scene hierarchy data before it's removed from the hierarchy.

Parameters

removedNode The node removed from the SceneSystem's scene tree.

◆ variableStep()

void SceneSystem::variableStep	(	float	simulationProgress,
		uint32_t	simulationLagMillis,
		uint32_t	variableStepMillis,
		std::vector< std::pair< ActionDefinition, ActionData > >	triggeredActions = {} )

Runs the variable step for the SceneSystem's root viewport and its descendants.

This variable step may run multiple times between simulation steps, or once every handful of simulation steps, depending on the processing power and tasks being performed by the platform on which this application is running.

Parameters

simulationProgress	The progress to the next simulation step after the previous simulation step as a number between 0 and 1.
simulationLagMillis	The time to the next simulation step at the present time, in milliseconds.
variableStepMillis	The time since the computation of the last frame.
triggeredActions	All unhandled actions triggered to the time this step is being run.

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

src/engine/scene_system.hpp
src/engine/scene_system.cpp

Classes

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ SceneSystem()

Member Function Documentation

◆ activateSubtree()

◆ addNode()

◆ deactivateSubtree()

◆ getActiveViewports()

◆ getActiveWorlds()

◆ getByPath()

◆ getCachedWorldTransform()

◆ getLocalTransform()

◆ getNode()

◆ getNodeByID() [1/2]

◆ getNodeByID() [2/2]

◆ getNodesByID()

◆ getRootViewport()

◆ getRootWorld()

◆ getSystemTypeName()

◆ inScene() [1/2]

◆ inScene() [2/2]

◆ isActive() [1/2]

◆ isActive() [2/2]

◆ isSingleton()

◆ markDirty()

◆ nodeActivationChanged()

◆ nodeAdded()

◆ nodeRemoved()

◆ onApplicationInitialize()

◆ onWorldEntityUpdate()

◆ removeNode()

◆ render()

◆ simulationStep()

◆ updateHierarchyDataInsertion()

◆ updateHierarchyDataRemoval()

◆ variableStep()