blog.tartiflop

In this post I’d like to show how to add textures to 3D objects rather than using plain colours which provides much more realistic (or at least interesting) rendering. You’ll find that with Away3D the concepts are very similar to those used in other 3D engines – for a comparison and some texture mapping references check out my equivalent tutorial for texture mapping in Papervision3D. I’m going to discuss texture mapping rather early on in this series of articles (earlier than for the Papervision3D series) simply because you’ll find that when come on to adding lighting and shading it opens up a much richer set of possibilities. But, I’m sure you’ll find that adding textures is a very simple process – at least, I hope so!

Previous articles summary :

• First steps in Away3D : Part 1 – Getting started
  Creation of a new Away3D project within eclipse or Flex Builder 3 and a simple example of a 3D scene illustrating some basic Away3D classes.
• First steps in Away3D : Part 2 – Animation
  Adding some basic animation to the scene by modifying 3D object parameters when entering a frame.

Adding textures to objects in Away3D (as with most, if not all, 3D engines) is done by mapping coordinates on bitmap data to triangle vertices, known as texture mapping. More specifically, a technique known as uv mapping is used where u and v are the coordinates of the bitmap data which are then passed to the renderer for every triangle vertex. The following diagram tries to explain this for a pyramid. The uv coordinates are totally invented but you can see that for a single triangle the uv coordinates for every vertex are mapped onto the bitmap data (having a maximum u being equal to 1, and similarly for the maximum v) and the resulting triangle from the bitmap used to render the pyramid face.

In this example you’ll see that a number of different primitives are used (a cube, sphere, torus and cylinder). Each triangle used to produce these 3D objects has the uv coordinates for each vertex calculated. You can see in the link above for uv mapping the calculation necessary for a sphere. As you’ll see below, the image used to give texture to the sphere has been pre-calculated so that once mapped it produces a realistic image of the earth.

Ok, so on with the example code. As usual this is built on the previous example and there are not too many differences. We’ll go into more detail on what’s changed later. The code produces five primitives, all rotating about the origin and each one rotating about its individual y-axis.

package {
  import away3d.cameras.Camera3D;
  import away3d.containers.ObjectContainer3D;
  import away3d.containers.Scene3D;
  import away3d.containers.View3D;
  import away3d.core.math.Number3D;
  import away3d.core.utils.Cast;
  import away3d.materials.BitmapMaterial;
  import away3d.materials.TransformBitmapMaterial;
  import away3d.primitives.Cube;
  import away3d.primitives.Cylinder;
  import away3d.primitives.Sphere;
  import away3d.primitives.Torus;
  
  import flash.display.Bitmap;
  import flash.display.Sprite;
  import flash.display.StageAlign;
  import flash.display.StageScaleMode;
  import flash.events.Event;
  
  [SWF(backgroundColor="#000000")]
  
  public class Example003 extends Sprite {

    [Embed(source="/../assets/earth.jpg")] private var EarthImage:Class;
    private var earthBitmap:Bitmap = new EarthImage();

    [Embed(source="/../assets/away3D.png")] private var Away3DImage:Class;
    private var away3DBitmap:Bitmap = new Away3DImage();

    [Embed(source="/../assets/checker.jpg")] private var CheckerImage:Class;
    private var checkerBitmap:Bitmap = new CheckerImage();

    private static const ORBITAL_RADIUS:Number = 150;

    private var scene:Scene3D;
    private var camera:Camera3D;
    private var view:View3D;
  
    private var group:ObjectContainer3D;
    private var sphere:Sphere;
    private var cube:Cube;
    private var centerCube:Cube;
    private var cylinder:Cylinder;
    private var torus:Torus;
    
    public function Example003() {
      
      // set up the stage
      stage.align = StageAlign.TOP_LEFT;
      stage.scaleMode = StageScaleMode.NO_SCALE;

      // Add resize event listener
      stage.addEventListener(Event.RESIZE, onResize);
      
      // Initialise Papervision3D
      init3D();
      
      // Create the 3D objects
      createScene();
      
      // Initialise frame-enter 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:25, focus:30, x:-200, y:400, z:-400});
      camera.lookAt(new Number3D(0, 0, 0));
      
      // 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 {

      // Create an object container to group the objects on the scene
      group = new ObjectContainer3D();
      scene.addChild(group);
    
      // Create a new sphere object using a bitmap material representing the earth
      var earthMaterial:BitmapMaterial = new BitmapMaterial(Cast.bitmap(earthBitmap));
      sphere = new Sphere({material:earthMaterial, radius:50, segmentsW:10, segmentsH:10});
      sphere.x = ORBITAL_RADIUS;
      group.addChild(sphere);

      // Create a new cube object using a tiled bitmap material
      var tiledAway3DMaterial:TransformBitmapMaterial = new TransformBitmapMaterial(Cast.bitmap(away3DBitmap), {repeat:true, scaleX:.5, scaleY:.5});
      cube = new Cube({material:tiledAway3DMaterial, width:75, height:75, depth:75});
      cube.z = -ORBITAL_RADIUS;
      group.addChild(cube);
  
      // Create a cylinder mapping the earth data again
      cylinder = new Cylinder({material:earthMaterial, radius:25, height:100, segmentsW:16});
      cylinder.x = -ORBITAL_RADIUS;
      group.addChild(cylinder);
  
      // Create a torus object and use a checkered bitmap material
      var checkerBitmapMaterial:BitmapMaterial = new BitmapMaterial(Cast.bitmap(checkerBitmap));
      torus = new Torus({material:checkerBitmapMaterial, radius:40, tube:10, segmentsT:8, segmentsR:16});
      torus.z = ORBITAL_RADIUS;
      group.addChild(torus);
  
      // Create a new cube object using a smoothed, precise bitmap material
      var away3DMaterial:BitmapMaterial = new BitmapMaterial(Cast.bitmap(away3DBitmap), {smooth:true, precision:2});
      centerCube = new Cube({material:away3DMaterial, width:75, height:75, depth:75});
      group.addChild(centerCube);
    }
    
    private function loop(event:Event):void {
      
      // rotate the group of objects
      group.yaw(2);
    
      // rotate the objects
      sphere.yaw(-4);
      cube.yaw(-4);
      cylinder.yaw(-4);
      torus.yaw(-4);

      // Render the 3D scene
      view.render();
    }

    private function onResize(event:Event):void {
      view.x = stage.stageWidth / 2;
      view.y = stage.stageHeight / 2;
    }
  }
}

