Sorry for the two month hiatus on posting. I was on a sabbatical and vacation from work for the last 6 weeks of 2009, and have spent the first couple of weeks of 2010 busy working on code, and preparing some events for the spring (more on that in another post).

Some of the stuff I have continued to spend a lot of time working on, has been building iPhone content using the Flash CS5 private beta. I have been doing a lot of work on trying to figure out how to get the best performance, and understand the limits of Flash content on the device. I plan to make a separate post on that in the next couple of days.

Anyways, the conference season is about to be in full swing, and the first talk I am doing this year, will be at FITC Amsterdam next month on Flash and iPhone. The talk is titled “Building High Performance iPhone Applications with ActionScript 3” and will discuss how to get the best performance from your Flash content, as well as what type of Flash content is best suited for the device. In addition to talking about some general tips and tricks, I will also be discussing some of the new hardware accelerated APIs, and showing some games I have been working on (including my new game Unicorn Bacon Adventure!).

If you are in Europe, and haven’t signed up for FITC yet, then what are you waiting for?!?!? This is one of the best conferences in the world, and the speaker line up for Amsterdam is simply amazing.

Prompted by some of the work from Grant Skinner (in particular his FOTB 2009 session) and Thibault Imbert, I have been doing a lot of research lately into optimizing ActionScript 3 content. Not just how to make it run faster, but how to approach the process of optimization.

I am also starting to work on a small project which works with pixel data from images, and on which I anticipate performance might be an issue when working with larger images. I figured this would be a good opportunity to use some of the early code as a case study. I wanted to post the process and results here.

The task that I will focus on is grabbing a palette of 16 colors from an image, created by averaging the colors within that image. Upon searching on google, I found a very good solution over at soulwire.co.uk, which I will use as the base for creating the palette. I want to point out that the original code targeted Flash Player 9 (and thus couldn’t take advantage of some things such as Vectors), and already ran pretty blazingly fast.

I am using Grant Skinner’s performance test harness to profile performance. Each test is run 50 times, and is tested in Flash Player MAC 10,0,32,18 (debug) in the browser.

You can download all of the code from here.

First, here is the original test case, based on soulwire’s code:

/*
	Code adapted from:
	http://blog.soulwire.co.uk/flash/actionscript-3/colourutils-bitmapdata-extract-colour-palette/
*/

package
{
	import flash.display.Bitmap;
	import flash.display.BitmapData;
	import flash.display.Sprite;
	import flash.events.Event;
	import flash.geom.Rectangle;
	import flash.geom.Point;

	import com.gskinner.utils.PerformanceTest;

	public class PixelSort extends Sprite
	{

		[Embed(source="../graphics/image.jpg")]
		public var TestImage:Class;

		public function PixelSort()
		{
			addEventListener(Event.ADDED_TO_STAGE, onAddedToStage);
		}

		private var d:BitmapData;
		private function onAddedToStage(evet:Event):void
		{
			removeEventListener(Event.ADDED_TO_STAGE, onAddedToStage);

			var b:Bitmap = new TestImage();

			d = b.bitmapData;

			var perfTest:PerformanceTest = PerformanceTest.getInstance();
			perfTest.out = trace;
			perfTest.testFunction(run, 50, "averagecolors", "averagecolors");
		}

		private function run():void
		{
			var out:Array = averagecolors(d, 16);
		}

		public function averageColour( source:BitmapData ):uint
		{
			var red:Number = 0;
			var green:Number = 0;
			var blue:Number = 0;

			var count:Number = 0;
			var pixel:Number;

			for (var x:int = 0; x < source.width; x++)
			{
				for (var y:int = 0; y < source.height; y++)
				{
					pixel = source.getPixel(x, y);

					red += pixel >> 16 & 0xFF;
					green += pixel >> 8 & 0xFF;
					blue += pixel & 0xFF;

					count++
				}
			}

			red /= count;
			green /= count;
			blue /= count;

			return red << 16 | green << 8 | blue;
		}		

		public function averagecolors( source:BitmapData, colors:int ):Array
		{
			var averages:Array = new Array();
			var columns:int = Math.round( Math.sqrt( colors ) );

			var row:int = 0;
			var col:int = 0;

			var x:int = 0;
			var y:int = 0;

			var w:int = Math.round( source.width / columns );
			var h:int = Math.round( source.height / columns );

			for (var i:int = 0; i < colors; i++)
			{
				var rect:Rectangle = new Rectangle( x, y, w, h );

				var box:BitmapData = new BitmapData( w, h, false );
				box.copyPixels( source, rect, new Point() );

				averages.push( averageColour( box ) );
				box.dispose();

				col = i % columns;

				x = w * col;
				y = h * row;

				if ( col == columns - 1 ) row++;
			}

			return averages;
		}
	}
}

