![]() |
Murl Engine API
Version 2018.3
|
#include <murl_graph_i_root.h>
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.
Inherited by Murl::Core::GraphRoot.
Public Member Functions | |
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 ()=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... | |
|
pure virtual |
Get the actual root node.
|
pure virtual |
Get the actual root namespace node.
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.
nodeIdPath | The node ID to find, with optional path specification when searching in sub-namespaces. |
|
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.
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().
className | The node class name. |
|
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).
className | The node class name. |
nodeId | The node ID. |
|
pure virtual |
Create a single node by its class name, given attributes and optional parameters.
className | The node class name. |
attributes | The attributes to deserialize. |
parameters | The optional parameters. |
|
pure virtual |
Create a single node by its class name, with given base resource path, attributes and optional 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. |
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.
node | The node to destroy. |
|
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.
graphResource | The graph resource template from which to create the sub-graph. |
|
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.
graphResource | The graph resource template from which to create the sub-graph. |
params | An attributes object containing custom parameters used for instantiation. |
Destroy an entire sub-graph.
The sub-graph represented by the given node must be de-initialized using DeInitGraph() before it can be destroyed.
node | The root node of the sub-graph to destroy. |
|
pure virtual |
Deserialize a given node from a set of attributes and optional parameters.
node | The node to deserialize. |
attributes | The attributes. |
parameters | The optional parameters. |
|
pure virtual |
Deserialize a given node from a set of attributes and optional parameters, with a given base resource path.
node | The node to deserialize. |
baseResourcePath | The base path for referencing relative resource IDs. |
attributes | The attributes. |
parameters | The optional parameters. |
|
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().
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. |
|
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.
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. |
|
pure virtual |
Initialize a single node and its sub-graph.
This method performs initialization of a node that is already attached to a parent.
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. |
|
pure virtual |
De-initialize a sub-graph.
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. |
|
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.
className | The controller class name. |
owner | The owning node. |
|
pure virtual |
Create a node controller by its class name, given attributes and optional parameters.
See CreateController(const String& className, Graph::INode* owner).
className | The controller class name. |
owner | The owning node. |
attributes | The attributes to deserialize. |
parameters | The optional 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).
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. |
|
pure virtual |
Destroy a node controller.
See CreateController(const String& className, Graph::INode* owner).
controller | The controller to destroy. |
|
pure virtual |
Deserialize a given controller from a set of attributes and optional parameters.
controller | The controller to deserialize. |
attributes | The attributes. |
parameters | The optional parameters. |
|
pure virtual |
Deserialize a given controller from a set of attributes and optional parameters, with a given base resource path.
controller | The controller to deserialize. |
baseResourcePath | The base path for referencing relative resource IDs. |
attributes | The attributes. |
parameters | The optional parameters. |
|
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.
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. |
|
pure virtual |
De-initialize a node controller.
See CreateController(const String& className, Graph::INode* owner).
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. |
Acquire a unique ID for pushing/popping user data objects on a tracker.
uniqueName | A unique name string for which to acquire an ID. |
Release a previously acquired unique user data ID.
uniqueName | The unique name string of the ID to release. |
Push a user data object with given ID for initialization/deinitialization.
id | The unique user data ID previously acquired via AcquireUserDataId(). |
userData | The user data object. |
Pop a user data object with a given ID.
id | The unique user data ID previously acquired via AcquireUserDataId(). |
|
pure virtual |
Get the most recent user data object with a given ID.
id | The unique user data ID previously acquired via AcquireUserDataId(). |
|
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.
|
pure virtual |
Print the entire scene graph to the system console.
|
pure virtual |
Lock the scene graph to prevent modifications.
|
pure virtual |
Unlock the scene graph after it has been locked.
Cancel the finish logic traversal for a given node.
node | The node to cancel. |
Cancel the finish input traversal for a given node.
node | The node to cancel. |
Cancel the finish outout traversal for a given node.
node | The node to cancel. |
|
pure virtual |
Get the array of result messages added during the last call to InitGraph() or InitNode().
|
pure virtual |
Get the array of result messages added during the last call to DeInitGraph() or DeInitNode().