blog.tartiflop

In the same spirit as the First steps in Papervision3D series of articles, I’m documenting my own progress in learning about this 3D engine for Flash. I hope as well that this provides a useful tutorial for others getting started with Away3D. I guess what I’m trying to say is that this is by no means a definitive guide to Away3D! This is my first day as well so if you find mistakes or have suggestions then please let me know!

Before starting I’d like to post a couple of links to a series of articles that I found very interesting and useful for beginners learning the basics of 3D programming. The first one one, Flash 3D Basics, provides a very good overview of the important elements for any 3D development. The second one is aimed directly at Away3D, but is relevant also to Papervision3D, and discusses the two main classes for any Away3D flash movie: The View and The Scene. You’ll see both of these being used below. Anyway, I’d really recommend taking a look at them.

For this post I’m really starting at the very beginning. My aim is simply to draw 3D shapes on the screen, exactly as I did for First steps in Papervision3D : Part 1. For this I’m assuming that you are using Flex Builder 3, or the Flex Builder 3 plugin for eclipse, as I am. I’m also assuming that you have Away3D built and ready to link to. My previous article on downloading and installing Away3D in eclipse might help if this isn’t the case.

For those of you who are new to using Flex Builder 3, we need to first of all create a new project and then set it’s build path to that of the Away3D source.

In eclipse (or Flex Builder 3), from the File menu, select New and then ActionScript project. You’ll see a New ActionScript Project window appear.

Type in a project name (for example I named it Tartiflop) and click on Finish. We then need to configure the project to use either the Away3D.swf library that I showed how to create before, or we link directly to the Away3D source. I prefer the second method simply because it gives me a more convenient access to the library source by navigating within eclipse. To do this, select the new project and right-click. Select Properties from the drop-down menu. Select the ActionScript Build Path on the left.

Select the Library path tab and click on Add Project….

Select the Away3D Flex Library project and click on OK. You’ll see that the library has now been added into the list of build path libraries.

We’re now ready to start creating our first Away3D flash movie! You’ll notice that the new project wizard of eclipse has automatically created an ActionScript class called Tartiflop.as. We don’t need this so you can delete it. For this post the class is called Example001.as so you’ll need to create a new ActionScript. Right-click on src in the Tartiflop project in the Flex Navigator tree. Select New and then ActionScript Class. Name the new class Example001 and click Finish.

The following code draws a sphere and three lines showing the x, y and z axes. Cut and paste the code below (we’ll go into the details of how it works later), save and it should hopefully compile without any errors!

package {
  import away3d.cameras.Camera3D;
  import away3d.containers.Scene3D;
  import away3d.containers.View3D;
  import away3d.core.base.Vertex;
  import away3d.materials.WireColorMaterial;
  import away3d.materials.WireframeMaterial;
  import away3d.primitives.LineSegment;
  import away3d.primitives.Sphere;
 
  import flash.display.Sprite;
  import flash.display.StageAlign;
  import flash.display.StageScaleMode;
  import flash.events.Event;
 
  [SWF(backgroundColor="#000000")]
 
  public class Example001 extends Sprite {

    private var scene:Scene3D;
    private var camera:Camera3D;
    private var view:View3D;
 
 
    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 a new scene where all the 3D object will be rendered
      scene = new Scene3D();
     
      // Create a new camera, passing some initialisation parameters
      camera = new Camera3D({zoom:20, focus:30, x:-100, y:-100, z:-500});
     
      // Create a new view that encapsulates the scene and the camera
      view = new View3D({scene:scene, camera:camera});

      // center the viewport to the middle of the stage
      view.x = stage.stageWidth / 2;
      view.y = stage.stageHeight / 2;
         addChild(view);
    }

    private function createScene():void {

      // First object : a sphere
     
      // Create a new material for the sphere : simple white wireframe
      var sphereMaterial:WireColorMaterial = new WireColorMaterial(0x000000, {wirecolor:0xFFFFFF});

      // Create a new sphere object using wireframe material, radius 50 with
      //   10 horizontal and vertical segments
      var sphere:Sphere = new Sphere({material:sphereMaterial, radius:50, segmentsW:10, segmentsH:10});

      // Position the sphere (default = [0, 0, 0])
      sphere.x = -100;
      scene.addChild(sphere);
 
      // Second object : x-, y- and z-axis
 
      // Create a origin vertex
      var origin:Vertex = new Vertex(0, 0, 0);

      // Create the red-coloured x-axis with a width of 2
      var xAxis:LineSegment = new LineSegment({material:new WireframeMaterial(0xFF0000, {width:2})});
      xAxis.start = origin;
      xAxis.end = new Vertex(100, 0, 0);
      scene.addChild(xAxis);
   
      // Create the green-coloured y-axis with a width of 2
      var yAxis:LineSegment = new LineSegment({material:new WireframeMaterial(0x00FF00, {width:2})});
      yAxis.start = origin;
      yAxis.end = new Vertex(0, 100, 0);
      scene.addChild(yAxis);
   
      // Create the blue-coloured z-axis with a width of 2
      var zAxis:LineSegment = new LineSegment({material:new WireframeMaterial(0x0000FF, {width:2})});
      zAxis.start = origin;
      zAxis.end = new Vertex(0, 0, 100);
      scene.addChild(zAxis);
 
    }
   
    private function loop(event:Event):void {
      // Render the 3D scene
      view.render();
    }

  }
}

