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.

If you have read my blog any this week, you have probably noticed that I have been doing some basic research on collision detection within the Flash Player. As part of this, I have put together a simple test suite, showing the performance of a couple of different techniques for checking for collision. This is by no means meant to be exhaustive (and currently tilts towards boundary collision). However, I wanted to post the results as the current information is useful (if nothing more than to confirm existing assumptions), and perhaps generate more tests an ideas around collision detection.

First, the test code (uses Flash Pro). clip1 and clip2 reference two overlapping MovieClips on the stage (clip2 is about 1/2 the size of clip1).

package
{
	import flash.display.MovieClip;
	import flash.geom.Point;
	import flash.display.Bitmap;
	import flash.display.BitmapData;
	import flash.geom.Rectangle;

	import com.gskinner.utils.PerformanceTest;

	public class CollisionDetectionTests extends MovieClip
	{
		public var clip1:MovieClip;
		public var clip2:MovieClip;

		private var dynamicClip1:MovieClip;
		private var dynamicClip2:MovieClip;	

		var point1:Point = new Point();
		var point2:Point = new Point();

		private var clip1Rect:Rectangle;
		private var clip1ClipBmpData:BitmapData;
		private var clip2Rect:Rectangle;
		private var clip2ClipBmpData:BitmapData;

		public function CollisionDetectionTests()
		{
			super();

			init();
			checkCollisions();
			runTests();
		}

		private function init():void
		{

			clip1Rect = clip1.getBounds(this);
			clip1ClipBmpData = new BitmapData(clip1Rect.width, clip1Rect.height, true, 0);
			clip1ClipBmpData.draw(clip1);

			clip2Rect = clip2.getBounds(this);
			clip2ClipBmpData = new BitmapData(clip2Rect.width, clip2Rect.height, true, 0);
			clip2ClipBmpData.draw(clip2);

			dynamicClip1 = new MovieClip();

			dynamicClip1.graphics.beginFill(0xFF0000);
			dynamicClip1.graphics.drawEllipse(0,0, 100,100);
			dynamicClip1.cacheAsBitmap = true;

			dynamicClip1.x = 300;
			dynamicClip1.y = 300;

			addChild(dynamicClip1);

			dynamicClip2 = new MovieClip();

			dynamicClip2.graphics.beginFill(0x0000FF);
			dynamicClip2.graphics.moveTo(0, 0);
			dynamicClip2.graphics.lineTo(100, 0);
			dynamicClip2.graphics.lineTo(100, 100);
			dynamicClip2.graphics.lineTo(0, 100);
			dynamicClip2.graphics.lineTo(0, 0);
			dynamicClip2.cacheAsBitmap = true;

			dynamicClip2.x = 250;
			dynamicClip2.y = 250;

			addChild(dynamicClip2);
		}

		private function checkCollisions():void
		{
			//make sure everything is working and returns true
			trace(checkHitTest());
			trace(boundsIntersection());
			trace(checkHitTestReverse());
			trace(checkBoundsManually());
			trace(hitTestCircle());
			trace(checkBitmapDataHit());
			trace(checkBitmapDataHitReverse());
			trace(checkBitmapDataHitInternal());
			trace(checkBitmapDataHitDynamic());
		}

		private function runTests():void
		{
			var perfTest:PerformanceTest = PerformanceTest.getInstance();
			perfTest.out = out;

			//this is to work around bug in test lib
			perfTest.testSuite({});

			perfTest.testFunction(checkHitTest, 10000, "checkHitTest", "Uses DisplayObject.hitTest");
			perfTest.testFunction(checkHitTestReverse, 10000, "checkHitTestReverse", "Uses DisplayObject.hitTest with clips reversed");
			perfTest.testFunction(boundsIntersection, 10000, "boundsIntersection", "Uses Rectangle.intersects()");
			perfTest.testFunction(checkBoundsManually, 10000, "checkBoundsManually", "manually checks if bounds intersect.");
			perfTest.testFunction(hitTestCircle, 10000, "hitTestCircle", "Check if bounding circles intersect.");
			perfTest.testFunction(checkBitmapDataHit, 10000, "checkBitmapDataHit", "Uses BitmapData.hitTest to check for collision.");
			perfTest.testFunction(checkBitmapDataHitReverse, 10000, "checkBitmapDataHitReverse", "Uses BitmapData.hitTest to check for collision. Instances reversed.");
			perfTest.testFunction(checkBitmapDataHitInternal, 10000, "checkBitmapDataHitInternal", "Uses BitmapData.hitTest to check for collision. BitmapData not cached.");
			perfTest.testFunction(checkBitmapDataHitDynamic, 10000, "checkBitmapDataHitDynamic", "Uses BitmapData.hitTest to check for collision. BitmapData not cached. MovieClips dynamic.");
		}

		private function checkHitTest():Boolean
		{
			return clip1.hitTestObject(clip2);
		}

		private function checkHitTestReverse():Boolean
		{
			return clip2.hitTestObject(clip1);
		}

		private function boundsIntersection():Boolean
		{
			return clip1.getBounds(this).intersects(clip2.getBounds(this));
		}

		private function hitTestCircle():Boolean
		{
			var dx:Number = (clip2.x + clip2.width / 2) - (clip1.x + clip1.width / 2);
			var dy:Number = (clip2.y + clip2.height / 2) - (clip1.y + clip1.height / 2);
			var dist:Number = Math.sqrt(dx * dx + dy * dy);

			return (dist < ((clip1.width / 2) + (clip2.width / 2)));
		}

		private function checkBoundsManually():Boolean
		{
			if(clip1.x < clip2.x + clip2.width &&
			   clip2.x < clip1.x + clip1.width &&
			   clip1.y < clip2.y + clip2.height &&
			   clip2.y < clip1.y + clip1.height
			   )
			{
				return true;
			}

			return false;
		}

		private function checkBitmapDataHit():Boolean
		{
			point1.x = clip1.x;
			point1.y = clip1.y;

			point2.x = clip2.x;
			point2.y = clip2.y;
			if(clip1ClipBmpData.hitTest(point1,
										255,
										clip2ClipBmpData,
										point2,
										255

								  ))
			{
				return true;
			}

			return false;
		}

		private function checkBitmapDataHitInternal():Boolean
		{
			var _clip1Rect:Rectangle = clip1.getBounds(this);
			var _clip1ClipBmpData:BitmapData = new BitmapData(_clip1Rect.width, _clip1Rect.height, true, 0);
			_clip1ClipBmpData.draw(clip1);

			var _clip2Rect:Rectangle = clip2.getBounds(this);
			var _clip2ClipBmpData:BitmapData = new BitmapData(_clip2Rect.width, _clip2Rect.height, true, 0);
			_clip2ClipBmpData.draw(clip2);	

			point1.x = clip1.x;
			point1.y = clip1.y;

			point2.x = clip2.x;
			point2.y = clip2.y;

			var hits:Boolean = false;
			if(_clip1ClipBmpData.hitTest(point1,
										255,
										_clip2ClipBmpData,
										point2,
										255
								  ))
			{
				hits = true;
			}

			_clip1ClipBmpData.dispose();
			_clip2ClipBmpData.dispose();

			return hits;
		}

		private function checkBitmapDataHitDynamic():Boolean
		{
			var dynamicClip1Rect:Rectangle = dynamicClip1.getBounds(this);
			var dynamicClip1ClipBmpData:BitmapData = new BitmapData(dynamicClip1Rect.width,
																	dynamicClip1Rect.height, true, 0);
			dynamicClip1ClipBmpData.draw(dynamicClip1);

			var dynamicClip2Rect:Rectangle = dynamicClip2.getBounds(this);
			var dynamicClip2ClipBmpData:BitmapData = new BitmapData(dynamicClip2Rect.width,
																	dynamicClip2Rect.height, true, 0);
			dynamicClip2ClipBmpData.draw(dynamicClip2);	

			point1.x = dynamicClip1.x;
			point1.y = dynamicClip1.y;

			point2.x = dynamicClip2.x;
			point2.y = dynamicClip2.y;	

			var hits:Boolean = false;
			if(dynamicClip1ClipBmpData.hitTest(point1,
										255,
										dynamicClip2ClipBmpData,
										point2,
										255
								  ))
			{
				hits = true;
			}

			dynamicClip1ClipBmpData.dispose();
			dynamicClip2ClipBmpData.dispose();

			return hits;
		}

		private function checkBitmapDataHitReverse():Boolean
		{
			point1.x = clip1.x;
			point1.y = clip1.y;

			point2.x = clip2.x;
			point2.y = clip2.y;	

			if(clip2ClipBmpData.hitTest(point2,
										255,
										clip1ClipBmpData,
										point1,
										255

								  ))
			{
				return true;
			}

			return false;
		}

		private function out(str:*):void
		{
			trace(str);
		}
	}
}

