The IRoot interface. More...

#include "murl_graph_i_root.h"

Inherited by Murl::Core::GraphRoot.

Public Member Functions

virtual const IFactoryGetGraphFactory () const =0
 Get the graph object factory. More...
 
virtual INodeGetRootNode () const =0
 Get the actual root node. More...
 
virtual INamespaceGetRootNamespace () const =0
 Get the actual root namespace node. More...
 
virtual INodeFindNode (const String &nodeIdPath) const =0
 Find a node in the graph by its ID. More...
 
virtual Bool CanModifyGraph () const =0
 Check if graph modifications are currently allowed. More...
 
virtual INodeCreateNode (const String &className)=0
 Create a single unnamed node by its class name. More...
 
virtual INodeCreateNode (const String &className, const String &nodeId)=0
 Create a single named node by its class name, using a given node ID. More...
 
virtual INodeCreateNode (const String &className, const IAttributes *attributes, const IAttributes *parameters)=0
 Create a single node by its class name, given attributes and optional parameters. More...
 
virtual INodeCreateNode (const String &className, const String &baseResourcePath, const IAttributes *attributes, const IAttributes *parameters)=0
 Create a single node by its class name, with given base resource path, attributes and optional parameters. More...
 
virtual Bool DestroyNode (INode *node)=0
 Destroy a single node. More...
 
virtual INodeCreateGraph (const Resource::IGraph *graphResource)=0
 Create a sub-graph from a given graph resource template. More...
 
virtual INodeCreateGraph (const Resource::IGraph *graphResource, const IAttributes *params)=0
 Create a sub-graph from a given graph resource template, with given parameters. More...
 
virtual Bool DestroyGraph (INode *node)=0
 Destroy an entire sub-graph. More...
 
virtual Bool DeserializeNodeAttributes (INode *node, const IAttributes *attributes, const IAttributes *parameters)=0
 Deserialize a given node from a set of attributes and optional parameters. More...
 
virtual Bool DeserializeNodeAttributes (INode *node, const String &baseResourcePath, const IAttributes *attributes, const IAttributes *parameters)=0
 Deserialize a given node from a set of attributes and optional parameters, with a given base resource path. More...
 
virtual Bool InitGraph (INode *rootNode, INode *parentNode, SInt32 index=-1, Bool releaseLock=true)=0
 Attach a sub-graph to the scene graph and initialize it. More...
 
virtual Bool DeInitGraph (INode *rootNode, Bool releaseLock=true)=0
 De-initialize a sub-graph and detach it from the scene graph. More...
 
virtual Bool InitNode (INode *rootNode, Bool releaseLock=true)=0
 Initialize a single node and its sub-graph. More...
 
virtual Bool DeInitNode (INode *rootNode, Bool releaseLock=true)=0
 De-initialize a sub-graph. More...
 
virtual IControllerCreateController (const String &className, Graph::INode *owner)=0
 Create a node controller by its class name. More...
 
virtual IControllerCreateController (const String &className, Graph::INode *owner, const IAttributes *attributes, const IAttributes *parameters)=0
 Create a node controller by its class name, given attributes and optional parameters. More...
 
virtual IControllerCreateController (const String &className, Graph::INode *owner, const String &baseResourcePath, const IAttributes *attributes, const IAttributes *parameters)=0
 Create a node controller by its class name, with given base resource path, attributes and optional parameters. More...
 
virtual Bool DestroyController (IController *controller)=0
 Destroy a node controller. More...
 
virtual Bool DeserializeControllerAttributes (IController *controller, const IAttributes *attributes, const IAttributes *parameters)=0
 Deserialize a given controller from a set of attributes and optional parameters. More...
 
virtual Bool DeserializeControllerAttributes (IController *controller, const String &baseResourcePath, const IAttributes *attributes, const IAttributes *parameters)=0
 Deserialize a given controller from a set of attributes and optional parameters, with a given base resource path. More...
 
virtual Bool InitController (IController *controller, Bool releaseLock=true)=0
 Initialize a node controller. More...
 
virtual Bool DeInitController (IController *controller, Bool releaseLock=true)=0
 De-initialize a node controller. More...
 
