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.

In conjunction with the CS4 release, the Adobe Developer Center has just post some new articles on Flash Player 10, and Flash Professional CS4.

Flash

• Introducing Adobe Flash CS4 Professional
• Generating sounds dynamically in Flash Player 10
• Creating blends, filters and fills with Adobe Pixel Bender
• New Flash samples
• Updated Flash quick starts

Flash Player

• Introducing Adobe Flash Player 10
• Detecting Flash Player versions and embedding SWF files with SWFObject 2
• Adobe Flash Player Administration Guide for Flash Player 10
• Understanding the security changes in Flash Player 10
• Policy file changes in Flash Player 9 and Flash Player 10

Here are the links I mentioned during the SparkProject.org meeting tonight in Tokyo:

Pixel Bender on Labs
Creating ActionScript libraries of Pixel Bender Filters
Tinic Uro’s Post on Pixel Bender in the Flash Player
Flash Player 10 Drawing API overview
Mysql ActioScript 3 Library

Below is another simple Pixel Bender filter that I created last night. This one basically, converts an image to gray scale, using the ITU-R Recommendation BT.709 algorithm described here.

Here is the filter:

<languageVersion : 1.0;>

kernel GrayScale
<   namespace : "mesh";
    vendor : "Mike Chambers";
    version : 1;
    description : "Gray scale filter";
>
{
    input image4 src;
    output pixel4 dst;

    void
    evaluatePixel()
    {
        dst = sampleNearest(src,outCoord());

        //algorithm from ITU-R Recommendation BT.709
        //http://local.wasp.uwa.edu.au/~pbourke/texture_colour/imageprocess/
        float avg = 0.2125 * dst.r + 0.7154 * dst.g + 0.0721 * dst.b;
        dst = float4(avg, avg, avg, dst.a);

    }
}

Again, its pretty simple, but I am trying to learn both Pixel Bender and image processing in general. The biggest thing I learned for this example is how to work with different vector sizes (which can be a little confusing). Im still wrapping my head around it, but once I get it down, Ill make a post on vectors in Pixel Bender.

After seeing all of the cool stuff people have been doing with Pixel Bender, I finally decided to spend a little time and start learning how to build them myself.

The learning curve isn’t too difficult, although you do have to learn some new concepts, and deal with some limitations (at least when creating filters for Flash). The most difficult part for me thus far, is just understanding color and pixel math and manipulation (something I need to read up on more).

Anyways, below if one of my first filters. I wanted to post it as it is a pretty simple example, while still potentially being useful. Basically, it creates a TV scanline effect by making every other row of pixels black.

Here is a before an after example (you need to click to view the full size in order to see the effect well).

Here is the code for the filter:

<languageVersion : 1.0;>

kernel ScanLines
<   namespace : "mesh";
    vendor : "Mike Chambers";
    version : 1;
    description : "Generates a TV Scanline effect";
>
{
    input image4 src;
    output pixel4 dst;

    void
    evaluatePixel()
    {
        //get the current pixel
        dst = sampleNearest(src, outCoord());

        //find out the vertical pixel size. In Flash this will always be 1
        float pixelVSize = pixelSize(src).y;

        //pixelVSize / 2.0 - outCoord() gives center of pixel, so we have to adjust to find
        //center of our pixel
        if( int(mod(((pixelVSize * outCoord().y) - pixelVSize / 2.0), 2.0 )) == 0)
        {
            //if on an even row, set the pixel to blackt
            dst.r = 0.0;
            dst.b = 0.0;
            dst.g = 0.0;

            //can also do
            ////dst = float4(0.0,0.0,0.0, 1.0);
        }
    }
}

Thanks to Kevin Goldsmith from the Pixel Bender team for helping me out.

The comments in the code explain what is going on.

You can load this into Pixel Bender to play around with it, and compile it for use in Flash Player 10.

I wanted to add a parameter to allow the line size to be set. It doesn’t look like I can store variables in between calls to evaluatePixel(). Im trying to figure out an algorithm to figure it out in one pass, but im not sure that my math skills are up to the task at the moment.

You can find all of my other posts on Pixel Bender here.