Copy the code above and compile it within Flex Builder 3 or Eclipse. The images I used are shown below – click on them and save them if you want to use the same ones.

Click on the image below to see the resulting flash movie. The images are embedded in the movie making it larger than the previous examples so it could take a couple of seconds to load.

The code follows the same style as the previous examples: initialisation of 3D elements, creation of scene and rendering loop. As usual I’ll just concentrate on what’s new.

Not really related to Away3D but important for projects (in Flex) using images is the ability to embed images in the compiled movie. As you can see the images are embedded in the class definition.

    [Embed(source="/../assets/earth.jpg")] private var EarthImage:Class;
    private var earthBitmap:Bitmap = new EarthImage();

    [Embed(source="/../assets/away3D.png")] private var Away3DImage:Class;
    private var away3DBitmap:Bitmap = new Away3DImage();

    [Embed(source="/../assets/checker.jpg")] private var CheckerImage:Class;
    private var checkerBitmap:Bitmap = new CheckerImage();

Using the Embed meta-tag we can add binary object to the compiled movie. These can then be converted into usable graphic elements, as shown above for a Bitmap. As with the same example in Papervision3D, I’m not going to go into detail of embedding objects here, rather I’ll leave you with these couple of references that are very useful. The first one is at at assertTrue and the second is from the Flex livedocs.

You’ll note that the source is “../assets”. This is because I have my assets folder at the same level as the src folder – when the Actionscript is compiled, the root folder is the src folder. If you want to compile the above source then simply create an assets folder and put the image files in it.

