Murl Engine Lua Addon API  Version 1.0 beta
Murl.Graph.IRoot

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.


Table members

Methods


GetRootNode()

Get the actual root node.

Murl.Graph.INode GetRootNode()

Returns
Murl.Graph.INode The root node.

GetRootNamespace()

Get the actual root namespace node.

Murl.Graph.INamespace GetRootNamespace()

Returns
Murl.Graph.INamespace The root namespace node.

FindNode(nodeIdPath)

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.

Murl.Graph.INode FindNode(String nodeIdPath)

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

CanModifyGraph()

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.

Boolean CanModifyGraph()

Returns
Boolean true if modifications are allowed.

CreateNode(className)

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().

Murl.Graph.INode CreateNode(String className)

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

CreateNode(className, nodeId)

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).

Murl.Graph.INode CreateNode(String className, String nodeId)

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

CreateNode(className, baseResourcePath, attributes, parameters)

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

Murl.Graph.INode CreateNode(String className, String baseResourcePath, Murl.IAttributes attributes, Murl.IAttributes 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
Murl.Graph.INode The newly created node, or null if failed.

CreateNode(className, attributes, parameters)

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

Murl.Graph.INode CreateNode(String className, Murl.IAttributes attributes, Murl.IAttributes parameters)

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

DestroyNode(node)

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.

Boolean DestroyNode(Murl.Graph.INode node)

Parameters
nodeThe node to destroy.
Returns
Boolean true if successful.

CreateGraph(graphResource)

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.

Murl.Graph.INode CreateGraph(Murl.Resource.IGraph graphResource)

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

CreateGraph(graphResource, params)

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.

Murl.Graph.INode CreateGraph(Murl.Resource.IGraph graphResource, Murl.IAttributes params)

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

DestroyGraph(node)

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

Boolean DestroyGraph(Murl.Graph.INode node)

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

DeserializeNodeAttributes(node, baseResourcePath, attributes, parameters)

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

Boolean DeserializeNodeAttributes(Murl.Graph.INode node, String baseResourcePath, Murl.IAttributes attributes, Murl.IAttributes parameters)

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

DeserializeNodeAttributes(node, attributes, parameters)

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

Boolean DeserializeNodeAttributes(Murl.Graph.INode node, Murl.IAttributes attributes, Murl.IAttributes parameters)

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

InitGraph(rootNode, parentNode, index, releaseLock)

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().

Boolean InitGraph(Murl.Graph.INode rootNode, Murl.Graph.INode parentNode, Integer index, Boolean releaseLock)

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
Boolean true if successful.

DeInitGraph(rootNode, releaseLock)

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.

Boolean DeInitGraph(Murl.Graph.INode rootNode, Boolean releaseLock)

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
Boolean true if successful.

InitNode(rootNode, releaseLock)

Initialize a single node and its sub-graph. This method performs initialization of a node that is already attached to a parent.

Boolean InitNode(Murl.Graph.INode rootNode, Boolean releaseLock)

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
Boolean true if successful.

DeInitNode(rootNode, releaseLock)

De-initialize a sub-graph.

Boolean DeInitNode(Murl.Graph.INode rootNode, Boolean releaseLock)

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
Boolean true if successful.

AcquireUserDataId(uniqueName)

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

Integer AcquireUserDataId(String uniqueName)

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

ReleaseUserDataId(uniqueName)

Release a previously acquired unique user data ID.

Boolean ReleaseUserDataId(String uniqueName)

Parameters
uniqueNameThe unique name string of the ID to release.
Returns
Boolean 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.

PopUserData(id)

Pop a user data object with a given ID.

Boolean PopUserData(Integer id)

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

TriggerSwapping(trigger)

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).

Boolean TriggerSwapping(Murl.IEnums.SuspendTrigger trigger)

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

PrintTree()

Print the entire scene graph to the system console.

Boolean PrintTree()

Returns
Boolean true if successful.

Lock()

Lock the scene graph to prevent modifications.

Boolean Lock()

Returns
Boolean true if successful.

Unlock()

Unlock the scene graph after it has been locked.

Boolean Unlock()

Returns
Boolean true if successful.

CancelFinishLogic(node)

Cancel the finish logic traversal for a given node.

Boolean CancelFinishLogic(Murl.Graph.INode node)

Parameters
nodeThe node to cancel.
Returns
Boolean true if successful.

CancelFinishInput(node)

Cancel the finish input traversal for a given node.

Boolean CancelFinishInput(Murl.Graph.INode node)

Parameters
nodeThe node to cancel.
Returns
Boolean true if successful.

CancelFinishOutput(node)

Cancel the finish outout traversal for a given node.

Boolean CancelFinishOutput(Murl.Graph.INode node)

Parameters
nodeThe node to cancel.
Returns
Boolean true if successful.

GetInitResults()

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

Murl.Array.GraphITrackerResultConst GetInitResults()

Returns
Murl.Array.GraphITrackerResultConst The array of messages.

GetDeInitResults()

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

Murl.Array.GraphITrackerResultConst GetDeInitResults()

Returns
Murl.Array.GraphITrackerResultConst The array of messages.