Last week I wrote a number of blog posts showing how to work with Pixel Bender filters in Flash, Flex and ActionScript. In particular, I wrote about how to embed pixel bender filters within a SWF and how to encapsulate custom Pixel Bender filters in an ActionScript 3 class. For this post, I am going to take the next step, and show how to create re-distributable SWC libraries of custom Pixel Bender filters that can be used in Flash Player 10 based projects (including Flex Builder, MXMLC and Flash Professional).

Basically, we will create a SWC (redistributable library of ActionScript classes) that contains our Pixel Bender filter encapsulated inside of an ActionScript class. We will create the SWC in Flex Builder although you could also easily do it using the compc command line tool included in the Flex SDK.

First, we need to set up Flex builder so that it will recognize the Flash Player 10 classes that we need to use to create and compile our filter class.

Download one of the Flex 3.2 nightly builds (I am using 3.2.0.3238) and extract it to a location on your desktop (I will refer to this as FLEX3.2_PATH). The builds contain support for compiling to Flash Player 9 and Flash Player 10.

Next, open up Flex Builder. We need to add the Flex SDK we just downloaded to Flex Builder. You can find complete instructions in this technote. Basically, go to Window > Preferences > Flex > Installed Flex SDKs > Add and point to the SDK you just downloaded.

Next, created a new “Flex Library Project” by going to File > New > Flex Library Project (dont worry, this is actually just an ActionScript library and doesn’t require or use Flex).

Specify a project name and where the project will be stored. In the Flex SDK version section, click the Use a specific SDK radio button, and then from the drop down, select the Flex SDK you just added (which should be named Flex 3.2).

Click the Next button (not the Finish button). This will take you to a panel where you can set build paths. We need to tell Flex Builder to compile for Flash Player 10, and not Flash Player 9. Select the Library path tab button at the top. This should show the Flex 3.2 SDK which you are using. Click the little arrow next to the SDK listing to expand the entry. This will show the SWCs being used to compile the project. Select the playerglobal.swc entry, and click the Remove button. This will remove the Flash Player 9 SWC from the project.

Next, we need to add the Flash Player 10 SWC. Click the Add SWC button and then browse to FLEX3.2_PATH/frameworks/libs/player/10 and select the playerglobal.swc in that directory and click ok.

Finally, make sure the playerglobal.swc entry is expanded and select the Link Type entry, and click the Edit button. Set the Link Type to External and click ok, and then click the Finish button.

The project is now configured to create SWC libraries that work with Flash Player 10 classes.

Note, you may get a compile error in the Problem view saying that nothing has been specified to be included in the SWC. You can ignore that for now.

Next, we need to add our Pixel Bender filter, and create the class that embeds it and provides an APIs for it. We will use the same filter and classes that I used in my earlier blog post here. Copy the testfilter.pbj file into the filters directory.

In the src directory of the project, create a new folder called “filters”. We will use this as the namespace for all of our custom filters (of course, you may want to use a different namespace and directory structure). Copy the filters pbj file into that directory.

Now we are ready to add our ActionScript class for the filter. I am not going to go through all of the steps of creating the class, you can get most of that in this post.

Right click on the filters folder, and select New > ActionScript Class. Give the class a name (I am using TestFilter for this example), set the Superclass to ShaderFilter and click the Finish button. If you just copy the class from the previous past, make sure to update the package path in the class definition.

Here is what the project layout looks like now:

Here is the filter class I created for the filter:

package filters
{
	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];
		}		

	}
}

At this point, we are ready to add the class to the SWC, and then compile the project.

Open Project > Properties > Flex Library Build Path. On the Classes tab, make sure the TestFilter class is selected. You do not need to include the filter pbj file in the SWC as this is compiled into the TestFilter class when the class is compiled into the SWC.

Click the OK button. The class and SWC should be compiled. If you get any compile errors you will need to fix them first. Once the SWC is compiled, you can find it in the projects bin folder.

You now have a SWC that contains your custom ActionScript Pixel Bender class and filter. At this point, you can distribute and / or reuse the SWC for other projects. Just link the SWC like you would any other SWC and your filter class will be available. Today, this works in Flex Builder and MXMLC (provided you set them up to compile to Flash Player 10). Once Flash Professional CS4 is released (which includes support for Flash Player 10) you will be able to use the SWC and filter there also (and yes, the SWC import bug is fixed).

Using this technique, you can create reusable libraries of custom Pixel Bender filters, and use them in your project just like the Flash Player’s built in filters.