To see the final result, right-click again on the Tartiflop project and select Run As and Flex Application. What you should see is the following: click on the image below to see the real flash movie (its not much more interesting than the image though!).

Let’s go into more detail with the code. I’m taking a look at this with the point of view of someone who has been using Papervision3D and its interesting to look at the similarities and differences between the two libraries. If you compare the code to the equivalent in Papervision3D, you can see that the codes resemble a lot.

The constructor of Example001 is identical to that of the equivalent example in Paperivision3D: the stage parameters are set so that the scene is scaled correctly, the 3D elements are initialised, the scene is created and then we add a frame-enter event listener.

Example001 inherits from the Sprite class as is indeed possible with Papervision3D. Papervision3D however provides a BasicView class where the scene, camera, view and renderer are all encapsulated (see part 2 of the Papervision3D series for example). Also the stage scaling is automatically encapsulated in the BasicView class.

    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);   
    }

However, as we can see, its not very complicated to initialise all the 3D elements individually - as we do in the init3D() function.

    private function init3D():void {

      // Create a new scene where all the 3D object will be rendered
      scene = new Scene3D();
     
      // Create a new camera, passing some initialisation parameters
      camera = new Camera3D({zoom:20, focus:30, x:-100, y:-100, z:-500});
     
      // Create a new view that encapsulates the scene and the camera
      view = new View3D({scene:scene, camera:camera});

      // center the viewport to the middle of the stage
      view.x = stage.stageWidth / 2;
      view.y = stage.stageHeight / 2;
         addChild(view);
    }

We first of all create a Scene3D object which is used later to contain all of our rendered 3D elements. Secondly we create a Camera3D which sets up all our viewing parameters and finally we create a View3D object which provides us with our window through which we observe the scene.

Interesting to note is the way we can create Away3D objects. Unlike Papervsion3D which has well defined constructors taking specific arguments, Away3D allows us to pass an array of initialisation parameters. One good point is that this makes the code more concise, however, personally, I feel that it is less intuitive: with Papervision3D I felt I could determine relatively quickly what was needed to construct an object but here you need to search more within a class to obtain useful information. Having said that I have to admit that I haven’t yet looked at the Away3D documentation! I’m someone who is too excited to get his hands dirty before reading the manual!

With respect to the camera, unlike Papervision3D it is not possible to modify the field of view (or fov) directly and instead we need to manipulate the zoom and focus of the camera (see my post on the relationship between all three and also this really good article explaining the Away3D camera). Having an OpenGL background I find the field of view more intuitive however this is just a personal opinion.

