#include "murl_graph_i_root.h"
Inherited by Murl::Core::GraphRoot.
Public Member Functions | |
virtual const IFactory * | GetGraphFactory () const =0 |
Get the graph object factory. More... | |
virtual INode * | GetRootNode () const =0 |
Get the actual root node. More... | |
virtual INamespace * | GetRootNamespace () const =0 |
Get the actual root namespace node. More... | |
virtual INode * | FindNode (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 INode * | CreateNode (const String &className)=0 |
Create a single unnamed node by its class name. More... | |
virtual INode * | CreateNode (const String &className, const String &nodeId)=0 |
Create a single named node by its class name, using a given node ID. More... | |
virtual INode * | CreateNode (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 INode * | CreateNode (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 INode * | CreateGraph (const Resource::IGraph *graphResource)=0 |
Create a sub-graph from a given graph resource template. More... | |
virtual INode * | CreateGraph (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 IController * | CreateController (const String &className, Graph::INode *owner)=0 |
Create a node controller by its class name. More... | |
virtual IController * | CreateController (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 IController * | CreateController (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()
|
pure virtual |
Get the graph object factory.
- Returns
- The graph object factory.
◆ GetRootNode()
|
pure virtual |
Get the actual root node.
- Returns
- The root node.
◆ GetRootNamespace()
|
pure virtual |
Get the actual root namespace node.
- Returns
- The root namespace node.
Referenced by Murl::Logic::GraphNodeT< NodeType >::GetReference(), Murl::Logic::GraphNodeT< NodeType >::GraphNodeT(), Murl::Logic::GraphPositionObject::Init(), Murl::Logic::GraphSoundObject::Init(), and Murl::Logic::GraphNodeT< NodeType >::ResolveReference().
◆ FindNode()
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
-
nodeIdPath The 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()
|
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]
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
-
className The node class name.
- Returns
- A pointer to the newly created node, or null if failed.
◆ CreateNode() [2/4]
|
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
-
className The node class name. nodeId The node ID.
- Returns
- A pointer to the newly created node, or null if failed.
◆ CreateNode() [3/4]
|
pure virtual |
Create a single node by its class name, given attributes and optional parameters.
- Parameters
-
className The node class name. attributes The attributes to deserialize. parameters The optional parameters.
- Returns
- A pointer to the newly created node, or null if failed.
◆ CreateNode() [4/4]
|
pure virtual |
Create a single node by its class name, with given base resource path, attributes and optional parameters.
- Parameters
-
className The class name of the node to create. baseResourcePath The base path for referencing relative resource IDs. attributes The attributes to deserialize. parameters The optional parameters.
- Returns
- The newly created node, or null if failed.
◆ DestroyNode()
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
-
node The node to destroy.
- Returns
- true if successful.
◆ CreateGraph() [1/2]
|
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
-
graphResource The 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]
|
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
-
graphResource The graph resource template from which to create the sub-graph. params An 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()
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
-
node The root node of the sub-graph to destroy.
- Returns
- true if successful.
◆ DeserializeNodeAttributes() [1/2]
|
pure virtual |
Deserialize a given node from a set of attributes and optional parameters.
- Parameters
-
node The node to deserialize. attributes The attributes. parameters The optional parameters.
- Returns
- true if successful.
◆ DeserializeNodeAttributes() [2/2]
|
pure virtual |
Deserialize a given node from a set of attributes and optional parameters, with a given base resource path.
- Parameters
-
node The node to deserialize. baseResourcePath The base path for referencing relative resource IDs. attributes The attributes. parameters The optional parameters.
- Returns
- true if successful.
◆ InitGraph()
|
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
-
rootNode The root of the sub-graph to add and initialize. parentNode The parent node where to insert. index The position within the parent node, or -1 if appending at the end. releaseLock If 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()
|
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
-
rootNode The root of the sub-graph to de-init. releaseLock If 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()
|
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
-
rootNode The root of the sub-graph to initialize. releaseLock If 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()
|
pure virtual |
De-initialize a sub-graph.
- Parameters
-
rootNode The root of the sub-graph to de-init. releaseLock If 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]
|
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
-
className The controller class name. owner The owning node.
- Returns
- A pointer to the newly created controller, or null if failed.
◆ CreateController() [2/3]
|
pure virtual |
Create a node controller by its class name, given attributes and optional parameters.
See CreateController(const String& className, Graph::INode* owner).
- Parameters
-
className The controller class name. owner The owning node. attributes The attributes to deserialize. parameters The optional parameters.
- Returns
- A pointer to the newly created controller, or null if failed.
◆ CreateController() [3/3]
|
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
-
className The class name of the controller to create. owner The owning node. baseResourcePath The base path for referencing relative resource IDs. attributes The attributes to deserialize. parameters The optional parameters.
- Returns
- The newly created controller, or null if failed.
◆ DestroyController()
|
pure virtual |
Destroy a node controller.
See CreateController(const String& className, Graph::INode* owner).
- Parameters
-
controller The controller to destroy.
- Returns
- true if successful.
◆ DeserializeControllerAttributes() [1/2]
|
pure virtual |
Deserialize a given controller from a set of attributes and optional parameters.
- Parameters
-
controller The controller to deserialize. attributes The attributes. parameters The optional parameters.
- Returns
- true if successful.
◆ DeserializeControllerAttributes() [2/2]
|
pure virtual |
Deserialize a given controller from a set of attributes and optional parameters, with a given base resource path.
- Parameters
-
controller The controller to deserialize. baseResourcePath The base path for referencing relative resource IDs. attributes The attributes. parameters The optional parameters.
- Returns
- true if successful.
◆ InitController()
|
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
-
controller The controller to initialize. releaseLock If 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()
|
pure virtual |
De-initialize a node controller.
See CreateController(const String& className, Graph::INode* owner).
- Parameters
-
controller The controller to de-init. releaseLock If 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()
Acquire a unique ID for pushing/popping user data objects on a tracker.
- Parameters
-
uniqueName A unique name string for which to acquire an ID.
- Returns
- The unique ID, or -1 if failed.
◆ ReleaseUserDataId()
Release a previously acquired unique user data ID.
- Parameters
-
uniqueName The 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()
Push a user data object with given ID for initialization/deinitialization.
- Parameters
-
id The unique user data ID previously acquired via AcquireUserDataId(). userData The user data object.
- Returns
- true if successful.
◆ PopUserData()
Pop a user data object with a given ID.
- Parameters
-
id The unique user data ID previously acquired via AcquireUserDataId().
- Returns
- true if successful.
◆ GetRecentUserData()
|
pure virtual |
Get the most recent user data object with a given ID.
- Parameters
-
id The unique user data ID previously acquired via AcquireUserDataId().
- Returns
- The user data object, or null if none is present.
◆ TriggerSwapping()
|
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
-
trigger The type of trigger to apply.
- Returns
- true if successful.
◆ PrintTree()
|
pure virtual |
Print the entire scene graph to the system console.
- Returns
- true if successful.
◆ Lock()
|
pure virtual |
Lock the scene graph to prevent modifications.
- Returns
- true if successful.
◆ Unlock()
|
pure virtual |
Unlock the scene graph after it has been locked.
- Returns
- true if successful.
◆ CancelFinishLogic()
Cancel the finish logic traversal for a given node.
- Parameters
-
node The node to cancel.
- Returns
- true if successful.
◆ CancelFinishInput()
Cancel the finish input traversal for a given node.
- Parameters
-
node The node to cancel.
- Returns
- true if successful.
◆ CancelFinishOutput()
Cancel the finish outout traversal for a given node.
- Parameters
-
node The node to cancel.
- Returns
- true if successful.
◆ GetInitResults()
|
pure virtual |
Get the array of result messages added during the last call to InitGraph() or InitNode().
- Returns
- The array of messages.
◆ GetDeInitResults()
|
pure virtual |
Get the array of result messages added during the last call to DeInitGraph() or DeInitNode().
- Returns
- The array of messages.
◆ CollectStatisticsObjects()
|
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
-
objects An 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