The SceneNode objects are the nodes that form the scene graph of a Scene. Each node has a collection of children SceneNodes, a local transform and, optionally, extents (bounding box). Additionally it may have visible objects attached, defined as a collection of renderable items, typically GeometryInstances, and a collection of LightInstances.
All matrices used for local and world transformations are Matrix43 objects.
The SceneNodes use lazy evaluation internally to avoid unnecessary calculations.
SceneNodes can be dynamic, which may move or change extents at some point. Non-dynamic (static) nodes never move or change extents. Static nodes are cheaper to render and update. Typically a level mesh would be static while the entities and FX would be dynamic.
Warning
Changing from dynamic to static or visa versa can be an expensive operation. Usually this will be specified at creation time using the dynamic property, either in the tool chain, through the Scene.load() load parameters or the SceneNode.create() parameters.
Rules:
- Root nodes (nodes with no parent) added to a scene must be uniquely named. Choose a naming convention for nodes in your code and assets.
- Nodes should not be renamed post create.
- Properties with get/set methods should not be directly accessed unless SceneNode.update(), Scene.updateNodes() or Scene.update() has been called and no further modification made.
- A node must only be in one scene.
Required scripts
The SceneNode object requires:
/*{{ javascript("jslib/aabbtree.js") }}*/
/*{{ javascript("jslib/utilities.js") }}*/
Summary
Create and return a sceneNode object initialized with the passed in parameters.
Syntax
var parameters =
{
name: "player1",
local: startPoint,
dynamic: true,
disabled: false
};
var player1Node = SceneNode.create(parameters);
Summary
Makes a nodes path by appending a child name to an ancestor path.
See getPath.
Syntax
SceneNode.makePath(parentPath, childName);
//example usage:
var childPath = SceneNode.makePath(parentNode.getPath(), "childname");
Summary
Get the name of the node. Not all nodes have a name.
Syntax
var name = node.getName();
Returns a JavaScript string.
Summary
Get the path of the node. This is a \ delimited string of it and its ancestors names, e.g. “grandParentName\parentName\name”.
Syntax
var path = node.getPath();
Returns a JavaScript string.
Summary
Add a SceneNode as a child of this node.
Syntax
node.addChild(sceneNode);
Summary
Remove the child from the SceneNode. If the node is in the scene then it will remove all references from it.
Syntax
parentNode.removeChild(childNode);
Summary
Finds a named child of this node.
Syntax
var childNode = parentNode.findChild(childNodeName);
Returns undefined if a child with the given name does not exist. This function only searches through the immediate children of parentNode.
Summary
Create a new node by copying the node.
This clones all descendant nodes as well as lights and renderable items.
Syntax
var cloneNode = originalNode.clone(cloneName);
Returns a SceneNode object.
Summary
Get the root node of this node.
Syntax
var root = node.getRoot();
Returns a SceneNode object. This function will return node if node is a root node.
Summary
Set the local transform matrix of the node. This is not valid for non-dynamic nodes that have been added to the scene.
Syntax
player1Node.setLocalTransform(matrix);
Summary
Get the local transform matrix of the node.
Syntax
var local = node.getLocalTransform();
Returns a Matrix43 object.
Summary
Get the world transform matrix of the node.
Syntax
var world = node.getWorldTransform();
Returns a Matrix43 object.
Summary
Update all the state of the node. This will not normally be required to be called manually as it is automatically called by Scene.update() or by calling Scene.updateNodes(). Once called properties, such as world and worldExtents, can be read without worrying about dirty state.
Syntax
node.update(scene);
Summary
Get the local extents of the node. These are not transformed by the local transformation matrix. These may be undefined.
Syntax
var localExtents = node.getLocalExtents();
Returns an extents object.
Summary
Get the world extents of the node. These may be undefined.
Syntax
var worldExtents = node.getWorldExtents();
Returns an extents object.
Summary
User defined extents that replace the ones calculated from any attached geometry. The extents should be defined based on the local transform being the identity matrix.
Syntax
node.addCustomLocalExtents(extents);
//example usage:
node.addCustomLocalExtents([-10, -10, -10, 10, 10, 10]);
Summary
Removes previously attached custom local extents.
Syntax
node.removeCustomLocalExtents();
Summary
Get previously attached custom local extents. Maybe undefined.
Syntax
var extents = node.getCustomLocalExtents();
This function returns an extents object.
Summary
User defined extents that replace the ones calculated from any attached geometry and the world transform. Even if the node moves the extents will not be recalculated. These can be used as an optimization for animated objects that are constrained to a location.
Syntax
node.addCustomWorldExtents(worldExtents);
//example usage:
var worldExtents = node.getWorldExtents().slice();
var padding = 10;
worldExtents[0] -= padding;
worldExtents[1] -= padding;
worldExtents[2] -= padding;
worldExtents[3] += padding;
worldExtents[4] += padding;
worldExtents[5] += padding;
node.addCustomWorldExtents(worldExtents);
Summary
Remove previously attached custom world extents.
Syntax
node.removeCustomWorldExtents();
Summary
Get previously attached world extents. Maybe undefined.
Syntax
var extents = node.getCustomWorldExtents();
Summary
Get world extents of the node and all its descendants. Maybe undefined.
Syntax
var extents = node.calculateHierarchyWorldExtents(destination);
Summary
Sets the node and all its descendants to be dynamic nodes. This can be an expensive operation.
Syntax
node.setDynamic();
Summary
Sets the node and all its descendants to be static nodes. This can be an expensive operation.
Syntax
node.setStatic();
Summary
Sets the node to be the passed in value. Disabled nodes are not rendered.
Syntax
node.setDisabled(boolean);
Summary
Gets if the node is disabled.
Syntax
var disabled = node.getDisabled();
Returns a boolean.
Summary
Enable or disabled the node and its descendants.
Syntax
node.enableHierarchy(boolean);
Summary
Add a renderable object to the node’s collection.
Syntax
node.addRenderable(renderable);
Summary
Add an array of renderable objects to the node’s collection.
Syntax
node.addRenderableArray(renderables);
Summary
Remove a renderable object from the node’s collection.
Syntax
node.removeRenderable(renderable);
Summary
Returns whether the node has any renderable objects.
Syntax
if (node.hasRenderables())
{
//...
}
Summary
Add a lightInstance object to the node’s collection.
Syntax
node.addLightInstance(lightInstance);
Summary
Add an array of lightInstance objects to the node’s collection.
Syntax
node.addLightInstanceArray(lightInstances);
Summary
Remove a lightInstance object from the node’s collection.
Syntax
node.removeLightInsance(lightInstance);
Summary
Returns whether the node has any lightInstance objects.
Syntax
if (node.hasLightInstance())
{
//...
}
Summary
Returns whether the node is in a scene.
Syntax
if (node.isInScene())
{
//...
}
Summary
Destroy the node and all its children. This destroys any attached renderables and lights. The node should not be used after calling destroy().
Syntax
scene.removeRootNode(node);
node.destroy();
node = null;
Summary
The version number of the SceneNode implementation.
Syntax
var sceneNodeVersionNumber = sceneNode.version;
Summary
The local is the local transformation Matrix43 object.
Syntax
var local = sceneNode.local;
Summary
The world is the world transformation Matrix43 object. See the top level summary for when this is valid.
Syntax
var world = sceneNode.world;
Summary
The world extents of the node. Maybe be undefined. See the top level summary for when this is valid.
Syntax
var extents = sceneNode.worldExtents;
Summary
An array of children of SceneNodes.
Syntax
var children = sceneNode.children;