virtual SInt32 AcquireUserDataId (const String &uniqueName)=0
 Acquire a unique ID for pushing/popping user data objects on a tracker. More...
 
virtual Bool ReleaseUserDataId (const String &uniqueName)=0
 Release a previously acquired unique user data ID. More...
 
virtual Bool PushUserData (SInt32 id, void *userData)=0
 Push a user data object with given ID for initialization/deinitialization. More...
 
virtual Bool PopUserData (SInt32 id)=0
 Pop a user data object with a given ID. More...
 
virtual void * GetRecentUserData (SInt32 id) const =0
 Get the most recent user data object with a given ID. More...
 
virtual Bool TriggerSwapping (IEnums::SuspendTrigger trigger=IEnums::SUSPEND_TRIGGER_MANUAL)=0
 Trigger swapping of scene graph nodes. More...
 
virtual Bool PrintTree () const =0
 Print the entire scene graph to the system console. More...
 
virtual Bool Lock ()=0
 Lock the scene graph to prevent modifications. More...
 
virtual Bool Unlock ()=0
 Unlock the scene graph after it has been locked. More...
 
virtual Bool CancelFinishLogic (INode *node)=0
 Cancel the finish logic traversal for a given node. More...
 
virtual Bool CancelFinishInput (INode *node)=0
 Cancel the finish input traversal for a given node. More...
 
virtual Bool CancelFinishOutput (INode *node)=0
 Cancel the finish outout traversal for a given node. More...
 
virtual const Array< const ITrackerResult * > & GetInitResults () const =0
 Get the array of result messages added during the last call to InitGraph() or InitNode(). More...
 
virtual const Array< const ITrackerResult * > & GetDeInitResults () const =0
 Get the array of result messages added during the last call to DeInitGraph() or DeInitNode(). More...
 
virtual Bool CollectStatisticsObjects (Index< const IStatisticsObject * > &objects) const =0
 Populate a given index with all statistics objects currently present in the graph. More...
 

Detailed Description

The IRoot interface.

This interface represents the root of a scene graph, containing exactly one Graph::INode as the actual root of the graph where other nodes can be inserted. The root object holds a reference to a Graph::IFactory object, so it is possible to create or destroy individual nodes or sub-graphs via respective methods.

Member Function Documentation

◆ GetGraphFactory()

virtual const IFactory* Murl::Graph::IRoot::GetGraphFactory ( ) const
pure virtual

Get the graph object factory.

Returns
The graph object factory.

◆ GetRootNode()

virtual INode* Murl::Graph::IRoot::GetRootNode ( ) const
pure virtual

Get the actual root node.

Returns
The root node.

◆ GetRootNamespace()

virtual INamespace* Murl::Graph::IRoot::GetRootNamespace ( ) const
pure virtual

◆ FindNode()

virtual INode* Murl::Graph::IRoot::FindNode ( const String nodeIdPath) const
pure virtual

Find a node in the graph by its ID.

Named nodes in the scene graph can be hierarchically organized using Graph::INamespace nodes. Namespaces provide a means of accessing individual named nodes using a file-system like path scheme, with the '/' character serving as a namespace delimiter.

Parameters
nodeIdPathThe node ID to find, with optional path specification when searching in sub-namespaces.
Returns
A pointer to the requested node, or null if not found.

Referenced by Murl::Logic::GraphPositionInstance::Init(), Murl::Logic::GraphReplication::Init(), and Murl::Logic::GraphSoundInstance::Init().

◆ CanModifyGraph()

virtual Bool Murl::Graph::IRoot::CanModifyGraph ( ) const
pure virtual

Check if graph modifications are currently allowed.

When the engine is in the middle of a scene graph traversal, it is usually a bad idea to perform any structural modifications (e.g. adding or removing nodes) of the graph from within a different thread context. Modifications should only occur when this method returns true, i.e. the graph is currently idle.

Returns
true if modifications are allowed.

◆ CreateNode() [1/4]

virtual INode* Murl::Graph::IRoot::CreateNode ( const String className)
pure virtual

Create a single unnamed node by its class name.