After the 3D base elements have been created we can move on to creating the scene. This, as is fairly obvious, is done in the createScene() function.

    private function createScene():void {

      // First object : a sphere
     
      // Create a new material for the sphere : simple white wireframe
      var sphereMaterial:WireColorMaterial = new WireColorMaterial(0x000000, {wirecolor:0xFFFFFF});

      // Create a new sphere object using wireframe material, radius 50 with
      //   10 horizontal and vertical segments
      var sphere:Sphere = new Sphere({material:sphereMaterial, radius:50, segmentsW:10, segmentsH:10});

      // Position the sphere (default = [0, 0, 0])
      sphere.x = -100;
      scene.addChild(sphere);
 
      // Second object : x-, y- and z-axis
 
      // Create a origin vertex
      var origin:Vertex = new Vertex(0, 0, 0);

      // Create the red-coloured x-axis with a width of 2
      var xAxis:LineSegment = new LineSegment({material:new WireframeMaterial(0xFF0000, {width:2})});
      xAxis.start = origin;
      xAxis.end = new Vertex(100, 0, 0);
      scene.addChild(xAxis);
   
      // Create the green-coloured y-axis with a width of 2
      var yAxis:LineSegment = new LineSegment({material:new WireframeMaterial(0x00FF00, {width:2})});
      yAxis.start = origin;
      yAxis.end = new Vertex(0, 100, 0);
      scene.addChild(yAxis);
   
      // Create the blue-coloured z-axis with a width of 2
      var zAxis:LineSegment = new LineSegment({material:new WireframeMaterial(0x0000FF, {width:2})});
      zAxis.start = origin;
      zAxis.end = new Vertex(0, 0, 100);
      scene.addChild(zAxis);
 
    }

The scene is very simple: no lighting and just two stationary types of objects. As with Papervision3D, most objects provide only the vertices of a given shape: the rendering (what we see on the screen) is done through the material.

In this example we use two types of materials for two different types of shapes. This is different to Papervision3D where any material seems to be usable with any object. Here, the two shapes belong to two different families: an AbstractPrimitive and an AbstractWirePrimitive. Each one uses a material also belonging to a different family: an ITriangleMaterial and an ISegmentMaterial respectively. If we give the wrong type of material to a particular primitive then it is not rendered.

The two shapes used are a Sphere (an AbstractPrimitive) and a LineSegment (an AbstractWirePrimitive). We therefore give them two different types of materials. In this example I’ve used a WireColorMaterial and a WireframeMaterial respectively. The WireColorMaterial is created with a face color (black in this case) and a wire color is passed in the list of initialisation arguments (being white). The wireframe material is simply white but I’ve passed a width of 2 in the initialisation parameters.

The sphere is created first, taking a list of initialisation parameters including the sphere material. It should be noted that these parameters can be set afterwards, not necessarily in the constructor. I then create 3 lines for each axis, each one with a different color wireframe material. The lines are then given two vertices to define their start and end positions. Each 3D object is added to the scene so that they are rendered.

As a first impression of Away3D, I actually find that the construction of these primitive objects is more concise than for Papervision3D. Looking through the source directory of Away3D I also get the impression that there is more choice of primitives compared to Papervision3D.

Finally for this example, a small function is used to render the scene. We added in the constructor a frame-enter event listener called loop.

    private function loop(event:Event):void {
      // Render the 3D scene
      view.render();
    }

Very simply, we call the function render of view to redraw the scene. This is another difference to Papervision3D: Papervision3D has a specific Renderer class used to draw the scene.

And that’s it! A very simple example of rendering a 3D scene in Away3D. Compared to Papervision3D, for something this simple, there really isn’t a huge difference. Overall I feel that Away3D is more concise but maybe loses degree of simplicity using the parameters array rather than having explicit constructor arguments… but that’s just a personal point of view though.

One surprise is the difference in file sizes between Papervision3D and Away3D. In Away3D the flash animation come to 136KB whereas in Papervision3D its at only 82KB. Okay, so neither are huge and maybe Away3D is a bigger library… but I’m interested to see how this compares for more complex examples.

Anyway, that’s it for this example. For me too its a first step - I just wanted to see what the Away3D library was like and how easy it was to convert from a Papervision3D source to an Away3D one. I hope to continue along the same theme to produce more complex examples over the coming weeks. As always, comments and suggestions as are always welcome so please don’t hesitate!

Next article:

• First steps in Away3D : Part 2 - animation
  Adding some basic animation to the scene by modifying 3D object parameters when entering a frame.