Learning AGAL with AGALMacroAssembler and OpenGL Examples

So the other day I sat down and thought to myself: self, it’s high time you learn you some of this new fancy pants AGAL that’s all the rage these days. Now, after a few days of playing around I am by no means a master at the art of shader programming, but due to the still huge lack of available material on the subject, I figured I’d share a few things I’ve learned. Please feel free to post some comments correcting me where I’m wrong as I’m bound to be. I’m hoping though, that this may help out a few folks who, like me, learned programming via actionscript and have never actually written a shader in their life.

I’m not going to go into the very basics of AGAL and uploading index and vertex data. There are plenty of tutorials out there about that. And if you’re looking for a book, this one by Christer Kaitila (aka Breakdance McFunkypants) is fantastic. In fact, here, I’m only going to use the utmost basic of vertex shaders and focus entirely on fragment shaders.

I know when most people start getting into shader programming they jump straight into the world of 3D. If you have the stamina and knowhow for such a leap, the more power to you. Me though, I’m still sticking to 2D fragment shaders because (a) they’re a good deal simpler to get your head around and (b) I’m completely obsessed those old school 2D demo effects – the likes you see on this site under the Plane Deformations in the drop down box. In fact, if you click on the ‘Fly’ example in that drop down box, that’s what we’re going to be making in Flash here shortly. You can check out the final result here.

Now when I started digging into AGAL (that is when I started googling around), one of the things I came across was the AGALMacroAssembler (as opposed to the AGALMiniAssembler which would normally be used to parse AGAL strings). Unfortunately, there is nearly no documentation about the macro assembler at all. I’m not sure why it’s being kept such a secret. The one place I found that mentioned it was the Ryan Speets site and I’m very thankful for that. There was still no real explanation of how to use it though so I just had to wing it.

I’ll try, then, to start at the beginning. For those who don’t know, AGAL is, essentially, assembly language (Adobe Graphics Assembly Language, that is).  The syntax can be very confusing when first checking it out as all operations are written like OPERATION DESTINATION, SOURCE1, SOURCE2. So, for example you just wanted to say something like: z = x + y, it would look something like this: add z, x, y. Using AGALMacroAssembler though, we can avoid that cryptic looking syntax. In fact, there are essentially 4 wonderful things about using AGALMacroAssembler: (1) You can use simpler syntax with actual math operators, (2) You can write comments – a HUGE plus, (3) You can set alias values (basically you can write your own variable names) and (4) You can write simple macros (essentially, functions). I won’t be bothering with 3 or 4 here, but 1 and 2 are more than enough reasons to hop right into using the AGALMacroAssembler.

Actually, one other benefit is the fact that you can keep all your shader code in a separate file. So, with that said, if you’d like to follow along and learn as I did, start a new actionscript project and, in a place where you would normally place your embed files (or even on the project root, for all I care), create a new text file named ‘shader.macro’. Inside that file type this:

A tiny explanation: Our vertex shader here is the most basic what can be found. All you really need to know is that it spits out uv coordinates into the register v0 which can be accessed in our fragment shader. In this case our fragment shader samples our uploaded texture (fs0) at those uv coordinates, stores that value in the ft0 register then moves that register into the oc (or Output Color register – oc is always the output of a fragment shader).

And what are these registers of which I speak? Well, this is overly simplified, but you can think of registers as the variables of your shader program. In a fragment shader there are 8 temporary registers available (ft0 – ft7) and 28 constant registers (fc0 – fc27). These constant registers hold data uploaded to your program from Actionscript. Each register also has 4 components all of which are like Number types in actionscript. In fact, the best way to think of registers in Actionscript terms is that they are Vectors of Numbers, each one with a length of 4. Instead of accessing them with square brackets like myVector[0], though, you access them with a dot and x, y, z, or w; as in ft0.x or fc1.w.

Let’s actually get something compiled though. For my experiments, I came up with a simple Actionscript template which I could easily update with different macro shaders. Here is the basic version.

