Unigine.NodeReference Class
| Inherits: | Node |
A node reference is a node that refers to an external .node file on the disk, which is obtained by exporting a node from the world.
The node reference should be used instead of the node if there a lot of identical objects repeated in the world: it will enable to avoid manual editing each object if you need to make the same changes in all of these objects.
Unlike regular nodes, reference nodes are loaded into the world faster because of the internal cache usage.
An NodeReference instance is an owner of the node (or nodes) stored by the reference, so it is responsible for loading and deleting them.
Node Reference Transformations#
NodeReference transformation differs from transformation of the node (or nodes) stored by the reference. However, matrix hierarchy is used for a NodeReference. So, when moving the NodeReference, its root node stored by the reference will also move relatively to this NodeReference. At that, the local transformation matrix of the root reference node won't be changed.
See Also#
- Article on Nodes that lists the main differences between the regular nodes and reference nodes
- Article on Node Reference
Creating a Node Reference#
To create a NodeReference, you should specify a path to the existing .node file. For example, you can export a node into a .node file and then create a NodeReference by using it:
using Unigine;
namespace UnigineApp
{
class AppWorldLogic : WorldLogic
{
public override bool Init()
{
// create a mesh
Mesh mesh = new Mesh();
mesh.addBoxSurface("box_0", new vec3(1.0f));
// create a dynamic mesh by using the mesh
ObjectMeshDynamic dynamic = new ObjectMeshDynamic(mesh);
// export the dynamic mesh into a .node file
World.SaveNode("unigine_project/nodes/node_reference_0.node", dynamic);
// create a node reference
NodeReference nodeRef = new NodeReference("unigine_project/nodes/node_reference_0.node");
return true;
}
}
}Also you can cast a Node instance to the NodeReference. However, such type casting is possible only if the Node type is NODE_REFERENCE. For example:
using Unigine;
namespace UnigineApp
{
class AppWorldLogic : WorldLogic
{
public void nodeCast(Node node)
{
// check if the node is a NodeReference
if (node.getType() == Node.NODE_REFERENCE)
{
// cast the node to the NodeReference
NodeReference nodeRef = node as NodeReference;
// set a name for the NodeReference
nodeRef.SetName("NodeReference_casted");
}
}
public override bool Init()
{
// create a NodeReference from the file
NodeReference nodeRef_0 = new NodeReference("unigine_project_10/nodes/node_reference_0.node");
// set a name
nodeRef_0.Name = "NodeReference_0";
// save changes into the .world file
Console.Run("world_save");
// get the added NodeReference as a Node
Node node = World.GetNodeByName("NodeReference_0");
// cast the obtained Node to a NodeReference
nodeCast(node);
return true;
}
}
}In the result, the NodeReference_0 node will be converted to the NodeReference_casted node.
Editing a Node Reference#
Editing a NodeReference includes:
- Changing the path to the referenced .node file.
- Editing the node stored by the reference.
using Unigine;
namespace UnigineApp
{
class AppWorldLogic : WorldLogic
{
public override bool Init()
{
// create a NodeReference instance
NodeReference nodeRef = new NodeReference("unigine_project_10/nodes/node_reference_0.node");
// set a name
nodeRef.Name = "NodeReference_0";
// get a node stored by the reference and check if it is an ObjectMeshDynamic
if (nodeRef.GetReference().GetType() == Node.OBJECT_MESH_DYNAMIC)
{
// cast the referenced node to the ObjectMeshDynamic type
ObjectMeshDynamic dynamic = nodeRef.GetReference() as ObjectMeshDynamic;
// set a material
dynamic.SetMaterial("mesh_base", 0);
// save changes on the referenced node into the .node file
World.SaveNode(nodeRef.NodeName, dynamic);
}
return 1;
}
}
}In the result, the source .node file, to which the NodeReference refers, will be updated and the NodeReference_0 node will refer to the updated node with the material assigned.
NodeReference Class
Properties
string NodeName#
// create an NodeReference instance
NodeReference nodeRef = new NodeReference("unigine_project/nodes/reference_0.node");
// ...
// return the path to the reference node
Log.Message("The referenced node is: {0}\n",nodeRef.getNodeName());// create an NodeReference instance
NodeReference nodeRef = new NodeReference("unigine_project/nodes/reference_0.node");
// ...
// change a reference node
nodeRef.setNodeName("unigine_project/nodes/reference_1.node");Node Reference#
// create a NodeReference instance
NodeReference nodeRef = new NodeReference("unigine_project/nodes/single_nref.node");
// get a node stored by the reference
Node node = nodeRef.getReference();
// if the node is a NodeDummy
if (node.getType() == Node.NODE_DUMMY){
// print the type name of each child node of the root node stored by the reference
for(int i = 0; i & node.getNumChildren(); i++) {
Log.Message("{0}: {1}\n",i,node.getChild(i).getTypeName());
}
}Members
static NodeReference ( string name ) #
Constructor. Creates a new object that references a node from a given file.Arguments
- string name - Path to a *.node file.
bool CanBeReference ( string name, Node node ) #
Returns a value indicating if the hierarchy of the given node does not contain a node reference with the given name.Arguments
- string name - Node reference name.
- Node node - Node to check.
Return value
1 if the hierarchy of the given node does not contain a node reference with the given name; otherwise, 0.Node DetachReference ( ) #
Returns the node stored by the reference and releases this node of ownership so it is no longer owned and referred to by the NodeReference. The node is managed by the World.// create a new NodeReference instance
NodeReference nodeRef = new NodeReference("unigine_project/nodes/node_reference_0.node");
// perform something
// ...
// get the node stored by the reference and release NodeReference ownership of the node
Node node = nodeRef.detachReference();
// destroy the NodeReference pointer as the NodeReference doesn't refer to a node any more
nodeRef.destroyPtr();