And here is the initial performance test:

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
averagecolors (50 iterations)
Player version: MAC 10,0,32,18 (debug)
averagecolors
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
method...................................................ttl ms...avg ms
averagecolors                                              1264    25.28
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––

First, considering what the code is doing, it is already pretty fast, taking only 25 ms to split the image into a grid, and loop through all of the pixels and averaging the values. However, there is probably some room for improvement, especially given that the original code targets Flash Player 9 and thus cant take care of Flash Player 10 optimizations such as using Vectors.

Now, the first thing I would normally do is to profile the SWF using the profiler in Flash Builder to find out where the most time is being sent. However, in this case, there are only two methods that do anything, averageColors and averageColor. averageColors is called once, while averageColor is called once for each swatch we want to create (in this case 16), and ends up looping over each pixel in the image (over those 16 calls). So these are the two areas we will focus on, with particular attention directed to averageColor.

The first thing I did was look at updating the content to Flash Player 10 by converting all of the Arrays to Vectors. I expected to get a decent boost from this, but the improvement was minimal.

Within the averageColors method, I looked at reusing the Point, Rectangle and BitmapData instances, instead of creating new ones on each iteration of the loop. Again, on the desktop this didn’t really make any difference. However, one thing to consider is that on a mobile device where memory allocation can be more expensive (and there is less RAM altogether), this change may have had a bigger impact (which I didnt test). This leads to an important point. It is important to test performance on the platforms which you are targeting, as some optimizations can have a different impact depending on where the content is running.

Next, I set the averageColor and averageColors methods as final, which allows them too be looked up at compile time (as opposed to runtime), this led to small improvement in performance, but again, not really anything significant.

At this point, I was getting a very slight performance improvement, but not really anything that mattered (basically, small enough to be insignificant),

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
averagecolors (50 iterations)
Player version: MAC 10,0,32,18 (debug)
averagecolors
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
method...................................................ttl ms...avg ms
averagecolors                                              1224    24.48
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––

Next, I moved on to the averageColor method, where I expected (and hoped) to have better results, as this is where the bulk of the work occurs.

First I converter some of the Numbers to ints and uints in places where Numbers were not needed. This led to a small improvement.

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
averagecolors (50 iterations)
Player version: MAC 10,0,32,18 (debug)
averagecolors
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
method...................................................ttl ms...avg ms
averagecolors                                              1190    23.80
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––

Next, I changed the bitmapData.getPixel call to use bitmapData.getVector. Doing this then allowed me to loop through the pixels using a single loop, instead of a nested double loop, and also eliminated a getPixel call for each pixel. I used a for each loop to loop through the pixel color values.

This provided another slight improvement (although not quite as much as I expected). We are now making some small gains.

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
averagecolors (50 iterations)
Player version: MAC 10,0,32,18 (debug)
averagecolors
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
method...................................................ttl ms...avg ms
averagecolors                                              1137    22.74
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––

Next, I decided to try a for loop, instead of a for each loop.

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
averagecolors (50 iterations)
Player version: MAC 10,0,32,18 (debug)
averagecolors
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
method...................................................ttl ms...avg ms
averagecolors                                               282     5.64
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––

Wow! As you can see, that makes a huge difference.

