Unigine.NodeReference Class

Inherits:

Sort by:

List of functions:

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.

NoticeThe world can contain several instances of node references referring to the same .node file.

The .node file usually contains a pre-fabricated node (or a hierarchy of nodes) with all the materials and properties that are required for its rendering. All changes that are made for the node reference via UnigineEditor are saved into this file.

Notice

When editing the node reference via the code, implement saving changes into the .node file.

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.

NoticeA bounding box of the reference node is equal to the bounding box of its root node stored by the reference (child nodes are disregarded).

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.

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:

Source code (C#)

using Unigine;

namespace UnigineApp
{
	class AppWorldLogic : WorldLogic
	{		
        public override int 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.get().saveNode("unigine_project/nodes/node_reference_0.node", dynamic);
            // create a node reference
            NodeReference nodeRef = new NodeReference("unigine_project/nodes/node_reference_0.node");
            nodeRef.release();
            // add NodeReference to UnigineEditor
            Editor.get().addNode(nodeRef);

			return 1;
		}
	}
}

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:

Source code (C#)

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 = NodeReference.cast(node);
                // set a name for the NodeReference
                nodeRef.setName("NodeReference_casted");
            }
        }

		public override int 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.setName("NodeReference_0");
            nodeRef_0.release();
            // add the NodeReference to UnigineEditor
            Editor.get().addNode(nodeRef_0);
            // save changes into the .world file
            Unigine.Console.get().run("world_save");
            // get the added NodeReference as a Node
            Node node = Editor.get().getNodeByName("NodeReference_0");
            // cast the obtained Node to a NodeReference
            nodeCast(node);

			return 1;
		}
	}
}

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.

To access the node to which the NodeReference refers, use the getReference() method as follows:

Source code (C#)

using Unigine;

namespace UnigineApp
{
	class AppWorldLogic : WorldLogic
	{
        public override int init()
		{
            // create a NodeReference instance
            NodeReference nodeRef = new NodeReference("unigine_project_10/nodes/node_reference_0.node");
            // set a name
            nodeRef.setName("NodeReference_0");
            nodeRef.release();
            // add the NodeReference to UnigineEditor
            Editor.get().addNode(nodeRef);

            // 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 = ObjectMeshDynamic.cast(nodeRef.getReference());
                // set a material
                dynamic.setMaterial("mesh_base", 0);
                // save changes on the referenced node into the .node file
                World.get().saveNode(nodeRef.getNodeName(), 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

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.

NodeReference cast(Node node)

Casts the Node instance to a NodeReference.

Source code (C#)

Node node = Editor.get().getNodeByName("NodeReference_0");
// check if the node is a NodeReference
if (node.getType() == Node.NODE_REFERENCE)
{	
	// cast the node to the NodeReference
	NodeReference nodeRef = NodeReference.cast(node);
	// set a name for the NodeReference
	nodeRef.setName("NodeReference_casted");
}

Arguments

Node node - Node instance.

Return value

NodeReference instance.

int setNodeName(string name)

Sets a reference to a new *.node file.

Source code (C#)

// 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");

Arguments

string name - Path to a *.node file.

Return value

Returns 1 if the new reference is set successfully; otherwise, 0.

string getNodeName()

Returns the path to the referenced *.node file.

Source code (C#)

// 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());

Return value

Path to the referenced *.node file.

Node getReference()

Returns the node stored by the reference. The method should be used when you need to change the referenced node. If getReference() has returned a NodeDummy instance, it means that several nodes of the same hierarchy level has been converted into the NodeReference.

Source code (C#)

// 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());
	}
}

Return value

Node instance.

int 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 by the NodeReference (the node becomes orphan). After being released the node should be appended to one of the scripts not to cause a memory leak.

Source code (C#)

// create a new NodeReference instance
NodeReference nodeRef = new NodeReference("unigine_project/nodes/node_reference_0.node");
// preform 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();
// add the obtained node to UnigineEditor
Editor.get().addNode(node);

Return value

Root node of the internal hierarchy.

int type()

Returns the type of the node.

Return value

NodeReference type identifier.

Last update: 2018-08-10

Help improve this article

Was this article helpful?

Report a problem related to this article

(or select a word/phrase and press Ctrl+Enter)

Unigine.NodeReference Class

List of functions:

Node Reference Transformations

See Also

Creating a Node Reference

Editing a Node Reference

NodeReference Class

Members

static NodeReference(string name)

Arguments

NodeReference cast(Node node)

Arguments

Return value

int setNodeName(string name)

Arguments

Return value

string getNodeName()

Return value

Node getReference()

Return value

int canBeReference(string name, Node node)

Arguments

Return value

Node detachReference()

Return value

int type()

Return value