In this post I hope to show how, in a few simple steps, we can create a simple 3D scene in Actionscript 3 using Papervision3D. As I’ve mentioned in previous posts, I’m no expert and am merely posting on the web the experiences I’ve had over the last few weeks in starting myself. A couple of useful links providing an introduction to 3D techniques and Papervision3D features provide a good starting point.
My main objective here is to highlight the principal elements necessary to render a 3D scene using certain principal pv3d classes namely Scene3D, Viewport3D, Camera3D and BasicRenderEngine. In the next post in this series I’ll show how Papervsion3D v2.0 provides a simple wrapper class, BasicView, that encapsulates all of these making it even simpler to get started. However, for this post I wanted to show the basic ingredients involved in Papervision3D.
Before starting, I’m assuming that you’re using Flex Builder 3 (or the Eclipse plugin) and have downloaded and compiled Papervision3D v2.0 (Great White) within this environment. You can check out these previous posts if you need help :
1. Creating a new project
From the File menu in Eclipse, select New -> ActionScript Project. In the new project wizard, enter the name of the project (here I’ve called it FirstSteps) and click on Next.
We now need to specific the source path. Rather unimaginatively, I use src entered next to the Main source folder label. I also change the name of the Main application file to Example001.as. Note that this can also be changed later. The output folder I left as its default value. Next click on the Library path tab to set up the import of Papervision3D.
Initially only the Flex 3 classes are included and we need to import the Papervision3D ones. You now have two options : either link this project to the Papervision3D one (see my last post) by clicking on the Add Project… button or copy the compiled as3 library from that project into the new project and link to it by clicking on Add SWC… For this example I’m going to use the first option - I’ve found it useful over the last few weeks to be able to wander through the Papervision3D source code during the development stages. I don’t know if there’s an advantage or not with using one option rather than the other… In any case you can always change how you import Papervision3D later by modifying the project properties. So, for the time being, click on Add Project… and select the Papervision3D project that we created before.
2. Example001.as
We’re now ready to start our first example. Open the newly created Example001.as file and replace what’s been automatically generated with the following code. This example draws a wire-frame sphere and the x-, y- and z- axes. What I really want to illustrate though is how the scene is set up.
package {
import flash.display.Sprite;
import flash.display.StageAlign;
import flash.display.StageScaleMode;
import flash.events.Event;
import org.papervision3d.cameras.Camera3D;
import org.papervision3d.core.geom.Lines3D;
import org.papervision3d.core.geom.renderables.Line3D;
import org.papervision3d.core.geom.renderables.Vertex3D;
import org.papervision3d.core.proto.MaterialObject3D;
import org.papervision3d.materials.WireframeMaterial;
import org.papervision3d.materials.special.LineMaterial;
import org.papervision3d.objects.DisplayObject3D;
import org.papervision3d.objects.primitives.Sphere;
import org.papervision3d.render.BasicRenderEngine;
import org.papervision3d.scenes.Scene3D;
import org.papervision3d.view.Viewport3D;
public class Example001 extends Sprite {
private var scene:Scene3D;
private var camera:Camera3D;
private var viewport:Viewport3D;
private var renderer:BasicRenderEngine;
public function Example001() {
// set up the stage
stage.align = StageAlign.TOP_LEFT;
stage.scaleMode = StageScaleMode.NO_SCALE;
// Initialise Papervision3D
init3D();
// Create the 3D objects
createScene();
// Initialise Event loop
this.addEventListener(Event.ENTER_FRAME, loop);
}
private function init3D():void {
// create viewport
viewport = new Viewport3D(0, 0, true, false);
addChild(viewport);
// Create new camera with fov of 60 degrees (= default value)
camera = new Camera3D(60);
// initialise the camera position (default = [0, 0, -1000])
camera.x = -100;
camera.y = -100;
camera.z = -500;
// target camera on origin
camera.target = DisplayObject3D.ZERO;
// Create a new scene where our 3D objects will be displayed
scene = new Scene3D();
// Create new renderer
renderer = new BasicRenderEngine();
}
private function createScene():void {
// First object : a sphere
// Create a new material for the sphere : simple white wireframe
var sphereMaterial:MaterialObject3D = new WireframeMaterial(0xFFFFFF);
// Create a new sphere object using wireframe material, radius 50 with
// 10 horizontal and vertical segments
var sphere:Sphere = new Sphere(sphereMaterial, 50, 10, 10);
// Position the sphere (default = [0, 0, 0])
sphere.x = -100;
// Second object : x-, y- and z-axis
// Create a default line material and a Lines3D object (container for Line3D objects)
var defaultMaterial:LineMaterial = new LineMaterial(0xFFFFFF);
var axes:Lines3D = new Lines3D(defaultMaterial);
// Create a different colour line material for each axis
var xAxisMaterial:LineMaterial = new LineMaterial(0xFF0000);
var yAxisMaterial:LineMaterial = new LineMaterial(0x00FF00);
var zAxisMaterial:LineMaterial = new LineMaterial(0x0000FF);
// Create a origin vertex
var origin:Vertex3D = new Vertex3D(0, 0, 0);
// Create a new line (length 100) for each axis using the different materials and a width of 2.
var xAxis:Line3D = new Line3D(axes, xAxisMaterial, 2, origin, new Vertex3D(100, 0, 0));
var yAxis:Line3D = new Line3D(axes, yAxisMaterial, 2, origin, new Vertex3D(0, 100, 0));
var zAxis:Line3D = new Line3D(axes, zAxisMaterial, 2, origin, new Vertex3D(0, 0, 100));
// Add lines to the Lines3D container
axes.addLine(xAxis);
axes.addLine(yAxis);
axes.addLine(zAxis);
// Add the sphere and the lines to the scene
scene.addChild(sphere);
scene.addChild(axes);
}
private function loop(event:Event):void {
// Render the 3D scene
renderer.renderScene(scene, camera, viewport);
}
}
}
When executed you should see a wireframe sphere to the left and the a red x-axis, green y-axis and blue z-axis (click on image to execute the Flash animation):
Now let’s go into a bit more detail into the code.
3. Initialising the stage
During the setup of the project we specified that Example001.as should be the main application file. This means that it has access to the stage and its associated variables. In the constructor of Example001.as we include the following lines of standard Actionscript code :
stage.align = StageAlign.TOP_LEFT;
stage.scaleMode = StageScaleMode.NO_SCALE;
The first line indicates that rendered scene should be aligned to the top-left of the browser. The second indicates that the displayed scene will remain the same size when the browser window is redimensioned.
The other pure Actionscript part is to specify an event listener so that the scene can be drawn on the stage (and updated if the scene changes). This is specified using the event listener :
this.addEventListener(Event.ENTER_FRAME, loop);
4. Initialising the 3D scene
There are three essential classes necessary to set up the scene : Scene3D, Viewport3D and Camera3D. I’d recommend playing around with the values that I’ve given in the code to see what differences they make - its always easier to learn through trial and error !
Firstly we specify the viewport which is added directly as a child of of Example001 and rendered on the stage :
viewport = new Viewport3D(0, 0, true, false);
addChild(viewport);
The first two parameters specify the size of the viewport (width and height respectively). By setting them both to 0 we indicate to Papervision3D that we want to use the full width of the stage. We could though for example have a viewport that is smaller than the stage. The first boolean value we pass is to resize the viewport when the stage (or browser window) is resized. The final value indicates that we are not rendering an interactive scene.
Next we set up the camera which specifies the user location relative to the scene and in which direction they are looking in. We imagine that the user is seeing the scene through a camera because variables such as zoom and focus can be specified.
// Create new camera with fov of 60 degrees (= default value)
camera = new Camera3D(60);
// initialise the camera position (default = [0, 0, -1000])
camera.x = -100;
camera.y = -100;
camera.z = -500;
// target camera on origin
camera.target = DisplayObject3D.ZERO;
The camera is created with a field of vision of 60 degrees, indicating the vertical visible angle. We then give it a position which by default is located at -1000 along the z-axis (positive values go into the screen). We then indicate that we want the camera to point towards the origin - if you leave this out you’ll notice that the camera by default looks along the z-axis.
Finally we create a Scene3D and a BasicRenderEngine.
// Create a new scene where our 3D objects will be displayed
scene = new Scene3D();
// Create new renderer
renderer = new BasicRenderEngine();
All 3D objects that we create with Papervision are added to the Scene3D, as we’ll see later, and the Renderer is used, as one might expect, to draw the scene.
That, at its very simplest, is how we set up Papervision3D before creating the 3D objects (actually, that’s not true : I’ll show in the next post an easier way !). As I said before, play around with the value and, more importantly, explore the Papervision3D code to see what the different parameters do.
5. Adding 3D objects to the scene
Here I’m going to add two simple objects to the scene : a sphere with a wireframe structure, and three lines to show the x-, y- and z-axes, each with a different colour.
We use a Papervision3D primitive object for the sphere - the people at Papervision3D have done all the hard work for us, all we need to do is give a few parameters for its size and amount of detail.
// Create a new material for the sphere : simple white wireframe
var sphereMaterial:MaterialObject3D = new WireframeMaterial(0xFFFFFF);
// Create a new sphere object using wireframe material, radius 50 with
// 10 horizontal and vertical segments
var sphere:Sphere = new Sphere(sphereMaterial, 50, 10, 10);
// Position the sphere (default = [0, 0, 0])
sphere.x = -100;
First of all we create a new material. All objects in Papervision3D have an associated material. To name but a few examples, the material can be simply to display edges (as we use here), a coloured material for a solid colour, a shaded one that takes into account lighting or a bitmapped material to show images. If you explore in the Papervision3D source to org/papervision3d/materials you’ll find a huge variety. For our example we create a wireframe material (showing the edges of the polygons used for the sphere) having a white colour.
The sphere is then created with this material. We give it a radius of 50 and specify that it is made up of 10 horizontal and vertical segments.
After the sphere, we create the axes.
// Create a default line material and a Lines3D object (container for Line3D objects)
var defaultMaterial:LineMaterial = new LineMaterial(0xFFFFFF);
var axes:Lines3D = new Lines3D(defaultMaterial);
// Create a different colour line material for each axis
var xAxisMaterial:LineMaterial = new LineMaterial(0xFF0000);
var yAxisMaterial:LineMaterial = new LineMaterial(0x00FF00);
var zAxisMaterial:LineMaterial = new LineMaterial(0x0000FF);
// Create a origin vertex
var origin:Vertex3D = new Vertex3D(0, 0, 0);
// Create a new line (length 100) for each axis using the different materials and a width of 2.
var xAxis:Line3D = new Line3D(axes, xAxisMaterial, 2, origin, new Vertex3D(100, 0, 0));
var yAxis:Line3D = new Line3D(axes, yAxisMaterial, 2, origin, new Vertex3D(0, 100, 0));
var zAxis:Line3D = new Line3D(axes, zAxisMaterial, 2, origin, new Vertex3D(0, 0, 100));
// Add lines to the Lines3D container
axes.addLine(xAxis);
axes.addLine(yAxis);
axes.addLine(zAxis);
The lines are created using the Line3D class. These lines need to be grouped together in a Lines3D object. As for the sphere, all these objects need to have an associated material : here we use the LineMaterial with different colours for each axis (red, green and blue for x, y and z respectively). Lines are defined simply by specifying two vertices. After they are created we add them to the Lines3D group.
We now have our main 3D objects. All that is left to do is add them to the scene.
// Add the sphere and the lines to the scene
scene.addChild(sphere);
scene.addChild(axes);
We now have Papervision3D initialised and the 3D objects created and added to the scene. All that’s left is to render the scene.
6. Rendering the scene
As mentioned previously, we use the Actionscript event listener to call a method at every frame of the Flash movie. In this method we simply use the BasicRendererEngine that we created earlier to update the rendered scene.
// Render the 3D scene
renderer.renderScene(scene, camera, viewport);
The renderer takes the scene (our 3D objects), the camera (the observer’s position) and the viewport (where we see the scene) and performs all the necessary calculations to convert the 3D data into 2D displayable data.
So, there we are - a simple example of using Papervision3D. As always I’d recommend playing around with the code to get a feel for what the different parameters are doing and more so to go into the Papervision3D code itself which is well documented to get a better understanding of what each class does. In the next post I’ll show how Papervision3D v2.0 encapsulates the camera, scene, viewpoint and renderer into a single simple class, but I think its useful to see each individual element on its own to start off with. Hopefully this post illustrates how simple the API is to use and provides a useful first step in Papervision3D development.
Next article:
