Creating Re-distributable ActionScript Libraries of Pixel Bender Filters

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).

Creating a Project for FP 10

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

        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.