This method creates a single node using the underlying graph factory. The newly created node is not yet inserted into the graph; instead, it is possible to create a number of individual nodes and create an entire sub-graph (e.g. using Graph::INode::AddChild()) before actually adding them to the graph. Adding (and initializing) such a sub-graph must be done via InitGraph().

Parameters
classNameThe node class name.
Returns
A pointer to the newly created node, or null if failed.

◆ CreateNode() [2/4]

virtual INode* Murl::Graph::IRoot::CreateNode ( const String className,
const String nodeId 
)
pure virtual

Create a single named node by its class name, using a given node ID.

This is equivalent to calling CreateNode(className) followed by a call to Graph::INode::SetId(nodeId).

Parameters
classNameThe node class name.
nodeIdThe node ID.
Returns
A pointer to the newly created node, or null if failed.

◆ CreateNode() [3/4]

virtual INode* Murl::Graph::IRoot::CreateNode ( const String className,
const IAttributes attributes,
const IAttributes parameters 
)
pure virtual

Create a single node by its class name, given attributes and optional parameters.

Parameters
classNameThe node class name.
attributesThe attributes to deserialize.
parametersThe optional parameters.
Returns
A pointer to the newly created node, or null if failed.

◆ CreateNode() [4/4]

virtual INode* Murl::Graph::IRoot::CreateNode ( const String className,
const String baseResourcePath,
const IAttributes attributes,
const IAttributes parameters 
)
pure virtual

Create a single node by its class name, with given base resource path, attributes and optional parameters.

Parameters
classNameThe class name of the node to create.
baseResourcePathThe base path for referencing relative resource IDs.
attributesThe attributes to deserialize.
parametersThe optional parameters.
Returns
The newly created node, or null if failed.

◆ DestroyNode()

virtual Bool Murl::Graph::IRoot::DestroyNode ( INode node)
pure virtual

Destroy a single node.

This method fails if the given node has children attached. Use DestroyGraph() when it is desired to recursively destroy an entire sub-graph. This method also fails when the given node is still initialized. Use DeInitGraph() on that node before actually destroying it.

Parameters
nodeThe node to destroy.
Returns
true if successful.

◆ CreateGraph() [1/2]

virtual INode* Murl::Graph::IRoot::CreateGraph ( const Resource::IGraph graphResource)
pure virtual

Create a sub-graph from a given graph resource template.

This method creates a sub-graph using the instantiation information present in a given graph resource template, which can be obtained from e.g. a Resource::ICollection object. If successful, the root node of the newly created sub-graph is returned.

Parameters
graphResourceThe graph resource template from which to create the sub-graph.
Returns
A pointer to the root of the newly created sub-graph, or null if failed.

◆ CreateGraph() [2/2]

virtual INode* Murl::Graph::IRoot::CreateGraph ( const Resource::IGraph graphResource,
const IAttributes params 
)
pure virtual

Create a sub-graph from a given graph resource template, with given parameters.

This method can be used to create a sub-graph in the same way as CreateGraph(graphResource), with an additional set of user-defined parameters.

Parameters
graphResourceThe graph resource template from which to create the sub-graph.
paramsAn attributes object containing custom parameters used for instantiation.
Returns
A pointer to the root of the newly created sub-graph, or null if failed.

◆ DestroyGraph()

virtual Bool Murl::Graph::IRoot::DestroyGraph ( INode node)
pure virtual

Destroy an entire sub-graph.

The sub-graph represented by the given node must be de-initialized using DeInitGraph() before it can be destroyed.

Parameters
nodeThe root node of the sub-graph to destroy.
Returns
true if successful.

◆ DeserializeNodeAttributes() [1/2]

virtual Bool Murl::Graph::IRoot::DeserializeNodeAttributes ( INode node,
const IAttributes attributes,
const IAttributes parameters 
)
pure virtual

Deserialize a given node from a set of attributes and optional parameters.

Parameters
nodeThe node to deserialize.
attributesThe attributes.
parametersThe optional parameters.
Returns
true if successful.

◆ DeserializeNodeAttributes() [2/2]