Finally, I explicitly cast i to an int when pulling the value from the Vector. This gave a small improvement, but again, nothing significant:

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
averagecolors (50 iterations)
Player version: MAC 10,0,32,18 (debug)
averagecolors
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
method...................................................ttl ms...avg ms
averagecolors                                               268     5.36
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––

I tried a couple of more optimizations in the method, around converting division operations to multiplication operation, and replacing Math.round calls but in this case it didnt make any difference.

I also looked at caching some constants used in some of the bitwise operations, changing

red += pixel >> 16 & 0xFF;
green += pixel >> 8 & 0xFF;

to

private var s16:Number = 16 & 0xFF;
private var s8:Number = 8 & 0xFF;

red += pixel >> s16;
green += pixel >> s8;

First, that optimization actually produces the wrong result (I had my operator precedence backwards). Second, it was actually slower:

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
averagecolors (50 iterations)
Player version: MAC 10,0,32,18 (debug)
averagecolors
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
method...................................................ttl ms...avg ms
averagecolors                                               349     6.98
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––

There are two lessons from this. First, make sure your optimizations produce the same results (ideally by creating and using unit tests). Second, bitwise operations are really, really fast. In this case, they are even faster than doing a variable lookup.

So, after going through the code, and applying a number of different optimizations, I was able to improve performance from an average of 25.28 ms, to 5.36 ms, an improvement of about 470%.

Here is the final code:

/*
	Code adapted from:
	http://blog.soulwire.co.uk/flash/actionscript-3/colourutils-bitmapdata-extract-colour-palette/
*/

package
{
	import flash.display.Bitmap;
	import flash.display.BitmapData;
	import flash.display.Sprite;
	import flash.events.Event;
	import flash.geom.Rectangle;
	import flash.geom.Point;

	import com.gskinner.utils.PerformanceTest;

	public class PixelSort extends Sprite
	{

		[Embed(source="../graphics/image.jpg")]
		public var TestImage:Class;

		public function PixelSort()
		{
			addEventListener(Event.ADDED_TO_STAGE, onAddedToStage);
		}

		private var d:BitmapData;
		private function onAddedToStage(evet:Event):void
		{
			removeEventListener(Event.ADDED_TO_STAGE, onAddedToStage);

			var b:Bitmap = new TestImage();

			d = b.bitmapData;

			var perfTest:PerformanceTest = PerformanceTest.getInstance();
			perfTest.out = trace;
			perfTest.testFunction(run, 50, "averagecolors", "averagecolors");
		}

		private function run():void
		{
			var out:Vector.<uint> = averagecolors(d, 16);
		}		

		public final function averageColour( source:BitmapData ):uint
		{
			var red:Number = 0;
			var green:Number = 0;
			var blue:Number = 0;

			var count:int = 0;
			var pixel:uint;

			var pixels:Vector.<uint> = source.getVector(new Rectangle(0,0, source.width, source.height));
			var len:int = pixels.length;

			for(var i:int = 0; i < len; i++)
			{
				pixel = pixels[int(i)];

				red += pixel >> 16 & 0xFF;
				green += pixel >> 8 & 0xFF;
				blue += pixel & 0xFF;

				count++;
			}

			red /= count;
			green /= count;
			blue /= count;

			return red << 16 | green << 8 | blue;
		}		

		public final function averagecolors( source:BitmapData, colors:int ):Vector.<uint>
		{

			var averages:Vector.<uint> = new Vector.<uint>(colors, false);
			var columns:int = Math.round( Math.sqrt( colors ) );

			var row:int = 0;
			var col:int = 0;

			var x:int = 0;
			var y:int = 0;

			var w:int = Math.round( source.width / columns );
			var h:int = Math.round( source.height / columns );

			var p:Point = new Point();
			var rect:Rectangle = new Rectangle(0,0,0,0);
			var box:BitmapData = new BitmapData( w, h, false );

			for (var i:int = 0; i < colors; i++)
			{
				rect.x = x;
				rect.y = y;
				rect.width = w;
				rect.height = h;

				box.copyPixels( source, rect, p );

				averages[i] =  averageColour( box );

				col = i % columns;

				x = w * col;
				y = h * row;

				if ( col == columns - 1 )
				{
					row++;
				}
			}
			box.dispose();
			return averages;
		}
	}
}

