Previous articles summary :
- First steps in Papervision3D : Part 1
Creation of a new Papervision3D project within eclipse or Flex Builder 3 and a simple example of a 3D scene illustrating some basic Papervision3D classes. - First steps in Papervision3D : Part 2
Illustration of use of new Papervision3D v2.0 class BasicView that encapsulates essential elements to rapidly start developing new 3D scenes. - First steps in Papervision3D : Part 3 - animation
Adding some basic animation to the scene by modifying 3D object parameters when entering a frame. - First steps in Papervision3D : Part 4 - lighting and shading
A point light source is added to the scene. Fours materials with different characteristics are added to spheres to illustrate how Papervision3D performs shading.
In this post, rather than adding more 3D rendering to the scene, I’d like to illustrate how Papervision3D provides us with a very simple interface so that users can interact with objects that we’ve created. As someone coming from an OpenGL background this is real magic ! Each triangle that we draw in a scene can listen to mouse events and call a specified function for example when we click on it or move the mouse over it.
The code sample that I show below is based on the previous post : four spheres with different shaded materials rotating about the origin. I’m now adding two different types of event listeners : a listener for standard Flash mouse events allowing the user can move around the scene by changing the camera position and a listener for Papervision3D InteractiveScene3DEvent events. The first of these is added to the stage, the second to individual DisplayObject3D objects.
To illustrate the interactions with the scene objects, I’m adding a third new element to code : tweens. Without having to calculate and specify the change in positions (for example) of objects within the code, a tween does all the hard work for us. A tween works on a particular property of an object and at each frame of an animation modifies this property in a particular manner. I’m not going to go into much detail here as its not the purpose of this post but you’ll find a lot of information on the web - here’s wikipedia’s definition for what its worth. The tweens I use here come from the opensource library Tweener which provides tweens for Actionscript2 and Actionscript3 as well as JavaScript and HaXE. To install it in your Eclipse/Flex Builder 3 environment follow the same guidelines that I gave with installing Papervision3D but rather than importing the source using SVN, simply download the zip file of the source from the Tweener homepage and extract it into the src folder of a new Tweener project. When its compiled link your own Actionscript project to the Tweener project.
Here’s the full code for the interactive scene and including the imports of the new Tweener library.
package {
import caurina.transitions.Tweener;
import flash.display.StageAlign;
import flash.display.StageScaleMode;
import flash.events.Event;
import flash.events.MouseEvent;
import org.papervision3d.core.proto.MaterialObject3D;
import org.papervision3d.events.InteractiveScene3DEvent;
import org.papervision3d.lights.PointLight3D;
import org.papervision3d.materials.shadematerials.CellMaterial;
import org.papervision3d.materials.shadematerials.FlatShadeMaterial;
import org.papervision3d.materials.shadematerials.GouraudMaterial;
import org.papervision3d.materials.shadematerials.PhongMaterial;
import org.papervision3d.objects.DisplayObject3D;
import org.papervision3d.objects.primitives.Sphere;
import org.papervision3d.view.BasicView;
public class Example005 extends BasicView {
private static const ORBITAL_RADIUS:Number = 200;
private var sphere1:Sphere;
private var sphere2:Sphere;
private var sphere3:Sphere;
private var sphere4:Sphere;
private var sphereGroup:DisplayObject3D;
private var light:PointLight3D;
private var doRotation:Boolean = false;
private var lastMouseX:int;
private var lastMouseY:int;
private var cameraPitch:Number = 60;
private var cameraYaw:Number = -60;
public function Example005() {
// specify that we want the scene to be interactive
super(0, 0, true, true);
// set up the stage
stage.align = StageAlign.TOP_LEFT;
stage.scaleMode = StageScaleMode.NO_SCALE;
// Initialise Papervision3D
init3D();
// Create the 3D objects
createScene();
// Listen to mouse up and down events on the stage
stage.addEventListener(MouseEvent.MOUSE_DOWN, onMouseDown);
stage.addEventListener(MouseEvent.MOUSE_UP, onMouseUp);
// Start rendering the scene
startRendering();
}
private function init3D():void {
// position the camera
camera.z = -500;
camera.orbit(cameraPitch, cameraYaw);
}
private function createScene():void {
// Specify a point light source and its location
light = new PointLight3D(true);
light.x = 400;
light.y = 1000;
light.z = -400;
// Create a new material (flat shaded) and make it interactive
var flatShadedMaterial:MaterialObject3D = new FlatShadeMaterial(light, 0x6654FF, 0x060433);
flatShadedMaterial.interactive = true;
sphere1 = new Sphere(flatShadedMaterial, 50, 10, 10);
sphere1.x = -ORBITAL_RADIUS;
// Create a new material (flat shaded) and make it interactive
var gouraudMaterial:MaterialObject3D = new GouraudMaterial(light, 0x6654FF, 0x060433);
gouraudMaterial.interactive = true;
sphere2 = new Sphere(gouraudMaterial, 50, 10, 10);
sphere2.x = ORBITAL_RADIUS;
// Create a new material (flat shaded) and make it interactive
var phongMaterial:MaterialObject3D = new PhongMaterial(light, 0x6654FF, 0x060433, 150);
phongMaterial.interactive = true;
sphere3 = new Sphere(phongMaterial, 50, 10, 10);
sphere3.z = -ORBITAL_RADIUS;
// Create a new material (flat shaded) and make it interactive
var cellMaterial:MaterialObject3D = new CellMaterial(light, 0x6654FF, 0x060433, 5);
cellMaterial.interactive = true;
sphere4 = new Sphere(cellMaterial, 50, 10, 10);
sphere4.z = ORBITAL_RADIUS;
// Create a 3D object to group the spheres
sphereGroup = new DisplayObject3D();
sphereGroup.addChild(sphere1);
sphereGroup.addChild(sphere2);
sphereGroup.addChild(sphere3);
sphereGroup.addChild(sphere4);
// Add a listener to each of the spheres to listen to InteractiveScene3DEvent events
sphere1.addEventListener(InteractiveScene3DEvent.OBJECT_CLICK, onMouseDownOnSphere);
sphere2.addEventListener(InteractiveScene3DEvent.OBJECT_CLICK, onMouseDownOnSphere);
sphere3.addEventListener(InteractiveScene3DEvent.OBJECT_CLICK, onMouseDownOnSphere);
sphere4.addEventListener(InteractiveScene3DEvent.OBJECT_CLICK, onMouseDownOnSphere);
// Add the light and spheres to the scene
scene.addChild(sphereGroup);
scene.addChild(light);
}
override protected function onRenderTick(event:Event=null):void {
// rotate the spheres
sphere1.yaw(-8);
sphere2.yaw(-8);
sphere3.yaw(-8);
sphere4.yaw(-8);
// rotate the group of spheres
sphereGroup.yaw(3);
// If the mouse button has been clicked then update the camera position
if (doRotation) {
// convert the change in mouse position into a change in camera angle
var dPitch:Number = (mouseY - lastMouseY) / 2;
var dYaw:Number = (mouseX - lastMouseX) / 2;
// update the camera angles
cameraPitch -= dPitch;
cameraYaw -= dYaw;
// limit the pitch of the camera
if (cameraPitch <= 0) {
cameraPitch = 0.1;
} else if (cameraPitch >= 180) {
cameraPitch = 179.9;
}
// reset the last mouse position
lastMouseX = mouseX;
lastMouseY = mouseY;
// reposition the camera
camera.orbit(cameraPitch, cameraYaw);
}
// call the renderer
super.onRenderTick(event);
}
// called when mouse down on stage
private function onMouseDown(event:MouseEvent):void {
doRotation = true;
lastMouseX = event.stageX;
lastMouseY = event.stageY;
}
// called when mouse up on stage
private function onMouseUp(event:MouseEvent):void {
doRotation = false;
}
// called when mouse down on a sphere
private function onMouseDownOnSphere(event:InteractiveScene3DEvent):void {
var object:DisplayObject3D = event.displayObject3D;
Tweener.addTween(object, {y:200, time:1, transition:"easeOutSine", onComplete:function():void {goBack(object);} });
}
// called when a tween created in onMouseDownOnSphere has terminated
private function goBack(object:DisplayObject3D):void {
Tweener.addTween(object, {y:0, time:2, transition:"easeOutBounce"});
}
}
}
This produces the following Flash animation (click on image below) where we see the four spinning spheres rotating about the origin. You can rotate the scene by clicking and moving the mouse. You can interact with the spheres by clicking on them to make them jump.
Now lets look at the two different types of interaction that occur with this scene.
Stage interaction and modifying the camera position
The objective is to look at the scene from different angles by clicking the mouse button and moving the mouse. The interaction with the mouse is initialised by listening to the standard Flash event listeners. In the constructor we add the following lines :
// Listen to mouse up and down events on the stage stage.addEventListener(MouseEvent.MOUSE_DOWN, onMouseDown); stage.addEventListener(MouseEvent.MOUSE_UP, onMouseUp);
When a mouse click occurs on the stage, calls are made to onMouseDown and onMouseUp. These methods modify a boolean value to indicate that the user wants to translate the camera and initialises the position of the mouse, necessary to determine the amount of movement that occurs during a frame.
// called when mouse down on stage
private function onMouseDown(event:MouseEvent):void {
doRotation = true;
lastMouseX = event.stageX;
lastMouseY = event.stageY;
}
// called when mouse up on stage
private function onMouseUp(event:MouseEvent):void {
doRotation = false;
}
The movement of the camera occurs by implementing code in the onRenderTick function which is called systematically at the beginning of every frame.
// If the mouse button has been clicked then update the camera position
if (doRotation) {
// convert the change in mouse position into a change in camera angle
var dPitch:Number = (mouseY - lastMouseY) / 2;
var dYaw:Number = (mouseX - lastMouseX) / 2;
// update the camera angles
cameraPitch -= dPitch;
cameraYaw -= dYaw;
// limit the pitch of the camera
if (cameraPitch <= 0) {
cameraPitch = 0.1;
} else if (cameraPitch >= 180) {
cameraPitch = 179.9;
}
// reset the last mouse position
lastMouseX = mouseX;
lastMouseY = mouseY;
// reposition the camera
camera.orbit(cameraPitch, cameraYaw);
}
The amount of horizontal and vertical movement of the mouse since the last frame (or the mouse down event was captured) are converted into angular displacements. These displacements are converted into a change in camera position. Rather than specifying and x, y and z values for the camera we are able to take advantage of its orbit function. The orbit takes two angles : yaw (or angle in the x-z plane) and pitch angle from the y axis which we limit to be between 0 and 180 degrees.
The orbit occurs around any given 3D object - in this case the origin as default - and has a particular distance from the object. This distance was initialised during the init3D method when we specified camera.z = -500. All subsequent orbital positions therefore have a distance of 500 from the origin. If you look into the code of the function orbit, you’ll see that these angles are subsequently converted into positional values for the camera.
After updating the camera position, the call to super.onRenderTick performs the necessary actions to render the scene at the modified viewing position.
Object interaction and tweening
The second type of interaction that we use takes advantage of Papervision3D’s power of detecting which 3D object is beneath the mouse. We need to explicitly indicate to Papervision3D that we want to have an interactive scene when we create the viewport and for each interactive material that we create, the interactions themselves are handled by adding listeners to the 3D objects.
First of all, to specify that we want an interactive scene we modify the call to the constructor of BasicView which is done by passing the value of true to the interactive scene argument (the second boolean shown below, the first being to indicate that we want the viewport to resize to the stage).
public function Example005() {
// specify that we want the scene to be interactive
super(0, 0, true, true);
Secondly, each object that we want to be interactive must have an interactive material. This is done by setting the variable interactive to true for the materials that we have created. For example, the flat shaded sphere is as such :
// Create a new material (flat shaded) and make it interactive var flatShadedMaterial:MaterialObject3D = new FlatShadeMaterial(light, 0x6654FF, 0x060433); flatShadedMaterial.interactive = true; sphere1 = new Sphere(flatShadedMaterial, 50, 10, 10);
Once the 3D objects have been created we add listeners to listen to Papervision3D interactive scene events, in this case when the user clicks on a sphere.
// Add a listener to each of the spheres to listen to InteractiveScene3DEvent events sphere1.addEventListener(InteractiveScene3DEvent.OBJECT_CLICK, onMouseDownOnSphere); sphere2.addEventListener(InteractiveScene3DEvent.OBJECT_CLICK, onMouseDownOnSphere); sphere3.addEventListener(InteractiveScene3DEvent.OBJECT_CLICK, onMouseDownOnSphere); sphere4.addEventListener(InteractiveScene3DEvent.OBJECT_CLICK, onMouseDownOnSphere);
All of these objects use the same function to handle the event.
// called when mouse down on a sphere
private function onMouseDownOnSphere(event:InteractiveScene3DEvent):void {
var object:DisplayObject3D = event.displayObject3D;
Tweener.addTween(object, {y:200, time:1, transition:"easeOutSine", onComplete:function():void {goBack(object);} });
}
The object that has been clicked on is sent as part of the InteractiveScene3DEvent data. Here we then see the implementation of Tweener.
Tweener contains static methods that allow us to modify object properties. In this case we simply modify the y position of the object so that it goes to a value of 200 in 1 second using the easeOutSine transition function. I’d recommend looking at the Tweener documentation on the different transition functions. The onComplete argument allows us to put the sphere back to its original position when the tween has completed.
// called when a tween created in onMouseDownOnSphere has terminated
private function goBack(object:DisplayObject3D):void {
Tweener.addTween(object, {y:0, time:2, transition:"easeOutBounce"});
}
}
This then uses another tween with an easeOutBounce transition to move the sphere back to the x-z plane.
As you can see, adding user interactions to the scene is very easy. Papervision3D provides a very simple interface to modify both camera position and produce interactions with individual objects in the scene. What I’ve shown here is just is a simple introduction to object interaction : there are different types of interactions for example when an object is added to a scene, the mouse moves over the object or the object is moved. Look inside the source of InteractiveScene3DEvent to get an idea of all the possibilities. Hopefully this at least has given a taster of what can be produced. As always comments and feedback are very welcome !
Next article:
- First steps in Papervision3D : Part 6 - Texture mapping
Create materials using bitmap data with the aim of having more detailed or realistic objects.
Thanx a lot. I’ll start PaperVision3D using your very well explained tutorials. Be sure that when my 3D webapp will be top rated I will thank you even more.
;)
Marco
Nice… hope to find more stuff like this. Your explanations is extremely well
Hi there again,
Your tutorials are great. You explain everything very well. I also have OpenGL bases so this is just a new way to acomplish the same visual results but with less efort and in a web environment.
I am just getting a problem in this tutorial because the camera is not moving for me because i get the following error in:
private function init3D():void {
// position the camera
camera.z = -500;
camera.orbit(cameraPitch, cameraYaw); <———– ERROR
}
and the error is 1061: Call to a possibly undefined method orbit through a reference with static type org.papervision3d.core.proto:CameraObject3D.
I have taken a look at the PV3D src and the orbit function is there so i can’t figure out the problem.
Regards and sorry for posting doubts in your comment section ;)
Are you sure you are using the src from the trunk repository (should be svn->trunk->as3->trunk->src) and NOT from CS4 branch? The CameraObject3D is different. You can take a look at the source directly at google code to verify.
Great tutorials!! Just 1 question: Is there a way to tween with the camera.orbit method instead of changing x, y, z manually?
Saved my life, man. Thanks a lot. I hope I’ll have some opensource code to share soon.
I combined this tutorial with the Collada one.
I use a gouraud texture (interactive = true) with the cow but It has to be in a MaterialsList. I get my gouraud cow but it’s no longer interactive. Any clues?
Got it!
I had to use the recursive method to ensure every object in the Collada got the interactive method for the event… as you did on the second example, duh.
Thanks so much for the awesome tutorials! Very well explained!
For the people, that like to use TweenLite instead of Tweener:
instead of
Tweener.addTween(object, {y:200, time:1, transition:”easeOutSine”, onComplete:function():void{ goBack(object);} });
use
TweenLite.to(object, 1, {y:200, ease: Sine.easeInOut, onComplete: goBack, onCompleteParams: [object]});
and instead of
Tweener.addTween(object, {y:0, time:2, transition:”easeOutBounce”});
use
TweenLite.to(object, 2, {y:0, ease: Bounce.easeOut});
to Vortek!
You might use cs4 ver. That time You have to change this.
—————————–
camera.x = cameraPitch;
camera.y = cameraYaw;
—————————–
That’ll fix your error.
Amazing tuts! Loveing them!
B4 using BasicView you could use;
//
viewport = new Viewport3D(708, 400, true,true);
addChild(viewport);
viewport.buttonMode = true;
//
How do you “viewport.buttonMode = true;” with BasicView, to get the cursor roll over back?
Thx.
wow, thank u so much for your tutorials - its really an easy way to get started with PV3D!!