You can download the code from here (requires Flash Pro and Grant Skinner’s Performance Testing Harness).

And here are the raw results:

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
checkHitTest (10000 iterations)
Uses DisplayObject.hitTest
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
method...................................................ttl ms...avg ms
[function]                                                    8     0.00
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
checkHitTestReverse (10000 iterations)
Uses DisplayObject.hitTest with clips reversed
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
method...................................................ttl ms...avg ms
[function]                                                    7     0.00
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
boundsIntersection (10000 iterations)
Uses Rectangle.intersects()
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
method...................................................ttl ms...avg ms
[function]                                                   33     0.00
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
checkBoundsManually (10000 iterations)
manually checks if bounds intersect.
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
method...................................................ttl ms...avg ms
[function]                                                   18     0.00
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
hitTestCircle (10000 iterations)
Check if bounding circles intersect.
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
method...................................................ttl ms...avg ms
[function]                                                   22     0.00
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
checkBitmapDataHit (10000 iterations)
Uses BitmapData.hitTest to check for collision.
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
method...................................................ttl ms...avg ms
[function]                                                    7     0.00
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
checkBitmapDataHitReverse (10000 iterations)
Uses BitmapData.hitTest to check for collision. Instances reversed.
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
method...................................................ttl ms...avg ms
[function]                                                    7     0.00
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
checkBitmapDataHitInternal (10000 iterations)
Uses BitmapData.hitTest to check for collision. BitmapData not cached.
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
method...................................................ttl ms...avg ms
[function]                                                 6332     0.63
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
checkBitmapDataHitDynamic (10000 iterations)
Uses BitmapData.hitTest to check for collision. BitmapData not cached.
Dynamic MovieClips
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
method...................................................ttl ms...avg ms
[function]                                                 1892     0.19
––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––