Lessons learned

Profile content to isolate bottlenecks : I skipped that step in this case since my code consisted of only two methods, but even in that case, the most significant improvement came from a single optimization. Profile so you know where to focus your efforts.

Test and profile all optimizations : Make sure to test performance after each optimization, as optimizations do not always have the desired effect.

Test on target devices and platforms : Optimizations can have a different impact on where they are run. This includes browser, platform and device, as well as player type (debug vs release). For example, when testing directly from Flash Authoring, results where significantly slower than when testing in the browser.

Test the results of the optimizations : Make sure that your optimizations do not break your code or content. The best way to do this is by using unit tests and running them after each optimization.

There is still some potential for optimization. In particular, since the code is essentially looping over all of the pixels of a bitmap and then doing some math operations on their values, this could be a good candidate for porting to PixelBender.

If you have any additional optimizations, questions or suggestions, post them in the comments.

Also, make sure to check out soulwire’s blog, as he is doing some very cool stuff with ActionScript 3 and Flash.

I dont have a formal computer science training / education, so I never got the chance to learn about working with low level data structures (bits and bytes). I have wanted to learn this for some time, but had difficulty finding resources for it which didnt assume I had a computer science degree.

Well, yesterday, FITC posted all of the video sessions from FITC Toronto, and I spent some time watching Lee Brimelow’s presentation on working with ByteArrays. It is a really great session, that provides a clear and solid foundation and understanding of working with ByteArrays and bits and bytes.

Anyways, after watching Lee’s session, it all finally clicked for me, and I spent some time last night putting together a simple parser that would dynamically load and display a 24Bit BMP image file within Flash.

I wanted to post the code below, along with complete comments, in order to provide a simple, real world example for anyone else interested in learning how to work with lower level file formats.

The code requires Adobe AIR (so I can load the BMP directly). In order to convert to the Flash Player in the browser, just replace the File loading with FileReference.browse.

