This article covers:

• Basics of a 3D composition in Papervision3D
• Building your first application

Basics of a 3D scene in Papervision3D

Before we’re ready to program some code for Papervision3D, we need to know a little bit more about 3D in Papervision3D. The following section is meant to give you a better understanding of the code that you will write. Each of these concepts relates directly to classes that are used by Papervision3D. All the object types that will be described are active elements in a 3D scene. Let’s have a visualized look at all these objects:

Scene

The scene is the entire composition of 3D objects in a 3D space. Think of it as your stage in Flash with three axes—x, y, and z. Each object that you want to be visible should be added to the scene. If you don’t add objects to the scene, they will not appear on your screen.

Camera

You can think of this as a real camera, which is somewhere in 3D space recording activity inside the scene. The camera defines the point of view from which you are viewing the scene. Because a camera in 3D is not a visible object, it is not part of our scene and you don’t need to add it. Like a real camera you can, for example, zoom and focus.

Cameras in 3D space can usually do more than real cameras. For example, in 3D you can, exclude objects to be rendered, when they are too close or too far away from the camera. The camera is able to ignore objects that are not in a certain, defined range. This is done for performance reasons. Objects that are too far away, or even behind the camera, don’t need to be recorded, saving a lot of calculation for objects that are in a position where the camera simply can’t see them.

Viewport

A viewport is a container sprite on your stage, and shows the output of what the camera sees. In the illustrative object overview, this has been compared with the lens of the camera. The lens is our window onto the 3D scene. We can make this window small and see just a small part of the scene, or make it big and see a lot. This works exactly as a real window in a wall—making it bigger will not affect how the world outside looks, but will have an effect on how much we can see from this world.

The following illustration contains the visualization of a relatively big viewport on the left, along with a relatively small and wide viewport on the right. The thick dark outlines represent the viewports. In the right image, you can clearly see how the window to the 3D world works and how changing its size will not stretch the view of the 3D object in the scene. It only affects how much we see of it.

3D Objects

A shape in 3D space is called a 3D object, or DisplayObject3D in Papervision3D. You can think of 3D objects as more advanced display objects just like sprites and movie clips. The difference is that a DisplayObject3D has a third axis, so we can place it anywhere in 3D space and rotate over each of the three axes.

Material

A material is the texture that is printed on an object. When an object doesn’t have a material applied, it will be invisible. There are a variety of materials available for you to use. For example, a very simple material is a color; a more advanced example of a material could be a live streaming video.

Render engine

A render engine is like a rolling camera. As long as you trigger the render engine, it will output information of the scene recorded by the camera to the viewport. When you stop triggering the render engine, your viewport will not show any new image from the scene and shows the last rendered image. Rendering is actually the most intensive task for your computer, as it needs to recalculate each object that is placed inside your scene and output this to the viewport.

Left-handed Cartesian coordinate system

Flash, as well as Papervision3D, make use of the Cartesian coordinate system. In Flash, a regular visual object can be positioned on the stage by entering an x and y value. The object will be positioned according to these values and relative to the upper left corner of the stage. A higher x value moves the object to the right, whereas a higher y value moves it downward.

The coordinate system in Papervision3D works essentially the same, except for the following two differences:

• Flash uses Cartesian coordinates on two axes, whereas Papervision3D makes use of them on three axes
• The y-axis in Flash is inversed compared to the y-axis in Papervision3D

In Papervision3D, we want to position objects not only on the x and y axes, but also on an extra axis, in order to position objects in depth. This third axis is called the z-axis.

In Flash, objects are positioned relative to the upper left corner, which is the 0, 0 coordinate. This is called the center point, or the origin. Predictably, the position of the origin in 3D space is located at 0, 0, 0. The three axes and the origin point are illustrated by the following image:

The plus and minus signs illustrate whether the coordinate values are increasing or decreasing in the direction away from the origin. Notice that the y-axis is inverted compared to 2D coordinates in Flash. When you want to position an object lower on your screen in Flash, you need to give it a higher y position. This is how 2D coordinates on a computer screen work. The above figure shows the y-axis as according to the coordinate system as it is used by Papervision3D.

Creating a basic class for Papervision3D

In the previous sections you’ve learned what a basic scene is made of, and how you can create your own classes. Now that we have gone through all this theory, it’s now time that we get our hands dirty by writing some code.

Start your favorite authoring tool. The first application we’ll build is a 3D scene containing a sphere that is rotating over its y-axis. A sphere is basically a “3D ball” and is built into Papervision3D as one of the default primitives.