Most of the results are as expected, although there is one surprise.

Doing a BitmapData.hitTest on a MovieClip placed onto the stage at author time (in Flash Pro) is 3 times slower than testing against a MovieClip generated and drawn at runtime. The only thing I can think that is happening is that perhaps for some reason the garbage collector is being triggered in the checkBitmapDataHitInternal and not the checkBitmapDataHitDynamic test. I have asked around internally what might be causing it, but I would be curious if anyone else is seeing the same results.

So, some quick conclusions from this:

1. DisplayObject.hitTest is a fast way to do a quick boundaries check.
2. Having to dynamically generate BitmapData for BitmapData.hitTest leads to a big performance hit.
3. If you can cache the BitmapData being compared, then BitmapData.hitTest performance is on par with the other techniques / APIs tested. However, performance degrades as the dimensions of the clips increase (see here).
4. Getting the BitmapData from a MovieClip that has cacheAsBitmap = false is 3 times slower than getting it from a MovieClip with the property set to true (Thanks to Renaun Erickson who figured out the performance discrepancy).

I will update the post and results as I learn more techniques and get more information.

If you find any bugs with the test, or would like to add some more tests (such as a test using BitmapData.getColorBoundsRect), just post them in the comments.

Updated : July 6, 2009 : Added info on cacheAsBitmap property impact on performance. (See this comment).

Updated : November 6, 2009 : Added optimized circle test in comments : Approaches performance of hitTest.

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.

I have just uploaded my slides from my FlashCamp London presentation on migrating from ActionScript 2 to ActionScript 3 using Flash Authoring.