package
{
	import flash.filesystem.File;
	import flash.filesystem.FileStream;
	import flash.filesystem.FileMode;

	import flash.display.Sprite;
	import flash.display.BitmapData;
	import flash.display.Bitmap;
	import flash.utils.Endian;

	import flash.geom.Rectangle;

	[SWF(width='550', height='400', backgroundColor='#FFFFFF', frameRate='12')]
	public class BMPViewer extends Sprite
	{
		private static const MAGIC_NUMBER:String = "BM";
		private static const BMP_DATA_OFFSET_POSITION:int = 0xA;
		private static const WIDTH_POSITION:int = 0x12;
		private static const HEIGHT_POSITION:int = 0x16;

		public function BMPViewer()
		{
			loadBMP();
			super();
		}

		/*
			Loads and reads a 24 Bit bitmap file.
			
			Based on BMP info from:
			http://en.wikipedia.org/wiki/BMP%5Ffile%5Fformat
		*/
		private function loadBMP():void
		{
			//Load BMP. This requires AIR.
			//Use FileReference.browse for
			//Flash Player
			var bmpFile:File = new File("app:/image.bmp");
			var fs:FileStream = new FileStream();

			//BMP files are Little Endian, which means their
			//least significant byte is first (right to left)
			fs.endian = Endian.LITTLE_ENDIAN;

			//open the file in READ mode
			fs.open(bmpFile, FileMode.READ);

			//check the first two bytes to make sure
			//it is a valid BMP file
			if(fs.readUTFBytes(2) != MAGIC_NUMBER)
			{
				trace("FAIL : NOT A BMP FILE");

				//not a BMP file, close steam
				//and exit
				fs.close();
				return;
			}

			//note, we could also grab the length from the 
			//header and make sure the file was the correct
			//length

			//change the cursors position to the point
			//in the header that contains the value / offset
			//of where the actual bitmap data begins
			//read in the 4 Bytes that contain the value
			fs.position = BMP_DATA_OFFSET_POSITION;
			var dataPosition:int = fs.readInt();

			//set cursor position to where the BMP
			//width is stored
			fs.position = WIDTH_POSITION;

			//read in the 4 Bytes that contain the width
			var bmpWidth:int = fs.readInt();

			//read in the 4 Bytes that contain the height
			var bmpHeight:int = fs.readInt();

			//set cursor to where the BMP pixel data begins
			fs.position = dataPosition;

			var row:int = 0;
			var column:int = 0;

			//every row length in a BMP file must bee a multiple
			//of 4 (see the spec). So, we need to determine how much
			//padding we need to add at the end of each line. 
			var padding:int = (bmpWidth % 4);

			//create a fixed length Vector to store the pixel
			//values as we read them.
			var pixels:Vector.<uint> = new Vector.<uint>(bmpWidth * bmpHeight, true);

			//loop through data (rows and columns)
			//note that data stored in BMP is backwards to Flash and is
			//stored from bottom row up, not top row down.
			//So we have to loop backwards
			var counter:int = 0;
			for(var i:int = bmpHeight; i > 0; i--)
			{
				for(var k:int = 0; k < bmpWidth; k++)
				{

					var position:int = ((i - 1) * bmpWidth) + k;
					/*
						This is the original code that I had which works fine
						but is not as effecient as what I have now.
						
						Basically, Pixels are stored within 3 sucessive Bytes
						in a BMP file, with one Byte each for Blue, Green and
						Red values (in that order).
						
						So, this reads the Bytes for each pixel, one at a time
						and then combines them into a single value which is
						the combined RGB pixel value.
						
						I left the code as I think it make it a little easier to
						understand what is going on, as well as how some of these
						calls can be optimized.
					*/

					/*
					var blue:int = fs.readUnsignedByte();
					var green:int = fs.readUnsignedByte();
					var red:int = fs.readUnsignedByte();
					
					pixels[position] = (red << 16 ^ green << 8 ^ blue);
					*/

					/*
						Here is the final code which is more efficient, as it only
						needs to make 2 read calls in order to get the values.
						
						Thanks to Thibault Imbert (bytearray.org) for pointing out
						and helping me understand the optimization.
					*/

					//bytes in file are in Blue, Green, Red order
					//int is 32 bits (8 bytes). So, we store the first two bytes of the pixel
					// (which contain the Red value), and
					//then shift everything over 1 byte (8bits) to make room for
					//the green and blue values (remember the file is little endian), which we
					// then write into the int in the right position
					//The final value has the colors in the correct order (Red, Green, Blue)

					var pixelValue:uint = fs.readUnsignedByte() | fs.readUnsignedShort() << 8;
					pixels[position] = pixelValue;
				}

				//we are at the end of the row, so now we have to move the cursor
				//forward so it ends on a multiple of 4
				if(padding)
				{
					fs.position += padding;
				}
			}

			//done reading file, close stream.
			fs.close();

			//create a Rectangle with width / height of Bitmap
			var rect:Rectangle = new Rectangle(0, 0, bmpWidth, bmpHeight);

			//create the BitmapData object to hold hold the BMP data.
			//we do a red fill here so it is easier to see if we have any errors
			//in our code
			var bmpData:BitmapData = new BitmapData(bmpWidth, bmpHeight, false, 0xFF0000);

			//copy the BMP pixel data into the BitmapData
			bmpData.setVector(rect, pixels);

			//create a new Bitmap instance using the BitmapData
			var bitmap:Bitmap = new Bitmap(bmpData);
			bitmap.x = 10;
			bitmap.y = 10;

			//add Bitmap to the display list
			addChild(bitmap);
		}
	}
}

You can download the example from here.

Thanks to Lee for his presentation, and Thibault Imbert who helped me understand some of the details around endianes, as well as made some suggestions for optimizations.

If you are interested in learning more, I strong suggest watching Lee’s FITC Presentation.

For the past month or two, I have been spending time building a game (something I havent done since my Flash 4 days). This has really been a lot of fun, as it has allowed me to use some of the Flash Player APIs which I really haven’t had a chance or need to use before.

