How to get up and running with Apparat

http://www.webdevotion.be/blog/2010/06/02/how-to-get-up-and-running-with-apparat/
@joa recently posted a simple example to illustrate the power of his powerfull optimization framework called Apparat.Apparat is a framework to optimize ABC, SWC and SWF files.From the description of the Google Code page we get a hint of what Apparat actually does: “Apparat is a framework to optimize ABC, SWC and SWF files.”. In layman’s terms: “Apparat will speed up your Actionscript projects by optimizing certain method calls.”. The Actionscript Library for example provides some ( much ) faster ways of doing math and bitwise operations. Read on to understand more about how to get up and running with Apparat.
First, a confession. This post you are reading right now, is not the original one. After I thought I was done writing it, I sent it over to Joa and asked for a * small * review. A review turned into a complete rewrite as I missed an essential part of the project and made things more complicated for people who just want to integrate Apparat into their projects. So, credit where due: thank you Joa. Without his help this post wouldn’t be where it is now.All in all, there are only three steps:Download Apparat ( the compiled version )
Download Scala ( Apparat is ( being re-) written Scala )
Integrate Apparat with a project ( we’ll use Joa’s example )

DOWNLOAD APPARAT

Let’s get started by downloading Apparat:

http://code.google.com/p/apparat/downloads/detail?name=apparat.zipThis file contains the compiled SWC among other compiled build tools ( Reducer, TDSI, Apparat, … ) that are part of Apparat.
You can extract this file wherever you want but it makes sense to put it somewhere close to your projects so you can go back to it easily in the future.

DOWNLOAD SCALA

We should install Scala from http://www.scala-lang.org/downloads. Scala is a general purpose programming language and states that “Code sizes are typically reduced by a factor of two to three when compared to an equivalent Java application”. Sounds interesting to me, but even more to Joa I guess, as he is using Scala to get Apparat to the next level.The version you need is RC3 at the time of writing this post. Windows users can download this zip, while the Mac / Unix archive would be this tgz archive.You can put the extracted folder anywhere, you don’t need to install anything. It does makes sense to put it somewhere next to your working directories. We’ll need the Scala directory in a moment, but first we’ll set up our ( example ) project.

INTEGRATE APPARAT WITH A PROJECT

For brevity’s sake and to make this howto as easy to follow along as possible, we’ll download Joa’s most recent example:

get it from http://blog.joa-ebert.com/2010/05/26/new-apparat-example/.After you extracted the source folder of the example project, you should put it in a nice place. Somewhere next to your other Flash projects maybe. Fire up FDT* and click File > New > New Flash Project from the application menu ( top of the window ) and point to the example folder as your working directory.* We’re using FDT because it allready comes with an ANT builder plugin. It should be possible to use Flash Builder but you’re on your own ( for now – maybe I’ll write something about that in a next post if there is interest ).If you’re not familiar with ANT you will learn something sweet from this post. ANT is a build tool, that can automate the sometimes tedious process of building a project. Imagine you want to compile an FLA from within FDT or Flash Builder, ANT can do that for you. It can even upload a compiled file to your staging server if you want. Do read more about ANT to learn all about it; its definitely worth it.In the introduction of Joa’s blog post we read:A complete example is also available. Just change the paths in the build.properties file and compile everything using Ant.So let’s do that. Open up the example project in your FDT workspace and edit the build.properties file. You can find all files related to ANT tasks in the “build” directory. You’ll find three empty variables there: FLEX_HOME, SCALA_HOME and APPARAT_HOME. Add the correct values for your machine. Windows users should use \ ( backslashes ) in stead of the forward slashes I’m using on my OS X machine. Update: everyone ( Mac & Win ) should use forward slashes.


Save your changes in the build.properties file.Next we’ll link our project to the compiled Apparat.swc file. The SWC is included in the Apparat download we extracted earlier. In the readme file of the example project we learn that we need to pass an APPARAT_FLEX path to our Flash project in FDT. Let’s do that by rightclicking on our example project and choosing New > Linked Libraries. Click the “add” button and create a new path “APPARAT_FLEX”. The path should point to your Apparat folder containing the Apparat.swc file.

Now we should be able to compile the project using the ANT task. Rightclick on the build/build.xml file. Choose Run as > Ant Build from the context menu. You should see ANT triggering several tasks in the Console view, with success off course. The result is a compiled version of both the example-apparat.swf and example-as3.swf files in your “bin” folder.You can see a clear difference in the framerate of the two swf files. On my recent MBP I get 28fps on the AS3 example and a whopping 40fps on the Apparat version. And don’t forget: that’s 80.000 particles flying by in front of you!

If you see some errors in the Console, try to figure out what’s wrong, chances are one of the variables we edited before in the build.properties file are wrong.

“WHAT’S THE DIFFERENCE BETWEEN ME AND YOU?”

What makes the Apparat version so fast? Inline methods sir. If you check out the two class files in the “src” folder of the example project in your FDT workspace, you can see they look almost the same. The only difference is that the the Apparat class file is using FastMath. As you can see from this screenshot ( click for full size ):

FastMath is a class provided by the Apparat SWC ( which we linked before ) and speeds up some mathematical functions. These function are recognized and “inlined”, making them so much faster. Inlining means that the compiler will put the actual method in the executed code, in stead of calling it from memory. So in stead of storing “Fastmath.rsqrt” it will put the actual code of the FastMath.rsqrt method where ever it is needed when compiling.

E.g.: in stead of using:

// AS3 version
dt = 1.0 / Math.sqrt(dx * dx + dy * dy)

the Apparat class uses:

// the faster Apparat way, will get inlined by the compiler
dt = FastMath.rsqrt(dx * dx + dy * dy)

Don’t forget to initialize FastMath when using it in your own projects!

CONCLUSION

Getting Apparat into your project should be very easy once you have gone through these ( actually simple ) steps. The learning curve was a bit steep for me, but I’m so glad I finally pulled it off with the help of Mr. Ebert. Please comment, ask, criticize in the comments below and tell us about your progress with this howto.If there is interest in articles like these, I’ll try to post more Apparat related articles in the nearby future.