If you check out the Flex SDK nightly builds, then you may have noticed that there are now Adobe AIR 1.5 bits included in the SDK. This is part of the AIR teams ongoing effort to continue to integrate closer into the Flex SDKs build process, and in general to provide more visibility into what is going on with AIR.

As the version number indicates, the Adobe AIR 1.5 release (code-named “Cosmo”) is a dot / incremental release. One of our original goals with AIR has been to update more frequently, as opposed to just having large updates at infrequent intervals. This release focuses on continuing to improve the foundation laid by the 1.0 and 1.1 release, and includes a number of changes and bug fixes, including, but not limited to:

• Flash Player 10 integration, including
  • 3D Effects and APIs
  • Custom Filters and Effects (Pixel Bender)
  • New Text engine (with support for right to left, and vertical text layout)
  • Drawing API enhancements
  • Updated Saffron engine for font rendering
  • Vector data type (typed Arrays)
  • Enhanced Sound APIs
  • Dynamic video streaming
  • and much more
• Integration of the SquirrelFish JavaScript VM into the Webkit HTML engine (should provide significant improvements to JavaScript execution)
• Support for new languages
  • Swedish
  • Dutch
  • Czech
  • Polish
  • Turkish
• Encrypted Local / SQLite databases
• Lots of bugs fixes and stability improvements, including the uber-annoying
  • AIR applications do not use the default browser to launch URLs on Vista
  • AIR applications open a new instance of Firefox to handle urls (as opposed to opening a new tab)

Note, that a couple of things from Flash Player 10 may not make the release for AIR 1.5. This includes Mac vector printing, and GPU / hardware accelerated rendering. We are also not picking up experimental features from the current WebKit builds.

The SDK contains the command line tools and libraries to author, test and package AIR files. It does not include a runtime installer or updated documentation. There is currently support for Mac and Windows, but not support for Linux (yet). However, expect more news on Linux very soon.

The nightly releases are not the same as labs releases. Just as with the Flex SDK nightly builds, they have not been tested nearly the same as milestone and labs releases. There are bugs. Sometimes, there will be really bad bugs, but in general, the quality and stability level will continually improve as we move toward the release this fall. While the nightly releases are not targeted at locating bugs, if you do find issues you want to report, you can use the bug report form to do so.

Of course, as with any pre-release information, this is all subject to change, although at this point we don’t anticipate any major changes.

If you have any questions, or want clarification on anything just post a comment below.

Ok. Last post on Pixel Bender for today (I promise). This one is simple, but ties together my previous posts.

Now, that we know how to load and use Pixel Bender filters in Flex, and know how encapsulte Pixel Bender filters in an ActionScript class, lets combine the two to leverage custom Pixel Bender filters in MXML.

First, again, we need our custom Pixel Bender class:

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

	}
}

Once we have defined that, we can then treat the class like any other filter, and use it directly within MXML, like so:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute"
	xmlns:local="*"
	>
	<mx:Image left="10" top="10" width="375" height="500" source="@Embed(source='image.jpg')">
    	<mx:filters>
     		<local:TestFilter value="25" />
    	</mx:filters>
	</mx:Image>
</mx:Application>

Note that the local namespace maps to the package that contains our custom filter (in this case, the root package).

Compiled using the Flex 3.1.0.2710 SDK, and requires Flash Player 10. The Flex team is working on making this workflow even easier for Flex 4, so keep an eye on the Flex 4 project page.

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

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.

Following up on my earlier post on how to embed Pixel Bender filters within a SWF, here is a super simple example that show how to use a Pixel Bender filter within a Flex application.

Compiled using the Flex 3.1.0.2710 SDK, and requires Flash Player 10.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute"
	applicationComplete="onApplicationComplete()">

	<mx:Script>
		<![CDATA[
			import flash.filters.*;
			import flash.utils.ByteArray;		

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

			private function onApplicationComplete():void
			{
				//Pass the loaded filter to the Shader as a ByteArray
				var shader:Shader = new Shader(new TestFilter() as ByteArray);

				shader.data.amount.value = [100];
				var filter:ShaderFilter = new ShaderFilter(shader);

				//add the filter to the image
				im.filters = [filter];
			}
		]]>
	</mx:Script>

	<mx:Image right="288" left="40" top="26" bottom="108" id="im" source="@Embed(source='image.jpg')"/>
</mx:Application>

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.