One thing which I have been (slowly) learning about are using Matrix transformations on DisplayObjects. I made a post earlier showing how (with much, much help from Senocular), I was able to use Matrix to do hit tests using BitmapData.hitTest on DisplayObjects which have had transformations applied to them (in this case, rotation).

Well, I recently had the need to convert some of my DisplayObjects to use the 2.5D APIs (by setting the z property to a value). Unfortunately, this ended up breaking a lot of my code, mostly because of how it changes how transformations are applied to a DisplayObject. Specifically, when you set the DisplayObject.z property to any value, DisplayObject.transform.matrix will return null, and you must use DisplayObject.transform.matrix3D instead. Where this causes problems is when you are using APIs that expect to use a Matrix instance, as opposed to Matrix3D instance, such as BitmapData.draw.

This is exactly the scenario I ran into, and this post will show one solution for how to convert from a Matrix3D to a Matrix instance, which can then be passed to the BitmapData.draw.

First, lets look at my original code:

shipBmpData = new BitmapData(shipBounds.width,
				shipBounds.height, true, 0);

var shipOffset:Matrix = ship.transform.matrix;
shipOffset.tx = ship.x - shipBounds.x;
shipOffset.ty = ship.y - shipBounds.y;			

shipBmpData.draw(ship, shipOffset);

Basically, this draws the bitmap data for my ship into a BitmapData instance, taking into account any transformations which have been applied to the ship (in this case rotation). In my code, this bitmap data is cached, and then later used with BitmapData.hitTest for collision detection (not shown here).

However, as soon as I set the z property on the ship (which is a DisplayObject), this code will no longer work, as ship.transform.matrix will return null (since 3D transformations are now being used).

At first, I figured I would just change my code to access the Matrix3D instance like so:

var shipOffset:Matrix3D = ship.transform.matrix3D;

and then pass this to the BitmapData.draw API. However, I was quickly reminded (by the compiler) that Matrix3D does not inherit from Matrix, and thus cannot be passed to BitmapData.draw.

Because of this I needed to convert from a Matrix3D to a Matrix instance, which could then be passed to BitmapData.draw. After some help from Ralph Hauwert (who tracked down a couple of bugs) I was able to get it working.

Before I show the code, it will be useful to look at which values Matrix and Matrix3D contain. First, here are the values held by a Matrix instance:

a  c  tx
b  d  ty
u  v  w

You can find a description of the properties in the Matrix docs.

Here are the values held by a Matrix3D instance:

scaleX  0         0          tx
0         scaleY  0          ty
0         0           scaleZ  tz
0         0          0          tw

From the Matrix3D docs:

The Matrix3D class uses a 4×4 square matrix: a table of four rows and columns of numbers that hold the data for the transformation. The first three rows of the matrix hold data for each 3D axis (x,y,z). The translation information is in the last column. The orientation and scaling data are in the first three columns. The scaling factors are the diagonal numbers in the first three columns

Basically, in addition to holding values for x and y, the Matrix3D class also has slots for z properties. Because the Matrix is a 3×3 matrix, and the Matrix3D is a 4×4 matrix converting from Matrix3d to Matrix means that we will have to discard some information. Luckily, in my case, I didnt need the z information, so i was able to discard it and map the related x, y values to the Matrix instance. We can then pass this new Matrix instance to the BitmapData.draw class.

For our purposes, the Matrix3D mapping to Matrix is:

a  c   0          tx
b  d  0          ty
0  0  scaleZ  tz
0  0  0          tw

Here is the code that maps between the two:

var shipOffset:Matrix3D = ship.transform.matrix3D;

var rawMatrixData:Vector.<Number> = shipOffset.rawData;

var matrix:Matrix = new Matrix();
matrix.a = rawMatrixData[0];
matrix.c = rawMatrixData[1];
matrix.tx = ship.x - shipBounds.x;

matrix.b = rawMatrixData[4];
matrix.d = rawMatrixData[5];
matrix.ty = ship.y - shipBounds.y;

ship.transform.matrix3D = null;
shipBmpData.draw(ship, matrix);
ship.transform.matrix3D = shipOffset;