virtual Bool Murl::Graph::IRoot::DeserializeNodeAttributes ( INode node,
const String baseResourcePath,
const IAttributes attributes,
const IAttributes parameters 
)
pure virtual

Deserialize a given node from a set of attributes and optional parameters, with a given base resource path.

Parameters
nodeThe node to deserialize.
baseResourcePathThe base path for referencing relative resource IDs.
attributesThe attributes.
parametersThe optional parameters.
Returns
true if successful.

◆ InitGraph()

virtual Bool Murl::Graph::IRoot::InitGraph ( INode rootNode,
INode parentNode,
SInt32  index = -1,
Bool  releaseLock = true 
)
pure virtual

Attach a sub-graph to the scene graph and initialize it.

After creating a single node or sub-graph, it must be attached and initialized in order to get processed. This method adds the sub-graph represented by rootNode as a child of the given parentNode and recursively calls Init() on that node. If it is desired to add the given sub-graph right at the scene graph root, the parentNode parameter may be obtained by calling GetRootNode().

Parameters
rootNodeThe root of the sub-graph to add and initialize.
parentNodeThe parent node where to insert.
indexThe position within the parent node, or -1 if appending at the end.
releaseLockIf false, it is implicitly assumed that the logic state is unlocked. Use with caution! This only works when it is ensured that this method is executed outside a single frame loop.
Returns
true if successful.

◆ DeInitGraph()

virtual Bool Murl::Graph::IRoot::DeInitGraph ( INode rootNode,
Bool  releaseLock = true 
)
pure virtual

De-initialize a sub-graph and detach it from the scene graph.

Before destroying a previously created node or sub-graph, it must be de-initialzed and detached using this method.

Parameters
rootNodeThe root of the sub-graph to de-init.
releaseLockIf false, it is implicitly assumed that the logic state is unlocked. Use with caution! This only works when it is ensured that this method is executed outside a single frame loop.
Returns
true if successful.

◆ InitNode()

virtual Bool Murl::Graph::IRoot::InitNode ( INode rootNode,
Bool  releaseLock = true 
)
pure virtual

Initialize a single node and its sub-graph.

This method performs initialization of a node that is already attached to a parent.

Parameters
rootNodeThe root of the sub-graph to initialize.
releaseLockIf false, it is implicitly assumed that the logic state is unlocked. Use with caution! This only works when it is ensured that this method is executed outside a single frame loop.
Returns
true if successful.

◆ DeInitNode()

virtual Bool Murl::Graph::IRoot::DeInitNode ( INode rootNode,
Bool  releaseLock = true 
)
pure virtual

De-initialize a sub-graph.

Parameters
rootNodeThe root of the sub-graph to de-init.
releaseLockIf false, it is implicitly assumed that the logic state is unlocked. Use with caution! This only works when it is ensured that this method is executed outside a single frame loop.
Returns
true if successful.

◆ CreateController() [1/3]

virtual IController* Murl::Graph::IRoot::CreateController ( const String className,
Graph::INode owner 
)
pure virtual

Create a node controller by its class name.

This method creates a node controller using the underlying graph factory. The "owner" parameter specifies which graph node shall be controlled, without having to add the controller to that node in the first place. This way, any number of controllers can be prepared for a node, and dynamically added/removed to/from the node during program execution without having to re-initialize the controllers. The controller must manually be added to the owner (even when an owner was given in this call) to be processed. If it is added before the node gets initialized, it is automatically initialized together with the controlled node. Otherwise the controller must explicitly be initialized via InitController(). The same applies when de-initializing/destroying the owner: If the controller is still attached, it gets automatically de-initialized/destroyed together with the owner. Otherwise, DeInitController()/DestroyController() must be called manually. The owner may be a null pointer at creation time, but in this case an explicit owner must be set via Graph::IController::SetOwner() before InitController() can be called. Theoretically it is possible to add the controller to a node that is different to the specified owner, but such a setup should be used with care. In practice, one should take care that the controller is only added to its defined owner.

Parameters
classNameThe controller class name.
ownerThe owning node.
Returns
A pointer to the newly created controller, or null if failed.

◆ CreateController() [2/3]

