Tutorial: Scenes

Introduction

The scene is represented in voxelent by the vxlScene class. A scene contains zero of more actors. Each actor represents a 3D object on the screen.

Creating a Scene

We can create a scene by simply writing:

var scene = new vxlScene();

This creates a new empty scene. The vxlScene constructor does not have any parameters.

Usually it is not necessary to create a scene. When you create a view using vxl.api.setup() the new view will have a freshly created scene object. As we saw in the views tutorial, this scene object can be accessed using:

var scene = view.scene; // view is an instance of vxlView

Managing Actors

A scene manages actors. There are several methods that are provided to achieve this:

• addActor(actor): adds the actor passed as parameter to the scene
• removeActor(actor): removes the actor passed as parameter to the scene
• getActorNames(): returns a list of strings, each element corresponding to the name of one actor in the scene
• hasActor(actor): returns true if the actor exists in the current scene. This method can receive an actor name or an actor object.
• getActorByName(name): retrieves an actor object by name
• getActorByUID(uid): retrieves an actor by UID (Unique Identifier).
• getPickableActors(): get actors that can respond to picking (more about this in the picking tutorial)
• reset(): eliminates all the actors in the scene leaving the scene empty.

Setting actor properties

A scene can also set actor properties for some of all of its actors. Let’s take a look at how this happens. Say for instance that we want to change the color of all the actors to blue. We then use the setPropertyForAll method:

var scene = vxl.c.view.scene; //get the scene associated to the current view
scene.setPropertyForAll('color',[0,0,1]);

here the color property that we want to change is passed as an string  (‘color’) and the second parameter is the value we want to change it with.

If instead what we want is to change only some actors, say we want to hide the actors that are being represented as wireframes on the scene, we proceed in two steps: first we retrieve those actors with the getActorsThat method and second we hide them using the setPropertyFor method. Let’s take a look at the code:

var list  = scene.getActorsThat(
     function(actor){ 
           return actor.mode == vxl.def.actor.mode.WIREFRAME;
      });

scene.setPropertyFor(list,'visible',false);

getActorsThat receives a function  This anonymous function has one parameter: the actor. Ths anonymous function is executed for every actor in the scene. getActorsThat will add to the returning list only those actors where the evaluating condition is true.

The second instruction is setPropertyFor. This method receives three parameters: a list of actors, a property name and a property value.

vxlScene API

For a complete reference of all the vxlScene operations available please refer to the vxlScene API page.