Basically, we get an instance of the Matrix3D class for the DisplayObject. We then access the raw data of the Matrix3D instance, and copy it into a new Matrix instance (ignoring and dropping the z values), and apply the transformation corrections in the process.

We can then pass this new Matrix instance to the BitmapData.draw API. However, as you probably noticed in the code, I had to first do an additional step. Specifically:

ship.transform.matrix3D = null;
shipBmpData.draw(ship, matrix);
ship.transform.matrix3D = shipOffset;

Before we draw the data to the BitmapData instance, we have to clear out the existing Matrix3D applied to the DisplayObject. This is to work around a bug discovered by Ralph Hauwert. When passing a DisplayObject which does not have a Matrix3D transformation (as in our first example) to BitmapData.draw, any transformations on the DisplayObject ARE NOT taken into account when drawing. However, when the the DisplayObject does have a Matrix3D transformation applied to it (such as when the z property has been set to a value), then any transformations ARE applied when drawing to BitmapData.draw. Because of this, we have to first store the Matrix3D associated with the DisplayObject, set it to null, draw the DisplayObject to the BitmapData instance, and then reapply the Matrix3D to the DisplayObject.

Update: as Ben Garney points out in the comments, since the transformation is applied to BitmapData.draw when Matrix3D is set, all we need to do is pass in either an identiy matrix, or null to the second argument of the API. So, in my case, this solves my problems, and removes the need to convert bewteen the matrix types.

The updated code is simply:

shipBmpData = new BitmapData(shipBounds.width,
				shipBounds.height, true, 0);
shipBmpData.draw(ship, null);

which turns out to be much less complex than when you use the 2D APIs. However, the technique above for converting between matrix types is still valid.

Update 2: It turns out passing in null or an identity matrix to BitmapData.draw. does not work correctly.

Of course, this is not always necessary when converting from a Matrix instance to a Matrix3D instance, but in my case it was. As you can imagine, this can have some significant performance implications, both because of memory allocation and deallocation, as well as the fact that removing the Matrix3D, even temporarily, changes how the DisplayObject is rendered.

Right now, this trade off is ok in my case, although I am not sure if it will be for the long term. Again, in my case, I may need to look at some re-architecting so I don’t have to work around this issue (such as nesting clips and cacheing the parent BitmapData, so I don’t have to apply the transformations).

Anyways, I am just learning the implications of using the 2.5D APIs in the Flash Player. This is an area where there is not currently a lot of information or documentation, especially information on the implications of moving from 2D to 2.5D APIs. Hopefully this will be useful.

Here are a couple of other resources which I found useful:

API docs for Matrix, Matrix3D, Transformation and DisplayObject.

Thibault Imbert’s Flash Player 10 Presentation, which has some good info on the 2.5D APIS.

Flash CS4 Docs : Working in three dimensions

As I mentioned above, I am still getting my head around some of this stuff, so if you have any clarifications or corrections, post them in the comments.

I have been learning some game development lately, and building my first game (well, at least my first game since Flash 4). I think game development and deployment are some of the real strengths of the Flash player, but ones which we haven’t specifically focused on in a while.

While working on my game, there were a couple of things I needed to do where additional player APIs could have made the development easier (as well as likely speeding up execution). This got me to thinking about other APIs that would be useful for game development. So, what new Flash Player APIs would you like to see that would make game development easier?

Here are a couple from me:

Hit test that tests visible bounds of Sprites. Something like:

sprite.hitTestVisible(anotherSprite):Boolean

Basically, something similar the API Grant Skinner created, but native to the player.

The next API I would like is one that would check for hits against multiple sprites, and return a vector of sprites that we colliding.

sprite.hitTestMultiple(sprites:Vector.<Sprite>):Vector.<Sprite>;

This would make it easy to do collision detection for multiple items, and perhaps lead to a performance boost.

So, what APIs would you like to see that would make game development easier. Please be as specific as possible (i.e. don’t just say “Physics engine” or 3D support). Leave you suggestions in the comments.

