Provides functionality for loading and managing scenes.
It is implemented as a hierarchy of SceneNodes with several acceleration structures to optimize visibility calculations and hardware dispatching.
Each SceneNode in the hierarchy can simultaneously reference multiple renderables, multiple LightInstances, a physics body and a camera. The SceneNode have axis-aligned extents calculated from the extents of these object.
The scene automatically synchronizes physics bodies transforms and extents with the attached rendering information.
A portal system is use in conjunction with several bounding volume hierarchies to reduce the cost of visibility calculations.
Material information for rendering is not propagated from parent to child. Each renderable item, e.g. a GeometryInstances, attached to a node have references to all the material information required to render it, but some of this information can be shared with other nodes in order to reduce memory requirements and state changes.
The format in which scenes are stored allows for external references to material information and other external scenes that can be embedded at any point in the node hierarchy in a recursive fashion. All these external references are resolved at load time, avoiding redundant data in order to provide optimal rendering of multiple instances of the same model. Metadata information can be stored on the nodes and materials in order to provide application specific information to use the scene.
Required scripts
The Scene object requires:
/*{{ javascript("jslib/scene.js") }}*/
/*{{ javascript("jslib/light.js") }}*/
/*{{ javascript("jslib/material.js") }}*/
/*{{ javascript("jslib/geometry.js") }}*/
/*{{ javascript("jslib/aabbtree.js") }}*/
/*{{ javascript("jslib/scenenode.js") }}*/
/*{{ javascript("jslib/utilities.js") }}*/
/*{{ javascript("jslib/vertexbuffermanager.js") }}*/
/*{{ javascript("jslib/indexbuffermanager.js") }}*/
Summary
Creates and returns a scene object with default values.
Syntax
var scene = Scene.create(mathDevice);
Summary
Loads and initializes a scene from the given scene parameters.
Syntax
function yieldFn(callback)
{
TurbulenzEngine.setTimeout(callback, 0);
}
var levelLoaded = false;
function levelLoadedFn()
{
levelLoaded = true;
}
var sceneParameters = {
append : true,
data : sceneData,
graphicsDevice : graphicsDevice,
mathDevice : mathDevice,
physicsDevice : physicsDevice,
collisionMargin : 0.1,
textureManager : textureManager,
keepLights : true,
keepCameras : false,
baseScene: null,
baseMatrix: null,
skin: null,
nodesNamePrefix : "level1",
shapesNamePrefix : "level1",
yieldFn : yieldFn,
onload : levelLoadedFn,
physicsManager : physicsManager,
dynamic : true,
disabled : true,
keepVertexData : true,
vertexBufferManager : vertexBufferManager,
indexBufferManager : indexBufferManager
};
scene.load(sceneParameters);
The Scene object loads external references asynchronously and it may delay execution of some of the loading in order to provide a cooperative environment with the rest of the application. This means that although the load method will return immediately, the whole scene will not be ready until the callback onload is executed.
Summary
Clears the scene, removing all nodes, geometries, lights, materials, physics objects, etc.
Syntax
if (reloadLevel)
{
scene.clear();
}
Summary
Add a root sceneNode, along with all its children, to the scene. The root node must have a unique name. Once added to the scene the name should not be changed.
A sceneNode can only be in one scene.
Syntax
var nodeRoot = SceneNode.create();
nodeRoot.setName("player1");
scene.addRootNode(nodeRoot);
Summary
Remove a root SceneNode, along with all its children, from the scene. See SceneNode.removeChild() to remove non-root nodes.
Syntax
scene.removeRootNode(nodeRoot);
//example usage:
var redLightNode = scene.findNode("redLight-node");
scene.removeRootNode(redLightNode);
Summary
Creates a clone of the SceneNode, along with all its descendants, and adds it to the scene’s root nodes.
See also SceneNode.clone().
Syntax
var cloneNode = scene.cloneRootNode(rootNode, cloneName);
//example usage:
var redLightNode = scene.findNode("redLight-node");
var redLightNode2 = scene.cloneRootNode(redLightNode, "redLight-node2");
Returns a SceneNode object.
Summary
Find a SceneNode with the given path. The path can be created from SceneNode.getPath(). A root node path is just its name.
Syntax
var node = scene.findNode(nodeName);
Returns a SceneNode object. If a node with the name nodeName doesn’t exist then this function returns undefined.
Summary
Add a named light to the scene’s collection of lights. Any light marked as global are added to the scene’s global light list. For non-global lights their visibility and influence is determined from the SceneNodes they are attached to.
Syntax
scene.addLight(light);
Summary
Remove a light from the scene’s collection of lights. Global lights are removed from the scene’s global lights list.
Syntax
scene.removeLight(light);
Summary
Get a light by name.
Syntax
var light = scene.getLight(lightName);
Returns a Light object.
Summary
Get an array of lights that affect all nodes. See also getCurrentVisibleLights.
Syntax
var globalLights = scene.getGlobalLights();
var numGlobalLights = globalLights.length;
if (numGlobalLights)
{
drawGlobalLights(globalLights, numGlobalLights);
}
Returns an array of Light objects.
Summary
Updates the node hierarchy and updates nodes extents.
Syntax
scene.update();
Summary
Updates all the sceneNodes so that world transforms and world extents are updated. Once this is called the SceneNode properties can be read directly. This method is called by scene.update().
Syntax
scene.updateNodes();
Summary
Updates the array of visible nodes for the given camera.
Syntax
scene.updateVisibleNodes(camera);
Summary
Get the current array of visible nodes.
You have to call scene.updateVisibleNodes(camera) before use this method.
Syntax
var visibleNodes = scene.getCurrentVisibleNodes();
var numVisibleNodes = visibleNodes.length;
if (0 < numVisibleNodes)
{
//...
}
Returns an array of SceneNode objects.
Summary
Get the current array of visible renderable objects.
You have to call scene.updateVisibleNodes(camera) before use this method.
Syntax
var visibleRenderables = scene.getCurrentVisibleRenderables();
var numVisibleRenderables = visibleRenderables.length;
if (0 < numVisibleRenderables)
{
//...
}
Returns an array of SceneNode objects.
Summary
Get the current array of visible lights.
This does not include global lights. See getGlobalLights.
You have to call scene.updateVisibleNodes(camera) before use this method.
Syntax
var visibleLights = scene.getCurrentVisibleLights();
var numVisibleLights = visibleLights.length;
if (0 < numVisibleLights)
{
//...
}
Returns an array of Light objects.
Summary
Creates a material in the scene from the material reference provided. The function will return false if:
Syntax
var material = {
effect : "phong",
parameters : {
diffuse : "textures/plastic.png"
}
};
var materialName = "PlasticMaterial";
if (scene.loadMaterial(graphicsDevice, textureManager, effectManager, materialName, material))
{
// ...
}
Summary
Checks if the scene already has a material with materialName. This function will return true if the materialName already exists on the scene.
Syntax
if (scene.hasMaterial(materialName))
{
// The material can be set on a renderable
node.renderables[0].setMaterial(scene.getMaterial(materialName));
}
Summary
Get a material by name.
Syntax
var material = scene.getMaterial(materialName);
Returns a Material object.
Summary
Get the world extents of the whole scene.
Syntax
var sceneExtents = scene.getExtents();
var maxHeight = sceneExtents[5];
Returns an extents object.
Summary
Destroys the scene, clearing it and freeing system resources.
The scene should not be used after this call.
Syntax
if (exitGame)
{
scene.destroy();
scene = null;
}
Summary
The version number of the Scene implementation.
Syntax
var sceneVersionNumber = scene.version;
Summary
The bounding box extents of all the nodes in the scene.
This should only be called after scene.updateNodes() or scene.update() has been called. Use scene.getExtents() otherwise.
Syntax
var minHeight = scene.extents[1];
Summary
The maximum distance to the camera near plane of the visible nodes axis-aligned bounding boxes.
Syntax
var maxSceneDepth = scene.maxDistance;