virtual IController* Murl::Graph::IRoot::CreateController ( const String className,
Graph::INode owner,
const IAttributes attributes,
const IAttributes parameters 
)
pure virtual

Create a node controller by its class name, given attributes and optional parameters.

See CreateController(const String& className, Graph::INode* owner).

Parameters
classNameThe controller class name.
ownerThe owning node.
attributesThe attributes to deserialize.
parametersThe optional parameters.
Returns
A pointer to the newly created controller, or null if failed.

◆ CreateController() [3/3]

virtual IController* Murl::Graph::IRoot::CreateController ( const String className,
Graph::INode owner,
const String baseResourcePath,
const IAttributes attributes,
const IAttributes parameters 
)
pure virtual

Create a node controller by its class name, with given base resource path, attributes and optional parameters.

See CreateController(const String& className, Graph::INode* owner).

Parameters
classNameThe class name of the controller to create.
ownerThe owning node.
baseResourcePathThe base path for referencing relative resource IDs.
attributesThe attributes to deserialize.
parametersThe optional parameters.
Returns
The newly created controller, or null if failed.

◆ DestroyController()

virtual Bool Murl::Graph::IRoot::DestroyController ( IController controller)
pure virtual

Destroy a node controller.

See CreateController(const String& className, Graph::INode* owner).

Parameters
controllerThe controller to destroy.
Returns
true if successful.

◆ DeserializeControllerAttributes() [1/2]

virtual Bool Murl::Graph::IRoot::DeserializeControllerAttributes ( IController controller,
const IAttributes attributes,
const IAttributes parameters 
)
pure virtual

Deserialize a given controller from a set of attributes and optional parameters.

Parameters
controllerThe controller to deserialize.
attributesThe attributes.
parametersThe optional parameters.
Returns
true if successful.

◆ DeserializeControllerAttributes() [2/2]

virtual Bool Murl::Graph::IRoot::DeserializeControllerAttributes ( IController controller,
const String baseResourcePath,
const IAttributes attributes,
const IAttributes parameters 
)
pure virtual

Deserialize a given controller from a set of attributes and optional parameters, with a given base resource path.

Parameters
controllerThe controller to deserialize.
baseResourcePathThe base path for referencing relative resource IDs.
attributesThe attributes.
parametersThe optional parameters.
Returns
true if successful.

◆ InitController()

virtual Bool Murl::Graph::IRoot::InitController ( IController controller,
Bool  releaseLock = true 
)
pure virtual

Initialize a node controller.

See CreateController(const String& className, Graph::INode* owner). This method performs initialization of a controller that is not yet added to an owning node.

Parameters
controllerThe controller to initialize.
releaseLockIf false, it is implicitly assumed that the logic state is unlocked. Use with caution! This only works when it is ensured that this method is executed outside a single frame loop.
Returns
true if successful.

◆ DeInitController()

virtual Bool Murl::Graph::IRoot::DeInitController ( IController controller,
Bool  releaseLock = true 
)
pure virtual

De-initialize a node controller.

See CreateController(const String& className, Graph::INode* owner).

Parameters
controllerThe controller to de-init.
releaseLockIf false, it is implicitly assumed that the logic state is unlocked. Use with caution! This only works when it is ensured that this method is executed outside a single frame loop.
Returns
true if successful.

◆ AcquireUserDataId()

virtual SInt32 Murl::Graph::IRoot::AcquireUserDataId ( const String uniqueName)
pure virtual

Acquire a unique ID for pushing/popping user data objects on a tracker.

Parameters
uniqueNameA unique name string for which to acquire an ID.
Returns
The unique ID, or -1 if failed.

◆ ReleaseUserDataId()

virtual Bool Murl::Graph::IRoot::ReleaseUserDataId ( const String uniqueName)
pure virtual

Release a previously acquired unique user data ID.

Parameters
uniqueNameThe unique name string of the ID to release.
Returns
true if the released ID is still in use by another class, or false if this was the last instance or the ID was unknown.

◆ PushUserData()

virtual Bool Murl::Graph::IRoot::PushUserData ( SInt32  id,
void *  userData 
)
pure virtual

Push a user data object with given ID for initialization/deinitialization.

