![]() |
Murl Engine Lua Addon API
Version 1.0 beta
|
The basic scene graph node interface.
Any class that is supposed to be part of a scene graph hierarchy must implement this interface.
See SetId() for a description of valid node IDs.
See Graph::INamespace for details about the hierarchical organization of node IDs.
Murl.Graph.INode.NODE_FLAG_IS_HEAD | |
Murl.Graph.INode.NODE_FLAG_IS_UNLOCKED | |
Murl.Graph.INode.NODE_FLAG_IS_INITIALIZED | |
Murl.Graph.INode.NODE_FLAG_IS_ACTIVE | |
Murl.Graph.INode.NODE_FLAG_IS_VISIBLE | |
Murl.Graph.INode.NODE_FLAG_IS_SWAPPED | |
Murl.Graph.INode.NODE_FLAG_IS_AUTOMATICALLY_SWAPPABLE | |
Murl.Graph.INode.NODE_FLAG_IS_MANUALLY_SWAPPABLE | |
Murl.Graph.INode.NODE_FLAG_IS_STATE_RECORDING_ENABLED | |
Murl.Graph.INode.NODE_FLAG_IS_FINISH_LOGIC_PENDING | |
Murl.Graph.INode.NODE_FLAG_IS_FINISH_INPUT_PENDING | |
Murl.Graph.INode.NODE_FLAG_IS_FINISH_OUTPUT_PENDING | |
Murl.Graph.INode.NODE_FLAG_IS_BOUNDING_VOLUME_MODIFIED | |
Murl.Graph.INode.NODE_FLAG_IS_PROCESS_LOGIC_TRIGGER_MODIFIED | |
Murl.Graph.INode.NODE_FLAG_IS_PROCESS_INPUT_TRIGGER_MODIFIED | |
Murl.Graph.INode.NODE_FLAG_IS_PROCESS_OUTPUT_TRIGGER_MODIFIED | |
Murl.Graph.INode.NODE_FLAG_IS_MODIFIED | |
Murl.Graph.INode.NODE_FLAG_LAST |
Murl.Graph.INode.CONFIG_CHANGED_TRIGGER_NONE | |
Murl.Graph.INode.CONFIG_CHANGED_TRIGGER_ALWAYS | |
Murl.Graph.INode.CONFIG_CHANGED_TRIGGER_SURFACE_SIZE | |
Murl.Graph.INode.CONFIG_CHANGED_TRIGGER_LANGUAGE | |
Murl.Graph.INode.CONFIG_CHANGED_TRIGGER_DIRTY |
Murl.Graph.INode.PROCESS_LOGIC_TRIGGER_NONE | |
Murl.Graph.INode.PROCESS_LOGIC_TRIGGER_ALWAYS | |
Murl.Graph.INode.PROCESS_LOGIC_TRIGGER_ACTIVE_SET | |
Murl.Graph.INode.PROCESS_LOGIC_TRIGGER_UPDATE_TRANSFORM | |
Murl.Graph.INode.PROCESS_LOGIC_TRIGGER_UPDATE_BOUNDING_VOLUME | |
Murl.Graph.INode.PROCESS_LOGIC_TRIGGER_TIMELINE_0_RUNNING | |
Murl.Graph.INode.PROCESS_LOGIC_TRIGGER_TIMELINE_1_RUNNING | |
Murl.Graph.INode.PROCESS_LOGIC_TRIGGER_TIMELINE_2_RUNNING | |
Murl.Graph.INode.PROCESS_LOGIC_TRIGGER_TIMELINE_3_RUNNING | |
Murl.Graph.INode.PROCESS_LOGIC_TRIGGER_TIMELINE_4_RUNNING | |
Murl.Graph.INode.PROCESS_LOGIC_TRIGGER_TIMELINE_5_RUNNING | |
Murl.Graph.INode.PROCESS_LOGIC_TRIGGER_TIMELINE_6_RUNNING | |
Murl.Graph.INode.PROCESS_LOGIC_TRIGGER_TIMELINE_7_RUNNING | |
Murl.Graph.INode.PROCESS_LOGIC_TRIGGER_TIMELINE_8_RUNNING | |
Murl.Graph.INode.PROCESS_LOGIC_TRIGGER_TIMELINE_9_RUNNING | |
Murl.Graph.INode.PROCESS_LOGIC_TRIGGER_TIMELINE_10_RUNNING | |
Murl.Graph.INode.PROCESS_LOGIC_TRIGGER_TIMELINE_11_RUNNING | |
Murl.Graph.INode.PROCESS_LOGIC_TRIGGER_TIMELINE_12_RUNNING | |
Murl.Graph.INode.PROCESS_LOGIC_TRIGGER_TIMELINE_13_RUNNING | |
Murl.Graph.INode.PROCESS_LOGIC_TRIGGER_TIMELINE_14_RUNNING | |
Murl.Graph.INode.PROCESS_LOGIC_TRIGGER_TIMELINE_15_RUNNING | |
Murl.Graph.INode.PROCESS_LOGIC_TRIGGER_TIMELINE_RUNNING | |
Murl.Graph.INode.PROCESS_LOGIC_TRIGGER_DIRTY |
Murl.Graph.INode.PROCESS_INPUT_TRIGGER_NONE | |
Murl.Graph.INode.PROCESS_INPUT_TRIGGER_ALWAYS | |
Murl.Graph.INode.PROCESS_INPUT_TRIGGER_ACTIVE_SET | |
Murl.Graph.INode.PROCESS_INPUT_TRIGGER_UPDATE_TRANSFORM | |
Murl.Graph.INode.PROCESS_INPUT_TRIGGER_UPDATE_BOUNDING_VOLUME | |
Murl.Graph.INode.PROCESS_INPUT_TRIGGER_DIRTY |
Murl.Graph.INode.PROCESS_OUTPUT_TRIGGER_NONE | |
Murl.Graph.INode.PROCESS_OUTPUT_TRIGGER_ALWAYS | |
Murl.Graph.INode.PROCESS_OUTPUT_TRIGGER_VISIBLE_SET | |
Murl.Graph.INode.PROCESS_OUTPUT_TRIGGER_UPDATE_TRANSFORM | |
Murl.Graph.INode.PROCESS_OUTPUT_TRIGGER_UPDATE_BOUNDING_VOLUME | |
Murl.Graph.INode.PROCESS_OUTPUT_TRIGGER_DIRTY |
Get the constant INode interface.
Murl.Graph.INode GetNodeInterface()
Add a child node. Add a given node as the next child of the current node.
Boolean AddChild(Murl.Graph.INode child)
child | The child node to add. |
Insert a child node at a given position. Insert a given node at a given position of the current node's children.
Boolean InsertChild(Murl.Graph.INode child, Integer index)
child | The child node to add. |
index | The zero-based index where to insert the node. |
Remove a child from a given position. Remove the child node specified by a given index.
Murl.Graph.INode RemoveChild(Integer index)
index | The zero-based index of the child to remove. |
Remove a child. Remove the first instance of a given child node from this node's children.
Murl.Graph.INode RemoveChild(Murl.Graph.INode child)
child | The child node to remove. |
Get this node's children. This returns a constant reference to this node's internal array of child nodes.
Murl.Array.GraphINode GetChildren()
Return the child at a given position. This returns a mutable pointer to this node's child at a given index.
Murl.Graph.INode GetChild(Integer index)
index | The zero-based index of the child. |
Return the first child with a given ID. This returns a mutable pointer to this node's child that has a given ID.
Murl.Graph.INode GetChild(String id)
id | The ID of the child to search for. |
Return the index of a child with a given ID.
Integer GetChildIndex(String id)
id | The ID of the child node to query. |
Return the index of a given child.
Integer GetChildIndex(Murl.Graph.INode node)
node | The child node to query. |
Return the number of this node's children.
Integer GetNumberOfChildren()
Add a node parent at the end of the array of current parents. By convention, the node's parent at index 0 represents the "real" parent, which is defined during scene graph creation. Any parents at an index greater than 0 are considered "virtual" parents, which result from a node being referenced multiple times by e.g. a Graph::IReference node.
Boolean AddParent(Murl.Graph.INode parent)
parent | The parent to add. |
Insert a node parent at a given index.
Boolean InsertParent(Murl.Graph.INode parent, Integer index)
parent | The parent to add. |
index | The zero-based index into the array of parents. |
Remove the parent from a given index.
Murl.Graph.INode RemoveParent(Integer index)
index | The index into the node's array of parents. |
Remove a given parent.
Murl.Graph.INode RemoveParent(Murl.Graph.INode parent)
parent | The parent to remove from the node's array of parents. |
Get a constant array of the node's parents.
Murl.Array.GraphINode GetParents()
Get a mutable pointer to the node's parent at a given index.
Murl.Graph.INode GetParent(Integer index)
index | The index into the node's array of parents. |
Get a mutable pointer to the node's parent with the given node ID.
Murl.Graph.INode GetParent(String id)
id | The node ID of the parent to retrieve. |
Return the index of a parent with a given ID.
Integer GetParentIndex(String id)
id | The ID of the parent node to query. |
Return the index of a given parent.
Integer GetParentIndex(Murl.Graph.INode node)
node | The parent node to query. |
Return the number of this node's parents.
Integer GetNumberOfParents()
Get a constant array of the node's controllers.
Murl.Array.GraphIController GetControllers()
Return the number of this node's controllers.
Integer GetNumberOfControllers()
Get a constant pointer to the namespace node this node belongs to.
Murl.Graph.INamespace GetCurrentNamespace()
Get a constant pointer to the namespace node this node's parent belongs to.
Murl.Graph.INamespace GetParentNamespace()
Get a constant pointer to the root namespace node.
Murl.Graph.INamespace GetRootNamespace()
Set the node ID. A node may have an optional ID, by which it can later be referenced from another node in the scene graph, or from a Logic::IProcessor to directly manipulate the node's properties from code. A valid node ID can only contain underscores ('_'), digits ('0'..'9') and/or alphabetic characters ('a'..'z' and 'A'..'Z'), and must not begin with a digit. In addition, node IDs must be unique within a common namespace.
See Graph::INamespace for examples of how to refer to individual nodes by their ID.
id | The node ID to set. |
Get the node ID.
String GetId()
Calculate the absolute path to the node.
String GetPath()
Check if this node is considered private. If a node is marked private, it is not possible to reference that node or any of its children from outside the sub-graph beneath that node.
Boolean IsPrivate()
Define whether this node represents the head of a sub-graph. When a sub-graph is created and added as a child of an existing scene graph node, this method must be called on the sub-graph's top node with isHead set to true. This must be done in order to detect any sub-graphs that were not correctly detached and destroyed before their respective parent graph is destroyed. Failing to do so may result in memory leaks or invalid node pointers.
Boolean SetHead(Boolean isHead)
isHead | If true, the node is set to be a head node. |
Check whether this node represents the head of a sub-graph.
Boolean IsHead()
Lock/unlock the node. Creating and destroying sub-graphs is usually an asynchronous task that is carried out in multiple stages. To prevent interference with regular graph traversals, it is necessary to have a sub-graph locked whenever it being initialized or de-initialized while it is linked to another scene graph node. Therefore, this method must be called with isLocked set to true prior to inserting it into the scene graph or prior to de-initializing it. The sub-graph may only be safely unlocked after it has been fully initialized, or detached from its parent.
Boolean SetLocked(Boolean isLocked)
isLocked | If true, the node gets locked for regular traversals. |
Check if this node is locked for regular traversals. See SetLocked().
Boolean IsLocked()
Set/clear the node's initial swap state. The node's swapped state is used as a hint to the engine, so that the node may decide to delay creation of any internal objects until they are actually used. This is usually the case for e.g. textures, which consume a large amount of video memory. Here, setting the node's swapped state results in not creating the video memory resources until the texture is referenced for the first time. By default, the swapped state is disabled. Note that this property can only be set before the node is initialized, after that the method returns false.
Boolean SetSwapped(Boolean isSwapped)
isSwapped | The swap state of the node. |
Check if this node is initially in the swapped state. See SetSwapped().
Boolean IsSwapped()
Enable/disable auto-swapping for this node. When enabled, the engine may decide to swap-out any node-specific resources when they have not been used during the last frame. Like the initial swap state set via SetSwapped(), this is only a hint and applies to certain nodes only, such as textures. By default, this feature is disabled. Note also that auto-swapping can only be set before the node is initialized. When auto-swapping is enabled, it is usually a good idea to also set the initial swap state to true (via SetSwapped()), as otherwise the node's resources are created at initialization and possibly immediately swapped out when the node is not being used in the following frame.
Boolean SetAutomaticSwappingEnabled(Boolean enabled)
enabled | If true, auto swapping is enabled. |
Check if auto-swapping is enabled for this node. See SetSwappable().
Boolean IsAutomaticSwappingEnabled()
Enable/disable manual swapping for this node. When enabled, the user can trigger a swap-out of any node-specific resources when they have not been used during the last frame, by calling the TriggerSwapping() method on the Graph::IRoot object that can be accessed e.g. via the Logic::IState object. See SetAutomaticSwappingEnabled().
Boolean SetManualSwappingEnabled(Boolean enabled)
enabled | If true, manual swapping is enabled. |
Check if manual swapping is enabled for this node. See SetManualSwappingEnabled().
Boolean IsManualSwappingEnabled()
Enable/disable state recording for this node.
Boolean SetStateRecordingEnabled(Boolean enabled)
enabled | If true, state recording is enabled. |
Check if state recording is enabled for this node. See SetStateRecordingEnabled().
Boolean IsStateRecordingEnabled()
Set/reset the initialized state of the node.
Boolean SetInitialized(Boolean isInitialized)
isInitialized | If true, the node is set to the initialized state. |
Check if this node is initialized.
Boolean IsInitialized()
Set/reset whether the finish logic traversal is pending.
Boolean SetFinishLogicPending(Boolean pending)
pending | The pending state. |
Check whether the finish logic traversal is pending.
Boolean IsFinishLogicPending()
Set/reset whether the finish input traversal is pending.
Boolean SetFinishInputPending(Boolean pending)
pending | The pending state. |
Check whether the finish input traversal is pending.
Boolean IsFinishInputPending()
Set/reset whether the finish output traversal is pending.
Boolean SetFinishOutputPending(Boolean pending)
pending | The pending state. |
Check whether the finish output traversal is pending.
Boolean IsFinishOutputPending()
Set/reset the "bounding volume modified" state of the node. The "bounding volume modified" state signals that there was some modification of one or more of the nodes within this node's sub-graph which affects this node's overall bounding volume. If isModified is true, the change is propagated to all of the node's parents, whereas a value of false clears this state in all of the node's child sub-graphs. This propagation is only done when the node is not locked. See SetModifiedFlags() and ClearModifiedFlags(), together with NODE_FLAG_IS_BOUNDING_VOLUME_MODIFIED.
Boolean SetBoundingVolumeModified(Boolean isModified)
isModified | If true, the bounding volume is flagged as modified. |
Check if the overall bounding volume was modified.
Boolean IsBoundingVolumeModified()
Set the "active modified" state of the node.
Boolean SetActiveModified()
Set the "visible modified" state of the node.
Boolean SetVisibleModified()
Set a combination of "modified" flags. This method sets the given flag bits in the node's internal state. The change is propagated to all of the node's parents when the node is unlocked. See SetBoundingVolumeModified().
Boolean SetModifiedFlags(Integer flags)
flags | The bit mask of flags to set. |
Clear a combination of "modified" flags. This method clears the given flag bits in the node's internal state. The change is propagated to all of the node's child sub-graphs when the node is unlocked. See SetBoundingVolumeModified().
Boolean ClearModifiedFlags(Integer flags)
flags | The bit mask of flags to clear. |
set current flags. (!) Use with caution! Messing around with node flags may cause undefined behavior.
Boolean SetNodeFlags(Integer flags)
flags | The flags bit mask. |
Get current flags.
Integer GetNodeFlags()
Increment the node's internal reference counter by 1. Whenever a node is persistently referenced from a different location in the application, this method must be called to indicate that it must not be destroyed, to prevent existing pointers to become invalid. Using a Graph::IReference node automatically performs this task together with its counterpart RemoveReference(), as do the individual Logic::GraphNodeT helpers. If a node is directly referenced from user code, it is up to the user to correctly increment/decrement the node's reference counter. A sub-graph can only be correctly destroyed when all of its children have a reference counter of 0.
Boolean AddReference()
Increment the node's internal reference counter by 1. See AddReference().
Boolean RemoveReference()
Create a bounding volume.
Murl.Graph.IBoundingVolume CreateBoundingVolume()
Destroy a given bounding volume.
Boolean, Murl.Graph.IBoundingVolume DestroyBoundingVolume(Murl.Graph.IBoundingVolume boundingVolume)
boundingVolume | A reference to the bounding volume pointer. After destruction, the pointer will be set to null. |
Get the node's bounding volume, if present.
Murl.Graph.IBoundingVolume GetBoundingVolume()
Get the node's active triggers for config change traversal.
Integer GetConfigChangedTriggers(Integer mask)
mask | A bit mask of triggers to check, from the ConfigChangedTriggers enumeration. |
Get the node's active triggers for logic traversal.
Integer GetProcessLogicTriggers(Integer mask)
mask | A bit mask of triggers to check, from the ProcessLogicTriggers enumeration. |
Get the node's active triggers for input traversal.
Integer GetProcessInputTriggers(Integer mask)
mask | A bit mask of triggers to check, from the ProcessInputTriggers enumeration. |
Get the node's active triggers for output traversal.
Integer GetProcessOutputTriggers(Integer mask)
mask | A bit mask of triggers to check, from the ProcessOutputTriggers enumeration. |
Get the node's active response for config change traversal.
Integer GetConfigChangedResponse()
Get the node's active response for logic traversal.
Integer GetProcessLogicResponse()
Get the node's active response for input traversal.
Integer GetProcessInputResponse()
Get the node's active response for output traversal.
Integer GetProcessOutputResponse()
Add the response of a node's child to a config change traversal.
Boolean AddChildConfigChangedResponse(Integer mask)
mask | A bit mask of triggers to add to the traversal response, from the ConfigChangedTriggers enumeration. |
Add the response of a node's child to a logic traversal.
Boolean AddChildProcessLogicResponse(Integer mask)
mask | A bit mask of triggers to add to the traversal response, from the ProcessLogicTriggers enumeration. |
Add the response of a node's child to a input traversal.
Boolean AddChildProcessInputResponse(Integer mask)
mask | A bit mask of triggers to add to the traversal response, from the ProcessInputTriggers enumeration. |
Add the response of a node's child to a output traversal.
Boolean AddChildProcessOutputResponse(Integer mask)
mask | A bit mask of triggers to add to the traversal response, from the ProcessOutputTriggers enumeration. |
Get the traversal states that are modified by the node and its sub-graph.
Integer GetModifiedTraversalStates()
Add the traversal states that are modified by a node's child.
Boolean AddChildModifiedTraversalStates(Integer mask)
mask | A bit mask of modified traversal states. |
Print the node and its sub-graph to the system console.
Boolean PrintTree(Integer indent, Integer includeNodeFlags, Integer excludeNodeFlags)
indent | The number of spaces to add in front of each output text line. |
includeNodeFlags | A bit mask made up from individual NodeFlags values specifying the nodes to include into the output (default is all flags). |
excludeNodeFlags | A bit mask made up from individual NodeFlags values specifying the nodes to exclude from the output (default is no flags). |
Converts the object content to a string in a reasonable format.