![]() |
Murl Engine Lua Addon API
Version 1.0 beta
|
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.
Get the actual root node.
Murl.Graph.INode GetRootNode()
Get the actual root namespace node.
Murl.Graph.INamespace GetRootNamespace()
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)
nodeIdPath | The node ID to find, with optional path specification when searching in sub-namespaces. |
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()
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)
className | The node class name. |
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)
className | The node class name. |
nodeId | The node ID. |
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)
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. |
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)
className | The node class name. |
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.
Boolean DestroyNode(Murl.Graph.INode node)
node | The node to destroy. |
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)
graphResource | The graph resource template from which to create the sub-graph. |
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)
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.
Boolean DestroyGraph(Murl.Graph.INode node)
node | The root node of the sub-graph to destroy. |
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)
node | The node to deserialize. |
baseResourcePath | The base path for referencing relative resource IDs. |
attributes | The attributes. |
parameters | The optional 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)
node | The node to deserialize. |
attributes | The attributes. |
parameters | The optional parameters. |
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)
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. |
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)
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. |
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)
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. |
De-initialize a sub-graph.
Boolean DeInitNode(Murl.Graph.INode rootNode, Boolean releaseLock)
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. |
Acquire a unique ID for pushing/popping user data objects on a tracker.
Integer AcquireUserDataId(String uniqueName)
uniqueName | A unique name string for which to acquire an ID. |
Release a previously acquired unique user data ID.
Boolean ReleaseUserDataId(String uniqueName)
uniqueName | The unique name string of the ID to release. |
Pop a user data object with a given ID.
Boolean PopUserData(Integer id)
id | The unique user data ID previously acquired via AcquireUserDataId(). |
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.
Boolean TriggerSwapping()
Print the entire scene graph to the system console.
Boolean PrintTree()
Lock the scene graph to prevent modifications.
Boolean Lock()
Unlock the scene graph after it has been locked.
Boolean Unlock()
Get the array of result messages added during the last call to InitGraph() or InitNode().
Murl.Array.GraphITrackerResultConst GetInitResults()
Get the array of result messages added during the last call to DeInitGraph() or DeInitNode().
Murl.Array.GraphITrackerResultConst GetDeInitResults()