Parameters
idThe unique user data ID previously acquired via AcquireUserDataId().
userDataThe user data object.
Returns
true if successful.

◆ PopUserData()

virtual Bool Murl::Graph::IRoot::PopUserData ( SInt32  id)
pure virtual

Pop a user data object with a given ID.

Parameters
idThe unique user data ID previously acquired via AcquireUserDataId().
Returns
true if successful.

◆ GetRecentUserData()

virtual void* Murl::Graph::IRoot::GetRecentUserData ( SInt32  id) const
pure virtual

Get the most recent user data object with a given ID.

Parameters
idThe unique user data ID previously acquired via AcquireUserDataId().
Returns
The user data object, or null if none is present.

◆ TriggerSwapping()

virtual Bool Murl::Graph::IRoot::TriggerSwapping ( IEnums::SuspendTrigger  trigger = IEnums::SUSPEND_TRIGGER_MANUAL)
pure virtual

Trigger swapping of scene graph nodes.

Certain memory-intensive nodes (e.g. Graph::FlatTexture) support on-demand swapping of their internal data storage when they are not currently active. This method triggers such a single swapping process on the whole scene graph; any nodes that have manual swapping enabled (e.g. by calling Graph::INode::SetManualSwappingEnabled()) react on this event and try to release any currently unused memory resources. Calling this method is useful after e.g. a memory warning from the OS, or if the application hides a certain scene. If the given trigger type has lower priority than another trigger previously set (e.g. SUSPEND_TRIGGER_MANUAL vs. SUSPEND_TRIGGER_EMERGENCY), the trigger with higher priority persists (SUSPEND_TRIGGER_EMERGENCY in this example).

Parameters
triggerThe type of trigger to apply.
Returns
true if successful.

◆ PrintTree()

virtual Bool Murl::Graph::IRoot::PrintTree ( ) const
pure virtual

Print the entire scene graph to the system console.

Returns
true if successful.

◆ Lock()

virtual Bool Murl::Graph::IRoot::Lock ( )
pure virtual

Lock the scene graph to prevent modifications.

Returns
true if successful.

◆ Unlock()

virtual Bool Murl::Graph::IRoot::Unlock ( )
pure virtual

Unlock the scene graph after it has been locked.

Returns
true if successful.

◆ CancelFinishLogic()

virtual Bool Murl::Graph::IRoot::CancelFinishLogic ( INode node)
pure virtual

Cancel the finish logic traversal for a given node.

Parameters
nodeThe node to cancel.
Returns
true if successful.

◆ CancelFinishInput()

virtual Bool Murl::Graph::IRoot::CancelFinishInput ( INode node)
pure virtual

Cancel the finish input traversal for a given node.

Parameters
nodeThe node to cancel.
Returns
true if successful.

◆ CancelFinishOutput()

virtual Bool Murl::Graph::IRoot::CancelFinishOutput ( INode node)
pure virtual

Cancel the finish outout traversal for a given node.

Parameters
nodeThe node to cancel.
Returns
true if successful.

◆ GetInitResults()

virtual const Array<const ITrackerResult*>& Murl::Graph::IRoot::GetInitResults ( ) const
pure virtual

Get the array of result messages added during the last call to InitGraph() or InitNode().

Returns
The array of messages.

◆ GetDeInitResults()

virtual const Array<const ITrackerResult*>& Murl::Graph::IRoot::GetDeInitResults ( ) const
pure virtual

Get the array of result messages added during the last call to DeInitGraph() or DeInitNode().

Returns
The array of messages.

◆ CollectStatisticsObjects()

virtual Bool Murl::Graph::IRoot::CollectStatisticsObjects ( Index< const IStatisticsObject * > &  objects) const
pure virtual

Populate a given index with all statistics objects currently present in the graph.

For this method to successfully return all the present objects, the method IEngineConfiguration::SetExtendedObjectStatisticsEnabled(true) must be called in the app's Configure() method.

Parameters
objectsAn index to receive all the present objects.
Returns
true if successful.

The documentation for this interface was generated from the following file:
  • murl_graph_i_root.h


Copyright © 2011-2024 Spraylight GmbH.