2. The Scene Graph

The Scene is Helix's main entry point; it's where all the 3D objects are placed: meshes, lights, cameras, and so on. The scene graph is the hierarchy of all scene objects with the Scene as its root. Each scene node has a transformation associated with it: position, rotation, scale.

There are two main categories of scene graph objects:

• Group nodes: These are scene graph nodes that can contain several child group nodes. Implemented as HX.SceneNode.
• Entities: These are scene graph nodes that represent actual "things" in the scene. Their concrete behavior is defined by the Components assigned to them. For example: adding a HX.DirectionalLight makes it behave as a directional light, adding HX.ModelInstance makes the object renderable. Entities themselves are also group nodes, so they can in turn contain child nodes.
• Cameras: These are special sub-types of Entities that are used to render the scene. HX.PerspectiveCamera is the most common type.

All scene graph nodes' transformations are relative to the parent group node they are added to; transforming the parent will transform all children as well.

Transforms

An object's position, rotation and scale can be adjusted either by changing their respective properties or by directly changing the matrix. The matrix and the properties are always in sync with each other, so no update calls need to be made manually: change the position, rotation or scale and the matrix will reflect this and vice versa. The position and scale properties are HX.Float4 objects, while the rotation object is a HX.Quaternion. See the documentation for the types for more in-depth info.

Important: All angles in Helix are in radians, not degrees!

var group1 = new HX.SceneNode();
group1.position.set(1.0. 0.0. 0.0);
group1.rotation.fromAxisAngle(HX.Float4.Y_AXIS, .5);

As mentioned above, transforms are always relative to the parent. Access the worldMatrix property to get the global transformation of an object.

Good parenting

Both the HX.Scene object as well as the HX.SceneNode objects are "containers": other scene graph objects can be added to them. For example:

var scene = new HX.Scene();
var group1 = new HX.GroupNode();
var group2 = new HX.GroupNode();
var primitive = new HX.SpherePrimitive();
var material = new HX.BasicMaterial();
var meshInstance1 = new HX.MeshInstance(primitive, material);
var meshInstance2 = new HX.MeshInstance(primitive, material);
var meshInstance3 = new HX.MeshInstance(primitive, material);

scene.attach(group1);
scene.attach(group2);

// create the Entities to give the MeshInstances a place in the scene
var entity1 = new HX.Entity(meshInstance1);
var entity2 = new HX.Entity(meshInstance2);
var entity3 = new HX.Entity(meshInstance3);
group1.attach(entity1);
group2.attach(entity2);
scene.attach(entity3);

Removing objects can be done by calling the detach method:

group1.detach(entity1);

The scene graph can be queried and navigated using the following properties and methods on HX.Scene and HX.SceneNode:

• numChildren: The number of immediate children of a node (so not grandchildren).
• getChild(i): Gets the child at the given index. The index just indicates the order in which it is added, and has no real useful meaning (unlike in 2D scene graphs, where it usually is associated with render order).
• contains(node): Indicates whether or not the given node is a direct child of the parent.
• findNodeByName(name): Finds a childnode recursively that has a given name
• findMaterialByName(name) : Finds a material assigned to a HX.ModelInstance somewhere in the scene graph.
• applyFunction(fnc): Calls the function for every object in the scene graph.