Papervision3D Basics

Papervision 3D is a powerful open source 3D library for Flash. It allows us to create animations and interactive applications in 3D. The current release of Papervision 3D supports Actionscript 3 and can be downloaded here. This post runs through some of the basics of setting up an Actionscript 3 papervision 3D project.

Get Adobe Flash player

In this example we will create a rotating 3D cube with a graphic applied to two surfaces. All of the working files for this example can be downloaded here. We start with a new blank .fla file in Flash CS4 (Flash CS3 will also be fine) and link it to an Actionscript class file called Main.as. Below is the complete code for Main.as. Following we will look at each part in more detail.

package
{
	import flash.display.Sprite; 
	import flash.events.*;
 
	import org.papervision3d.view.Viewport3D;
	import org.papervision3d.scenes.Scene3D;
	import org.papervision3d.cameras.Camera3D;
	import org.papervision3d.materials.ColorMaterial;
	import org.papervision3d.render.BasicRenderEngine;
 
	import org.papervision3d.materials.WireframeMaterial;
	import org.papervision3d.materials.MovieAssetMaterial;  
 
	import org.papervision3d.materials.utils.*;
	import org.papervision3d.objects.primitives.Cube;
 
	public class Main extends Sprite
	{
		private var viewport: Viewport3D;
		private var scene: Scene3D;
		private var camera: Camera3D;
		private var renderer: BasicRenderEngine;
 
		private var cube:Cube;
 
		public function Main():void
		{
			//viewport = new Viewport3D(w, h, scaleToStage, interactive);
			this.viewport = new Viewport3D(400, 400, false, true);
			this.addChild(viewport);
 
			this.scene = new Scene3D();
			this.camera = new Camera3D();
			this.renderer = new BasicRenderEngine();
 
			var wireframeMaterial:WireframeMaterial = new WireframeMaterial(0x333333);
			wireframeMaterial.doubleSided = true;
 
			var movieAssetMaterial:MovieAssetMaterial = new MovieAssetMaterial("Pic", true);
			movieAssetMaterial.doubleSided = true;
 
			var materialsList:MaterialsList = new MaterialsList();
			materialsList.addMaterial( wireframeMaterial, "front" );
			materialsList.addMaterial( wireframeMaterial, "back" );
			materialsList.addMaterial( movieAssetMaterial, "left" );
			materialsList.addMaterial( movieAssetMaterial, "right" );
			materialsList.addMaterial( wireframeMaterial, "top" );
			materialsList.addMaterial( wireframeMaterial, "bottom" );
 
			this.cube = new Cube(materialsList, 600, 600, 600, 3, 3, 3); 
			this.scene.addChild(cube);
 
			this.addEventListener(Event.ENTER_FRAME, this.onEnterFrame);
		}
 
		private function onEnterFrame(e:Event):void
		{
			this.cube.rotationX -= 2;
			this.cube.rotationY -= 2;
			this.cube.rotationZ -= 2;
 
			this.renderer.renderScene(scene, camera, viewport);
		}
 
	}
 
}


Firstly we need to import all the various classes and packages required for the project. These will be explained in more detail below. Please note that we need to have downloaded the papervision library (supplied with the source files) and included it in the source folder for our project.

