Tutorial: Actors

Introduction

Each model that has been loaded is represented by an actor in a scene.  When a model is loaded, a new actor for that model is automatically created and added to the current scene.

Actors and Models

Actors are designed to be lightweight representations of models.

Actors are represented in voxelent by the vxlActor class.

var actor = new vxlActor(model);

The constructor takes one parameter: the model the actor will represent.

An actor extracts model properties such as colors and textures. These properties are stored into the actor material attribute . However, an actor does not copy geometric information such as vertices, indices and normals. This design allows to change individual settings for actors that could be sharing the same geometry, saving memory.

[diagram actor vs models goes here]

 Retrieving actors using the public API shortcuts

As we saw in the Scene tutorial, we can obtain references to actors currently being displayed through the scene management operations. We can also use the getActor shortcut available in the public API:

var actor = vxl.api.getActor(a); //a can be the actor name or the actor UID.

The following shortcut operations are also available through the public API:
vxl.api.getActorByName, vxl.api.getActorByUID, vxl.api.getActorNames, vxl.api.getActorsThat

As it can be seen in the public API page, these operation shorcuts can work with the current scene or with a scene passed as a parameter.

 Basic actor operations

Let’s take a look at some of the basic actor operations:

Changing color

An actor color can be change using the setColor method. This method internally changes the diffuse property of the vxlMaterial object associated with the actor. Say for instance that we have an actor named cone in the current scene. Then to change its color we write:

var cone = vxl.c.scene.getActorByName('cone');
cone.setColor(0,1,0); // sets the cone color to green

Where the parameters correspond to the R, G and B color components in the [0,1] range. There are other properties that can be used to update the appearance of an actor. These will be discussed with detail in the tutorial about materials.

Shading

An actor can stop reacting to light sources by setting the shading property to false.

shaded cone (left), unshaded cone(right)

This is achieved by the setShading operation. Using the same actor cone created in the previous section:

cone.setShading(false); // cone stops reacting to light sources;
cone.setShading(true); // the cone starts reacting to light sources again;

Hiding/Showing

An actor can be stop from being rendered by setting its visible property to false. This is done with the setVisible operation:

cone.setVisible(false); // the cone is not rendered
cone.setVisible(true); // the cone is rendered again

Moving

An actor location can be repositioned using the setPosition property. For example, if we want to move the cone to the origin we would write something like this:

cone.setPosition(0,0,0); // vxlActor.setPosition(x,y,z);

On the other hand if we just want to translate the actor in relation to its current position we can use the translate operation:

actor.translate(0,10,0); // translates the actor 10 units in the positive Y-axis direction (up).

Rotating

We can rotate actors using the rotateX, rotateY, and rotateZ operations, which receive the angle in degrees (360):

cone.setPosition(0,0,0).rotateX(10).rotateZ(10); //rotate the actor 10 degrees in on the X axis, then it rotates 15 degrees on the Z axis.

The previous example shows that rotation and translation  operations can be concatenated.

Changing the scale

The scale of an actor can be changed using the setScale method. This method receives one or three parameters. When using one parameter the scale will change equally in all the axes. Otherwise, when three parameters are used. The scale is changed for the x, y and z components independently:

cone.setScale(2);// the actor doubles its dimensions
cone.setScale(1,2,1);  // the actor doubles its height (y-component);

vxlActor API

To obtain a complete reference of all the properties available to actors make sure of checking the vxlActor API page.