You can view and download the slides from here.

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.

One of the top feature requests that end users have been asking for from AIR applications (on Mac) is the ability for those applications to leverage the open source Growl notification framework on Mac. However, this was not previously possible due to how applications are required to communicate with Growl.

I am really excited to announce that Adobe has been working with the Growl team to add support to Growl for Adobe AIR and Flash applications. Among other things, this will enable Adobe AIR applications to leverage the Growl notification framework on Mac. The best part, is that it is implemented in a way that is not just limited to use by Flash and AIR.

The new functionality is not yet in the release version of Growl, but if you are a developer you can download a nightly source build of Growl with the support. This will allow you to play around with the functionality and begin to add Growl support to your application.

In addition, I have put together a new open source ActionScript project, named as3growl, which provides an API for working with the new Growl functionality. The project is hosted at Google code and already contains the complete API source, API docs, examples, documentation, unit tests and other information.

I have posted information on how to grab the correct Growl source and compile it. You can find it in the Known Issues section of the as3growl Release Notes.

If you find any issues, or have any feature requests, you can log them here.

You can find more info about Growl on their site.

Update (November 17, 2008) : I created a mailing list for the project here.

I have switched over to using TextMate for some of my experimentations with ActionScript. I like how lightweight it is, its extensibility, command completion functionality, and ease of setting up new projects. I find it is perfect for quickly testing new code and ideas.

I have put together a couple of bash scripts, which coupled with the ActionScript 3 and Flex TextMate bundles have made working in TextMate a little easier for me.

The first script is called autocompile, which takes a class file, and compiles it anytime the file changes. This is really useful in TextMate as you can see any compile errors as you code.

autocompile

#!/bin/bash

# mxmlc autocompile bash script
# create by mike chambers
# http://www.mikechambers.com

#how often it check for changes in seconds
LOOP_INTERVAL=2

#make sure that a file name was passed in
if [ -z $1 ];then
        echo "You must specify a file to compile"
        exit 0
fi

#make sure that the file exists
if [ ! -e $1 ]; then
        echo "$1 does not exist"
        exit 0;
fi

#function to call mxmlc
function compile()
{
        mxmlc $1
}

#compile on load
compile $1

#get and store the last modified date of the file
MODDATE=`stat -f %m $1`

#loop every 2 seconds
while [ true ]
do
        #get the modified date
        TDATE=`stat -f %m $1`

        #check to see if it has changed
        if [ "$TDATE" != "$MODDATE" ]; then
                #file changed. Store new date
                MODDATE=$TDATE

                #compile
                compile $1
        fi

        #sleep until we check file again
        sleep $LOOP_INTERVAL
done

Using the script is easy, just pass in the name of the file you want it to compile:

autocompile Foo.as

The next script is called as. Basically, it takes the name of an ActionScript class file, generates the file from a template, opens it within a new project in TextMate, and automatically compiles the file when it is changed. This makes it very simple to setup a new project and start coding.

#!/bin/bash

# script for creating and setting up ActionScript projects in
# TextMate
# create by mike chambers
# http://www.mikechambers.com

#make sure that a file name was passed in
if [ -z $1 ];then
        echo "You must specify a Class file name"
        exit 0
fi

#get the class name (remove .as)
classname=`echo $1 | cut -d'.' -f1`

#dir that contains the as.template file
#make sure to set this
#there should be a way to get this automatically
wdir="/Users/mesh/bin/astmp"

#write the contents of the template to the class file.
cat $wdir/as.template | sed s/CLASSNAME/$classname/ > $1

#open the current directory and file in textmate
mate .

#begin to autocompile it
autocompile $1

This requires that the following as.template file is in the directory referenced in the script (in the wdir variable).

as.template

package
{
        import flash.display.Sprite;
        public class CLASSNAME extends Sprite
        {
                public function CLASSNAME()
                {
                }
        }
}

In order to create the new project, create a new directory, cd to it and run the as command, passing in the name of the ActionScript class file you want it to create.

mkdir Foo
cd Foo
as Foo.as

