Node API

Introduction

Three scene graphs are provided in the library: an X3D scene graph, a GL scene graph and a MESH scene graph. They share the common interface X3DTK::X3DAbstractNode that is presented here. We can separate this interface into two aspects: the run-time type informations and the node handling.

Run-time type informations

C++ has its own RTTI mechanism that is based on polymorphic classes. This mechanism enables us to downcast through the dynamic_cast operator. Nevertheless the "double dispatching" technique requires that the RTTI is more precise than just a downcast that succeeds or fails.

X3DTK::SFType

The main class of the run-time type informations is X3DTK::SFType. Each node references one X3DTK::SFType that is unique by node type. Because the X3D nodes belong to a class hierarchy, the X3DTK::SFType objects are part of a dynamic tree, image of the inheritance tree. It can be printed by:

 SFType::printInheritanceTree();

This tree is dynamic meaning that its shape depends on the execution and contains only the types that are in used.

Inherited type and name can be accessed:

 X3DTK::SFNode N;
 // Gets the name of the type
 const X3DTK::SFString &name = N->getype->getName();
 // Gets the parent of the type
 X3DTK::SFType *type = N->getType()->getParent();
 // Gets the children of the type
 X3DTK::MFType mtype = N->getType()->getChildren();

X3DTK::SFComponent and X3DTK::SFSceneGraph

X3D nodes are divided into components and belong to a scene graph. For example, X3DTK::X3D::Cylinder is a node that belongs to the Geometry3D component and to the X3D scene graph, whereas X3DTK::GL::Cylinder belongs to the Geometry3D component and to the GL scene graph.

You access to the component and the scene graph of a X3DTK::SFType by:

 X3DTK::SFNode N;
 // Gets the component of the type
 X3DTK::SFComponent *com = N->getType()->getComponent(); 
 // Gets the component of the type
 X3DTK::SFSceneGraph *sg = com->getSceneGraph(); 

These informations are not really useful but are necessary to the working of the "double dispatching" technique.

Node handling

The library provides an intuitive way to dynamically handle nodes, by creating, deleting adding child, and getting the type informations.

Creation, destruction

X3DTK nodes are designed to be used as pointers. That is why the copy constructor is made protected. A node can be created in two ways:

 // creating a new node
 SFNode N = new X3DTK::X3D::Box();
 // cloning the node
 SFNode C = N->clone();

Usually, node creation is not explicit, but is made by an abstract factory X3DTK::X3D::Creator that creates a node from its name, and is called by an X3DTK::X3DLoader, or by a processor that converts a scene graph to another one.

You can delete the node by calling explictly the delete operator, but it suppresses only the node and not its children. For that use the generic processor called X3DTK::MemReleaser that ensures you to delete all the sub-tree, except for shared nodes that are not deleted.

Name access

As we saw it before, type information can be retrieved from:

 X3DTK::SFNode N = new X3D::Group();
 // Gets the name of the type
 const X3DTK::SFString &name = N->getTypeName();
 // Gets the component name of the type
 const X3DTK::SFString &com = N->getComponentName();
 // Gets the scene graph name of the type
 const X3DTK::SFString &sg = N->getSceneGraphName();
 // "X3D::Group" is displayed
 cout << sg << "::" << name << endl;

Children handling

Naturally children can be added, however they must be valid children. Two ways to give a node a child are provided:

 // new nodes
 SFNode S = new X3D::Shape();
 SFNode B1 = new X3D::Box();
 SFNode B2 = new X3D::Box();
 // sets the child B1
 S->setChild(B1);
 // Removes B1 and adds B2
 if (S->getGeometry() != 0)
 {
   S->removeChild(B1);
   S->setChild(B2);
 }

When a node is cloned and has children, they are not cloned but shared, nevertheless the clone has no father, otherwise the integrity of the scene graph would be in great danger!

 // new nodes
 SFNode G = new X3D::Group();
 SFNode S = new X3D::Shape();
 SFNode B = new X3D::Box();
 // adding children
 G->setChild(S);
 S->setChild(B);
 // cloning S
 SFNode C = S->clone();
 // B is now a shared child by S and C, but C has no father.

Let's see how to delete a sub-tree where nodes are shared, and let's take the former nodes.

 #include <X3DTK/memreleaser.h>

 // Getting the instance of MemReleaser
 X3DTK::MemReleaser *releaser = X3DTK::Singleton<X3DTK::MemReleaser>::getInstance();
 // releases C, but not B because B is shared by S
 releaser->release(C);
 // releases S and B because B is not shared
 releaser->release(S);

---