Darron Schall has just checked in some changes and bug fixes to the JSON support in as3corelib. Among other things, Darron has added a strict mode which allows you to specify how strict of a conformance to the JSON spec you want the library to follow.

You can read all of the details over on Darron’s blog. As Darron notes, these are not in the build yet, so if you want to play around with the changes, you have to grab the source.

I will try and do a new build soon with some more JSON changes, as well as some new code contributed from the community.

As you have probably seen, Adobe has dropped the licensing restrictions on both the SWF and FLV file formats. Among other things, you can know use the formats to create players that read in the formats.

Check out Ryan Stewart’s weblog for more discussion

We have also put up a site with some information, which includes a FAQ.

You can also download the specs:

• SWF 9
• FLV
• AMF Specification

Continuing my series of posts of interesting, but not too useful ActionScript tips (which I learned from studying Objective-C), did you know that you dont have to initialize your counter variable within a for loop.

For example, this is perfectly valid:

package {
	import flash.display.Sprite;

	public class LoopTest extends Sprite
	{
		public function LoopTest()
		{
			var i:int = 0;
			for(; i < 5; i++)
			{
				trace(i);
			}

		}
	}
}

As you can see, the variable is initialized outside of the loop.

You also don't have to include the test condition in the loop:

package {
	import flash.display.Sprite;

	public class LoopTest extends Sprite
	{
		public function LoopTest()
		{
			var i:int = 0;
			for(; ; i++)
			{
				trace(i);

				if(i > 5)
				{
					break;
				}
			}

		}
	}
}

However, if you do this (which you probably shouldn't) you have to have code in the loop to exit, or else you will freeze up the player with an infinite loop.

And what the heck, lets get rid of incrementing the variable in the loop definition:

package {
	import flash.display.Sprite;

	public class LoopTest extends Sprite
	{
		public function LoopTest()
		{
			var i:int = 0;
			for(; ; )
			{
				trace(i);

				if(i > 5)
				{
					break;
				}

				i++;
			}

		}
	}
}

I can't think of any reasons off the top of my head why this would be useful, but if you have any thoughts / uses, post them in the comments.

I have been studying some Objective-C in my spare time, and was reading up on Bitwise operators tonight. I came across a simple way to exchange the value of two variables using the Exclusive-OR (XOR) operator that doesn’t require creating a temporary variable.

Normally, if you wanted to exchange the value of two variables, you would have to create a temp variable to store values temporarily (which uses additional memory). For example:

package
{
	import flash.display.Sprite;
	import flash.system.System;

	public class SwitchVariables extends Sprite
	{
		public function SwitchVariables()
		{
			var a:int = 5;
			var b:int = 6;
			var temp:int;

			trace("a = " + a + " : b = " + b);

			temp = a;
			a = b;
			b = temp;

			trace("a = " + a + " : b = " + b);
		}
	}
}

Notice that you have to create an additional variable, named temp to temporarily store the value while it is switched.

However, you can use the Bitwise XOR Operator to switch the values without having to create the temporary variable. For example:

package
{
	import flash.display.Sprite;
	import flash.system.System;

	public class SwitchVariables extends Sprite
	{
		public function SwitchVariables()
		{
			var a:int = 5;
			var b:int = 6;

			trace("a = " + a + " : b = " + b);

			a ^= b;
			b ^= a;
			a ^= b;

			trace("a = " + a + " : b = " + b);
		}
	}
}

You can find a good explanation of what the Exclusive OR operator does here and a discussion of the XOR swap algorithm here.

This is probably not needed in most cases (it can make the code a little harder to read), but if you are exchanging the value of variables in a loop and running into memory issues, this might come in handy.

Have any other bitwise operator tips? Post them in the comments.

Denis Sosnovtsev has posted a really useful blog post over on the atellis labs site. The post shows how to upload files from Flash to a .NET backend. The example includes both ActionScript and .NET / C# code snippets.

You can view the entire post here.

You can also view Mark Piller’s session from the on AIR Bus tour on integrating .NET with Adobe AIR applications.

Know any other good ActionScript / .NET resources and tutorials? Post them in the comments.