package
{
	import flash.display.Sprite; 
	import flash.events.*;
 
	import org.papervision3d.view.Viewport3D;
	import org.papervision3d.scenes.Scene3D;
	import org.papervision3d.cameras.Camera3D;
	import org.papervision3d.materials.ColorMaterial;
	import org.papervision3d.render.BasicRenderEngine;
 
	import org.papervision3d.materials.WireframeMaterial;
	import org.papervision3d.materials.MovieAssetMaterial;  
 
	import org.papervision3d.materials.utils.*;
	import org.papervision3d.objects.primitives.Cube;

Next we begin to define our class. We start out by creating several instance variables which will be used throughout the class. Each will be explained as they are initialised throughout the project.

	public class Main extends Sprite
	{
		private var viewport: Viewport3D;
		private var scene: Scene3D;
		private var camera: Camera3D;
		private var renderer: BasicRenderEngine;
 
		private var cube:Cube;


Here we create our constructor method which will be called by the Flash player as soon as the project is initialised. The first task is to initialise our viewport instance variable. The ViewPort3D object is the root element for our 3D scene; added directly to the Flash stage. The first two arguments define the width and height of the container, the third argument tells the viewport wether or not it should scale to the size of the stage and the fourth argument tells the ViewPort if the container should be interactive or not. If we allow the ViewPort to be interactive we can use mouse interactions and events with the different components of our 3D scene.

		public function Main():void
		{
			//viewport = new Viewport3D(w, h, scaleToStage, interactive);
			this.viewport = new Viewport3D(400, 400, false, true);
			this.addChild(viewport);

Now we need to instantiate our other core Papervision3D objects. Scene3D forms a secondary container which holds all of our 3D elements. Camera3D defines the angle, distance and perspective of our 3D scene. BasicRenderEngine draws our 3D scene.

			this.scene = new Scene3D();
			this.camera = new Camera3D();
			this.renderer = new BasicRenderEngine();

Next we will create two surface materials for our 3D cube. One is a simple wireframe plane while the second is a MovieClip from our library. When we define our WireframeMaterial object we supply one argument; it’s colour. Here we have used 0x333333 which is a neutral grey colour. Next when creating our MovieAssetMaterial object we supply two arguments. The first “Pic” is the name of a Movie Clip in our library which contains a vector drawing. The drawing is a regal clip art from Adobe Illustrator. The second argument “true” tells Papervision to use transparency with our MovieClip. For both surface materials we specify that they should be double sided.

			var wireframeMaterial:WireframeMaterial = new WireframeMaterial(0x333333);
			wireframeMaterial.doubleSided = true;
 
			var movieAssetMaterial:MovieAssetMaterial = new MovieAssetMaterial("Pic", true);
			movieAssetMaterial.doubleSided = true;


In order to apply these surfaces to our cube we need to create a MaterialsList and specify which surfaces should match which sides of the cube. ie: front, back etc.

			var materialsList:MaterialsList = new MaterialsList();
			materialsList.addMaterial( wireframeMaterial, "front" );
			materialsList.addMaterial( wireframeMaterial, "back" );
			materialsList.addMaterial( movieAssetMaterial, "left" );
			materialsList.addMaterial( movieAssetMaterial, "right" );
			materialsList.addMaterial( wireframeMaterial, "top" );
			materialsList.addMaterial( wireframeMaterial, "bottom" );

With our surfaces areas defined we now need to create our Cube object and add it to our 3D scene. The first argument tells our cube to use the MaterialsList we created in the previous step. The other arguments specify the width,height and depth of our cube.

			this.cube = new Cube(materialsList, 600, 600, 600, 3, 3, 3); 
			this.scene.addChild(cube);

The previous code, on its own, will render our 3D cube to the stage. However we want to rotate our cube over time. In order to do this we will add an ENTER_FRAME event listener to our project and manipulate the cubes properties over time. This finalises our constructor.

			this.addEventListener(Event.ENTER_FRAME, this.onEnterFrame);
		}


Finally we build our onEnterFrame function which will be called continuously by Flash in a loop. Here we change the cubes rotation on all three axis and apply the changes to our 3D scene using our BasicRenderEngine object. The final 3D scene can be seen below.

		private function onEnterFrame(e:Event):void
		{
			this.cube.rotationX -= 2;
			this.cube.rotationY -= 2;
			this.cube.rotationZ -= 2;
 
			this.renderer.renderScene(scene, camera, viewport);
		}
 
	}
 
}

Get Adobe Flash player


Leave a Reply

Your email address will not be published. Required fields are marked *