The basic document class

First, have a look at the document class that defines the basic structure for the rotating sphere application.

package {
 import flash.display.Sprite;
 import org.papervision3d.cameras.Camera3D;
 import org.papervision3d.objects.primitives.Sphere;
 import org.papervision3d.render.BasicRenderEngine;
 import org.papervision3d.scenes.Scene3D;
 import org.papervision3d.view.Viewport3D;
 
 public class FirstApplication extends Sprite
 {
 private var scene:Scene3D;
 private var viewport:Viewport3D;
 private var camera:Camera3D;
 private var renderEngine:BasicRenderEngine;
 private var sphere:Sphere;
 
 public function FirstApplication()
 {
 scene = new Scene3D();
 camera = new Camera3D();
 sphere = new Sphere();
 scene.addChild(sphere);
 viewport = new Viewport3D();
 addChild(viewport);
 renderEngine = new BasicRenderEngine();
 renderEngine.renderScene(scene,camera,viewport);
 }
 }
}

Let’s have a look at this in detail. While we do that, you can create a new project in Flash, Flex Builder, or Flash Builder with a document class called FirstApplication. If you’re using Flex Builder or Flash Builder, don’t forget to configure the path to the Papervision3D source.

We know that we need to have a scene, a camera, a viewport, a 3D object with a material, and a render engine, in order to create a rendered output on the screen. Remember that the document class needs to extend Sprite. To make all these available inside the class, we need to import them first.

import flash.display.Sprite;
import org.papervision3d.cameras.Camera3D;
import org.papervision3d.objects.primitives.Sphere;
import org.papervision3d.render.BasicRenderEngine;
import org.papervision3d.scenes.Scene3D;
import org.papervision3d.view.Viewport3D;

Now that the imports are set, we define the properties of the class.

private var scene:Scene3D;
private var viewport:Viewport3D;
private var camera:Camera3D;
private var renderEngine:BasicRenderEngine;
private var sphere:Sphere;

We only define the properties and their class types here, without assigning any value. We’ll do that inside the constructor. Let’s first create the constructor.

public function FirstApplication()
{
}

We start by creating a scene inside the constructor. A scene is needed as the holder for our 3D objects. It’s very easy to create one.

scene = new Scene3D();

All you have to do is create an instance of the Scene3D class, which doesn’t take any parameters.

Next, we add a Camera3D, which is just as easy as the creation of a new Scene.

camera = new Camera3D();

A camera can take parameters when you create a new instance; however, the default values will do for now.

The scene and camera are useless as long as there are no 3D objects in the scene to film. For this example a sphere will be used, which is one of the built-in 3D objects.

sphere = new Sphere();

A camera, as well as a sphere, takes parameters when you instantiate it. However, when you do not pass any parameters, a default sphere will be created.

Now that we have created our sphere, we need to add it to the scene, otherwise it will not be seen by the camera. This works in exactly the same way as adding regular display objects to the display list in Flash, by using the addChild() method.

scene.addChild(sphere);

That looks familiar, right?

Now that we have a scene, a camera, and a sphere, we need to set up the window to the 3D scene, so we can see what is going on in there. We need to define our viewport and add it to the stage to make it visible.

viewport = new Viewport3D();
addChild(viewport);

While creating a new viewport, you can pass optional parameters to it, but the default parameters are again fine for now.

We are now just one step away from publishing our application. First we need to get our camera rolling. This is done by defining the render engine, which will render the current view of the camera to the viewport.

renderEngine = new BasicRenderEngine();
renderEngine.renderScene(scene,camera,viewport);

Now that the render engine is defined and an instruction to render the scene is added, we are ready to publish this project. This should result in the following image of triangles that together form something like a circle:

Case sensitivity
Pay attention to upper cases and lower cases in the examples. Not following these conventions might result in an error. A good example of this is the definition and instantiation of a sphere as we did in our FirstApplication.
var sphere:Sphere = new Sphere();
Here we see that we have defined a class property called sphere (lowercase) of a Sphere (uppercase) type, containing an instance of Sphere (uppercase). Giving a variable/property the same name as the defined object type will often cause problems.

The result of these few lines of code may not look very impressive yet, but in fact this is the beginning of something that will soon become exciting and could never be accomplished this easy by regular Flash use. When you have managed to compile this application that shows the triangles, you’ve made it through the hardest part of this example. Let’s continue building your first application and see how we can add the illusion of 3D to our object, which still looks very 2D.