This will create a new File.as file that contains the stub code for the Foo class. It will then open the Foo.as file in a new project in TextMate, and will compile the class anytime it changes (printing any compile errors and warnings to the terminal).

Note that I could automate the directory creation also, although I decided not to do that right now.

Couple of notes:

• You must have the TextMate command line tools installed and in your path (TextMate > Help > Terminal Usage).
• as and autocompile must be placed within your path.
• You must update the wdir variable in the as script to point to the path where the as.template file is stored.
• Make sure to set the as and autocompile script to be executable : chmod 755
• The Flex SDK must be installed with the bin directory (that contains mxmlc) added to your path.

I also have the ActionScript 3 and Flex bundles installed within TextMate. I setup my mm.cfg so that it writes trace statements and warnings to the flashlog.txt file, and then I open that file in the Console so I can view runtime debug info (you can also just tail -f the file in terminal). (You can open the console from the ActionScript 3 Bundle in TextMate : Bundles > ActionScript 3 > Debug > Open Flash Log in Console)

Finally, I modify the Run command for the file in TextMate to open the SWF in the standalone debug Flash player (which I have set to be the default handler for the swf file type). In order to do this, I just modified the ActionScript 3 Bundle Run command (CMD-R) to execute:

name=`echo $TM_FILEPATH | cut -d'.' -f1`
open $name.swf

So, now as I type, I can see the errors as I make them, and can just hit CMD-R to test the SWF and see the runtime debug info in the console.

One additional thing I might do is to modify the autocompile script to play a sound when the compile fails.

Post any questions, suggestions or errors in the comments.

If you read my blog regularly (or just today) you should have noticed that I have been playing around with some Pixel Bender filters and ActionScript / Flex (all inspired by Lee Brimelow’s video screencast on creating and using Pixel Bender filters in Flash Player 10.)

Previously, I posted some code showing how to embed a custom Pixel Bender filter within a SWF and then apply the filter to an image. That works well, but the code is not that reusable since the filter loading code is mixed in with the main code.

Below is a simple example that shows how to encapsulate a custom filter inside of an ActionScript 3 class, which you can then use and re-use like any other built in filter.

Document Class : PBFilter.as

package
{
	import flash.display.Bitmap;
	import flash.display.Sprite;

	// SWF Metadata
	[SWF(width="600", height="400", backgroundColor="#000000", framerate="30")]

	public class PBFilter extends Sprite
	{
		//The image to display the filter on
		[Embed(source="image.jpg")]
		private var image:Class;

		private var im:Bitmap;

		public function PBFilter():void
		{
			im = new image() as Bitmap;
			addChild(im);

			var filter:TestFilter = new TestFilter();
				filter.value = 30;

			//add the filter to the image
			im.filters = [filter];
		}

	}
}

Filter Class : TestFilter.as

package
{
	import flash.display.Shader;
	import flash.filters.ShaderFilter;
	import flash.utils.ByteArray;

	public class TestFilter extends ShaderFilter
	{
		//the file that contains the binary bytes of the PixelBender filter
		[Embed("testfilter.pbj", mimeType="application/octet-stream")]
		private var Filter:Class;		

		private var _shader:Shader;

		public function TestFilter(value:Number = 50)
		{
			//initialize the ShaderFilter with the PixelBender filter we
			//embedded
			_shader = new Shader(new Filter() as ByteArray);

			//set the default value
			this.value = value;
			super(_shader);
		}

		//This filter only has one value, named value
		public function get value():Number
		{
			return _shader.data.amount.value[0];
		}

		public function set value(value:Number):void
		{
			//not that pixel bender filters take an array of values, even
			//though we only have one in our example
			_shader.data.amount.value = [value];
		}		

	}
}

Compiled using the Flex 3.1.0.2710 SDK (although it does not use the Flex Framework), and requires Flash Player 10.

You would of course, have to add the appropriate getters and setters depending on the values your custom Pixel Bender filter accepts.

Using this technique, you could then create a SWC (distributable ActionScript library) to package your custom filter(s) and re-use them in MXMLC, Flex Builder and / or Flash Authoring.

You can see an example of the filter here.

You can find more information on Pixel Bender here.

You can download the filter from here.