Monday, December 15th, 2008
Discover General Elektriks!
Monday, December 15th, 2008
Having looked at the different types of texture mapped and coloured materials with different lighting aspects, I want to discuss briefly a couple of more interactive and dynamic materials. These don’t necessarily add realism to a scene but can be very useful for 3D website development to provide a richer user experience. To do this we use the MovieMaterial and VideoMaterial. If you’re interested here is an equivalent tutorial for movie materials in Papervision3D.
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. - First steps in Away3D : Part 3 - Texture mapping
Create materials using bitmap data with the aim of having more detailed or realistic objects. - First steps in Away3D : Part 4 - Scene interaction
Listen to mouse events to interact with the scene and with individual rendered objects. - First steps in Away3D : Part 5 - Lighting and shading
A light source is added to the scene and the materials are changed to illustrate how Away3D renders objects with different shading characteristics. - First steps in Away3D : Part 6 - Normal mapping and environment mapping
Additional realism is added to the scene by applying normal maps (to give a higher level of shading characteristics) and environment maps (as an alternative to simple lighting models).
This article will be looking at two materials available in Away3D: the MovieMaterial for rendering Flash movies onto a surface and VideoMaterial to show Flash video streams on an object (using .flv files). As well as being able to show another Flash animation, mouse events are mapped to the MovieMaterial allowing it to be interactive, even in a 3D environment.
This article is taking advantage of the very latest types of materials available with Away3D: to be able to compile the examples and develop your own you may need to use the repository (SVN) version of Away3D. If you don’t have away3d.materials.VideoMaterial available in your Away3D source then this is the case. Here’s an article on downloading and installing Away3D from SNV if you need help.
To illustrate these different materials we’re going to create three simple planes rotated and translated to form three sides of a cube. Two of these will be rendered using MovieMaterials and the third with a Flash video stream using a VideoMaterial. One of the MovieMaterial planes will be interactive and I’ll show how a external Flash movie can be embedded in the compiled animation.
So let’s look at the code. For this example we will actually have three ActionScript classes: the main Away3D class and two additional classes to be used for the individual MovieMaterial cube faces. The latter two will be shown at the end of the article just for completeness.
package { import away3d.cameras.HoverCamera3D; import away3d.containers.ObjectContainer3D; import away3d.containers.Scene3D; import away3d.containers.View3D; import away3d.core.base.Object3D; import away3d.core.render.Renderer; import away3d.events.MouseEvent3D; import away3d.materials.MovieMaterial; import away3d.materials.VideoMaterial; import away3d.primitives.Plane; import caurina.transitions.Tweener; import flash.display.Sprite; import flash.display.StageAlign; import flash.display.StageScaleMode; import flash.events.Event; import flash.filters.BlurFilter; [SWF(backgroundColor="#222222")] public class Example007 extends Sprite { private var videoURL:String = "http://www.tartiflop.com/away3d/FirstSteps/AmIWrong.flv"; [Embed(source="/../assets/DrawTool.swf")] private var DrawToolEmbedded:Class; private var scene:Scene3D; private var camera:HoverCamera3D; private var view:View3D; private var planeGroup:ObjectContainer3D; private var doRotation:Boolean = true; public function Example007() { // set up the stage stage.align = StageAlign.TOP_LEFT; stage.scaleMode = StageScaleMode.NO_SCALE; // Add resize event listener stage.addEventListener(Event.RESIZE, onResize); // Initialise Away3D init3D(); // Create the 3D objects createScene(); // Initialise frame-enter loop this.addEventListener(Event.ENTER_FRAME, loop); } /** * Initialise all 3D components. */ 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 HoverCamera3D({zoom:25, focus:30, distance:200}); camera.yfactor = 1; // Create a new view that encapsulates the scene and the camera view = new View3D({scene:scene, camera:camera}); // center the view to the middle of the stage view.x = stage.stageWidth / 2; view.y = stage.stageHeight / 2; // ensure that the z-order is calculated correctly view.renderer = Renderer.CORRECT_Z_ORDER; addChild(view); } /** * Create the objects of the scene */ private function createScene():void { // Video material using a flash streaming video URL var frontMaterial:VideoMaterial = new VideoMaterial({file:videoURL}); // Movie material from an embedded flash animation var topMaterial:MovieMaterial = new MovieMaterial(new DrawToolEmbedded(), {lockW:320, lockH:240, interactive:true, smooth:true, precision:5}); // Movie material from another class var leftMaterial:MovieMaterial = new MovieMaterial(new Pong(), {smooth:true, precision:5}); // Create three planes with different material, blurred by default // and position them them to create tree sides of a cube var topPlane:Plane = new Plane({material:topMaterial, width:100, height:100, segmentsW:2, segmentsH:2, ownCanvas:true}); topPlane.rotationY = -180; topPlane.y = 50; topPlane.filters.push(new BlurFilter(8, 8)); var leftPlane:Plane = new Plane({material:leftMaterial, width:100, height:100, segmentsW:2, segmentsH:2, ownCanvas:true}); leftPlane.rotationZ = -90; leftPlane.rotationY = -90; leftPlane.x = 50; leftPlane.filters.push(new BlurFilter(8, 8)); var frontPlane:Plane = new Plane({material:frontMaterial, width:100, height:100, segmentsW:2, segmentsH:2, ownCanvas:true}); frontPlane.rotationX = -90; frontPlane.rotationZ = 180; frontPlane.z = 50; frontPlane.filters.push(new BlurFilter(8, 8)); // Create an object container to group the sides of the cube planeGroup = new ObjectContainer3D(); scene.addChild(planeGroup); planeGroup.addChild(topPlane); planeGroup.addChild(leftPlane); planeGroup.addChild(frontPlane); // Add mouse listeners to each plane for mouse down, over and out events topPlane.addOnMouseDown(onMouseClickOnObject); leftPlane.addOnMouseDown(onMouseClickOnObject); frontPlane.addOnMouseDown(onMouseClickOnObject); topPlane.addOnMouseOver(onMouseOverObject); leftPlane.addOnMouseOver(onMouseOverObject); frontPlane.addOnMouseOver(onMouseOverObject); topPlane.addOnMouseOut(onMouseLeavesObject); leftPlane.addOnMouseOut(onMouseLeavesObject); frontPlane.addOnMouseOut(onMouseLeavesObject); } /** * Frame-enter event handler */ private function loop(event:Event):void { // update camera position updateCamera(); camera.hover(); // Render the 3D scene view.render(); } /** * Update the camera position from mouse positions */ private function updateCamera():void { if (doRotation) { camera.targetpanangle = (stage.stageWidth - stage.mouseX) / stage.stageWidth * 90; camera.targettiltangle = (stage.stageHeight - stage.mouseY) / stage.stageHeight * 70 } } /** * Event listener for mouse click on plane. Makes the camera look * directly at the plane and move closer to it. */ private function onMouseClickOnObject(event:MouseEvent3D):void { var object:Object3D = event.object; doRotation = false; // Calculate angles necessary for camera var theta:Number = Math.atan2(object.x, object.z); var len:Number = Math.sqrt(object.x*object.x + object.z*object.z); var phi:Number = Math.atan2(object.y, len); // rotate camera position camera.targetpanangle = theta * 180 / Math.PI; camera.targettiltangle = phi * 180 / Math.PI; // move camera towards plane Tweener.addTween(camera, {distance:150, time:0.5, transition:"easeOutSine"}); } /** * Event listener for mouse over plane. Removes the blur filter. */ private function onMouseOverObject(event:MouseEvent3D):void { var object:Object3D = event.object; object.filters = new Array(); } /** * Event listener for mouse out of plane. Adds blur filter and moves * camera away from plane if it isn't already. */ private function onMouseLeavesObject(event:MouseEvent3D):void { var object:Object3D = event.object; object.filters.push(new BlurFilter(8, 8)); Tweener.addTween(camera, {distance:200, time:0.5, transition:"easeOutSine"}); doRotation = true; } /** * Resize the scene when the stage resizes */ private function onResize(event:Event):void { view.x = stage.stageWidth / 2; view.y = stage.stageHeight / 2; } } }
This (along with the other ActionScript classes shown below) produces a cube that rotates as the mouse moves. One face shows a Flash video stream (Etienne de Crécy : Am I Wrong), another is an interactive drawable surface and the third a simple Pong simulation. Each face is blurred until the mouse enters it. Clicking on a face moves the camera directly above it and moves towards it. Moving the mouse outside of a face blurs the face again and the cube regains its original size. You can see the finished result by clicking on the image below.
As usual, the code for Example007 follows the same style as shown in the previous articles of this series. Lets look at what has changed.
The constructor and initialisation of Away3D elements is virtually identical to before so not worth looking at here. Lets move onto the scene creation (createScene())and see how we use these new materials. To start off with the materials are created.
// Video material using a flash streaming video URL var frontMaterial:VideoMaterial = new VideoMaterial({file:videoURL}); // Movie material from an embedded flash animation var topMaterial:MovieMaterial = new MovieMaterial(new DrawToolEmbedded(), {lockW:320, lockH:240, interactive:true, smooth:true, precision:5}); // Movie material from another class var leftMaterial:MovieMaterial = new MovieMaterial(new Pong(), {smooth:true, precision:5});
As you can see, the VideoMaterial is very easy to create - simply pass the URL of the Flash video stream in the initialisation parameters and its ready! Compared to Papervision3D this is much easier (in fact, the internet connection and creation of the video stream is encapsulated in the VideoMaterial class). If you want the video to loop you can set the loop parameter to true, also sent in the initialisation parameters array. If you want to pause/play the video then you can access the netStream object directly from the material to control the playback.
The MovieMaterial is similarly easy to create. The constructor takes a Sprite object which will be mapped to the surface. I show two cases here: one where the object is an instantiation of a class in the same project, another where we embed a previously compiled Flash movie. Other than the smooth and precision parameters as we discussed in the texture mapping tutorial, we can indicate that the material should be interactive by specifying the interactive parameter to be true. Similarly we can force a size of the Sprite by giving the lockW and lockH parameters being the width and height - note that these have no relation to the dimensions of the object to which the material is mapped.
These materials are used just like all the other materials presented in this series of articles: simply create an object and pass the material to it.
// Create three planes with different material, blurred by default // and position them them to create tree sides of a cube var topPlane:Plane = new Plane({material:topMaterial, width:100, height:100, segmentsW:2, segmentsH:2, ownCanvas:true}); topPlane.rotationY = -180; topPlane.y = 50; topPlane.filters.push(new BlurFilter(8, 8)); var leftPlane:Plane = new Plane({material:leftMaterial, width:100, height:100, segmentsW:2, segmentsH:2, ownCanvas:true}); leftPlane.rotationZ = -90; leftPlane.rotationY = -90; leftPlane.x = 50; leftPlane.filters.push(new BlurFilter(8, 8)); var frontPlane:Plane = new Plane({material:frontMaterial, width:100, height:100, segmentsW:2, segmentsH:2, ownCanvas:true}); frontPlane.rotationX = -90; frontPlane.rotationZ = 180; frontPlane.z = 50; frontPlane.filters.push(new BlurFilter(8, 8)); // Create an object container to group the sides of the cube planeGroup = new ObjectContainer3D(); scene.addChild(planeGroup); planeGroup.addChild(topPlane); planeGroup.addChild(leftPlane); planeGroup.addChild(frontPlane);
As you can see, three planes are created, as shown in previous articles, and a different material passed to each one. These planes are then rotated and translated to form three faces of a cube. I also added a BlurFilter just to show how adding effects to Away3D objects is very simple as well.
Moving onto the mouse event listeners, for this example I don’t have a stage mouse listener to rotate the scene, only listeners for the MouseEvent3D events. Here, for each face, I add a mouse down, mouse over and mouse up listener that are triggered only when the mouse interacts with a specific 3D object.
// Add mouse listeners to each plane for mouse down, over and out events topPlane.addOnMouseDown(onMouseClickOnObject); leftPlane.addOnMouseDown(onMouseClickOnObject); frontPlane.addOnMouseDown(onMouseClickOnObject); topPlane.addOnMouseOver(onMouseOverObject); leftPlane.addOnMouseOver(onMouseOverObject); frontPlane.addOnMouseOver(onMouseOverObject); topPlane.addOnMouseOut(onMouseLeavesObject); leftPlane.addOnMouseOut(onMouseLeavesObject); frontPlane.addOnMouseOut(onMouseLeavesObject);
Looking first at the mouse down listener, the objective is to make the camera look directly at a cube face.
/** * Event listener for mouse click on plane. Makes the camera look * directly at the plane and move closer to it. */ private function onMouseClickOnObject(event:MouseEvent3D):void { var object:Object3D = event.object; doRotation = false; // Calculate angles necessary for camera var theta:Number = Math.atan2(object.x, object.z); var len:Number = Math.sqrt(object.x*object.x + object.z*object.z); var phi:Number = Math.atan2(object.y, len); // rotate camera position camera.targetpanangle = theta * 180 / Math.PI; camera.targettiltangle = phi * 180 / Math.PI; // move camera towards plane Tweener.addTween(camera, {distance:150, time:0.5, transition:"easeOutSine"}); }
From the object location we can calculate a camera tilt and pan angle. Using the properties targetpanangle and targettiltangle the camera moves gently towards the desired position. To move the camera towards the object I’ve added a Tweener call (as we looked at in scene interaction). In this function we also turn off the automatic camera movement (the camera follows the mouse otherwise as shown below).
Moving on to the mouse over event listener, here we simply remove the BlurFilter making the face come into focus.
/** * Event listener for mouse over plane. Removes the blur filter. */ private function onMouseOverObject(event:MouseEvent3D):void { var object:Object3D = event.object; object.filters = new Array(); }
Finally for the listeners, the mouse out event listener adds the BlurFilter, ensures that the camera moves freely with the mouse movement again and executes another Tweener call to take the camera back to its original distance.
/** * Event listener for mouse out of plane. Adds blur filter and moves * camera away from plane if it isn't already. */ private function onMouseLeavesObject(event:MouseEvent3D):void { var object:Object3D = event.object; object.filters.push(new BlurFilter(8, 8)); Tweener.addTween(camera, {distance:200, time:0.5, transition:"easeOutSine"}); doRotation = true; }
That leaves us with just the event loop and the camera update function. You’ll notice that the update loop is very similar to before - there is no rotation applied to the scene objects this time but we do update the camera position.
To move the camera automatically, the relative mouse position on the screen is simply converted into pan and tilt angles and applied to the camera target angles as shown below.
/** * Update the camera position from mouse positions */ private function updateCamera():void { if (doRotation) { camera.targetpanangle = (stage.stageWidth - stage.mouseX) / stage.stageWidth * 90; camera.targettiltangle = (stage.stageHeight - stage.mouseY) / stage.stageHeight * 70 } }
Note that if the user has clicked on a cube face then the doRotation boolean is false allowing the user to interact more easily with the different movie or video stream material.
And that’s all there is to it! As you’ll see, mouse events are mapped effectively to the embedded Flash animations, even in 3D, and the streaming of video is very clean and very simple to implement. Hopefully this has provided a useful introduction to these types of materials, don’t hesitate to look into the code itself to understand them more. As always comments, questions and suggestions are very welcome too!
As promised, just for completeness, you’ll find the source for the drawing tool movie and the automated Pong game below - going into the detail of these is out of the scope of this article !
DrawTool.as :
package { import flash.display.Sprite; import flash.events.MouseEvent; import flash.text.TextField; import flash.text.TextFieldAutoSize; import flash.text.TextFormat; public class DrawTool extends Sprite { private var isDrawing:Boolean = false; private var sprite:Sprite; public function DrawTool() { // create a drawing surface sprite = new Sprite(); sprite.graphics.beginFill(0xEEEEEE); sprite.graphics.moveTo(0, 0); sprite.graphics.lineTo(320, 0); sprite.graphics.lineTo(320, 240); sprite.graphics.lineTo(0, 240); sprite.graphics.endFill(); addChild(sprite); // create text and format var textFormat:TextFormat = new TextFormat(); textFormat.size = 30; textFormat.font = "Arial"; var text:TextField = new TextField(); text.x = 50; text.y = 100; text.textColor = 0x222222; text.text = "click to draw!"; text.setTextFormat(textFormat); text.autoSize = TextFieldAutoSize.LEFT; text.selectable = false; addChild(text); // listen to mouse events this.addEventListener(MouseEvent.MOUSE_DOWN, onMouseDown); this.addEventListener(MouseEvent.MOUSE_UP, onMouseUp); this.addEventListener(MouseEvent.MOUSE_MOVE, onMouseMove); } /** * Event listener for mouse down event. Starts drawing circles. */ private function onMouseDown(event:MouseEvent):void { isDrawing = true; drawCircle(this.mouseX, this.mouseY); } /** * Event listener for mouse up event. Stops drawing circles. */ private function onMouseUp(event:MouseEvent):void { isDrawing = false; } /** * Event listener for mouse move event. Draws a circle. */ private function onMouseMove(event:MouseEvent):void { if (isDrawing) { drawCircle(this.mouseX, this.mouseY); } } /** * Function to draw a circle. */ private function drawCircle(x:int, y:int):void { sprite.graphics.beginFill(Math.random() * 0xFFFFFF, 0.5); sprite.graphics.drawCircle(x, y, 5); sprite.graphics.endFill(); } } }
Pong.as :
package { import flash.display.Sprite; import flash.events.Event; [SWF(backgroundColor="#000000")] /** * Simple computerised Pong copy. */ public class Pong extends Sprite { private static const COURT_WIDTH:Number = 320; private static const COURT_HEIGHT:Number = 240; private static const BALL_WIDTH:Number = 5; private static const BAT_WIDTH:Number = 5; private static const BAT_HEIGHT:Number = 30; private static const COLOUR:Number = 0xDDDDDD; private var player1:Sprite; private var player2:Sprite; private var ball:Sprite; private var ballSpeedX:Number; private var ballSpeedY:Number; private var activePlayer:int; private var playerIsMoving:Boolean = false; private var playerSpeed:Number; private var playerDestination:Number; public function Pong() { createCourt(); addPlayer1(); addPlayer2(); addBall(); this.addEventListener(Event.ENTER_FRAME, onFrameEnter); } /** * Creates the court with net */ private function createCourt():void { var background:Sprite = new Sprite(); background.graphics.beginFill(0x000000); background.graphics.moveTo(0, 0); background.graphics.lineTo(COURT_WIDTH, 0); background.graphics.lineTo(COURT_WIDTH, COURT_HEIGHT); background.graphics.lineTo(0, COURT_HEIGHT); background.graphics.endFill(); addChild(background); var net:Sprite = new Sprite(); var nPoints:Number = 32; var pointHeight:Number = (COURT_HEIGHT / nPoints); var drawHeight:Number = pointHeight * 0.6; var drawWidth:Number = drawHeight / 2; // Create dashed net for (var i:Number = 0; i < nPoints; i++) { var x:Number = COURT_WIDTH / 2 - drawWidth / 2; var y:Number = i*pointHeight; net.graphics.beginFill(COLOUR); net.graphics.moveTo(x, y); net.graphics.lineTo(x+drawWidth, y); net.graphics.lineTo(x+drawWidth, y+drawHeight); net.graphics.lineTo(x, y+drawHeight); net.graphics.endFill(); } addChild(net); } /** * Add left-hand player */ private function addPlayer1():void { player1 = new Sprite(); createBat(player1); player1.x = 20; player1.y = (COURT_HEIGHT / 2) - (BAT_HEIGHT / 2); addChild(player1); } /** * Add right-hand player */ private function addPlayer2():void { player2 = new Sprite(); createBat(player2); player2.x = COURT_WIDTH - 20 - BAT_WIDTH; player2.y = (COURT_HEIGHT / 2) - (BAT_HEIGHT / 2); addChild(player2); } /** * Create a bat */ private function createBat(player:Sprite):void { player.graphics.beginFill(COLOUR); player.graphics.moveTo(0, 0); player.graphics.lineTo(BAT_WIDTH, 0); player.graphics.lineTo(BAT_WIDTH, BAT_HEIGHT); player.graphics.lineTo(0, BAT_HEIGHT); player.graphics.endFill(); } /** * Add ball to scene and initialise speeds */ private function addBall():void { ball = new Sprite(); ball.graphics.beginFill(COLOUR); ball.graphics.moveTo(0, 0); ball.graphics.lineTo(BALL_WIDTH, 0); ball.graphics.lineTo(BALL_WIDTH, BALL_WIDTH); ball.graphics.lineTo(0, BALL_WIDTH); ball.graphics.endFill(); ball.x = 0; ball.y = 20; addChild(ball); ballSpeedX = 6; ballSpeedY = 5; activePlayer = 1; } /** * Called at every frame */ private function onFrameEnter(event:Event):void { // update ball position updateBall(); // update player position updateActivePlayer(); // detect hits hitTest(); } /** * Updates the ball position taking into account court dimensions */ private function updateBall():void { ball.x = ball.x + ballSpeedX; ball.y = ball.y + ballSpeedY; // Detect if ball escapes a player if (ball.x > COURT_WIDTH - BALL_WIDTH) { ball.x = 0; ball.y = COURT_HEIGHT / 2; ballSpeedY = Math.random() * 10; } else if (ball.x < 0) { ball.x = COURT_WIDTH - BALL_WIDTH; ball.y = COURT_HEIGHT / 2; ballSpeedY = -Math.random() * 10; } // Detect wall hits: invert ball y-direction and initiate player position calculation if (ball.y < 0) { ball.y = 0; ballSpeedY = -ballSpeedY; playerIsMoving = false; } else if (ball.y > COURT_HEIGHT - BALL_WIDTH) { ball.y = COURT_HEIGHT - BALL_WIDTH; ballSpeedY = -ballSpeedY; playerIsMoving = false; } } /** * Updates player position or calculates new position */ private function updateActivePlayer():void { var player:Sprite; var calculatedTime:Number; // calculate time for ball to reach player if (activePlayer == 0) { player = player1; calculatedTime = Math.abs(player.x + BAT_WIDTH - ball.x) / Math.abs(ballSpeedX); } else { player = player2; calculatedTime = Math.abs(player.x - (ball.x + BALL_WIDTH)) / Math.abs(ballSpeedX); } if (playerIsMoving) { // update player position player.y = player.y + playerSpeed; // ensure that player does not leave the court if (player.y > COURT_HEIGHT - BAT_HEIGHT) { player.y = COURT_HEIGHT - BAT_HEIGHT; playerIsMoving = false; } else if (player.y < 0) { player.y = 0; playerIsMoving = false; } // determine if player is more or less in position if (Math.abs(player.y - playerDestination) < BAT_HEIGHT / 4) { playerIsMoving = false; } } else { // calculate expected ball position var calculatedY:Number = ball.y + ballSpeedY * calculatedTime; var random:Boolean = false; if (calculatedY < 0 || calculatedY > COURT_HEIGHT) { calculatedY = Math.random() * COURT_HEIGHT; random = true; } // calculate desired player position with a random element playerDestination = calculatedY - (BAT_HEIGHT / 2) + (0.4 * (Math.random() - 0.5) * BAT_HEIGHT); if (playerDestination < 0) { playerDestination = 0; } else if (playerDestination > COURT_HEIGHT - BAT_HEIGHT) { playerDestination = COURT_HEIGHT - BAT_HEIGHT; } // Calculate a random speed for player if (player.y < playerDestination) { playerSpeed = 5 + Math.random() * 10; } else { playerSpeed = -5 + Math.random() * -10; } // increase speed if player can't work out ball position if (random) { playerSpeed = playerSpeed * 2; } // only move player if really necessary (+ stupidity estimate) if (Math.abs(playerDestination - player.y) > BAT_HEIGHT / 2) { playerIsMoving = true; } } } /** * Determine if ball hits a bat */ private function hitTest():void { var player:Sprite; var check:Boolean = false; // check to see if ball is at same x position as bat if (activePlayer == 0) { player = player1; if (ball.x > player1.x && ball.x < player1.x + BAT_WIDTH) { check = true; } } else { player = player2; if (ball.x + BALL_WIDTH > player2.x && ball.x + BALL_WIDTH < player2.x + BAT_WIDTH) { check = true; } } if (check) { // verify y position if ((ball.y + BALL_WIDTH <= player.y + BAT_HEIGHT) && (ball.y >= player.y)) { // hit, change player activePlayer = 1 - activePlayer; // reverse ball direction ballSpeedX = -ballSpeedX; // calculate new ball speed in y var batPosition:Number = (ball.y + (BALL_WIDTH / 2)) - (player.y + (BAT_HEIGHT / 2)); ballSpeedY = batPosition / BAT_HEIGHT * 10 * (1 + Math.random() * 0.1); } } } } }
Saturday, December 13th, 2008
Following from my previous articles on setting up an Alchemy development environment in Flex Builder 3 and passing/returning objects to/from C++, I wanted to test some of the claims of the speed increase possible with the use of this tool.
With the particular interest in 3D Flash applications, I wanted to test specific mathematical operations using vectors and matrices, namely cross products, normalisation, rotation matrix calculations and vector transformations.
I had initially aimed to create a mathematical library where these functions can be calculated on native ActionScript objects - for example create a function to calculate the cross product of two vectors. However one aspect of Alchemy that became immediately evident is that the cost of marshaling data through the AS3-C++ API is horrendously expensive. This is quite normal so I guess I was naive to expect good results from this. But to give you an example of how expensive this is, for a simple iterative calculation of the cross product of two vectors followed by a normalisation: if the mathematical functions are performed in C++, ie iteratively calling the Alchemy compiled functions, the result is about 1000 times slower than natively performing the calculations in AS3!
So, my first advice is: limit the number of Alchemy calls!!
Anyway, in this article I’ll concentrate on performing pure C++ speed tests (called from AS3) - so computationally intensive calculations performed in a single Alchemy call - compared to the equivalent pure AS3 speed tests.
The tests performed here concentrate on vector and matrix operations. I’ve therefore created very simple Vector and Matrix classes in C++. The Vector class is used to perform dot product, normalisation and cross product operations as shown below.
Vector3D.h :
#ifndef VECTOR3D_H_ #define VECTOR3D_H_ #include "AS3.h" class Vector3D { public : Vector3D(); Vector3D(double x, double y, double z); Vector3D(const AS3_Val& as3Vector); virtual ~Vector3D(); double dot(const Vector3D& v) const; Vector3D cross(const Vector3D& v) const; double modulus() const; Vector3D normalise() const; void setX(double x); void setY(double y); void setZ(double z); double getX() const; double getY() const; double getZ() const; private : double _x; double _y; double _z; }; #endif /*VECTOR3D_H_*/
Vector3D.cpp :
#include "Vector3D.h" #include <cmath> Vector3D::Vector3D() : _x(0), _y(0), _z(0) { } Vector3D::Vector3D(const AS3_Val& as3Vector) { AS3_ObjectValue(as3Vector, "x:DoubleType, y:DoubleType, z:DoubleType", &_x, &_y, &_z); } Vector3D::Vector3D(double x, double y, double z) : _x(x), _y(y), _z(z) { } Vector3D::~Vector3D() { } double Vector3D::dot(const Vector3D& v) const { return v._x*_x + v._y*_y + v._z*_z; } Vector3D Vector3D::cross(const Vector3D& v) const { Vector3D result; result._x = _y*v._z - _z*v._y; result._y = _z*v._x - _x*v._z; result._z = _x*v._y - _y*v._x; return result; } double Vector3D::modulus() const { return std::sqrt(_x*_x + _y*_y + _z*_z); } Vector3D Vector3D::normalise() const { double mod = modulus(); return Vector3D(_x/mod, _y/mod, _z/mod); } void Vector3D::setX(double x) { _x = x; } void Vector3D::setY(double y) { _y = y; } void Vector3D::setZ(double z) { _z = z; } double Vector3D::getX() const { return _x; } double Vector3D::getY() const { return _y; } double Vector3D::getZ() const { return _z; }
One point, specific to Alchemy, is in one of the constructors for the Vector3D: the properties are extracted from the passed AS3 Vector3D object, as discussed in my previous article.
The Matrix3D C++ class is as follows.
Matrix3D.h :
#ifndef MATRIX3D_H_ #define MATRIX3D_H_ #include "Vector3D.h" class Matrix3D { public : Matrix3D(); virtual ~Matrix3D(); void setRotationX(double degrees); void setRotationY(double degrees); void setRotationZ(double degrees); void setIdentity(); Vector3D transformVector(const Vector3D& vector) const; private : double _M00; double _M01; double _M02; double _M10; double _M11; double _M12; double _M20; double _M21; double _M22; }; #endif /*MATRIX3D_H_*/
Matrix3D.cpp :
#include "Matrix3D.h" #include <cmath> Matrix3D::Matrix3D() : _M00(1), _M01(0), _M02(0), _M10(0), _M11(1), _M12(0), _M20(0), _M21(0), _M22(1) { } Matrix3D::~Matrix3D() { } void Matrix3D::setIdentity() { _M00 = 1; _M01 = 0; _M02 = 0; _M10 = 0; _M11 = 1; _M12 = 0; _M20 = 0; _M21 = 0; _M22 = 1; } void Matrix3D::setRotationX(double degrees) { setIdentity(); double radians = degrees / 180 * M_PI; _M11 = cos(radians); _M12 = -sin(radians); _M21 = sin(radians); _M22 = cos(radians); } void Matrix3D::setRotationY(double degrees) { setIdentity(); double radians = degrees / 180 * M_PI; _M00 = cos(radians); _M02 = sin(radians); _M20 = -sin(radians); _M22 = cos(radians); } void Matrix3D::setRotationZ(double degrees) { setIdentity(); double radians = degrees / 180 * M_PI; _M00 = cos(radians); _M01 = -sin(radians); _M10 = sin(radians); _M11 = cos(radians); } Vector3D Matrix3D::transformVector(const Vector3D& vector) const { Vector3D result; result.setX(_M00*vector.getX() + _M01*vector.getY() + _M02*vector.getZ()); result.setY(_M10*vector.getX() + _M11*vector.getY() + _M12*vector.getZ()); result.setZ(_M20*vector.getX() + _M21*vector.getY() + _M22*vector.getZ()); return result; }
One of the objectives of using the Matrix3D class is to test the performance of the trigonometric functions. A common source of intensive calculations in 3D graphics is the rotation of vectors so this provides a useful test directly aimed at this field.
Two tests are to be examined: one for cross product calculations and another for matrix transformations. These are defined in the main.cpp file.
#include "AS3.h" #include "Vector3D.h" #include "Matrix3D.h" AS3_Val speedTest1(void* self, AS3_Val args) { // Declare AS3 variables AS3_Val as3Vector1; AS3_Val as3Vector2; // Extract variables from arguments array AS3_ArrayValue(args, "AS3ValType, AS3ValType", &as3Vector1, &as3Vector2); // Create native C++ objects with AS3 parameters Vector3D vector1(as3Vector1); Vector3D vector2(as3Vector2); Vector3D vector3; // Speed test : calculate cross products and normalise for (int i = 0; i < 1000000; i++) { vector3 = vector1.cross(vector2); vector3 = vector3.normalise(); vector1 = vector2; vector2 = vector3; } // Obtain a class descriptor for the AS3 Vector3D class AS3_Val vector3DClass = AS3_NSGet(AS3_String("flash.geom"), AS3_String("Vector3D")); AS3_Val params = AS3_Array(""); // Construct a new AS3 Vector3D object with empty parameters AS3_Val result = AS3_New(vector3DClass, params); // Set the x, y and z properties of the AS3 Vector3D object, casting as appropriate AS3_Set(result, AS3_String("x"), AS3_Number(vector3.getX())); AS3_Set(result, AS3_String("y"), AS3_Number(vector3.getY())); AS3_Set(result, AS3_String("z"), AS3_Number(vector3.getZ())); // Release what's no longer needed AS3_Release(params); AS3_Release(vector3DClass); // return the AS3 Vector return result; } AS3_Val speedTest2(void* self, AS3_Val args) { // Declare AS3 variable AS3_Val as3Vector; // Extract variables from arguments array AS3_ArrayValue(args, "AS3ValType", &as3Vector); // Create native C++ object with AS3 parameters Vector3D vector(as3Vector); Vector3D copy = vector; Matrix3D rotationX; Matrix3D rotationY; Matrix3D rotationZ; // Speed test : calculate rotation matrices and transform vector for (int i = 0; i < 1000; i++) { vector = copy; for (double ang = 0; ang < 180; ang++) { rotationX.setRotationX(ang); rotationY.setRotationY(ang); rotationZ.setRotationZ(ang); vector = rotationX.transformVector(vector); vector = rotationY.transformVector(vector); vector = rotationZ.transformVector(vector); } } // Obtain a class descriptor for the AS3 Vector3D class AS3_Val vector3DClass = AS3_NSGet(AS3_String("flash.geom"), AS3_String("Vector3D")); AS3_Val params = AS3_Array(""); // Construct a new AS3 Vector3D object with empty parameters AS3_Val result = AS3_New(vector3DClass, params); // Set the x, y and z properties of the AS3 Vector3D object, casting as appropriate AS3_Set(result, AS3_String("x"), AS3_Number(vector.getX())); AS3_Set(result, AS3_String("y"), AS3_Number(vector.getY())); AS3_Set(result, AS3_String("z"), AS3_Number(vector.getZ())); // Release what's no longer needed AS3_Release(params); AS3_Release(vector3DClass); // return the AS3 Vector return result; } /** * Main entry point for Alchemy compiler. Declares all functions available * through the Alchemy bridge. */ int main() { // Declare all methods exposed to AS3 typed as Function instances AS3_Val speedTest1Method = AS3_Function(NULL, speedTest1); AS3_Val speedTest2Method = AS3_Function(NULL, speedTest2); // Construct an object that contains references to all the functions AS3_Val result = AS3_Object("speedTest1:AS3ValType, speedTest2:AS3ValType", speedTest1Method, speedTest2Method); // Release what's no longer needed AS3_Release(speedTest1Method); AS3_Release(speedTest2Method); // Notify the bridge of what has been created -- THIS DOES NOT RETURN! AS3_LibInit(result); // Should never get here! return 0; }
For an explanation of the code and the C++ API of Alchemy, I’ll refer you to my previous article on passing and returning objects to and from C++ using Alchemy.
The first test, speedTest1, performs 1,000,000 times the cross product of two vectors (initially passed by AS3) followed by a normalisation. The resulting vector is used in the following iteration. At the end of all the iterations, the final vector is returned to AS3.
The second test, speedTest2, calculates rotation vectors around the x, y and z axes. A vector (initially passed by AS3), is then rotated by each matrix individually. This is repeated for 180 steps, increasing the angle of rotation by 1 degree at a time. This again is repeated for a total of 1,000 iterations. The final vector is returned to AS3.
Let’s have a look now at the ActionScript class that calls these tests, and the equivalent pure AS3 tests.
package { import cmodule.vector.CLibInit; import flash.display.Sprite; import flash.display.StageAlign; import flash.display.StageScaleMode; import flash.geom.Matrix3D; import flash.geom.Vector3D; import flash.text.TextField; import flash.text.TextFieldAutoSize; import flash.utils.getTimer; public class AlchemySpeedTest extends Sprite { private var vectorUtils:Object; public function AlchemySpeedTest() { // Set up the stage stage.align = StageAlign.TOP_LEFT; stage.scaleMode = StageScaleMode.NO_SCALE; // Create the Alchemy bridge to C++ methods var loader:CLibInit = new CLibInit; vectorUtils = loader.init(); // Create a text field var timerText:TextField = new TextField(); timerText.autoSize = TextFieldAutoSize.LEFT; addChild(timerText); // Initialise a timer var time0:int = getTimer() // Perform the speed test var vector:Vector3D = speedTest1(); //var vector:Vector3D = speedTest2(); //var vector:Vector3D = nativeSpeedTest1(); //var vector:Vector3D = nativeSpeedTest2(); // Calculate the elapsed time var time1:int = getTimer() var totalTime:int = time1 - time0; // Display elapsed time and final vector timerText.text = "Time taken = " + totalTime + " vector = (" + vector.x + ", " + vector.y + ", " + vector.z + ")"; } /** * Speed test using C++ to iteratively calculate the cross products of two vectors */ private function speedTest1():Vector3D { var vector1:Vector3D = new Vector3D(0.123, 0.456, 0.789); var vector2:Vector3D = new Vector3D(0.987, 0.654, 0.321); return vectorUtils.speedTest1(vector1, vector2); } /** * Speed test using C++ to iteratively calculate rotation matrices and apply these to a vector */ private function speedTest2():Vector3D { var vector:Vector3D = new Vector3D(0.123, 0.456, 0.789); return vectorUtils.speedTest2(vector); } /** * Speed test using AS3 to iteratively calculate the cross products of two vectors */ private function nativeSpeedTest1():Vector3D { var vector1:Vector3D = new Vector3D(0.123, 0.456, 0.789); var vector2:Vector3D = new Vector3D(0.987, 0.654, 0.321); var vector3:Vector3D; var time0:int = getTimer() for (var i:int = 0; i < 1000000; i++) { vector3 = vector1.crossProduct(vector2); vector3.normalize(); vector1 = vector2; vector2 = vector3; } return vector3; } /** * Speed test using AS3 to iteratively calculate rotation matrices and apply these to a vector */ private function nativeSpeedTest2():Vector3D { var vector:Vector3D = new Vector3D(0.123, 0.456, 0.789); var copy:Vector3D = vector.clone(); var rotationX:Matrix3D = new Matrix3D(); var rotationY:Matrix3D = new Matrix3D(); var rotationZ:Matrix3D = new Matrix3D(); for (var i:int = 0; i < 1000; i++) { vector = copy.clone(); for (var ang:Number = 0; ang < 180; ang++) { rotationX.identity(); rotationX.appendRotation(ang, Vector3D.X_AXIS); rotationY.identity(); rotationY.appendRotation(ang, Vector3D.Y_AXIS); rotationZ.identity(); rotationZ.appendRotation(ang, Vector3D.Z_AXIS); vector = rotationX.transformVector(vector); vector = rotationY.transformVector(vector); vector = rotationZ.transformVector(vector); } } return vector; } } }
Without going into too many details of the code, you’ll see that in the constructor we can choose one of four tests: speedTest1 and speedTest2, as discussed above, and nativeSpeedTest1 and nativeSpeedTest2 which perform the same calculations but using pure ActionScript classes. The time taken to perform the calculations is then displayed along with the final vector so that we can be sure that the results are the same in a TextField.
To make reasonable comparisons I’ve tried to make the object creation in both ActionScript and C++ relatively equal: creating objects takes time so can obfuscate the obtained timing results. If you find any glaring differences between the C++ and ActionScript versions then please let me know and I’ll modify this post.
If you’d like to take a look at the whole project (set up using automake and ant as shown in my previous article on setting up a development environment for Alchemy in Flex Builder 3) then you can find all the files here.
Results
The native and Alchemy speed tests were compared initially to ensure that they both produce the same results. One surprising result was that for the matrix rotation test, the resulting vector diverged progressively as the number of iterations increased. This is presumably because of rounding errors being different between C++ (which uses double floating point values) and ActionScript. To limit this, you’ll notice that the vector is reset before the inner iteration over the 180 angles.
More important are the timing results… and the winner is… !
For speedTest1 (vector cross product and normalisation) I obtained the following:
Alchemy : 1309ms (averaged from 4 runs: 1346, 1285, 1284, 1322)
Native : 1192ms (averaged from 4 runs: 1232, 1147, 1176, 12123)
For speedTest2 (rotation matrix creation and vector transformation) the following times were obtained:
Alchemy : 814ms (averaged from 4 runs: 803, 826, 814, 813)
Native : 792ms (averaged from 4 runs: 774, 787, 789, 816)
Conclusion
As you can see, even with computationally intensive calculations, native ActionScript beats Alchemy compiled C++. Shame - I was expecting huge improvements! And don’t forget that calling Alchemy code is very expensive - these tests have minimised this cost.
But is it really surprising? After all, we’re not executing natively compiled C++ code: we’re executing C++ bytecode compiled for the ActionScript virtual machine. Plus the native ActionScript functions have already been optimised.
Going to some extent to explain this, this article at Automata Studios on Understanding Adobe Alchemy (who used Alchemy to port OggVorbis to ActionScript 3) provides very interesting reading. As they say in the article:
“… Knowing that Alchemy is just spitting out the same AVM2 bytecode that Flash and Flex spit out it is pretty confusing how Alchemy code could be faster than standard ActionScript. In fact, it is not faster across the board - just in specific types of operations and when the length of a task can be used to overcome Alchemy’s intrinsic overhead….
And also:
“… Now, what are these operations that Alchemy does so well? Memory access and function calls. Alchemy compiled code utilizes new bytecodes added to FP10 for working with ByteArrays - which as you’ll remember are what make up the “RAM” in Alchemy. …”
So the result seems somewhat less attractive than that claimed by Adobe (“… Ideally suited for computation-intensive use cases (…) performance can be considerably faster than ActionScript 3.0 …”) and much more specific to the type of operations being performed.
The tests shown here are of course very limited in their scope: the idea is to provoke some discussion about where Alchemy can be beneficial rather than just stating that Alchemy will produce pure gold in all situations.
One area which may be of interest is that of green threads as stated in the above article. However these threads are platform independent and are executed in the virtual machine rather on the native OS. This limitation means that the benefits of multi-core processors cannot be tapped into… so can they really produce reasonable results when calculations are performed in parallel?
Anyway, I hope this has been of interest and of some use - as always comments, suggestions and questions are welcome!
Saturday, December 13th, 2008
Following from my last article on setting up an Alchemy development environment in Flex Builder 3, I wanted to illustrate briefly how objects can be passed to C++ methods using Alchemy (and similarly how the ActionScript properties can be extracted) and how we can return objects to the calling AS3 code.
This article has been prompted since I found very little useful documentation on the web, so hopefully this’ll be useful for other beginners! Other than the C++ API for Alchemy provided by Adobe (which is essential), I’ve found the following links very useful in providing concrete examples of getting started in Alchemy:
- Creating a button with Alchemy by Manfred Webber
- The OggVorbis library sources to be compiled with AS3
These provided the essential lines of code necessary to understand the API, and be able to pass objects to C/C++ and similarly return objects to ActionScript.
The following is some C code to illustrate this. Essentially a flash.geom.Vector3D object is passed to a function, foo, which then returns a copy of the object to the calling function.
#include "AS3.h" AS3_Val foo(void* self, AS3_Val args) { // declare local variables double x; double y; double z; // ******* Passing objects as parameters to C++ ******* // Declare AS3 variable AS3_Val as3Vector; // Extract variables from arguments array (in this case a flash.geom.Vector3D) AS3_ArrayValue(args, "AS3ValType", &as3Vector); // Extract properties from object and store in local variables AS3_ObjectValue(as3Vector, "x:DoubleType, y:DoubleType, z:DoubleType", &x, &y, &z); // ******* Returning objects to AS3 ******* // Obtain a class descriptor for the AS3 Vector3D class AS3_Val vector3DClass = AS3_NSGet(AS3_String("flash.geom"), AS3_String("Vector3D")); AS3_Val params = AS3_Array(""); // Construct a new AS3 Vector3D object with empty parameters AS3_Val result = AS3_New(vector3DClass, params); // Set the x, y and z properties of the AS3 Vector3D object, casting as appropriate AS3_Set(result, AS3_String("x"), AS3_Number(x)); AS3_Set(result, AS3_String("y"), AS3_Number(y)); AS3_Set(result, AS3_String("z"), AS3_Number(z)); // Release what's no longer needed AS3_Release(params); AS3_Release(vector3DClass); // return the AS3 flash.geom.Vector3D object return result; } /** * Main entry point for Alchemy compiler. Declares all functions available * through the Alchemy bridge. */ int main() { // Declare all methods exposed to AS3 typed as Function instances AS3_Val fooMethod = AS3_Function(NULL, foo); // Construct an object that contains references to all the functions AS3_Val result = AS3_Object("foo:AS3ValType", fooMethod); // Release what's no longer needed AS3_Release(fooMethod); // Notify the bridge of what has been created -- THIS DOES NOT RETURN! AS3_LibInit(result); // Should never get here! return 0; }
Let’s take a look at this bit by bit. Starting with the function foo, all functions visible to ActionScript have to be declared in the same way:
AS3_Val foo(void* self, AS3_Val args) {
The return value is always an AS3_Val type and a function always receives a pointer along with an AS3_Val type argument. AS3_Val can be thought of as the Object type in AS3 - all concrete types inherit from this so utilities are needed to extract useful information from them.
First of all: extracting objects from the args parameter. Whatever, and however many, arguments are passed we always use the method AS3_ArrayValue to extract the real arguments: arguments are always passed in the form of an Array. In the example we do the following:
// Declare AS3 variable AS3_Val as3Vector; // Extract variables from arguments array (in this case a flash.geom.Vector3D) AS3_ArrayValue(args, "AS3ValType", &as3Vector);
Here we declare an AS3_Val variable (implying that we are expecting an AS3 Object). If the types passed are primitive types (or String types) we could do the following:
int arg0 = 0; char* arg1 = NULL; double arg2 = 0.0; AS3_ArrayValue(arr, "IntType, StrType, DoubleType", &arg0, &arg1, &arg2);
Here the primitive AS3 types are converted to native C++ primitives.
Coming back to our example, we now have an AS3 Object (stored as an AS3_Val type) and we’d like to extract data from it. This is done by making an AS3_ObjectValue call.
// Extract properties from object and store in local variables AS3_ObjectValue(as3Vector, "x:DoubleType, y:DoubleType, z:DoubleType", &x, &y, &z);
Here we pass the extracted Object, declare the identifiers and types of properties and a list of local variables to store the value in. For the Vector3D we want to obtain the x, y and z properties which are converted to local DoubleType values.
To return an ActionScript object, we need to perform a lookup for the class name with the relevant namespace. From this we can get a class descriptor which can then be instantiated.
// Obtain a class descriptor for the AS3 Vector3D class AS3_Val vector3DClass = AS3_NSGet(AS3_String("flash.geom"), AS3_String("Vector3D"));
Here, for example, we obtain an AS3_Val representing the class flash.geom.Vector3D, using the AS3_NSGet function. We can then create an object from this.
AS3_Val params = AS3_Array(""); // Construct a new AS3 Vector3D object with empty parameters AS3_Val result = AS3_New(vector3DClass, params);
This object is create with no parameters using the AS3_New function. Again, the result is stored in the base AS3_Val type. Having created a new object we can then modify its properties.
// Set the x, y and z properties of the AS3 Vector3D object, casting as appropriate AS3_Set(result, AS3_String("x"), AS3_Number(x)); AS3_Set(result, AS3_String("y"), AS3_Number(y)); AS3_Set(result, AS3_String("z"), AS3_Number(z));
The AS3_Set function takes an AS3 Object, a property identifier and a value, correctly cast to the required AS3 value type, in this case an AS3_Number type. Note that I’ve tried to pass these values in the params Array but have never been successful - if anyone has any tips on doing this I’d be happy to hear from you.
So, now we have an AS3 object created and its properties set. Now we need to do a bit of memory management before returning the object. This is done using the AS3_Release function.
// Release what's no longer needed AS3_Release(params); AS3_Release(vector3DClass);
Finally, we return the created object:
// return the AS3 flash.geom.Vector3D object return result;
To export the function foo to ActionScript, the following main function is called - the Alchemy compiler always looks for this function, so its here that we always declare our interface. For the above example the following is necessary:
int main() { // Declare all methods exposed to AS3 typed as Function instances AS3_Val fooMethod = AS3_Function(NULL, foo); // Construct an object that contains references to all the functions AS3_Val result = AS3_Object("foo:AS3ValType", fooMethod); // Release what's no longer needed AS3_Release(fooMethod); // Notify the bridge of what has been created -- THIS DOES NOT RETURN! AS3_LibInit(result); // Should never get here! return 0; }
Without going into too many details, essentially we create Function objects containing the native C/C++ methods. These are then given an AS3 interface using the AS3_Object function and then passed to the AS3_LibInit function which provides the entry point from ActionScript.
The following ActionScript class shows how we call the Alchemy compiled functions, passing a Vector3D object and obtaining another one in return.
package { import cmodule.vector.CLibInit; import flash.display.Sprite; import flash.geom.Vector3D; public class Test extends Sprite { public function Test() { // Create the Alchemy bridge to C++ methods var loader:CLibInit = new CLibInit; var alchemyTest:Object = loader.init(); var vector:Vector3D = new Vector3D(0.123, 0.456, 0.789); var returnVector:Vector3D = alchemyTest.foo(vector); trace("Return vector = (" + returnVector.x + ", " + returnVector.y + ", " + returnVector.z + ")"); } } }
Our connection to the C/C++ code is performed by creating a new CLibInit function and calling init.
// Create the Alchemy bridge to C++ methods var loader:CLibInit = new CLibInit; var alchemyTest:Object = loader.init();
This creates a basic ActionScript Object. The functions cannot be seen at the time of compilation (at least not in Flex Builder) but are obtained at run time. The resulting function call on foo is shown as follows:
var vector:Vector3D = new Vector3D(0.123, 0.456, 0.789); var returnVector:Vector3D = alchemyTest.foo(vector);
As required, we pass a Vector3D and get a new Vector3D object in return.
And that’s it! If you’d like to have a look at the source and the project set-up together (using the same automake and ant files as discussed in the previous article) then you can find them here.
This is a very quick introduction to passing and returning objects using Alchemy. The API provides many more possibilities but this articles aims to illustrate some of the basic, but essential, functions available - for other beginners I hope this is useful! In my next article I’ll look at some of the capabilities of Alchemy.
Friday, December 12th, 2008
I’ve recently been reading a lot of articles recently about the new Alchemy research project at Adobe Labs. At first glances this looks very exciting: compile optimised C/C++ code to be executed within an ActionScript 3 Flash movie. As quoting from the Alchemy home page :
“… Ideally suited for computation-intensive use cases, such as audio/video transcoding, data manipulation, XML parsing, cryptographic functions or physics simulation, performance can be considerably faster than ActionScript 3.0 and anywhere from 2-10x slower than native C/C++ code.”
Sounds good! Ideal even when thinking about 3D graphics that are heavily dependent on vector and matrix calculations…
So, I decided to take a look and see how easy it was to integrate C++ code into an ActionScript project and what the benefits were. I discovered fairly quickly that documention on the web is fairly limited which has prompted this blog entry. Also, I’m a fan of the eclipse development environment and like all my work to be concentrated within the same window so wanted the Alchemy development to be done in parallel to the ActionScript development.
First off, it should be noted that this article is aimed mainly at Mac users: Hopefully there are things along the way that will be useful for Windows but I’m going to be looking at an automake utility to compile the Alchemy code which may not work on Windows (maybe under Cygwin, but I’ve not tried it).
Here are a few links to get started anyway:
- The main Alchemy home page at Adobe Labs
- Essential Adobe guide for installing and getting started with Alchemy
- The C/C++ API
- The ActionScript 3 API
- A couple of libraries built with Alchemy
First of all download Alchemy Toolkit from Adobe. Personally I copied the extracted directory to the Applications folder in my home directory. Then follow the instruction given on the Getting Started page.
NOTE !! I had huge trouble to start with because I was running a shell with tcsh: you must have bash (which is anyway the default for Mac) running for this to work!
Once I managed to compile the C code using the Alchemy tools, I went straight to Flex Builder 3 to try to integrate the ActionScript and compiled swf together.
In Flex Builder (or the Eclipse plugin as I’m using), create a new ActionScript project called EchoTest, as is the case for the ActionScript class shown on the Alchemy Getting Started page. Now we need to ensure that the project is compiled for Flash Player 10 (this is easily possible if you have Flex Builder 3.0.2 installed). Go to the project Properties menu item, select ActionScript Compiler and for Require Flash Player version enter 10.0.0 and click OK.
In the newly created EchoTest class, copy the code from the GettingStarted page that is linked to compiled C.
package { import flash.display.Sprite; import cmodule.stringecho.CLibInit; public class EchoTest extends Sprite { public function EchoTest() { var loader:CLibInit = new CLibInit; var lib:Object = loader.init(); trace(lib.echo("foo")); } } }
This won’t compile because we need to link to the Alchemy-compiled C code. Create a bin directory at the root of the project and copy stringecho.swf, compiled before, here. Go into the project Properties menu item, select ActionScript Build Path, go to the Library Path tab and select Add SWC…. Browse to the bin directory and select stringecho.swf. Now when you click on OK you should find that the project compiles.
To see anything happen you need to run in debug mode… even then its not very exciting: you’ll just see foo written in the Console.
The main objective (for me at least) is to set up an environment where we can compile the C/C++ code with Alchemy within the Flex environment. For this I’m going to be combining some automake files with shell scripts and link them to Eclipse with an ant build file.
Lets first of all copy the alchemy source in the project. Create a directory called alchemy at the root of the project. Into this, copy the C file from the Alchemy samples (ALCHEMY_HOME/samples/stringecho/stringecho.c).
For automake we need a configure.in file and (depending on the project) several Makefile.am files.
At the project root, copy the following into configure.in :
dnl Process this file with autoconf to produce a configure script. AC_INIT(alchemyTest, 0.0.1) AC_CONFIG_AUX_DIR(config) AC_CONFIG_SRCDIR(alchemy/stringecho.c) AM_INIT_AUTOMAKE dnl Compiler AC_PROG_CXX AC_PROG_CC AC_LANG(C++) AC_LANG(C) CFLAGS="" AM_CFLAGS="-Wall -O3 -swc " AC_SUBST(AM_CFLAGS) CXXFLAGS="" AM_CXXFLAGS="-Wall -O3 -swc " AC_SUBST(AM_CXXFLAGS) dnl Initialise top_srcdir top_srcdir=. AC_OUTPUT([ Makefile alchemy/Makefile ])
Create a Makefile.am file at the project root as well containing the following line (indicating simply which is the main alchemy source directory):
SUBDIRS = alchemy
Finally in the alchemy directory, copy the following also into a Makefile.am file :
INCLUDES = -I$(top_srcdir)/alchemy bin_PROGRAMS = stringecho.swc stringecho_swc_SOURCES = \ stringecho.c
That’s all that’s needed for the automake part. Now we need a couple of shell scripts to be called from ant and that take into account the environment variables necessary for the Alchemy tools.
At the root, create a file called init and copy the following:
#!/bin/sh if [ ! -d config ] then mkdir config; fi if [ ! -x AUTHORS ] then touch AUTHORS; touch README; touch NEWS; touch ChangeLog; fi aclocal -I config autoconf automake --gnu --add-missing if [ ! -d obj ] then mkdir obj; fi path=`pwd` cd obj ../configure --prefix=`pwd`/.. cd $path
Once it is created, make sure it is executable by changing the file permissions (chmod +x init). This will essentially create any necessary directories and files (for automake) and launch the configuration process. This will then create all the necessary Makefiles.
In the same directory (the root) create a file called build (that should also be executable) and copy this:
#!/bin/bash ALCHEMY_HOME=$HOME/Applications/Alchemy source $ALCHEMY_HOME/alchemy-setup PATH=$ALCHEMY_HOME/achacks:$PATH export PATH cd obj make -e install
Here we specify the home of Alchemy (so, obviously, change the directories accordingly) and we then launch the compilation, passing the environment variables at the same time (with the -e flag).
Finally, we come to the ant build file. The following should be copied into build.xml at the project root.
<project name="EchoTest" basedir="."> <property name="builddir" value="."/> <target name="compile alchemy"> <exec executable="${builddir}/build"/> </target> <target name="init alchemy"> <exec executable="${builddir}/init"> </exec> </target> <target name="remove obj"> <exec executable="rm"> <arg line="-fr"/> <arg line="obj"/> </exec> </target> </project>
This includes a couple of targets to initialise the compilation (create the Makefiles) and compile the C source. A final target just removes the compiles object files.
in the end you should have a project structure that looks something like this:
So let’s test this. Open the Ant view in eclipse by selection the menu Window, Show View, Other… and then searching for the Ant view. Drag and drop build.xml into this view and you should find the targets compile alchemy and init alchemy available.
NOTE !!! For this to work you need to lauch eclipse from the command line using the command tcsh -e ./eclipse from the installed eclipse directory. I don’t know why, but ant behaves differently - I presume because environment variables are passed to it! If you could tell me why, or how to avoid this, I’d be very happy to hear from you!
So, back again, assuming that eclipse is launched as tcsh -c ./eclipse, double click on the init alchemy target. You should hopefully see the configuration process in the console terminated with BUILD SUCCESS! This means that the Makefiles are ready. You can now double click on build alchemy to compile the C code. If it works you should see output that resembles that shown of the compilation on the Getting Started page.
The init process is typically necessary only once. From now on when modifying the C code just launch the build target.
This has now compiled stringecho.swc in the bin directory. Refresh the workspace (fn_key + F5 on a Mac) if it doesn’t refresh automatically which then recompiles the ActionScript if a change has occurred. In this case, I’m simply showing a build process so there’s no difference to the result. However, in future projects, you’ll find that every time you recompile using the Alchemy tools you’ll need to refresh the workspace otherwise the ActionScript project isn’t updated.
Also to note, when editing the C or C++ files, I’d recommend using the CDT plugin for eclipse rather than an external editor - again it avoids switching application for compiling the same project!
Anyway, hope this is of some use to people getting started with Alchemy (like me!). If you find any problems then please let me know… same if you have any comments. Next I’ll be looking at testing some of what Alchemy is supposed to be capable of!
Sunday, December 7th, 2008
Back again after a break longer than predicted! In this tutorial I’ll show how we can add more stunning visual effects to objects by applying normal maps (to give the impression that an object is composed of many more triangles from the rendered shading) and environment maps (for objects to appear shiny and reflecting the surrounding environment). An equivalent tutorial for Papervision3D can be found at my post on texture mapping with lighting, bump mapping and environment mapping.
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. - First steps in Away3D : Part 3 - Texture mapping
Create materials using bitmap data with the aim of having more detailed or realistic objects. - First steps in Away3D : Part 4 - Scene interaction
Listen to mouse events to interact with the scene and with individual rendered objects. - First steps in Away3D : Part 5 - Lighting and shading
A light source is added to the scene and the materials are changed to illustrate how Away3D renders objects with different shading characteristics.
Normal maps - or Dot3 bump maps - can be seen as something of an evolution from standard bump maps. Bump maps, as used in Papervision3D, contain a single value describing a displacement perpendicular to a surface. Normal maps, however, are more detailed because they contain three axis elements, effectively describing the normal to a specific point on a surface, replacing the triangle normal entirely. Whereas a bump map would be rendered the same for any point of view, a normal map is rendered differently depending on the viewer’s position: hence giving a much better impression of realism.
Normal maps are mapped in much the same way as a texture map, using the same uv values as for a texture. The bitmap data used in a normal map is split into the three components red, green and blue, each one giving a representation of the normal vector components in x, y and z respectively. So, normal values between -1 and 1 are discretised to an integer value between 0 and 255.
Normal maps greatly increase the performance of rendering a 3D object since the normals are given directly rather than requiring a calculation from triangles. So, a complex model requiring thousands of triangles can be reduced to, say, a few hundred (a low-poly model) with a normal map being derived from the original model. You can check out wikipedia for more information on normal mapping. For an example of a low-poly model using a normal map generated from a more complex one, check out this demo of normal mapping at Away3D.
Environment mapping, or reflection mapping, is a technique used to map a surrounding environment onto an object giving the impression that the object has a mirrored surface. The technique is much more efficient than ray tracing and, even though it is not exact, still produces realistic effects. Again, wikipedia contains some useful information on environment mapping.
In this tutorial I’m going to show normal mapping on a cube and a sphere and environment mapping on a sphere. Following from the last post on Lighting and Shading, we’re going to be using another couple of CompositeMaterials: namely the Dot3BitmapMaterial and the EnviroBitmapMaterial.
It should be noted that while normal mapping can produce a more realistic effect than bump mapping, it can be more complex to implement. Since a normal map replaces the normal to a surface we cannot use the same map on an object that has many faces (unless the normal map has been created specifically for example as shown in the Away3D demo above). This is a problem for example for Primitives. A Cube for example has six faces with six discrete principal normals - if we use the same normal map for each surface then each face will have the same normal data and hence be rendered identically, rather than each face being independent. Currently we therefore have to provide six independent normal maps.
My method for this example however is to create a cube using six individual planes using the same normal map and rotating and translating them: the normal map data is then rendered correctly for each face.
I also had a problem retrieving normal maps from the web for use in this tutorial. To help me I created a small utility that takes bump (displacement) map data and converts this into normal map data for either a plane or a sphere. You can try this out yourselves by checking out my article on displacement map to normal map conversion. With this utility you are able to specify the direction of the displacement (for a plane) or the direction against which the angle phi is calculated for a sphere.
So, lets get on with the code! Below you’ll see the next example in this series, producing three rotating texture-mapped objects each one rendered with either an environment map or normal map.
package { import away3d.cameras.HoverCamera3D; import away3d.containers.ObjectContainer3D; import away3d.containers.Scene3D; import away3d.containers.View3D; import away3d.core.render.Renderer; import away3d.core.utils.Cast; import away3d.lights.DirectionalLight3D; import away3d.materials.Dot3BitmapMaterial; import away3d.materials.EnviroBitmapMaterial; import away3d.primitives.Plane; import away3d.primitives.Sphere; import flash.display.Bitmap; import flash.display.BitmapData; import flash.display.Sprite; import flash.display.StageAlign; import flash.display.StageScaleMode; import flash.events.Event; import flash.events.MouseEvent; [SWF(backgroundColor="#000000")] public class Example006 extends Sprite { [Embed(source="/../assets/away3D.png")] private var Away3DImage:Class; private var away3DBitmap:Bitmap = new Away3DImage(); [Embed(source="/../assets/normalMap.png")] private var NormalImage:Class; private var normalBitmap:Bitmap = new NormalImage(); [Embed(source="/../assets/asteroidNormal.png")] private var SphereNormalImage:Class; private var sphereNormalBitmap:Bitmap = new SphereNormalImage(); [Embed(source="/../assets/checker.jpg")] private var CheckerImage:Class; private var checkerBitmap:Bitmap = new CheckerImage(); [Embed(source="/../assets/envMap.png")] private var EnvironmentImage:Class; private var envBitmap:Bitmap = new EnvironmentImage(); private static const ORBITAL_RADIUS:Number = 150; private static const CAMERA_ORBIT:Number = 600; private var scene:Scene3D; private var camera:HoverCamera3D; private var view:View3D; private var planeGroup:ObjectContainer3D; private var normalSphere:Sphere; private var envSphere:Sphere; private var doRotation:Boolean = false; private var lastMouseX:int; private var lastMouseY:int; private var lastPanAngle:Number = 60; private var lastTiltAngle:Number = -60; public function Example006() { // set up the stage stage.align = StageAlign.TOP_LEFT; stage.scaleMode = StageScaleMode.NO_SCALE; // Add resize event listener stage.addEventListener(Event.RESIZE, onResize); // Listen to mouse up and down events on the stage stage.addEventListener(MouseEvent.MOUSE_DOWN, onMouseDown); stage.addEventListener(MouseEvent.MOUSE_UP, onMouseUp); // Initialise Away3D init3D(); // Create the 3D objects createScene(); // Initialise frame-enter loop this.addEventListener(Event.ENTER_FRAME, loop); } /** * Initialise all 3D components. */ 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 HoverCamera3D({zoom:25, focus:30, distance:600}); camera.targetpanangle = camera.panangle = -10; camera.targettiltangle = camera.tiltangle = 20; camera.yfactor = 1; // Create a new view that encapsulates the scene and the camera view = new View3D({scene:scene, camera:camera}); // center the view to the middle of the stage view.x = stage.stageWidth / 2; view.y = stage.stageHeight / 2; // ensure that the z-order is calculated correctly view.renderer = Renderer.CORRECT_Z_ORDER; addChild(view); } /** * Create the objects and lighting of the scene */ private function createScene():void { // Create 3 different materials: two normal mapped ones (planar and spherical) and an // environment mapped one. var normalMapMaterial:Dot3BitmapMaterial = new Dot3BitmapMaterial(Cast.bitmap(away3DBitmap), Cast.bitmap(normalBitmap), {smooth:true, precision:5}); var envMapMaterial:EnviroBitmapMaterial = new EnviroBitmapMaterial(Cast.bitmap(checkerBitmap), Cast.bitmap(envBitmap), {smooth:true, precision:5}); var sphereNormalMapMaterial:Dot3BitmapMaterial = new Dot3BitmapMaterial(new BitmapData(1, 1, false, 0x666666), Cast.bitmap(sphereNormalBitmap), {smooth:true, precision:5}); // create a new directional white light source with specific ambient, diffuse and specular parameters var light:DirectionalLight3D = new DirectionalLight3D({color:0xFFFFFF, ambient:0.25, diffuse:0.75, specular:0.9}); light.x = 10000; light.z = 50000; light.y = 50000; scene.addChild(light); // Create six with the same (normal mapped) material and position them them to create a cube var topPlane:Plane = new Plane({material:normalMapMaterial, width:100, height:100, segmentsW:2, segmentsH:2, ownCanvas:true}); topPlane.y = 50; var leftPlane:Plane = new Plane({material:normalMapMaterial, width:100, height:100, segmentsW:2, segmentsH:2, ownCanvas:true}); leftPlane.rotationZ = 90; leftPlane.x = -50; var frontPlane:Plane = new Plane({material:normalMapMaterial, width:100, height:100, segmentsW:2, segmentsH:2, ownCanvas:true}); frontPlane.rotationX = 90; frontPlane.z = -50; var bottomPlane:Plane = new Plane({material:normalMapMaterial, width:100, height:100, segmentsW:2, segmentsH:2, ownCanvas:true}); bottomPlane.rotationX = 180; bottomPlane.y = -50; var rightPlane:Plane = new Plane({material:normalMapMaterial, width:100, height:100, segmentsW:2, segmentsH:2, ownCanvas:true}); rightPlane.rotationZ = -90; rightPlane.x = 50; var backPlane:Plane = new Plane({material:normalMapMaterial, width:100, height:100, segmentsW:2, segmentsH:2, ownCanvas:true}); backPlane.rotationX = -90; backPlane.z = 50; // Create an object container to group the sides of the cube planeGroup = new ObjectContainer3D(); scene.addChild(planeGroup); planeGroup.addChild(topPlane); planeGroup.addChild(leftPlane); planeGroup.addChild(frontPlane); planeGroup.addChild(bottomPlane); planeGroup.addChild(rightPlane); planeGroup.addChild(backPlane); planeGroup.x = -100; planeGroup.z = 100; // Create a sphere with normal-mapped material normalSphere = new Sphere({material:sphereNormalMapMaterial, radius:65, segmentsW:10, segmentsH:10, ownCanvas:true}); normalSphere.x = 100; normalSphere.z = 100; scene.addChild(normalSphere); // Create a sphere with environment-mapped material envSphere = new Sphere({material:envMapMaterial, radius:65, segmentsW:10, segmentsH:10, ownCanvas:true}); envSphere.z = -90; scene.addChild(envSphere); } /** * Frame-enter event handler */ private function loop(event:Event):void { // rotate the objects planeGroup.rotationY += 2; normalSphere.rotationY += 2; envSphere.rotationY += 2; // update camera position updateCamera(); camera.hover(); // Render the 3D scene view.render(); } /** * Update the camera position from mouse movements */ private function updateCamera():void { if (doRotation) { camera.targetpanangle = 0.5 * (stage.mouseX - lastMouseX) + lastPanAngle; camera.targettiltangle = 0.5 * (stage.mouseY - lastMouseY) + lastTiltAngle; } } /** * Mouse down listener for camera rotation */ private function onMouseDown(event:MouseEvent):void { lastPanAngle = camera.targetpanangle; lastTiltAngle = camera.targettiltangle; lastMouseX = stage.mouseX; lastMouseY = stage.mouseY; doRotation = true; stage.addEventListener(Event.MOUSE_LEAVE, onStageMouseLeave); } /** * Mouse up listener for camera rotation */ private function onMouseUp(event:MouseEvent):void { doRotation = false; stage.removeEventListener(Event.MOUSE_LEAVE, onStageMouseLeave); } /** * Mouse stage leave listener for camera rotation */ private function onStageMouseLeave(event:Event):void { doRotation = false; stage.removeEventListener(Event.MOUSE_LEAVE, onStageMouseLeave); } /** * Resize the scene when the stage resizes */ private function onResize(event:Event):void { view.x = stage.stageWidth / 2; view.y = stage.stageHeight / 2; } } }
If you want to use the same images as in this example then away3D.png and checker.jpg you’ll find in the previous post on texture mapping in Away3D. The new images are shown below.
The first two images (the normal maps) were created using the utility described above. The first one from a bump map I used for a Papervision3D tutorial on bump mapping, the second one comes from a bump map I found on the internet at gamedev.net. The environment map comes from and old OpenGL example I discovered on my hard disk… if you search for “opengl sphere map” in Google you’ll find plenty of instances!
Once its all compiled you should see three rotating objects with either normal and environment mapped data. Click on the image below to see the Flash movie. You can click anywhere and move the mouse to rotate the scene.
So, lets go into more detail on each part of the code. There’s nothing too complicated here but a few changes from the last time…
The first change comes from the initialisation of the 3D basics of the scene, specifically with the camera.
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 HoverCamera3D({zoom:25, focus:30, distance:600}); camera.targetpanangle = camera.panangle = -10; camera.targettiltangle = camera.tiltangle = 20; camera.yfactor = 1; // Create a new view that encapsulates the scene and the camera view = new View3D({scene:scene, camera:camera}); // center the view to the middle of the stage view.x = stage.stageWidth / 2; view.y = stage.stageHeight / 2; // ensure that the z-order is calculated correctly view.renderer = Renderer.CORRECT_Z_ORDER; addChild(view); }
I’ve now chosen to use a HoverCamera3D. This simplifies the movement and positioning of the camera. You’ll remember that previously I used the basic Camera3D class and had to calculate specific values of x, y and z as well as redirect the camera towards the origin. Much of this is included in the HoverCamera3D class. By specifying targettiltangle and targetpanangle the camera will calculate a trajectory necessary to move the camera to a new position and keep it focused on a particular target. To maintain the orbital radius of the camera we set the yfactor to 1 otherwise a more elliptical orbit is calculated.
You’ll see towards the end of the code how we perform an interaction with the camera. If we look at the loop function, called on every frame-enter event we can see how the camera position is updated.
private function loop(event:Event):void { // rotate the objects planeGroup.rotationY += 2; normalSphere.rotationY += 2; envSphere.rotationY += 2; // update camera position updateCamera(); camera.hover(); // Render the 3D scene view.render(); }
The object rotation is self evident so we’ll ignore that. The updateCamera function recalculates the camera position from mouse position. More importantly the camera.hover() call makes the camera move gradually towards the target tilt and pan angles giving a smoother animation of the camera than in previous examples.
For completeness, the updateCamera function and the mouseDown event listener are shown below.
private function updateCamera():void { if (doRotation) { camera.targetpanangle = 0.5 * (stage.mouseX - lastMouseX) + lastPanAngle; camera.targettiltangle = 0.5 * (stage.mouseY - lastMouseY) + lastTiltAngle; } } private function onMouseDown(event:MouseEvent):void { lastPanAngle = camera.targetpanangle; lastTiltAngle = camera.targettiltangle; lastMouseX = stage.mouseX; lastMouseY = stage.mouseY; doRotation = true; stage.addEventListener(Event.MOUSE_LEAVE, onStageMouseLeave); }
As you can see, the target angles are updated in the updateCamera function, taking into account the current mouse position. The onMouseDown function performs the necessary initialisation of pan and tilt angles. It also adds an event listener to detect when the mouse leaves the stage: this is useful because if the mouse button is released outside the stage, the onMouseUp listener is not called and we can obtain a state in which the scene is continuously rotated even if the mouse button is up.
So, on to more interesting elements of the code: normal mapped and environment mapped materials!
All the interesting stuff happens in createScene where the materials and objects are created.
private function createScene():void { // Create 3 different materials: two normal mapped ones (planar and spherical) and an // environment mapped one. var normalMapMaterial:Dot3BitmapMaterial = new Dot3BitmapMaterial(Cast.bitmap(away3DBitmap), Cast.bitmap(normalBitmap), {smooth:true, precision:5}); var envMapMaterial:EnviroBitmapMaterial = new EnviroBitmapMaterial(Cast.bitmap(checkerBitmap), Cast.bitmap(envBitmap), {smooth:true, precision:5}); var sphereNormalMapMaterial:Dot3BitmapMaterial = new Dot3BitmapMaterial(new BitmapData(1, 1, false, 0x666666), Cast.bitmap(sphereNormalBitmap), {smooth:true, precision:5}); // create a new directional white light source with specific ambient, diffuse and specular parameters var light:DirectionalLight3D = new DirectionalLight3D({color:0xFFFFFF, ambient:0.25, diffuse:0.75, specular:0.9}); light.x = 10000; light.z = 50000; light.y = 50000; scene.addChild(light); // Create six with the same (normal mapped) material and position them them to create a cube var topPlane:Plane = new Plane({material:normalMapMaterial, width:100, height:100, segmentsW:2, segmentsH:2, ownCanvas:true}); topPlane.y = 50; var leftPlane:Plane = new Plane({material:normalMapMaterial, width:100, height:100, segmentsW:2, segmentsH:2, ownCanvas:true}); leftPlane.rotationZ = 90; leftPlane.x = -50; var frontPlane:Plane = new Plane({material:normalMapMaterial, width:100, height:100, segmentsW:2, segmentsH:2, ownCanvas:true}); frontPlane.rotationX = 90; frontPlane.z = -50; var bottomPlane:Plane = new Plane({material:normalMapMaterial, width:100, height:100, segmentsW:2, segmentsH:2, ownCanvas:true}); bottomPlane.rotationX = 180; bottomPlane.y = -50; var rightPlane:Plane = new Plane({material:normalMapMaterial, width:100, height:100, segmentsW:2, segmentsH:2, ownCanvas:true}); rightPlane.rotationZ = -90; rightPlane.x = 50; var backPlane:Plane = new Plane({material:normalMapMaterial, width:100, height:100, segmentsW:2, segmentsH:2, ownCanvas:true}); backPlane.rotationX = -90; backPlane.z = 50; // Create an object container to group the sides of the cube planeGroup = new ObjectContainer3D(); scene.addChild(planeGroup); planeGroup.addChild(topPlane); planeGroup.addChild(leftPlane); planeGroup.addChild(frontPlane); planeGroup.addChild(bottomPlane); planeGroup.addChild(rightPlane); planeGroup.addChild(backPlane); planeGroup.x = -100; planeGroup.z = 100; // Create a sphere with normal-mapped material normalSphere = new Sphere({material:sphereNormalMapMaterial, radius:65, segmentsW:10, segmentsH:10, ownCanvas:true}); normalSphere.x = 100; normalSphere.z = 100; scene.addChild(normalSphere); // Create a sphere with environment-mapped material envSphere = new Sphere({material:envMapMaterial, radius:65, segmentsW:10, segmentsH:10, ownCanvas:true}); envSphere.z = -90; scene.addChild(envSphere); }
To start off with the three different materials are created. Firstly a Dot3BitmapMaterial taking the Away3D texture and a random normal map. I’ve chosen to smooth the material and have increased the precision of rendering to 5 pixels. The second material uses the EnviroBitmapMaterial using the checkered texture and the OpenGl sphere-map for the environment data, again smoothed as before. Incidentally, the shininess of the material can be modified by specifying the reflectiveness parameter in the initialisation parameters, taking a value between 0 and 1 (for most reflective). The final Dot3BitmapMaterial material, rather than using a bitmap file, creates a plain grey bitmap. The normal map comes from the asteroid spherical normal map.
We add a DirectionalLight3D to the scene to provide uniform lighting, independent of light distance. It should be noted that the Dot3BitmapMaterial will not currently work with a PointLight3D. Also, the EnviroBitmapMaterial is independent of the source: the environment map provides the equivalent shading.
For the cube we create six Planes, each using the same material. These are then rotated and translated to form a cube. They are finally added to a ObjectContainer3D so that we can rotate all of them together in the loop function. Note as well that, as before, each object needs to have its own canvas which is specified within the initialisation parameters.
The two spheres are then created: one using an environment map, the other with normal mapped data. These are then positioned and added to the scene, again with independent canvases.
And that’s all there is to it! As you’ll see, the normal map produces fantastic results and really adds a feeling of depth to the object surface. The environment map really gives the impression that the object is very shiny. These effects are very simple to produce in Away3D but be aware too that added realism comes at a cost - the frame rate is bound to be slower than without these effects - so be warned!
Anyway, I hope this has been a useful addition to basic lighting and shading. As always, let me know if you have any comments or questions!
Next article:
- First steps in Away3D : Part 7 - Movie and video materialsAdd depth to website by displaying interactive movies or videos as materials on 3D surfaces.
Friday, December 5th, 2008
I’m currently looking at the normal mapping materials that are available in Away3D and became aware that to do a decent test it’d be nice to be able create normal maps myself. Previously, when looking at lighting effects in Papervision3D, I created my own bump map from random data very easily. I’ve tried doing the same for a normal map but haven’t found a decent utility to help me do that… so, I decided to write one myself.
Assuming that the displacement map image is applied to a single surface, the normal to the surface can be calculated quite easily by taking the gradients in the x and y directions and calculating the cross product of the two (see this description from Wolfram MathWorld on surface normals for example).
Using the bitmap data (assuming it is greyscale), we can calculate the gradients using finite difference calculations using the pixel data as a height (displacement) and the pixel position as the x and y coordinates (again, Wolfram MathWorld on finite differences provides a useful source of information). The normals can then be calculated at each individual pixel and converted into red, green and blue data.
The Flex application shown below reads displacement map data, calculates the normals, and creates normal map data. You can check it out by clicking on the image below or visiting http://www.tartiflop.com/disp2norm/.
Note that this requires Flash Player 10 because it uses some of the new features available: namely reading and writing to the local file system and the use of the Vector3D class.
If you’re interested you can check out the source as well.
Two additional features are available:
- Selection of the displacement direction. For example if you have a displacement on a xz surface, for the lighting to be correct you need to specify that the displacement is in the y direction.
- Amplitude selection. You can modify the coarseness of the displacements by adjusting the amplitude factor - low is a smooth surface, high is a very rough surface.
Update !
The converter can now create normal maps for spherical objects too!
Simply select the Spherical radio button and the normal map will be produced for a sphere. It assumes that the displacement map data has also been created for a sphere. The axis from which phi is calculated can be chosen using the combo. For example, in Away3D, this is the y axis for the Sphere primitive.
For info, the normal is calculated differently (and more simply): from the pixel indices, equivalent to spherical positions, we can calculate Cartesian positions. These can be converted into vectors and hence the cross product of vectors running across the pixel (in latitude and longitude directions), taking into account the displacement map data, gives us directly the normal to the sphere… hope that makes some kind of sense!
If you have any comments or questions then please let me know!