Now that we have embedded the images and obtained bitmap data we can start to create texture mapped materials. This is done in createScene where some different methods of creating different textures is examined.

    private function createScene():void {

      // Create an object container to group the objects on the scene
      group = new ObjectContainer3D();
      scene.addChild(group);
    
      // Create a new sphere object using a bitmap material representing the earth
      var earthMaterial:BitmapMaterial = new BitmapMaterial(Cast.bitmap(earthBitmap));
      sphere = new Sphere({material:earthMaterial, radius:50, segmentsW:10, segmentsH:10});
      sphere.x = ORBITAL_RADIUS;
      group.addChild(sphere);

      // Create a new cube object using a tiled bitmap material
      var tiledAway3DMaterial:TransformBitmapMaterial = new TransformBitmapMaterial(Cast.bitmap(away3DBitmap), {repeat:true, scaleX:.5, scaleY:.5});
      cube = new Cube({material:tiledAway3DMaterial, width:75, height:75, depth:75});
      cube.z = -ORBITAL_RADIUS;
      group.addChild(cube);
  
      // Create a cylinder mapping the earth data again
      cylinder = new Cylinder({material:earthMaterial, radius:25, height:100, segmentsW:16});
      cylinder.x = -ORBITAL_RADIUS;
      group.addChild(cylinder);
  
      // Create a torus object and use a checkered bitmap material
      var checkerBitmapMaterial:BitmapMaterial = new BitmapMaterial(Cast.bitmap(checkerBitmap));
      torus = new Torus({material:checkerBitmapMaterial, radius:40, tube:10, segmentsT:8, segmentsR:16});
      torus.z = ORBITAL_RADIUS;
      group.addChild(torus);
  
      // Create a new cube object using a smoothed, precise bitmap material
      var away3DMaterial:BitmapMaterial = new BitmapMaterial(Cast.bitmap(away3DBitmap), {smooth:true, precision:2});
      centerCube = new Cube({material:away3DMaterial, width:75, height:75, depth:75});
      group.addChild(centerCube);
    }

As you can see, the creation of the 3D objects is very simple: just create a new primitive, pass it some initialisation arguments and create a new material for it. Of course, compared the previous example, the materials are now texture mapped. Two different materials are used in this example: the BitmapMaterial for simple texture mapping and TransformBitmapMaterial which gives us more options.

Starting with the Sphere, we use a simple BitmapMaterial and pass it bitmap data. The class Cast in Away3D provides useful transformation routines – in this case to return the BitmapData of the Bitmap object.

      var earthMaterial:BitmapMaterial = new BitmapMaterial(Cast.bitmap(earthBitmap));

The Sphere is then created using this material. All uv mapping is handled by the Sphere itself to render the image over the sphere triangles.

The next object is a Cube. Here I want to illustrate how to tile images over an object. Tiling allows us to repeat an image over a surface, for example imagine a scene with a grassy plain with the same grass image repeated a number of times. This allows us to keep the image size reasonable and have a texture mapped object that isn’t too pixelated.

      var tiledAway3DMaterial:TransformBitmapMaterial = new TransformBitmapMaterial(Cast.bitmap(away3DBitmap), {repeat:true, scaleX:.5, scaleY:.5});

To tile bitmap we need to use the TransformBitmapMaterial class. With this we can manipulate the image data, for example, here we scale it to half its size and indicate that it should be repeated. Scaling here implies that the maximum u and v coordinates of the texture become 0.5 rather than 1 hence we should see a two-by-two image drawn on each face of the cube. If the repeat:true initialisation parameter is skipped then the image is drawn only once… try recompiling without this to see the result.

The Cylinder and Torus objects use simple BitmapMaterials again just to show how the bitmaps are mapped to these primitives.

Finally the cube in the center shows an example of a texture map using a smoothed image and uses more precise perspective calculations when rendered. This link for texture mapping shows what happens for affine texture mapping: Away3D (as for Papervision3D) tries to optimise the calculation for rendering textures and this can result in a distorted image. You can see this in the above example for the tiled cube where the black lines appear to be wavy. The distortion can, however, be corrected but of course this produces a more cpu-intensive calculation.

      var away3DMaterial:BitmapMaterial = new BitmapMaterial(Cast.bitmap(away3DBitmap), {smooth:true, precision:2});

For the central cube we set smooth:true to have a less pixelated texture and we set precision:2 to indicate that the texture should be correctly rendered to within 2 pixels. A value of 0 turns off the precision calculation.

As an alternative to using more precise rendering of a texture we can also increase the number of triangles used so that the distortion becomes less evident. You can check out this example for Papervision3D that illustrates the result. Of course, increasing the number of triangles increases the render time but within limits it can produce a visually acceptable rendering quicker than a single precise texture mapping.

So that’s it for texture mapping at its simplest! As you can see there’s nothing too complicated in adding bitmaps to 3D objects but bear in mind that it is obviously more cpu-intensive that simple coloured objects. As with the previous articles I’d recommend having a look at the Away3D source – you’ll see that there are a lot of different types of materials in the away3D.materials package including the BitmapFileMaterial which loads an image from a URL, rather than embedding it in the movie. Anyway, hope this has been of use. As always, questions and comments are welcome!

Next article:

• First steps in Away3D : Part 4 – Scene interaction
  Listen to mouse events to interact with the scene and with individual rendered objects.