Note that this Actionscript file requires an embedded image to use as your texture. This can be any old image you’d like, but make sure it’s dimensions are in powers of 2 (2, 4, 8, 16, 32, 64, etc). Me, I’m using a picture of brick wall that’s 512×512. Now, if you compile that, you’ll see – well, you should just see your embedded image taking up the screen. Not very exciting, but it’s a start. Let’s try screwing around a little bit, just to get an idea of what’s going on. Open your shader.macro file back up and try changing it to this:

Compile again and now you’ll see the same image but all crazy colored. What the hell happened? Well, it turns out that the x, y, z, w register components actually map to the red, green, blue and alpha of your image (as a side note, when using the AGALMacroAssembler, you can actually use r, g, b, and a instead of x, y, z and w, but I wouldn’t recommend it. Just stick to xyzw and know that they correspond to  red, green, blue, and alpha). So, with this little twist, you’ve now mapped the original blue to the red, the original red to the green, and the orignal green to the blue of your output color (the alpha stays the same).

Let’s try sending the shader program some values from Actionscript now. As I mentioned earlier, Actionscript values are stored in the constant registers, fc0 – fc27. Also remember that these registers are really just vectors of numbers. So to send some values, we just use the setProgramConstantsFromVector() method and send a vector of 4 numbers (even if you plan on only using 1 component value, be sure to send all 4 – just fill out the unused with 1’s).

Change your onTick() method to look like this then:

Then change your shader.macro file as so:

Compile again, and wowie zowie. You now have an image with a red value that pulses with time. Easy peasy. Try doing the same to the other color components or using +, -, or / instead of * just to get an idea of what happens.

So, that’s all good and well, but how do we do something cool? Well, unfortunately, there are very few AGAL shader examples scattered around the internet. There are, though, at least a bijillion and 6, OpenGL / GLSL examples to be found. Go back and look at that ‘Fly’ example on the Shadertoy page. In fact, copy that main function and paste it into your shader.macro file (remember with AGALMacroAssembler we can add comments just as we can in Actionscript). So now your file should look like this:

The first thing to note about GLSL fragment shaders is that there is always a gl_FragCoord and a gl_FragColor. The gl_FragCoord is the input uv position (in our case that’s v0) and the gl_FragColor is always the output (recall in AGAL terms that means ‘oc’). You will also see ‘resolution’ used quite a bit. This is a little trickier, but I usually just make it 1 x 1 and that seems to do the trick as we’ll do here

Now the first thing you will want to do when porting OpenGL examples to AGAL is to weed out the constants. This is actually trickier than it might seem. AGAL will not let you perform any mathematical operations on two constants – that will need to be pre computed in Actionscript. For example, you cannot say ft1 = fc1.x * fc2.y – you will have to multiply those things together in actionscript and send them along as a separate constant. So, what I do is look through the OpenGL and write comments about what constants I’ll need right there in my .macro file. Doing so now and I get something that looks like this (I also like to try to group varying items like time into a single register):

Remember that you’ll want to fill all four components of the register which is why you see them padded with 1’s. Go ahead and add these straight into the onTick method of your Actionscript file like so:

The next thing you’ll want to do is ‘unwrap’ the glsl code. Essentially, you’ll want to have only one math operation per line. You can use some generic a, b, c variable names for the time being, but use the correct constant registers and  components. Eventually, you’ll get something that looks like this:

Now comes the tricky part. Now we need to replace those generic variable names with temporary registers. Remember there are only 8 to choose from so you’ll really want to keep in mind what you want to save to use for later computations and what you can overwrite. With a little perseverance though, you may come up with something like this:

Now, because I went back and used a previous version of something I had written (yes, I cheated), here is the Actionscript that goes with the above AGAL macro in its entirety:

Cross your fingers, compile, and you should have something like this.

And that is, as they say, that. Hopefully, that can help some folks out. Here’s a few other examples I’ve been playing around with (ported from OpenGL sources posted round the web):

A little pulse thing
A little bokeh like thing
A little metablob thing
A little post processing image effect thing

Oh, and I suppose I should have mentioned, you can find AGALMacroAssembler here.

Have fun and happy shading…