Download the source for all of these demos here.

There are several parts to this demo, and I’m going to give credit where its due right now. The first part is the vector rendering of the metaballs; the real innovator here is Hannu Kankaanpää, who has a great write up on a clever rendering algorthim, which I’ve adapted from Python to ActionScript. The second part is the eye-candy, the pixel shader. The folks over at omino made this spiffy distortion/chromatic aberration filter for AfterEffects, which I then adapted to run in Flash’s crippled PixelBender environment. I’m not totally satisfied with my conversion, but it does the job. I won’t be going over the details of the refraction, but the PixelBender source file is included.

Pro-tip: Right click on any of these demos for an option to turn on a profiler, so you can watch the performance.

Fields of Metaballs

So what is a metaball really? The mathematical terms for a metaball are either an isoline (two dimensional) or an isosurface (three dimensional). This demo only explores the two dimensional aspects. Isolines are analogous to a contour map; the center of each metaball is like the peak of a mountain, and the line formed by them is the contour of an elevation on that mountain. As those peaks get closer together, they begin to merge and a bridge emerges. If they sit on top of each other, they form one extra large mountain. In this demo, the graph on the top is like a side-view of the system; the metaballs on the bottom can be thought of as a cross-section of that system.

Mathematically, each metaball in the system has a position ( ) and a strength ( ), and the system as a whole has a “gooiness” constant ( ). We can find the strength (or elevation, in our analogy) of a particular point ( ) by plugging everything in to a fall-off function for each metaball in the system, and summing the results. In our implementation, the fall-off function is

This formula might look familiar; when it is an inverse square relationship, or basically Newtonian attraction. Really any fall-off function could be used, as long as it is smooth and has a domain of , and there are some that are more efficient by leaving out the division. But, with some tricks in the code, this one does just fine.

/**
 * Check the strength of this metaball on a point in space.
 * @param	v	The point to check against.
 * @param	c	The exponential constant of the field.
 * @return	The strength of this metaball's field at the point.
 */
public function strengthAt(v:Vector2D, c:Number):Number
{
    var div:Number = Math.pow( Vector2D.subtract(_position, v).lengthSq, c * 0.5 );
    return (div != 0) ? (_strength / div) : 10000;
}

Rendering with Vectors

A regular brute-force metaball renderer would operate by taking this formula and solving it for each pixel or voxel in the system. People have also cheated the effect in Flash using a variety of BitmapData tricks; generally something like drawing circles, applying a strong blur filter and then using BitmapData.threshold(). This can work really well; just look at this awesome demo. Hannu’s approach is a little more complex, but very optimized for the CPU. It also has the unique benefit of having a vector output, which can come in handy given that most of Flash is vector based.

To explain how it works, lets return to our contour map analogy. Suppose you were in a mountain range and wanted to find the contour at around 500 feet elevation. One approach would involve standing on each square foot of dirt and measuring the elevation and then plotting those elevations on some kind of grid. This would be easy and fast if you had thousands of people with you to simultaneously measure each of those square foot plots. But if you’re all alone, like the CPU is, you need a more straightforward approach. Instead, you start at the top of one of the mountains, and descend in any direction until you reach 500 feet elevation. Then you start walking in either direction, never going up or down, only around. When you return to the spot you started at, you’ve successfully plotted the 500 foot elevation contour for that mountain (and any other mountain peaks you walked around). Instead of evaluating every square foot in the mountain range, you only make one evaluation per step you take.

This introduces some unique complexity issues; a GPU solution has a fixed complexity for a certain resolution and number of metaballs, whereas Hannu’s algorithm changes in complexity based on the position of the metaballs. There are also additional problems, such as how far each step should be, how many steps to take before you “give up,” and how to tell when you’re done. I’m not going to post the whole rendering algorithm here; it is messy, a bit long, and not particularly insightful. There are two loops; in the first loop, the algorithm locates a point on the edge of each metaball. The second loop traces the field normal (using second order Runge-Kutta) between the edge points found in the first loop, like a set of dominoes falling into each other. At every step, we write a coordinate to a graphics object, and end with a tidy, convenient GraphicsPath object. What’s the point? Well, that’s up to you, but here is something you could never do with a pixel-based renderer:

There’s Always a Downside

The biggest issue is the stability. Just like dominoes, sometimes things don’t line up quite right. Its a natural problem with a less rigorous approach, and there isn’t much to do about except adding additional error-checking and more generous tolerances. I developed the system for an application that would use four or five metaballs at most, and for that, the system is relatively stable. But…add enough metaballs to the stress test below, and things will start to go haywire; spiraling edges, inversions, the works. Another downside is recognized by Hannu; in certain configurations, a set of three or more metaballs can form a donut-like shape. A rigorous evaluation would show a hole in the middle, but this edge tracing technique may miss it some frames and pick it up in others. I think it could be addressed if it was a huge issue for a certain application, but in general it seems pretty unlikely.

The performance is decent on Flash Player 10, and I’m sure some keen eyes could find plenty of room for optimization. Turn on the profiler on the stress test below (its in the right click menu) and see how much you can break it!

Download the source for all of these demos here.

Download the files here.

Breaking It Down

The flow can be broken into several pieces. The main class, called a Flow, handles things like user input, positioning of the elements, and z-sorting. Inside a Flow is an array of FlowContainer‘s, which is really where the magic happens. The FlowContainer actually encapsulates various transformations, and applies a percentage of those transformations to itself based on the position of the mouse within the Flow. Both the Flow and FlowContainer extend MovieClip, and this means that any DisplayObject can be added as a child to the FlowContainer and it will inherit its various transformations.

Wow, that was abstract. What do I mean when I say FlowContainer encapsulates transformations? Every DisplayObject has a property transform which holds various information about the object’s position and color. I’ll make an example with a transformation matrix, which is a three by three matrix. The template of the matrix is:

The elements a, b, c, and d control the scaling of the DisplayObject, while tx and ty control the translation of the DisplayObject. The u, v, and w usually provide additional information if its needed, but in a standard two dimensional transformation they are unnecessary. The most basic transfomation matrix is the identity matrix. The identity matrix, when applied to the object, does absolutely nothing.

Now, lets say we want to translate, or move, the object 56 pixels to the right and 32 pixels down. The transformation matrix we would use is,

;

Easy. Scaling is similar, and uses a to scale horizontally and d to scale vertically. So to make our object 4.4 times wider and 2.6 times taller, we would use,

;

Note that the translation is still there, now its just scaling at the same time. Rotation is the strangest, because its actually a compound operation. Without getting too mathy, the elements a and d of the array control scale and the elements c and b control skew. If you do both operations at the same time, you can rotate the object. I’m going to remove the scaling from the previous matrix for clarity. If we wanted to rotate the DisplayObject by 70 degrees (about 1.2 radians) we would use,

;

Let’s look at all this nonsense in action to drive the point home.

There, that’s a little more interesting. Try manipulating a, b, c, and d to make the box kind of rotate. Also, note that a, b, c, and d are all relative to the blue box’s registration point in the top left, while tx and ty are the translation from the parent’s registration point to the child’s registration point. Why does this happen? If tx is 56 and ty is 32, why isn’t the blue box at pixel (56, 32)? This is because the when the display object is rendering, it doesn’t stop at its own transformation matrix. It actually traverses up the display list and concatenates (multiplies) each and every transformation matrix above it to find an absolute transformation matrix relative to the stage. The inverse of this is that if we change the transformation matrix of a DisplayObject, all of the children of the object inherit that transformation.

Go with the Flow

Back to flows. How can we use all these transformations to make a cool effect like the cover flow? We can think of each FlowContainer in the Flow as having two appearances. One is when its out of focus, or off to the side. The other is when it is in focus, either in the center of the screen (like in the classic cover flow) or directly underneath the mouse (like in our flow example). If we define those two appearances as matrices, we can easily interpolate between the appearances based on whatever input we’re using (the mouse, a slider, arrow keys, etc.). For basic transformations, our FlowContainer class keeps track of four variables.

private var lerp:Number; // the percentage of the effect currently being applied
 
private var positioning:Matrix; // the original position of the object, letting our transformations be relative
 
private var transformNone:Matrix; // the relative transformation when lerp is 0
private var transformFull:Matrix; // the relative transformation when lerp is 1

To set the values of these, we use a single method with some constants for context.

/**
 * Bind a transformation matrix to either the near or far appearence of the 
 * container. To specify whether the transformation happens near or away from 
 * the mouse, set the distance parameter to either Flow.NEAR_EFFECT or Flow.FAR_EFFECT.
 * @param	value		the transformation matrix to be bound
 * @param	distance	the distance constant at which the transformation is applied
 */
public function bindTransformEffect(value:Matrix, distance:String):void
{
	if (distance == Flow.NEAR_EFFECT)
		transformFull = value.clone();
	else if (distance == Flow.FAR_EFFECT)
		transformNone = value.clone();
	else
		throw new TypeError("The distance must be either Flow.NEAR_EFFECT or Flow.FAR_EFFECT");
 
	synchronize();
}

After these are set, we use synchronize() to match the appearance of the container with whatever matrices were set.

public function synchronize():void
{
	var lerpedTransform:Matrix;
 
	if (lerp != 0.0) {
		lerpedTransform = Util.lerpMatrix(lerp, transformNone, transformFull);
		lerpedTransform.concat(positioning); // make the transformation relative to the original position
	}
	else {
		// transformNone is cloned because otherwise the concat operation would compound
		lerpedTransform = transformNone.clone();
		lerpedTransform.concat(positioning);
	}
 
	transform.matrix = lerpedTransform;
}

There are two things to especially take note of in that code block. The first is at Util.lerpMatrix(), where we use linear interpolation between transformNone and transformFull. This is kind of bad, because linear interpolation doesn’t handle rotation correctly. But, it is a heck of a lot faster and easier than the alternatives: quaternions, slerping, or matrix decomposition/recomposition. If you’re like us and only need to use scaling and translation, here is the linear interpolation algorithm.

public static function lerpMatrix(value:Number, low:Matrix, high:Matrix):Matrix
{
	if (value < 0.0 || value > 1.0)
		throw new RangeError("The lerp value must be a percentage between 0.0 and 1.0.");
 
	var result:Matrix = new Matrix();
 
	result.a = value * (high.a - low.a) + low.a;
	result.b = value * (high.b - low.b) + low.b;
	result.c = value * (high.c - low.c) + low.c;
	result.d = value * (high.d - low.d) + low.d;
	result.tx = value * (high.tx - low.tx) + low.tx;
	result.ty = value * (high.ty - low.ty) + low.ty;
 
	return result;
}

The second thing to take note of is the concat() function, where we concatenate (multiply) the positioning variable onto the transformation. This is because its way easier for whoever is interfacing with this code to define the translations relative to wherever they’ve placed the object. The tx and ty value can look like 50 and -25, instead of random nonsense like 480 and 312. But, the transform property of the DisplayObject stores transformations relative to its parent, not itself, so we have to take care of that step ourselves.

In addition to transformations, we also store ColorTransformation objects and BlurFilter objects to lerp between and synchronize in our FlowContainer. After seeing how the regular transformations work, hopefully these are pretty easy to understand. Using only the FlowContainer object, we can make something like this:

A Little Organization

The final step is organizing these little nuggets of transformation juju into a usable UI component. Its a lot simpler than you might think; the Flow object only has about three substantial functions. The first step though, is keeping track of the FlowContainers so that we can iterate through them quickly. After that, adding DisplayObjects is easy.

/**
 * Add a component to the flow. The component can be anything; if it is not already 
 * a flow container, it will be wrapped in one automatically.
 * @param	item	the component to be added to the flow
 */
public function addComponent(item:DisplayObject):void
{
	var fc:FlowContainer
 
	if ( !(item is FlowContainer) ) {
		fc = new FlowContainer();
		fc.addChild(item);
	}
	else
		fc = FlowContainer(item);
 
	items.push(fc);
	addChild(fc);
}

After all the items are added, we need to put them in their place. We use the variable track here; its just a invisible movie clip that lets us separate the Flow‘s area for interaction from its area for display. A simple spacing algorithm, followed by the z-sorting algorithm:

/**
 * Organizes the flowable items into an even spread along the track.
 */
public function organize():void
{
	var item:FlowContainer;
 
	for (var i:int = 0; i < items.length; ++i) {
		item = (items[i] as FlowContainer);
 
		item.x = track.x + ( Number(i + 1) / Number(items.length + 1) ) * track.width;
		item.x -= item.width / 2.0; // center the component in its slot
		item.y = track.y;
 
		item.freezePositioning(); // stores the flow containers current position as the start point for any relative transformations
	}
}
 
/**
 * Sorts the z-index of the items based on their distance to the mouse.
 */
private function zsort():void
{
	var i:int = 0;
	var j:int = numChildren - 1;
 
	// make i the index of the component which should have the highest z-index
	while (i < (items.length - 1) && items[i].effectPercent <= items[i + 1].effectPercent) { 		++i; 	} 	 	/* 	 Move this component to the top of the z-stack. Note that j will then 	 point to the next highest spot on the z-stack because of the post-decrement 	 operator. 	 */ 	swapChildren(items[i], getChildAt(j--)); 	 	// sort the items left of the middle item 	for (var k_left = i - 1; k_left >= 0; --k_left) {
		swapChildren(items[k_left], getChildAt(j--));
	}
 
	// sort the items right of the middle item
	for (var k_right = i + 1; k_right < items.length; ++k_right) {
		swapChildren(items[k_right], getChildAt(j--));
	}
}

Then, we just listen to the mouse and update the FlowContainers. The input could easily be replaced by a slider or arrow buttons for something more infinite.

private function moveListener(e:MouseEvent):void
{
	// relative to the envelope of the flow
	var mouseX:Number = e.stageX - this.x;
 
	for (var i:int = 0; i < items.length; ++i) {
		var distance = Math.abs(items[i].x + items[i].width / 2.0 - mouseX);
 
		// here, effectNone and effectFull are numbers which indicate the distance from
		// the mouse where there is no effect, and full effect. then it just maps the distance
		// between those and winds up with a percentage.
		var percent:Number = Util.map( distance, effectNone, effectFull, 0.0, 1.0);
 
		items[i].effectPercent = Util.clamp(percent, 0.0, 1.0);
	}
 
	zsort(); // if a new flow container is in focus, it needs to be on top!
}

Custimization

That’s the last of it really. Put all the pieces together, and you end up with something like this:

To drive home how simple this framework makes it, here is all of the code used to configure the above flow.

var flow:Flow;
 
flow.farEffectDistance  = 150.0;
flow.nearEffectDistance = 0.0;
flow.maintainEffect = false;
 
for (var i:int = 0; i < 12; ++i)
	flow.addComponent(new SampleContainer());
 
flow.organize();
 
flow.transformEffect(new Matrix(1.5, 0, 0, 1.5, -30.0, -40.0), Flow.NEAR_EFFECT);
 
flow.blurEffect(new BlurFilter(4, 4, 1), Flow.FAR_EFFECT);

And to make it obvious how easy it is to customize it, here are some wacky settings that you might never want, but if you do, its possible. And that’s the important part.

var flow:Flow;
 
flow.farEffectDistance  = 150.0;
flow.nearEffectDistance = 0.0;
flow.maintainEffect = false;
 
for (var i:int = 0; i < 8; ++i)
	flow.addComponent(new SampleContainer());
 
flow.organize();
 
flow.transformEffect(new Matrix(0.2, 1, 1, 0.2, 2.0, -2.0), Flow.FAR_EFFECT);
flow.transformEffect(new Matrix(1.0, 0, 0, 1.0, 25.0, -25.0), Flow.NEAR_EFFECT);
 
flow.colorEffect(new ColorTransform(1, 1, 1, 0, 0, 0, 0, 0), Flow.FAR_EFFECT);

And guess what? Those buttons will always work.

Download the files here.

Please Grab The Download Here.

The majority of the C code is from Xiph.org. We basically took that, and hacked out the parts that wouldn’t compile through the alchemy/cygwin environment, such as the self tests and some of the macros. We then also forced some of the ifdefs to the correct settings, and reorganized the file structure to make it a bit easier to compile under cygwin. Once that was up and running, we spent the majority of our time building the wrapper C code (hookoggvorbislib.c) and the AS3 interface layer to access that C code. You can check out our Decoder/Encoder post to see how to use the library.

Once you download the source you can go into the alchemy/ogglib folder and check out all of the Alchemy source.
For a quick Cygwin refresher you can check out our other Alchemy Series posts on getting set up:
http://labs.byhook.com/2011/03/01/alchemy-series-part-2-environment-setup/
http://labs.byhook.com/2011/03/09/alchemy-series-part-3-ubiquitous-hello-world/

To compile the library it takes a couple of steps:
1) Open your Cygwin environment and turn on alc with “alc-on”
2) Change the directory to the alchemy/ogglib/lib folder
3) Delete the old object and archive files:./reset.sh
4) Compile the Xiph lib: ./compileLib.sh
5) Archive the lib: ./arcLib.sh
6) Move back up a directory level, and link with the wrapper:

cd ..
./linklib.sh

That should create a brand new .swc for you called hookOggVorbisLib.swc

Most of the concepts used in the wrapper code have been covered through out our Alchemy series and its fairly well commented. So feel free to poke around and see whats up. There is one limitation thus far, seeking is not working properly for the decoding. Of course if you decode the whole file into memory, then you can seek through the bytearray as you see fit. But the seeking to parts of the ogg data, and decoding from there is not working. If someone feels like tackling that let us know

In any case, have fun and let us know if you manage to put any of this to good use, we would love to hear about it!

Also remember to like us on Facebook if you want to stay updated, or even just to show your support:

And/Or you can follow me on Twitter:

For any of this to make sense, you will probably want to follow along with the code in the example which you can download here:
Example Source

Multiple File Compilation and Linking
While doing my own research on Alchemy, I came across many a forum post asking about compiling and linking C libraries that were comprised of multiple files, as most are. So this week’s example has been split up into multiple files to try and demonstrate the process. In the alchemy folder bundled with the example code, this is a folder called “lib”. In there is a couple of C files and a few Bash scripts. For the purpose of this example, we are going to consider this our Library. In order get our library compiled and ready to link with our Alchemy wrapper we have to complete a few intermediate steps.

The first step is to compile each of the .c files individually and create .o (object) files from them. These object files are what is linked together in the end to create the swc. Since most C libraries out there have lots of files, its probabaly most convenient to create a bash script to handle the compile. In our case its the “compilelib.sh” file.

#!/bin/bash
optLevel=3
 
gcc -I../include -I./ -Wall -O$optLevel -c loopstart.c
gcc -I../include -I./ -Wall -O$optLevel -c cancelstate.c

The first line should look familiar to you from previous posts, but just in case you missed it, it simply tells cygwin to interpret this script with the “bash” shell located at “/bin/bash”. Next we create a variable to make it easy to alter some compile settings without having to edit each line individually. Then we have the now familiar “gcc” calls. The “-I” switches tell gcc to add these folders to its search path when looking for files and definitions, such as (.h) header files. In this case we are telling it to look in the “include” folder one level up, and to also look in its own folder. The “include” folder has our “alcexample.h” file which contains the declarations for our library functions and data structures. The -Wall tells gcc to report all types of warnings while compiling. -O is the compiler optimization setting. At one point I thought the optimization was messing with Alchemy, I was wrong. But I figured it would be good to suggest leaving the variable in there as an example. You could probably do the whole include bit with a var too. Lastly “-c” tells gcc to not run the linker, and just save out the object file. Once those files have been compiled into object files, we need to archive the library together into one file. Thus the “arclib.sh” script:

#!/bin/bash
ar csr exampleLib.a loopstart.o cancelstate.o

To build the archive we use the “ar” program. The command line settings break down like this:
c – create the archive
s – this creates an object file index in the archive which “allows routines in the library to call each other without regard to their placement in the archive” (from ranlib docs)
r – inserts the object file into the archive and replaces duplicates instead of appending

Lastly we feed it the name we want the archive to be called and a list of object files we want included.

At this point we have the library built and archived ready for use in our Alchemy wrapper. So if you pop up one folder level you will see our main Alchemy file, alcexample.c, as well as another Bash script that will finish our build called “compileandlink.sh”:

#!/bin/bash
gcc -I./include -L./lib -lexampleLib -Wall alcexample.c -swc -O3 -o alcexample.swc

This looks very similar to our “compilelib.sh” script, with a couple of notable exceptions. This time we are using the “-L” switch to add a library path to the gcc search path. We then follow that with a “-l” switch and the name of our library. The “-c” has also been replaced by a “-o” and a “-swc”. Which means that gcc will now link the project and create your brand new .swc file

So, basically the moral of the story is to build a multi-file library, it takes three steps:
1) Basic library compile to object files
2) Archiving of the .o files to a single archive file (with indicies)
3) Final compile and link

Great, now that we can compile the example, lets jump back into looking at code.

Bound States
So a few posts ago, I had mentioned that the first parameter for the AS3_Function() call was usually NULL, and I at the time didn’t know why. Well, its been figured out You can replace this NULL with a pointer to some data of whatever kind you like. This can be a handy shortcut so you don’t have to continuously pass in the pointer address from flash to your function calls when you want to access data within the C code. If you take a look at the alcexample.c file and head down to main(), you will see it looks much like the rest of the examples. However instead of passing NULL into our AS3_Functions we are now passing a pointer to a struct.

typedef struct
{//LoopState
unsigned int totalLoops;
int isCancelled;
} LoopState;

//Setup main state
LoopState *mainState = initState();
mainState->isCancelled = 1;
mainState->totalLoops = 0;
 
//Virtual Function (thunk) mappings
AS3_Val setCancelStateMethod = AS3_Function(mainState, setCancelState);
AS3_Val startStateLoopMethod = AS3_FunctionAsync(mainState, startStateLoop);
AS3_Val cleanUpMethod = AS3_Function(mainState, cleanUp);

The struct itself is defined in the “alcexample.h” file, and simply included into the “alcexample.c” file. Its a fairly basic structure that simply has two members, totalLoops, and isCancelled. In main() we essentially “new up” an instance of that struct (really just allocate some memory for it) by calling initState() which basically does this:

LoopState *state = (LoopState*)malloc(sizeof(LoopState));
return (unsigned int)state;

This is a bit of a spin on what we did in the last post. Since we aren’t going to report this memory address back to Flash, we can return the pointer to the LoopState instance directly. This way we won’t have to resolve the pointer from the memory address every time we want to use it, since its already a pointer.

After we malloc some space, and grab the pointer to it, we set up some default values in the struct. We set isCancelled to 1 (which we will signify “true”) and set the totalLoops count to 0.

With our state all set up, we can pass that pointer in to our thunks. Which means that the C functions mapped in those thunks will be fed that pointer as its first argument. So now we don’t need to pass the pointer to that data in every time. It just gets bound to the thunk and we get access to it at all times in the functions. This is great for convenience, but you do give up flexibility for it. You won’t be able to change what pointer is bound to the thunk, so if you want to be able to access different data every time you call the function, you will need to pass in your own pointer, or a memory address that can be used to get the pointer, which is what we did for the imageData struct in the last post.

Lets take a look at the setCancelState() function in the cancelState.c file as an example of how to use this “state” data.

//Get loop state from data passed in
LoopState *state = (LoopState*)data;
 
//Vars to store passed in cancel state
int cancelState;
 
//Parse args for cancel state
AS3_ArrayValue(args, "IntType", &cancelState);
 
//Set new cancel state
state->isCancelled = cancelState;
 
//Debug print
fprintf(stderr, "Cancel State: %i", state->isCancelled);
 
return AS3_Null();

The first thing we do is cast and save the “data” argument into the “state” variable. This is mainly for convenience. Next we parse out the arguments passed in from flash, which in this case is either a 1 or a 0 and save that in “cancelState”. Finally we set the “isCancelled” member of state to be whatever was passed in from flash. Pretty straight forward. All of the other functions work in the same fashion with regard to getting access to the LoopState structure. When calling this function from Flash it looks like this:

//Cancel Loop by setting the LoopState->isCancelled to 1 (true)
_lib.setCancelState(1);

Async and the Thiz
The last major “feature”, if you will, in this example, is the use of the AS3_FunctionAsync(). This will allow you to set an ActionScript callback that will be called when the function finishes. Back in main() you will see the thunk definition for this:

AS3_Val startStateLoopMethod = AS3_FunctionAsync(mainState, startStateLoop);

From ActionScript the call looks like this:

//Call async function
_lib.startStateLoop(handleLoopComplete, this);

This means that when startStateLoop() completes, handleLoopComplete will be called in ActionScript. Unfortunately, that is all this means. I know what you’re thinking, “The function will run in its own thread! Finally multi-threaded flash!” Sadly, this is not the case. Then you ask “So why even make a separate Function type if it simply plays out like every other function?” The answer to that is in flyield(). This is a magical function in Alchemy that will “pause” alchemy and give up its timeslice back to Flash. This means that every time you call flyield(), flash gets to execute for another tick. Then Alchemy will execute some more until flyield() is called again. So even though its not really multi-threaded, you can let your C code churn on some data for a while without locking up your swf and its UI. This is useful for instance if you are encoding sound data or some other cpu intesive task. This way you can throw up a progress indicator of some kind and its visuals can be updated while the C code is doing its thing. A quick thing to note, is that your UI will be locked up while the C code is doing something, it will only get updated when flyield() is called. Which means that the longer you wait to call flyield() the longer the UI is unresponsive. If this is less than the time it takes to render a frame, then no one will notice. This means that you will probably need to do some experimentation on your target hardware to determine how much processing you can do in C before giving it up to Flash. The downside is that while Flash is doing stuff, your C code is not. Which means that the more often you yield to flash, the slower your number crunching in C happens.

Now, I mentioned progress bars, and initially you probably just skimmed over that without any other thoughts, but there is an issue there. If your C code is running in a timeslice, how exactly do you get the “progress” of the number crunching back to flash to display? If you pop open loopstart.c we can take a look.

The first clue is in the argument parsing. Besides the void *data argument, there is the other AS3_Val that gets passed in. This gets stored in the AS3_Val clientObj variable.

//var to hold a reference to the Thiz
AS3_Val clientObj;
 
//Parse passed in arguments and get ref to Thiz
AS3_ArrayValue(args, "AS3ValType", &clientObj);

If you’ll notice, from ActionScript we make this call

//Call async function
_lib.startStateLoop(handleLoopComplete, this);

Notice the “this”? That is an actionScript reference to an actionScript object. When that is brought into C and converted to an Alchemy Data Type, its called a “Thiz”. A thiz is essentially a virtual object much like a tunk is a virtual function, which is not to be confused with a C++ virtual function. Now that we have this thiz we can do some cool things directly to our running Flash code. In our case we are going to update the flash code with the current progress of our C code.

//Build an array of parameters to pass to the ActionScript
//Method call
AS3_Val params = AS3_Array("IntType", state->totalLoops);
 
//Call method on Thiz
AS3_CallS("updateFromAlc", clientObj, params);

The AS3_CallS() takes three arguments, a const char* (C string) of the name of the method you want to call, the thiz you want to call the method on, and a list of params to pass to the method you are calling. In our case, all we are passing is the totalLoop count from the LoopState. In actionScript our updateFromAlc() method looks like this:

public function updateFromAlc($totalLoops:int):void
{//updateFromAlc
	//Update the UI (happens during a yield)
	_textView.numLoopsText.text = $totalLoops.toString();
}//updateFromAlc

As you can see the method is expecting an integer to be passed to it, and it gets that from the state->totalLoops member from the C code. So now we have full communication from the C code to Flash, and also from Flash to the C code. Its worth mentioning that if you check out the Alchemy docs you will see you can also get and set properties on ActionScript objects that are passed in to the C functions.

Async Cancellation
There is one final interesting bit to this example. If you check out the while loop in the startStateLoop() method, you will see this:

while(state->isCancelled == 0)

This essentially means that the loop is going to keep running until something changes in the LoopState data. Specifically when isCancelled becomes non-zero. If you think about it a bit, it at first seems impossible to change that state data while the loop is running. However, as it turns out, during a flyield() you can actually call other functions on the C code while Flash has control! Crazy right? So in the Alchemy C code, the execution pointer is sitting at the flyield() call. Flash gets its time slice, and then calls another function, in our case setCancelState(1), and changes the state data. On the next tick, the Alchemy Code gets its next time slice and then continues on from original point of execution, one line after the flyield() call. Now, the next time through the loop, state->isCancelled is now 1, and the loop exits. Execution continues to the bottom of the function where the total number of loops is returned. When this return is hit, guess what is called… our ActionScript method handleLoopComplete(), and to it is passed the total number of loops. Yay! This means we have full control of our C based async functions directly from Flash! I mean what else can you ask for from a single threaded virtual machine?

Fin
Welp, that about wraps it up. There will probably be one more post in this series, but it won’t be so much of a tutorial as a information on our Ogg Vorbis library So for those of you following along at home, thanks for reading about our Alchemy Adventures! As always, if you get around to making something cool with any of this info, let us know, we would love to see it!

Also remember to like us on Facebook if you want to stay updated, or even just to show your support:

And/Or you can follow me on Twitter:

Thanks to the hard work of others and huge leaps in processing power, exploring the world of real-time graphics is much easier. I’d wanted to build something with Processing ( http://processing.org ) for quite some time. It has a huge following, tons of libraries, and was born at MIT. Also, It’s much more difficult for my mother to unplug the internet and destroy my work.

Twitter Data for real-time artwork
The twitter streaming server is referred to as ‘Firehose’ for good reason. It’s continuously spewing tweets and all of their accompanying meta-data. This provides a great look into real time data from around the world, and is a great source for generative graphics. I find this approach interesting as it really starts to show some patterns in the chaotic reality that is human social behavior. The stream is in JSON format and easily consumed using java or in this case the twitter4j lib. ( http://twitter4j.org ) I’m sure other social media platforms will or do have similar streams. I look forward to using them in future works for something even more visually abstract.

Wrapping it all up
Based on the streaming data from twitters “firehose”, and the very cool opengl capabilities of processing I decided to map each tweet out to a 3D globe. Using natural language processing we color the tweets points, and text to a color representing the sentiment of the tweet. Pinkish is negative, Blue is Positive, and white is neutral. Now not all tweets from the stream are created equal. This is because not all users tweet from a geo enabled device. So, in the case that the tweet does not include geographical location data we simply do not plot it on the globe. But every tweet is analyzed by the NL engine and then used in the data set for the radial graph around the globe.

Using the great toxi libs I was able to track the tweets floating down the the surface as solids in a voxel grid. They are then converted to a triangular mesh and I draw them out to the screen in the render loop. If you watch them closely you will see the mesh uses the color of the tweet it represents, and mixes colors with nearby tweets creating a colorful mesh of voxely awesomeness. I realize this is nothing more than visual noise. But the intention here was to create something visually entertaining as well (semi-)informative.

Making since of tweets
Have you seen the mindless jabber on twitter? It’s a bunch of “Got my #verizon #iphone #today! Can’t wait to download hipstermatic so I can be a photographer!”, “#Superbowl ads are the lolz!” or “#bacon for lunch again!” What’s the use in any of that? Well, using the very cool Lingpipe natural language engine we can make an attempt to extract the sentiment of tweets. While it’s not 100% accurate (the authors claim somewhere in the 80% range) it is very useful for driving visual cues in the visualization. It’s also great at identifying language or allowing us to filter stuff out such as people who are just tweeting links to porn sites or lolcats.

Computational linguistics is a science in itself. Let’s break down the basics used used here to classify the tweets.

In a new Processing sketch we include Lingpipe and connect to twitter to monitor the stream and build a Language Model (LM) that will later be loaded into the main visualization sketch to classify the tweets from the stream.

Pseudo code:

1
2
3
4
5
6
7
8

import com.aliasi.util.*;
import com.aliasi.classify.*;
 
mCategories = [ “positive”, ”negative”,  “neutral”, “url” ];
int nGram = 8;
mClassifier
= DynamicLMClassifier
.createNGramProcess(mCategories,nGram);

We initialize an instance of DynamicLMClassifier using a factory method and pass in an array of categories we will be using, and an n-gram size. In this case we used a 8-gram as suggested by the authors of Lingpipe. Later when we send in a sequence of characters (a tweet) the LMClassifier will break it down into n-grams. This allows Lingpipe to efficiently compare other sequences of characters later when we ask it to classify a tweet from the stream.

Now as tweets come in from the stream I can save them out to a text file categorized in folders to build the language model and save it out for later use. This is just a quick and dirty way to keep twitter data around after closing a processing sketch. After quite a few long hours of classifying each tweet ( and slowly loosing a little faith in humanity after reading that many random tweets ) I can generate a reusable data model to be used in the main sketch:

Pseudo code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

for (int i = 0; i < mCategories.length; ++i) {
String category = mCategories[i];
Classification classification = new Classification(category);
File file = new File( polarityFolder, mCategories[i]);
File[] trainFiles = file.listFiles();
for (int j = 0; j < trainFiles.length; ++j) {
File trainFile = trainFiles[j];
if (isTrainingFile(trainFile)) {
++numTrainingCases;
String tweet = Files.readFromFile(trainFile,"ISO-8859-1");
numTrainingChars += tweet.length();
Classified<CharSequence> classified
 
 
= new Classified<CharSequence>(tweet,classification);
 
 
mClassifier.handle(classified);
}
}
}

Then simply save the instance of the classifier out and we have a model baked and ready to go.

Pseudo code:

1
2
3
4

FileOutputStream fileOut = new FileOutputStream(dataPath("")+"\\polarity.model");
ObjectOutputStream objOut = new ObjectOutputStream(fileOut);
mClassifier.compileTo(objOut);
objOut.close();

You can download this utility sketch here: LingPipePolarityGenerator.zip
(Download the lingpipe.jar from http://alias-i.com/lingpipe/ and drop it into the code folder to run the sketch)

Back in the main sketch it’s trivial to load the model back in and ask it to classify the tweets as they come in from the stream.

Pseudo code:

1
2
3
4

InputStream fileIn = createInput("polarity.model");
ObjectInputStream objIn = new ObjectInputStream(fileIn);
loadedModelClassifier = (LMClassifier)objIn.readObject();
Streams.closeInputStream(objIn);

We now have our model instance ( loadedModelClassifier ) ready to classify tweets like this:

Pseudo code:

1
2

Classification classification = loadedModelClassifier.classify( tweetFromStreamString );
System.log( classification.bestCategory() );

The call to the bestCategory method will yield a string representation of the best match based on the sample data we supplied to the model in the utility sketch. Language detection is done in the same fashion, but it uses a model supplied with lingpipe and is reasonably accurate as well.

Lingpipe manages to encapsulate all of the complex methods of Computational Linguistics and yields some very useful results. Find more information on it here: http://alias-i.com/lingpipe/

The Results
Once things started coming together I started to notice some patterns immediately. The most apparent pattern is the number percentage of positive, negative, and neutral tweets. And to my surprise they tend to stick to about 39%, 13%, 48% respectively. Looks like people on twitter aren’t nearly as negative as I had originally thought them to be!

PROTIP: Global Illumination renders with Sunflow library
I’m no Java evangelist, but some of the open source libraries out there for the java platform are very cool. In this case Sunflow ( http://sunflow.sourceforge.net/ .) I rewrote all the geometry routines in the processing sketch to spit out data that sunflow could load in and render. The results are pretty fun, this was definitely a rewarding endeavor. Hey real-time is awesome, but so is global illumination and ambient occlusion shaders. Some day I’m sure the two will converge!

Have a go at it
Click here to run the sketch in your browser. It will not run in the browser on MacOS, so if that is your platform of choice give grab the standalone version linked below.

Standalone for Windows
Standalone for MacOS

You can download the processing sketch source here: socialSentiment_src.zip

The Example can be Downloaded Here.

This example is broken up into three different parts. The first deals with basic object creation and return, the second, deals with ByteArrays as file streams in C (I promise that is super useful), and finally the third is keeping data stored in C as a way of keeping state internal to your library.

So if you run the supplied example inside of the Flash CS5 IDE or from FlashDevelop/Builder, or something that watches for traces, you will see this:

– Start Basic Data Example –
(ALC) Text: Test Text
(ALC) Int: 15
(ALC) Number: 3.141592
(ALC) AS3 Obj Text: Hawt String
(ALC) AS3 Obj Int: 42
Obj: Test Text
Obj: 15
Obj: 3.141592

– Start ByteArrays as Streams Example –
In Bytes Length: 10000
>Out Bytes Length Before: 0
(ALC) Bytes Read 1024
(ALC) Bytes Written 1024
(ALC) Bytes Read 2048
(ALC) Bytes Written 2048
(ALC) Bytes Read 3072
(ALC) Bytes Written 3072
(ALC) Bytes Read 4096
(ALC) Bytes Written 4096
(ALC) Bytes Read 5120
(ALC) Bytes Written 5120
(ALC) Bytes Read 6144
(ALC) Bytes Written 6144
(ALC) Bytes Read 7168
(ALC) Bytes Written 7168
(ALC) Bytes Read 8192
(ALC) Bytes Written 8192
(ALC) Bytes Read 9216
(ALC) Bytes Written 9216
(ALC) Bytes Read 10000
(ALC) Bytes Written 10000
>Out Bytes Length After: 10000

– Start Image Data Example –
Length: 40000
Memory address for RED image: 1069136
Length: 10000
Memory address for GREEN image: 1069152

You will also see a Red square with a translucent and smaller Green square on top of it. Epic exciting I know, but the behind the scenes bits are pretty awesome if you ask me First up, basic data handling example.

Data in, Data out
At this point, I’m assuming you have worked your way through the Part 3 post, and are fairly comfortable compiling things, and working with that compiled swc in flash. But I do want to point out some changes in the main() function of this example.

//Virtual Function (thunk) maps
AS3_Val showArgsMethod = AS3_Function(NULL, showArgs);
AS3_Val storeImageBytesMethod = AS3_Function(NULL, storeImageBytes);
AS3_Val adjustAlphaMethod = AS3_Function(NULL, adjustAlpha);
AS3_Val getImageBytesMethod = AS3_Function(NULL, getImageBytes);
AS3_Val freeImageBytesMethod = AS3_Function(NULL, freeImageBytes);
AS3_Val copyBytesMethod = AS3_Function(NULL, copyBytes);

The first bit is still the same. We declare and define an AS3_Function thunk for each of the function we want to expose and map that to the actual internal C function. So far so standard.

The next line you’ve seen before as well

//Bundle up the thunks into an AS3 Object.  This object is what flash sees
//after you call init() on the loaded Alchemy loader.
AS3_Val flashObj = AS3_Object("showArgs:AS3ValType, copyBytes:AS3ValType", showArgsMethod, copyBytesMethod);

This, as before, creates an AS3 Object that will hold the mappings to our internal functions. This is how those functions are accessed from ActionScript. You also pass in a Type Template pattern as a string, and then references to the thunks. Still pretty normal. However you will notice that we’ve defined six functions, but have only included two in our AS3 Object. If we put all six in there, the line starts to get very unwieldy. So we can use the AS3_SetS() function to attach more properties/functions to our AS3 Object.

AS3_SetS(flashObj, "storeImageBytes", storeImageBytesMethod);
AS3_SetS(flashObj, "adjustAlpha", adjustAlphaMethod);
AS3_SetS(flashObj, "getImageBytes", getImageBytesMethod);
AS3_SetS(flashObj, "freeImageBytes", freeImageBytesMethod);

AS3_SetS() allows use to add properties by name and set their inial value. The first parameter is the object we want to add our properties to. The second is a (constant) char* list of characters that is the name of our property. Lastly we pass in the initial value of that property. In this case, we are passing in the thunks we made to expose out C functions with. That is the first bit of data management in the first example. Setting properties at runtime to AS3 Objects. Remember this is a “real” AS3 Object, so it can be returned to Flash and used directly.

This concept is more obviously implemented in the showArgs() C function. This function serves no purpose other than to demonstrate a few different ways of dealing with basic data. From Flash we do this:

/////****** BASIC DATA EXAMPLE *****\\\\\
//Demonstrate Object Properties
trace("-- Start Basic Data Example --");
var testObj:Object = { stringProp:"Hawt String", answerProp:42 };
var retObj:Object; 
retObj = _lib.showArgs("Test Text", 15, 3.141592, testObj);
trace("Obj: " + retObj.myText);
trace("Obj: " + retObj.myInt);
trace("Obj: " + retObj.myDbl);

and we should get the following debug output:
– Start Basic Data Example –
(ALC) Text: Test Text
(ALC) Int: 15
(ALC) Number: 3.141592
(ALC) AS3 Obj Text: Hawt String
(ALC) AS3 Obj Int: 42
Obj: Test Text
Obj: 15
Obj: 3.141592

Once the C library is instantiated, we can start to call functions on it. In this case we are creating a new object, “testObj” and defining a few dynamic properties on it by hand.

var testObj:Object = { stringProp:"Hawt String", answerProp:42 };

Then we make the call, passing in a few more parameters in addition to the testObj:

retObj = _lib.showArgs("Test Text", 15, 3.141592, testObj);

This maps, not surprisingly, to the showArgs() function in our C file. So lets dig into that a bit.
The first bit is very similar to our echoMe() function from the previous post. We declare some variables, and parse out the arguments using the AS3_ArrayValue() function.

//Declare some variables to hold the passed in data
char* myText;	//AS3_String maps to char*
int myInt;		//AS3_Int maps to int
double myDbl;	//AS3_Number maps to double
AS3_Val myObj;	//AS3_Object passed in.
 
//Declare some more vars to hold the values parsed out of myObj
char* testObjString;
int testObjInt;
 
//Delcare var for our return object
AS3_Val returnObj;
 
//Parse out arguments using AS3_ArrayValue
//This takes the passed in args object, and creates new C values
//from it based on the string of types given as a pattern
AS3_ArrayValue(args, "StrType, IntType, DoubleType, AS3ValType", &myText, &myInt, &myDbl, &myObj);

So this is expecting us to pass in a String, Int, Double, and a Generic AS3 Value. Which we do with “Test Text”, 15, 3.141592, and testObj and store those in their respective C variables. The first three are fairly standard, so we store them and then print them out with fprintf() which I touched on last time. Basically fprintf takes a stream to write to and some things to write out in a specific format:

//Print out the basic arguments
fprintf(stderr, "(ALC) Text: %s", myText);
fprintf(stderr, "(ALC) Int: %i", myInt);
fprintf(stderr, "(ALC) Number: %f", myDbl);

In this case, our stream is stderr (declared in stdio.h). The flash debugger will catch this and print it out much like a trace. The second argument we have a char* (a string of characters) and a format identifier. Lastly is a list of values that will populate those format identifiers. A good reference for fprintf is here: http://www.cplusplus.com/reference/clibrary/cstdio/fprintf/
As you can probably tell, %s will display a char*, %i will display an integer, and %f will display a floating point value. There are many things you can display in this manner, check out the reference page above for a complete list.

So that takes care of passing in basic atomic data. What about objects and other forms of complex data? For that we can use AS3_ObjectValue()

//Parse passed in AS3 Object into valid C types
AS3_ObjectValue(myObj, "stringProp:StrType, answerProp:IntType", &testObjString, &testObjInt);
fprintf(stderr, "(ALC) AS3 Obj Text: %s", testObjString);
fprintf(stderr, "(ALC) AS3 Obj Int: %i", testObjInt);

AS3_ObjectValue() works in a similar fashion to AS3_ArrayValue(). You give it an AS3 object, a type template, and the destinations for the parsed values. The AS3_ObjectValue() handles all of the details of the type conversion, which is nice. Then we print out the respective values. So far so good. So what about returning an AS3 object? We can do that too:

//Build return object
returnObj = AS3_Object("myText:StrType", myText);
AS3_SetS(returnObj, "myInt", AS3_Int(myInt));
AS3_SetS(returnObj, "myDbl", AS3_Number(myDbl));

This should look mighty familiar to you, as its nearly identical to what we did when putting our thunks together in main(). First we make an object with AS3_Object(), and feed it a property name:Type and then an initial value. From there we can add more dynamic properties with AS3_SetS(). Its as simple as that.

So now we can send data into C functions, modify it, print it, and recombine it to be returned back to flash as a proper AS3 object. As you will discover, once you get the hang of getting your values converted back and forth, working with Alchemy isn’t so hard at all So lets look at something slightly (no much mind you) more practical.

ByteArrays and File Streams
I’ve read quite a few posts and comments on the internet debating whether or not Alchemy is faster than straight ActionScript, since it all runs within the flash virtual machine anyway. The consensus seems to be a giant “it depends”. For me however, its not so much about that. Its more about being able to access the bagillion (careful, thats a technical term) lines of C/C++ code out there that has been written to do just about anything you want over the last 40ish years. For us it was getting access to Xiph’s wonderful Ogg and Vorbis libraries for dealing with sound data. Can you imagine flash with access to something like FMOD? Or even physics engines? or C based path finding libraries? Yeah epic… For me, this is the real power of Alchemy, though the faster memory access is also a nice bonus My real point to all of that blathering is many of the libraries out there (especially libraries that convert stuff) use file data off of the command line, and write the modified data back out to a file stream. So instead of trying to convert your data or make deep hacks at the C code, you can simply stream your ByteArray data as a standard file stream right to the library, as if it were coming right off of the command line. The core concept for this was demonstrated here: http://segfaultlabs.com/devlogs/alchemy-asynchronous-jpeg-encoding

The idea is that we can use funopen() to redefine how the file streams work in C. Basically we replace the built in methods for accessing the data with our own. For this we can use Alchemy’s ByteArray functions:

/******************************************
* bytearray manipulations for use as C streams
*******************************************/
static int readba(void *src, char *dst, int length)
{//readba
	return AS3_ByteArray_readBytes(dst, (AS3_Val)src, length);
}//readba
 
static int writeba(void *dst, const char *src, int length)
{//writeba
	return AS3_ByteArray_writeBytes((AS3_Val)dst, (char *)src, length);
}//writeba
 
static fpos_t seekba(void *src, fpos_t offs, int whence)
{//seekba
	return AS3_ByteArray_seek((AS3_Val)src, offs, whence);
}//seekba
 
static int closeba(void *src)
{//closeba
	AS3_Val zero = AS3_Int(0);
	AS3_SetS((AS3_Val)src, "position", zero);
	AS3_Release(zero);
	return 0;
}//closeba

To make use of these new functions we can reassign them like this:

//Open bytearrays as stdio streams
FILE *output = funopen((void *)outBytes, readba, writeba, seekba, closeba);

For this section of the post we will be using the copyBytes() function from the alcexample.c file. The we call this from ActionScript in the “Byte Arrays as C Streams” section of Main.as

/////***** BYTE ARRAYS AS C STREAMS *****\\\\\
trace("\n-- Start ByteArrays as Streams Example --");
var inBytes:ByteArray = new BitmapData(50, 50, true, 0xFFFFFFFF).getPixels(new Rectangle(0, 0, 50, 50));
var outBytes:ByteArray = new ByteArray();
inBytes.position = 0;
 
trace("In Bytes Length: " + inBytes.length);
trace(">Out Bytes Length Before: " + outBytes.length)
_lib.copyBytes(inBytes, outBytes);
trace(">Out Bytes Length After: " + outBytes.length);

So what are we doing here? To demonstrate how to use ByteArrays as C streams, we will simply be taking some byte data, iterating over it all, and pushing it into a new output stream. Effectively making a copy of the byte data. I know its not that exciting, but its what made our OggVorbis encoder possible. So I think its a pretty awesome concept.

In the above ActionScript, we are simply generating some byte data to copy by making a white square as bitmap data, and using getPixels() to convert that to a ByteArray. Then we create an empty ByteArray as a container for the copied byte data. Finally we call copyBytes() on the C lib and pass in the input and output ByteArrays.

Meanwhile… In the C copyBytes() function we start off like we always do, declare some vars, and parse out the arguments.

//Declare byte arrays
AS3_Val inBytes;
AS3_Val outBytes;
 
//Declare other needed vars
long inLength;
long outLength;
long bytesRead = 0;
long bytesWritten = 0;
int i = 0;
 
//Parse args
AS3_ArrayValue(args, "AS3ValType, AS3ValType", &inBytes, &outBytes);

This parses our arguments and assigns our two ActionScript ByteArrays to inBytes and outBytes. The goal here is to read through all of the inBytes bytes, and copy it to the outBytes ByteArray, all the while treating it like a file stream.

Next we set up the streams to make use of our ByteArray wrapper functions from before.

//Open bytearrays as stdio streams
FILE *output = funopen((void *)outBytes, readba, writeba, seekba, closeba);
FILE *input = funopen((void *)inBytes, readba, writeba, seekba, closeba);

Now being as though we are treating these guys as streams, we don’t know how many bytes there will be, so we are going to want to store off the length of the ByteArrays, using our old friend AS3_ObjectValue()

//check length
AS3_ObjectValue(inBytes, "length:IntType", &inLength);
AS3_ObjectValue(outBytes, "length:IntType", &outLength);

Now that we are all set up, we can actually do something with the data. To make an attempt to stay faithful to what generally happens, we are going to copy 1k chunks of the stream to a buffer, (where you would in theory modify the data) and then copy the contents of that buffer back to the output stream

while(bytesRead < inLength)
{//copy bytes
	//Read 1k at a time
	for(i = 0; i < 1024 && bytesRead < inLength; i++)
	{//read to buffer
	bytesRead += fread(readBuffer, 1,1,input);
	}//read to buffer
 
	fprintf(stderr, "(ALC) Bytes Read %ld", bytesRead);
 
	//write 1k out to stream
	for(i = 0; i < 1024 && bytesWritten < inLength; i++)
	{//write to output
		bytesWritten += fwrite(readBuffer, 1,1,output);
	}//write to output
 
	fprintf(stderr, "(ALC) Bytes Written %ld", bytesWritten);
 
}//copy bytes

Now our ActionScript outBytes ByteArray will contain a copy of the contents of the inBytes ByteArray.

Finally when we are all done, we close up the streams, and release our AS3 objects:

//Close up streams
fclose(output);
fclose(input);
 
AS3_Release(inBytes);
AS3_Release(outBytes);

Pointers and Data Structures
Ok, so far so good I hope. All of this was in preparation for this last section. In this part of the example, we will be demonstrating how to store data into malloc’d memory inside of the Alchemy code. For this example we will be making use of the storeImageBytes(), freeImageBytes(), adjustAlpha(), and getImageBytes() functions in the alcexample.c file. If pointers or non-memory managed languages are new to you, you may want to grab a quick nap, or take a break and get something to eat. Its not the simplest thing in the world on first viewing.

Deep Breath, here we go.

If you run the example swf, you will see a red box with a smaller translucent green box sitting inside of it. What we are going to do, is store the bitmap data for both boxes inside of the Alchemy code (on the heap) and save off the memory address that starts the contents of that data. Once its stored there, we can manipulate it within the C code, without having to push that data into Alchemy again and again. We can just manipulate it right in memory, and when we are done, we can pull it back out. This is an example of how to keep state inside of your C code.

First up, creating the ByteArrays that contain our bitmap data for the boxes:

/////******* STATE MANAGEMENT ******\\\\\
//Build a red test image (red square)
trace("\n-- Start Image Data Example --");
var redBytes:ByteArray;
var redBD:BitmapData = new BitmapData(100, 100, true, 0xFFFF0000);
redBytes = redBD.getPixels(redBD.rect);
 
//Build Green Test image (green square)
var greenBytes:ByteArray;
var greenBD:BitmapData = new BitmapData(50, 50, true, 0xFF00FF00);
greenBytes = greenBD.getPixels(greenBD.rect);

Once we have that we store that data on heap:

//Store bytes in alchemy memory
redBytes.position = 0;
var redPtr:Number = _lib.storeImageBytes(redBytes);
trace("Memory address for RED image: " + redPtr);
 
greenBytes.position = 0;
var greenPtr:Number = _lib.storeImageBytes(greenBytes);
trace("Memory address for GREEN image: " + greenPtr);

As you can see when we call _lib.storeBytes() we get a number back in return. This number is the memory address that represents the start of our stored data. Any time you want to access that data you will need to pass that back into the C code, which will then get a reference to the data from the memory address. But before we get too far ahead or ourselves, lets check out what storeImageBytes() does.

The first part should at this point be very familiar to you. Declare some vars, parse the arguments, and store the values from the arguments. In this case we are also saving off the length of the passed in ByteArray.

//Delcare incoming byte array
AS3_Val bytes;
 
//Var to hold the length value
int length;
 
//Pars args
AS3_ArrayValue(args, "AS3ValType", &bytes);
 
//Determine length
AS3_ObjectValue(bytes, "length:IntType", &length);

This next bit, grabs some memory from the heap and stores a pointer to that memory

//Allocate memory for and save an instance of the imageData Struct
imageData *image = (imageData *)malloc(sizeof(imageData));

I know, I know, there is that pesky “imageData” type that I haven’t mentioned yet. So lets get to that real quick. At the very top of the alcexample.c file, you will see the definition for that typedef struct.

typedef struct
{//imageData
        unsigned char *data;
	int length;
} imageData;

Basically this is just an object that has two properties or members, “data”, and “length”. Data is a pointer to some memory that holds a list of unsigned chars. Why unsigned chars you ask? Well, they have a valid range of 0 to +255. Hmmm… what else goes from 0 to 255? Oh I know! A single channel of color data! In flash if I say 0xFFFF0000 you probably immediately think Red at full Alpha, because Flash uses the ARGB color format (alpha, red, green, blue). This is a hex number, when converted to Decimal, looks like 255 255 0 0 (argb). So half alpha blue would look like 127 0 0 255 or 0x7F0000FF. So what we are going to do is store the actual image byte data right there in the “data” member. Then we are also going to store the length of our byte data in the “length” member. However we want to make sure that our instance of the imageData struct doesn’t go out of scope when we leave the storeImageBytes() function, so we need to grab some memory off of the heap, instead of the stack. Which is where the malloc line, once again, comes into play.

malloc(sizeof(imageData))

With a pointer to our newly malloc’d imageData instance, we can access the “data” member of that instance and malloc some more memory to store our actual byte data in and also save off the length:

//Allocate some heap memory
image->data = (unsigned char *)malloc(sizeof(unsigned char)*length);
 
//Save length
image->length = length;

Now with everything ready, we can read in our byte data from the passed in ByteArray and shove it into our struct. We can use Alchemy’s built in ByteArray methods to get the data out.

//Write bytes to buffer
AS3_ByteArray_readBytes(image->data, bytes, length);

So now if we checked out the data that has been stored (assuming its from the red square bitmap data) when we execute this:

fprintf(stderr, "A: %i", image->data[0]);
fprintf(stderr, "R: %i", image->data[1]);
fprintf(stderr, "G: %i", image->data[2]);
fprintf(stderr, "B: %i", image->data[3]);

we would see:
A: 255
R: 255
G: 0
B: 0

That would be the ARGB colors of the first pixel in our red square. Awesome right?

After we do some clean up we can then return the memory address of our struct instance:

return AS3_Number((long)image);

That number is the number we are going to store in our ActionScript code, to be used to reference the image data that we care about.

Great so now we have the data in there, what can we do. Well staying consistent with the rest of the horribly forced examples, we are going to modify the Alpha Channel of that image data. From ActionScript we are going to do this:

//Adjust the alpha of the image bytes
_lib.adjustAlpha(redPtr, 0.8);
_lib.adjustAlpha(greenPtr, 0.3);

The first argument is that memory address we received from when we stored the image data. The second argument is a 0 – 1 value that we will multiply against our Alpha Channel bytes in our stored image data.

The adjustAlpha() function once again starts out like the rest. Delcare some vars and parse the arguments

//Get access to image data from memory address
imageData *image;
unsigned int imageAddress;
 
//Storage for alpha multiplier
double alphaMult;
int count;
 
unsigned char alpha;
unsigned char red;
unsigned char green;
unsigned char blue;
 
//Parse args
AS3_ArrayValue(args, "IntType, DoubleType", &imageAddress, &alphaMult);

Next however, is the tricky bit. We need to take that passed in memory address and create a pointer to the data at that address, which is of the imageData type defined by our struct

//Get pointer to image
image = (imageData *)imageAddress;

So now, image is a pointer to the imageData instance we care about. So lets do something with it.

//Walk pixels
count = 0;
while(count < image->length)
{//each pixel
	alpha = image->data[count];
	red = image->data[++count];
	green = image->data[++count];
	blue = image->data[++count];
 
	//Modify channels
	alpha = (unsigned char)(alpha*alphaMult);		
 
	//Store back into data
	image->data[count-3] = alpha;
	image->data[count-2] = red;
	image->data[count-1] = green;
	image->data[count-0] = blue;
 
	count++;
}//each pixel

Nothing earth shattering here, but if you come from a purely ActionScript background, some things may look a bit funky. The most obvious item is the “->”. Never fear, all this does is dereference the “image” pointer and grab the value at the memory address of the member data. So for alpha= image->data[count] we are simply getting the byte that is stored in that imageData instance at “count” index. So if “count” is 0, and we are looking at the red square then the value would be 255 or 0xFF because that pixel has full Alpha (“A”rgb). Then we simply walk down each byte and do whatever we want with it. In this case, we are mutiplying the alpha value by the alpha multiplier that was passed into the function. Then we write that back to the “data” member. Simple enough. The thing to remember is that we have modfied the data on the heap, so its permenantly set that way now, until of course we change it again.

So cool… We have managed to store some data, and modify it. Now its time to get that modified data back into Flash. I’ll bet you couldn’t have guessed we use the getImageBytes() function

From ActionScript we can do this to get our data back out

//Get altered image back from Alchemy
var newRedBytes:ByteArray; 
newRedBytes = _lib.getImageBytes(redPtr);
newRedBytes.position = 0;

We call getImageBytes() on the C lib, and feed it the memory address to the data we care about, just as before. From there we get a brand new ByteArray that is filled with our modified image data and returned back to Flash. As with the rest of the of the functions, we again, set up some vars, and parse the args. Then we generate a pointer to our data once again. But then we get to do something new. We create an actual ActionScript ByteArray in C.

//Create a new byte array
AS3_Val flash_utils_namespace = AS3_String("flash.utils");
AS3_Val no_params = AS3_Array("");
AS3_Val ByteArray_class = AS3_NSGetS(flash_utils_namespace, "ByteArray");
AS3_Val outBytes = AS3_New(ByteArray_class, no_params);

The key function here is the AS3_NSGetS(). This gets a class definition that can then be newed up. The first parameter is the package path (as an AS3_String) to the class definition you want. In this case we are using “flash.utils”. The second parameter is a constant char* (C string) of the name of the AS3 Class we want. In this case its “ByteArray”. Then on the next line we new it up with AS3_New(). We pass to it the class definition and an array of parameters. In this case we don’t need to send anything to the ByteArray constructor, so we just use an empty AS3_Array(“”). At this point we have an honest to goodness AS3 ByteArray. Which means we can fill it with bytes.

//Write bytes to byte array
AS3_ByteArray_writeBytes(outBytes, image->data, image->length);

In our case we take the modified image data, and shove it into our newly created ByteArray. Lastly we do a bit of clean up and return the new ByteArray back to flash.

From there, in ActionScript we take those bytes, and build a new BitmapData object from it, and display it on screen.

//Set Bitmap data based on data returned from Alchemy
var newRedBD:BitmapData = new BitmapData(redBD.width, redBD.height, true, 0x00000000);
newRedBD.setPixels(redBD.rect, newRedBytes);
 
//Put result image on stage
var newRedImg:Bitmap = new Bitmap(newRedBD);
addChild(newRedImg);

Now we have a semi transparent red block on screen w00t!

The final bit is some manual memory management. From Flash we can call

_lib.freeImageBytes(redPtr);

Which results in

//Pointer to image data
unsigned int imageAddress;
imageData *image;
 
//Parse ags
AS3_ArrayValue(args, "IntType", &imageAddress);
 
//Get access to our image data
image = (imageData *)imageAddress;
 
//Release memory used by our image data
free(image->data);
free(image);

Lots more of the same, vars, args, pointers, blah, blah, blah. But then there is the free() call. Basically we are just giving that memory back, and Flash’s Garbage Collected can now reclaim it.

Great Googly Moogly
So, if you have made it this far, congratulations, you have reached the light at the end of the tunnel, and the train is running late, so its actual sun light this time.

However, we still have two more Alchemy Posts in the series. Part 5 covers some other random details, like mult-file compiling/linking, Asynchronous functions, and talking to ActionScript from the C code. Should be a riot

Remember to like us on Facebook if you want to stay updated, or even just to show your support:

And/Or you can follow me on Twitter:

Thanks for reading!

Please download the source files for this example here.

Also please make sure that you have the alchemy environment setup and running from Part 2.

Now go ahead and launch Cygwin.bat and get your Cygwin shell up and running.

Quick Cygwin Intro
First lets go over a few Cygwin Bash Shell commands:
At any point you can open the manual (man pages) which has more info on each of these commands. To access those simply type:

man command

and press enter.

Replace “command” with the command you are interested in. An example of this would be:
man ls

That will give you something that looks like this:

Use the arrow keys to move up and down, and “q” to quit.

Useful Cygwin Commands:
ls:
This will list the files in the current directory. Some useful options are -a -l -h. A is for
“All”, l is for “Long”, and h is for “Human Readable”.
You can combine them like this:
ls -alh

cd:
Change directory. There are no drive letters in Cygwin. So “cd” gets you everywhere.
cd /cygdrive/e/alchemyStuff
That will put you in the “alchemyStuff” directory of the “c” drive.

pwd:
Print Working Directory. Just tells you what directory you are in.
When you see a “~” that means your home directory.

rm:
Remove – it deletes stuff, so rm dumbFile.c will delete dumbFile.c.

ln:
Create a link. Kind of a shortcut to a folder. I generally use the “-s” option and make a
symbolic link to my current project (saves a lot of cd’ing):
ln -s /cygdrive/e/AlchemyHelloWorld
This will put the link/shortcut into whatever directory you are currently in.
So now from my home directory (cd ~) I can quickly get to my project:
cd AlchemyHelloWorld

dos2unix:
If you create a file in windows, it uses different line endings, newline + carriage return
Cygwin just used new line. So if you run:
dos2unix myWindowsFile.sh
It will convert the linendings and other little things to the proper format.

./:
The dot+slash is super useful. Your current working directory is probably not in the
global path. So in order to run anything you will need to put a ./ in front of it. As you will
see later in this post, to compile our stuff, we will use:
./compileHello.sh
That runs the bash script “compileHello.sh” from the current directory.

Now with that out of the way we can get to the good stuff. Lets take a quick look at the files in the example:
alchemy folder:
- compileHello.sh
this is a script that does our compiling.

- hello.c
this is the C code for our hello world alchemy library

- hello.swc
this is the compiled swc that we will access from flash.

bin folder:
This is the standard FlashDevelop AS3 Project bin folder. Just contains the index.html
file and the swf of our example. Nothing special here

src folder:
- Main.as
this is our document class that is the entry point for the example.

This example doesn’t have any on stage visual output so its not embedded in the page like the examples in the other posts. Which means you will have to download the example and run it through FlashDevelop or some other IDE to catch the trace output. Which brings us to….

Setting up the example
If you are using FlashDevelop, then all you have to do is double click on the project file. Then navigate to the alchemy folder and right click on the “hello.swc” file, and select “Add To Library”. Then press F5. In the output pane you should see:

(fcsh)Build succeeded
Done(0)
[Starting debug session with FDB]
Generating Hi Message in Alchemy
Response From Alchemy: Hi From Alchemy!
Echo: Echo This!

If you are using the Flash CS5 IDE, you will need to create a new .fla file in the “src” folder, and use “Main” as the document class. Then go to File->Publish Settings->Flash->ActionScript3 Settings->Library Path and add “../alchemy” as a library path.
Now do a “ctrl-enter” and you shoudl get the following output:

Generating Hi Message in Alchemy
Response From Alchemy: Hi From Alchemy!
Echo: Echo This!

Compiling
Cool, so now that you know what the end result is, lets compile the hello.c file from scratch, shall we?

Pop into the Cygwin shell, and “cd” your way to where ever you have the source files extracted to.

First we have to turn alchemy “on”, so type:
alc-on

and press enter. Now when you run gcc it will run through Alchemy.

To do that go into the /alchemy folder and type:
./compileHello.sh

This is a bash script that I made so I don’t have to type so much. The contents of the script look like this:

#!/bin/bash
gcc -Wall hello.c -swc -O3 -o hello.swc

The first line tells Cygwin that it should use “bash” to interpret the script. The next line is the actual gcc command. Now remember if you make a bash script in windows (like in notepad or whatever), and access it through Cygwin, you will need to run “dos2unix compileHello.c” to convert the end lines.

gcc obviously executes the gcc compiler and then we pass a few options to it.
First -Wall, this says, turn all of the (W)arnings on. Next is the .c file that we want to compile, and in this case its hello.c. Next -swc says create a swc. -O3 sets the optimiztion to level 3 (compiler level optimizations will do things like inline your functions and various other compiler voodoo to make your stuff execute faster). Lastly -o says output to hello.swc.

If all goes well you may get a warning about POSIX file paths, (which can be ignored, see previous post) and a warning about ‘main’ arguments being dropped. This can also safely be ignored. You should then get a bunch of other stuff that prints out that looks like:

So after all of that preliminary stuff, we can finally get on to the code. Pop open the alchemy/hello.c file, and lets go through it.

Finally Some Code
When starting a new C file that needs flash access you will need to include the “AS3.h” header file.

#include "AS3.h"

That will get you access to the various AS3 Value types, and the functions that allow you to convert data to and from ActionScript types.

Now jump down to the main() function at the very bottom. This is where the initial setup happens that exposes your carefully crafted C functions to flash. First up is the creation of a virtual function (basically an ActionScript function object that will reference a C function) or a “Thunk” as its technically called.

//Create the thunk (a virtual function that can be exposed to flash)
//this assigns a reference to a C function to an AS3 Function
//definition that can be passed to AS3_Object()
AS3_Val sayHiMethod = AS3_Function(NULL, sayHi);
AS3_Val echoMeMethod = AS3_Function(NULL, echoMe);

The first thing beyond the comments is “AS3_Val” this a data type that comes with “AS3.h”. Basically its a place to store objects that are going to ActionScript or coming from ActionScript. In this case, its going to put assigned to an object that is going to be visible to ActionScript.

//Bundle up the thunks into an AS3 Object.  This object is what flash sees
//after you call init() on the loaded Alchemy loader.
AS3_Val flashObj = AS3_Object("alchemySayHi:AS3ValType, alchemyEchoMe:AS3ValType", sayHiMethod, echoMeMethod);

This is where we actually expose things to ActionScript. The “flashObj” object will be available as a means of communication between our flash bits and our alchemy bits. AS3_Object is a function that creates an as3 object with the properties passed in as its arguments. The first argument is a comma separated list of propertyName:propertyType value pairs. The second argument is the values of those properties. In the next part of the series we will be taking a deeper look into AS3_Object as well as the other data management abilities of alchemy. So for now, just know that this is where you give flash access to your C/Alchemy functions. So in this case, the object will have a property on it called “alchemySayHi” and it will be of type AS3ValType. This property will contain a reference to our thunk “sayHiMethod” from a few lines before. That thunk references the C sayHi() function. So from flash we can call lib.alchemySayHi() and it will execute the C sayHi() function. Just to be a little clearer, “lib” in this case is the returned “flashObj” that we created. The same goes for the “alchemyEchoMe” property, that will reference the “echoMeMethod”, which in turn executes the echoMe() C function. Got all that?

As you are I’m sure well aware, Flash/ActionScript is a “Managed” system. Meaning that the virtual machine manages all of the memory allocation and freeing. This is good and bad, but in either case a discussion for another time. C on the other hand is not a managed system. Meaning that if we create stuff that takes up memory, we need to free that same stuff, so we don’t leave memory stranded out there that can no longer be accessed. The rule of thumb is, if we create it, we release it. There is one exception however. If you are returning an object that you created it will be released automatically. The last bit to keep in mind in terms of memory management is that when compiled down through Alchemy, the C code is now Adobe Virtual Machine byte code. Which means it runs with in the VM. Which ultimately means the memory is managed. However, the Garbage Collector won’t know to free up the memory used in the C code if you don’t explicitly free it. So for all intents and purposes, you can just pretend that the C code is still an unmanaged memory system. Just know its lie

So all of that was to simply justify these lines:

//We created a new AS3_Val, so we have to release it now that we are done with it
AS3_Release(sayHiMethod);
AS3_Release(echoMeMethod);

Lets take a quick break from C for the moment, and see how we can use the stuff in the main() function. If you pop open Main.as in the /src folder, and meander down to the init() function you will see this:

//Setup the alchemy library
_loader = new CLibInit();
_lib = _loader.init();

When you compile your C code through Alchemy, it builds you a swc with a package path that looks like this:

import cmodule.hello.CLibInit;

Its cmodule.your_swc_name. In there is the CLibInit class. This is the Alchemy loader. You new that up, and then call init() on the new CLibInit object. This is what runs your main() function from the C code. This retuns that “flashObj” object that we attached the two function references to. That means we are free to do some crazy stuff like this:

//Now that we are all set up, we can call the exposed method
var response:String;
response = _lib.alchemySayHi();
trace("Response From Alchemy: " + response);

Holy moly thats some ridiculous stuff right there. Basically its doing what it says. Its finding the “alchemySayHi” property from the Alchemy object, and executing that as a function, which it is, because we stored an AS3_Function(NULL, sayHi) in that property.

Ok, so we didn’t spend that long in ActionScript, but I figure you know how most of that works already Back to C!

Lets take a look at the sayHi() function in hello.c

AS3_Val sayHi(void *data, AS3_Val args)

That is the start of the function definition for sayHi(). Now, I’m not going to lie, I don’t know how to use the first parameter, void *data. The docs state this:
“Create a synchronous function callback object, binding the function pointer with the data passed in. data can be used to hold state for the function”
So for now, I’m going to skip it until I understand it enough to properly inform you. The second parameter however, I have a grasp on: AS3_Val args
When you call a thunk from ActionScript it passes the parameters to this argument as an AS3 Array. You can then pull apart that Array and use those passed in values within your function. There is an example of that in the echoMe() function. We will get to that in a bit.

Next up in the sayHi() function is:

AS3_Val traceOut;
traceOut = AS3_String("Generating Hi Message in Alchemy");

First we make a variable of type AS3_val and call it “traceOut”. This is going to be passed to an AS3_Trace() call. If you check out the docs for AS3_Trace() you will see that it takes an AS3_Val val as its parameter. So we need to make one of those, and in this case we called it “traceOut”. Now that we have our AS3_Val we are going to want to store a string in it. In C there is no real concept of strings. They are essentially pointers to a list of chars. We will go more into that in a bit. For our current case however, we are going to make an AS3_String and store that into traceOut. Which will then be traced out. Super exciting.. I know…

traceOut = AS3_String("Generating Hi Message in Alchemy");
AS3_Trace(traceOut);

It might be a good time to point out that AS3_String() is not a cast, it is a real C function defined in Alchemy. This creates a new object that is of type AS3_String. So just keep in mind that the only real ActionScript data type here is the AS3_Val type. There is no AS3_String type, its a factory function.

But alas, I said the word create again. Which can only mean one thing:

//We created it, we release it
AS3_Release(traceOut);

Finally for a little added pizazz (yes I said pizazz), we are going to return something back to ActionScript. Part 5 of our series will talk at length about communicating between Flash and the Alchemy code, but I figured I could slip this in now

//Retun a string (an as3 string mind you) to flash
//When something is returned, it is automatically "released"
return AS3_String("Hi From Alchemy!");

So in Main.as this is where “High From Alchemy!” is returned:

response = _lib.alchemySayHi();
trace("Response From Alchemy: " + response);

This is what give us the output you see in your output window

Lastly we are going to talk about the echoMe() function in hello.c. I’m going to skim this one a bit, as it dips into the pool of the Part 4 post on data manipulation, but I figured I better give you something so you come back next time

The function:

/*****************************************************************************
* echoMe:
*		This function will take a string from Flash, and trace it out.
* 
* arguments:
*		(AS3_String) a string of text to echo out.
*
* returns:
* 		(AS3_Val) NULL
******************************************************************************/
AS3_Val echoMe(void *data, AS3_Val args)
{//echoMe
 
	//Declare a variable to hold our input (which will be an as3 string)
	char* inputString;
 
	//Parse "args" array from flash
	AS3_ArrayValue(args, "StrType", &inputString);
 
	//Do the echo to stderr
	fprintf(stderr, "Echo: %s", inputString);
 
	//We created it, we release it
	free(inputString);
 
	//Return nothing.
	//Compiler is expecting an AS3_Val to be returned.
	//We have to use AS3_Val so we can create the thunk in main()
	//Therefore we have to return something, which in this case is nothing :)
	//Ok, well its not nothing, its Null, and more than that its an AS3 null,
	//not a C null.
	return AS3_Null();
 
}//echoMe

So the function definition is exactly the same as the sayHi() function. But then everything gets all different and stuff, and we sort of exit ActionScript land, and splash around a bit in puddles of C code.
The first line declares a varible called inputString. This is of type char* which is a C type. Basically its a point to a memory address that will contain a list of characters. Sounds familiar doesn’t it?
Next we use the AS3_ArrayValue() function to pull apart the “args” parameter. The first parameter in the AS3_ArrayValue() call is the source array from flash. In this case its “args”. The next parameter is a string of comma separated Class/Type names. This describes what the type of each element in the array is, so order is paramount. The last parameter is where the value from the array will be stored. In this case its going to be stored at the memory address specified by inputString. (for more info, look up C pointers and dereferencing). If you check out the docs for AS3_Array you will see a list of types and what they map to in C. In this case “StrType” maps to char*. Go figure

Cool, so now, what do we do. Well, list print out whatever was passed into the echoMe() call. This time we are going to use a C function to do it, fprintf(). That is another one you are going to have to look up. C programming is a bit beyond the scope of this post, but I will explain whats going on a bit here.

fprintf(stderr, "Echo: %s", inputString);

Stderr stands for Standard Error. We are telling fprintf to print our stuff out to the standard error pipe. We do this so that FlashDevelop and the Flash IDE catch it and display it in the output window. The next parameter is a string. In this string is a %s which tells fprintf that you want to replace that %s with a char* value. Hence the third parameter, intputString, which as you know is a char* value. So when this is executed, it will display
“Echo: Echo This!”
or whatever you pass in to it.

Now, since we created a char*, we need to free it, which is what the free() call does. Go figure.
Lastly, since we promised the compiler that this function was going to return a AS3_Val, we need to do that. However, since we don’t have anything useful to return we are just going to return an AS3_Null(). Now again, remember, AS3_Null() is a function that creates an object, which flash will read as Null, so again, its not a cast.

Whew, for so few lines of code, that took some serious explaining. Hopefull this will help you understand how to get started with this stuff. In the next part we are going to try to do something useful

As always, if you want updates for when new posts come out, Like us on facebook at the Hook page:

And/Or follow me on Twitter:

Tune in next time, on the same bat channel. (I would have said same bat time too, but I can’t promise that )

To get started we are going to first need the Adobe Flex SDK, please download this and unzip it to c:\flexsdk
http://opensource.adobe.com/wiki/display/flexsdk/Flex+SDK

Currently the latest release is Flex4.1 Update 4.1.0.16076.

Now we can grab Adobe Alchemy:
http://labs.adobe.com/downloads/alchemy.html

Just check the box at the bottom and download the “Alchemy Toolkit for Cygwin on Windows”
When that finishes downloading, unzip it into c:\alchemy (make sure that you don’t unzip it into folders within that, you want the folder structionto be c:\alchemy and then a bunch of folders such as c:\alchemy\achacks, c:\alchemy\bin, etc…

Next you will need to make sure you have Java installed. If you do, please continue. If you do not, please download and install it from here:
http://www.java.com/en/download/index.jsp

Last up is Cygwin’s setup.exe file:
http://www.cygwin.com/

Look for setup.exe about half way down the page, and download that to c:\cygwin (you can put this wherever you like, but I will be using c:\cygwin and c:\alchemy through out the post for simplicity)

This setup file is basically a client front end that allows you to download and install whatever linux packages you will need to get the job done.

Double click on the setup.exe to get things started.
- Click next on the first screen.
- On the second screen select “install from internet” and click next.
- Set your root directory on the third screen to c:\cygwin and install for all users. Click Next
- Set your local package directory to be c:\cygwin as well, click next.
- Set up your proxy settings if you have any (if you are behind a corporate firewall or something) otherwise select “Direct Connection” and click next.
- Select a mirror, I usually use http://mirrors.kernel.org click next.
- You may get a Setup Alert warning you that this is your first install, so you should check out the docs. This is normal, and fine, just click OK.
- This takes you to the package selection screen.

Yes I know, its scary, but you’ll be fine There are a few packages that we need to install for the Alchemy setup, and a few that I install for convenience. Here are the required packages (you can type the name in the search box to help narrow down the list) Once you find the package, click on the “Skip” button on the left, and that will change to a version number. That means that package will download. The next column over has 2 check boxes. The first says Download Binaries, the second says Download Source. For this we only need the binaries.
Required:
- All -> Devel -> gcc-g++: C++ compiler

- All -> Archive -> zip: Info-ZIP compression utility

- All -> Perl -> perl: Larry Wall’s Practical Extracting and Report Language

Optional:
- All -> Shells -> rxvt: VT102 terminal emulator

- All -> Editors -> emacs: The extensible, customizable, real-time display editor

Once all of the packages are selected, you can click Next

This will bring up a screen about Resolving Dependencies. Make sure the check box is checked at the bottom of the window, and click Next.
The great download starts. Might be a good time to take a quick break as this will take a few minutes.
When the download/install is complete, just click finish.

Finally with everything installed, we can configure it all

Parts of the next section were learned from:
http://www.developria.com/2009/04/setting-up-adobe-alchemy.html
and
http://labs.adobe.com/wiki/index.php/Alchemy:Documentation:Getting_Started
Both are excellent articles for getting the Alchemy Environment setup and running.

Now we have to add some things to cygwin’s path. In the c:\cygwin\etc folder there will be a file called “profile”. Please open that in Notepad++ or other proper text editor (in other words, not Microsoft WORD!).

The first line that isn’t a comment should be:

PATH=/usr/local/bin:/usr/bin:/bin:$PATH

We need to add alchemy and the flexsdk to that path:

PATH=/usr/local/bin:/usr/bin:/bin:/cygdrive/c/alchemy/achacks:/cygdrive/c/flexsdk/bin:$PATH

Please take note of the /cygdrive/c portions of the path. This is how you access your drives from within cygwin. If you want to access the “e” drive for instance it would be /cygdrive/e/ and not e: as it is within windows.

We also need to make sure all of the Alchemy setup scripts run when we start cygwin. So right before the “PATH=” line that you just edited, we need to add the following:

source /cygdrive/c/alchemy/alchemy-setup

You can now save and close the “profile” file.

If you installed the rxvt package (its a replacement terminal, because the default terminal for cygwin is terrible) then please open your c:\cygwin\cygwin.bat file and make it look like this:

@echo off
 C:
 chdir \cygwin\bin
 start rxvt -sr -sl 10000 -fg white -bg black -fn fixedsys -fb fixedsys -tn cygwin -e /bin/bash --login -i

Now run the cygwin.bat file and it will drop you into a cygwin terminal. We have to do one last bit of configuration and then we are done! Yay!

You will probably get a bit of messaging about Skeleton files being copied over. This is good
Here we have to setup alchemy. So from the terminal type:

cd /cygdrive/c/alchemy

This will put you in the Alchemy directory on your C: drive.
From here type:

./config

You should get a screen that looks like this:

Now close the cygwin window, and in your text editor open the c:\alchemy\alchemy_setup file.
Find the lines:

# Set this variable if you do not want to use the adl executable from your path
#export ADL=/path/to/your/adl (or adl.exe)

and replace the #export line with the following (be sure to remove the # at the beginning of the line)

export ADL=/cygdrive/c/flexsdk/bin/adl.exe

You will also need to locate this line:

export ASC=$(cygpath -m -s -p $ALCHEMY_HOME/bin/asc.jar)

and change it to:

export ASC=$ALCHEMY_HOME/bin/asc.jar

The POSIX to Windows path conversion doesn’t seem to work. This change will throw a warning about POSIX file paths, but everything will work just fine.
Save that, and restart cygwin (c:\cygwin\cygwin.bat)

That should do it! You should have have function cygwin/alchemy environment.
So lets compile something shall we?
Type:

cd /cygdrive/c/alchemy/samples/stringecho

Then type this to remove the old .swc:

rm stringecho.swc

Now you can compile this sample provided by Adobe to make sure everything is cool.

First turn on the Alchemy gcc compiler, type:
(you will only need to do this once per cygwin session)

alc-on

Then run the actual link and compile, type:

gcc stringecho.c -O3 -Wall -o stringecho.swc

If you run into troubles with the swc being corrupt you may need to include the -swc switch as suggested by “coderyy” in the comments. Thanks for the tip!

gcc stringecho.c -O3 -Wall -swc -o stringecho.swc

With any luck you will get a screen that looks like this:

(yes you can ignore the “Arguments Dropped” warning)

if you type ‘ls’ (short for list, same as ‘dir’ in dos) you will see your shiny new stringecho.swc

In the next episode we will go over how to use that .swc and how to create your very own .c files that you can access from Flash!

As always if you want to get notified of new posts in this series, (or any of our labs posts) please ‘Like’ us on Facebook:

Or you can Follow me on Twitter:

Thanks for reading and good luck!

*** POST UPDATED: Crackling issue fixed with “on the fly” decoder, please see below ***

So we finally have both halves of the equation! You can now, encode audio to the Ogg Vorbis format as well as decode it, all from the same library. A significant portion of the Decoding code was brought over from the Ogg Vorbis decoder on the Adobe Libraries page, written by Branden Hall of Automatastudios.com. Thanks Branden!

So a fair bit of the library was rearranged (from our previous version) to make it a touch easier to use. First up, the main example. This shows off most of the features in the library. Keep scrolling for the second example which demonstrates “on the fly” decoding.

Download The Library and Examples
Download Just The library

If you have read our last post, you already know about some of the encoder features, but there have been a few changes, so we will go over each of them again.

The fist major change is there is now an OggManager class. This class is a wrapper for all of the alchemy bits, and is the main point of control for encoding and decoding Ogg Vorbis data. The quick answer is simply new up an instance of the OggManager, and then call .encode() or .decode(). From there you can listen for some events, and do what you need to do. For the long answer, lets start with the encoder portion of the library.

Encoder
The encoder works in 2 phases, first, the sound data is converted to a 44100, 16bit stereo pcm WAV format and is then encoded to Ogg Vorbis. The encoding process can take some time depending on how much data you are encoding. So this process is a fully asynchronous process. You can keep track of the progress by listening for the following events:
OggManagerEvent.ENCODE_BEGIN
OggManagerEvent.ENCODE_COMPLETE
OggManagerEvent.ENCODE_PROGRESS
OggManagerEvent.ENCODE_CANCEL
OggManagerEvent.WAV_ENCODE_BEGIN
OggManagerEvent.WAV_ENCODE_COMPLETE
OggManagerEvent.WAV_ENCODE_CANCEL
OggManagerEvent.WAV_ENCODE_PROGRESS

The encoding process can be canceled at any time by calling .cancel() on the OggManager instance. Please note that the process may not cancel right away, so please listen for the OggManagerEvent.ENCODE_CANCEL event to know when exactly the cancel has happened.

The method signature for the encode() method looks like this:

public function encode($rawBytes:ByteArray, $oggComments:OggComments=null, $oggQuality:Number=0.5, $wavLoopsPerYield=10, $vorbisLoopsPerYield:int=1, $progressNotifications:Boolean=true):void

$rawBytes is a byte array containg the raw flash sound data that is to be converted. $oggComments is an OggComments object that contains the tags/comments for the Ogg Vorbis file. These include things like Artist, Album, Title, etc… Next is the $oggQuality setting. This number ranges from -0.1 to 1 according to the xiph.org docs. 1 being the highest (largest file size, highest bitrate) and -0.1 being the lowest. I’ve played with different settings (as can you in the example above), and found that it is really amazing how low of a bitrate and how small of a file size you can get without sacrificing too much audio fidelity. $wavLoopsPerYield and $vorbisLoopsPerYield are performance settings. These basically decide how much time Alchemy gets to do the encode, before giving up its time slice to flash. The higher the number, the quicker the encode, but the slower flash will be. Lastly we have the $progressNotifications parameter. If this is true, progress notification events will be dispatched. Having this turned on, may slow the encode slightly, but without it, you won’t know how far along in the encode you are. You will however get BEGIN, COMPLETE and CANCEL events in either case. Currently the encoder still expects 44.1kHz, 16bit, Stereo data. Possibly in the future support for more formats will be implemented.

Decoder
The decoder can be used in two different ways. The first is where you can give it ByteArray full of Ogg Vorbis encoded bytes and after a few moments, it will give you back raw flash sound data. The other is to decode small chunks at a time, such as during the handling of a SAMPLE_DATA event when playing a sound. The example at the top of the post, is an example of how to decode the entire file all at once. The example below is how to decode the ogg file on the fly.

Decoding the full file all at once is fairly trivial. You can simply call .decode() on the OggManager instance:

public function decode($oggBytes:ByteArray, $samplesPerLoop:int=2048, $delayPerLoopInMS:int=33, $progressNotifications:Boolean=true):void

The method signature breaks down as follows:
$oggBytes is the byteArray that contains your Ogg Vorbis encoded bytes from a file or wherever. The second parameter is an integer that controls how many bytes are decoded per loop. Just like the encoder, the decoding process is fully asynchronous. More bytes per loop speeds up the decode, but slows down flash. The third parameter controls how long to wait before kicking off another decode loop. If your decode loops are taking a long time, you will want to increase this number so that it doesn’t start to stack up decoding loops. Each chunk decode is handled by a timer, and the timer delay is set based on this parameter. The last parameter tells the OggManager to dispatch progress events for the decoding process or not. This is the same as with the encoder. Decoding may be faster if you do not dispatch progress events. BEGIN, COMPLETE and CANCEL events are always dispatched, regardless of this setting.

You can also keep track of the progress of the decode by listening for the following events:
OggManagerEvent.DECODE_BEGIN
OggManagerEvent.DECODE_COMPLETE
OggManagerEvent.DECODE_PROGRESS
OggManagerEvent.DECODE_CANCEL

The “On The Fly” decoding is very similar. (please have a look ath the DecodeOnTheFlyExample.as and .fla files) The main difference is you have to initialize the decoder before you start decoding. This is handled automatically if you are decoding the whole file at once but not if you are doing it on the fly.

To do that you can simply:

_oggManager.initDecoder(_oggBytes);

From there you can decode away, until you reach the end of the ogg bytes:

//Make sound
_sound = new Sound();
_sound.addEventListener(SampleDataEvent.SAMPLE_DATA, handleSoundData, false, 0, true);
_soundChannel = _sound.play();

private function handleSoundData(e:SampleDataEvent):void
{//handleSoundData
	var result:Object;
	var tmpBuffer:ByteArray = new ByteArray();
	result = _oggManager.getSampleData(_oggManager.dataPtr, NUM_SAMPLES, _oggManager.audioInfo.blockAlign, _oggManager.audioInfo.sampleMultiplier, tmpBuffer);
 
	if (tmpBuffer.length < NUM_SAMPLES * BYTES_PER_SAMPLE)
	{//reset
		trace("Reset");
		//Right now the only way to rewind is reseting the decoder
		_oggManager.initDecoder(_oggBytes);
		result = _oggManager.getSampleData( NUM_SAMPLES, tmpBuffer);
	}//reset
 
	tmpBuffer.position = 0;	
	while (tmpBuffer.bytesAvailable)
	{//feed
		//feed data
		e.data.writeFloat(tmpBuffer.readFloat());		//Left Channel
		e.data.writeFloat(tmpBuffer.readFloat());		//Right Channel
	}//feed
 
}//handleSoundData

The important part is the getSampleData line:

oggManager.getSampleData(NUM_SAMPLES, tmpBuffer);

The first parameter is how many flash sound samples you want back from the decoding. The second parameter is where those decoded bytes are stored. As you can see in the example code above we simply store the decoded bytes into tmpBuffer and then write those bytes back to the SAMPLE_DATA event. Its as simple as that. The one thing to be aware of however, is that seeking is not currently supported. So once you reach the end of the decode, you will need to initialize the decoder again to start back at the beginning of the ogg vorbis data. So depending on your needs you may want to cache this data as its decoded in a byte array for later use. But like I said, it kind of depends on what exactly you are doing with the data.

Please check out the Examples and feel free to just download the Wrapper and SWC.

In the next Alchemy installment we will go over getting an Alchemy Environment setup for Windows, and go through recompiling the sources for the SWC. From there we will talk about how to write your own Alchemy code, as well as other tips and tricks we have learned along the way.

Until next time you can get updates from our Facebook page:

Or you can follow me on Twitter:

Good luck, and please let us know if you use this in a cool project, we would love to see it!

********** UPDATE **********

Good news everyone! I fixed the crackling issue with the “on the fly” realtime decoder. It should now function properly with clean (not clipped) sound. The issue turned out to be that we were dropping unused bytes. So now all of the bytes are fed to the SAMPLE_DATA event, instead of just the requested number of samples. The block alignment would sometimes force more bytes to be decoded than the exact number of requested samples. The code and downloads have been updated, and the code in the post has also been updated.
Good luck!

Make sure you have a mic hooked up, and click record. Once you have recorded some sound, click, stop. At this point you can fill in some info for the file (these are used to set the metadata/comments/tags). Then click Encode to watch it encode the data. Progress of the encode and the time it took to encode is listed at the right. Finally you can click Save, and you can save your newly encoded .ogg file to your local machine. Please note that the performance tuning in this example is set to keep flash as responsive as possible while the encoding is taking place. This naturally slows the encoding performance. Please see below to learn how to adjust the tuning to your needs. Also, before we get started, I would like to mention, that we are planning on creating a series of posts about what we have learned working with Adobe Alchemy in the coming weeks. Now, with that out of the way, on with the show!

You can download the source and encoder swc for this example here:
http://labs.byhook.com/oggencoder/ovexample.zip

Quick props to all of the authors/sites that helped me get started with Alchemy:
- Forcing stdin/stdout to deal with ActionScript ByteArrays:
http://segfaultlabs.com/devlogs/alchemy-asynchronous-jpeg-encoding

- flyield() example:
http://segfaultlabs.com/devlogs/alchemy-asynchronous-jpeg-encoding

- Process for compiling multiple source files under gcc:
http://ccgi.codegadget.plus.com/blog/2010/04/03/alchemy-c-library-1/

-Alchemy Documentation
http://labs.adobe.com/wiki/index.php/Alchemy:Documentation:Developing_with_Alchemy:C_API

More on all of those things coming in the next few posts!

Encoder Usage
Currently this encoder takes 44.1kHz, 16bit, stereo wav formatted PCM data to do the encode (Adobe’s WAVWriter class is used to do the wav conversion in this example). This version allows for different quality settings, async performance tuning, and the recommended Ogg Comment Tags.

I’m hoping the next release of our encoder will handle more types of input (different bitrates, mono support, etc..) as well as the ability to cancel the encode at any time. I am also hoping to get a decoder working within this same package, for convenience. For now, however I would suggest using the very well done Ogg Vorbis decoder from Branden Hall at automatastudios.com. If you check out the sources for our Sequencer, you can see some examples of how to use the Decoder from Automata Studios.

Additionally in the coming weeks we will be posting about making use of Alchemy in general. From setup through all the steps we took creating this encoder. We will also be posting code snippets for commonly needed alchemy abilities, such as reading and writing to and from ByteArrays, calling ActionScript methods from Alchemy, and a slew of other tid-bits that were hard to find online.

During those posts I will be releasing the source code to the encoder, but I have to read through all of the licenses for the different pieces of the Xiph example code to be sure that I’m not violating any of those by redistributing modified versions of Xiph.org’s sources. Usually this just means that specific comments have to stay intact, and probably a readme file sent along with the sources. But until then, I figured the .swc could be useful to people as is

For more immediate notifications of updates to the encoder you can:

Or get updates from our Facebook page:

Wow, it felt dirty saying that, but this is where we will be posting about updated versions of the encoder.

Much of the encoder code was taken from the example C code on the Xiph.org website. It was then altered to expose parts to Flash as well as altered to allow for asynchronous operation. The Vorbis and Ogg C libraries were modified for compilation through Adobe Alchemy (FlaCC). All of this was linked and archived to a .swc for use within flash.

Be sure to add the swc to the library in your IDE. For Flash CS5, you will need to go to Publish Settings -> Flash Tab -> Script Settings -> Library Path Tab. In there you can either add the path to the folder containing the swc, or you can add the swc itself.

As part of the example code there is an OggEncoder actionscript class. This simplifies the use of the encoder swc.

Use of the encoder is fairly simple. First new up an instance of the OggEncoder, and listen for ENCODE_COMPLETE and ENCODE_PROGRESS events to keep track of the status.

//Create a new instance of the encoder
_oggEncoder = new OggEncoder();
 
//Listen for progress and complete events from the encoder (encode happens async)
_oggEncoder.addEventListener(OggEncoderEvent.ENCODE_COMPLETE, handleEncodeComplete, false, 0, true);
_oggEncoder.addEventListener(OggEncoderEvent.ENCODE_PROGRESS, handleEncodeProgress, false, 0, true);

To start the encode progress, you will need to convert your sound data to a 44.1kHz, 16bit, 2Channel stereo wav file, with adobe’s WAVWriter Class.

//Setup up wav writer for flash sound -> wav conversion
var wavWriter:WAVWriter = new WAVWriter();
wavWriter.numOfChannels = 2;
wavWriter.sampleBitRate = 16;
wavWriter.samplingRate = 44100;
 
//Save converted data to _wavBytes (I would suggest modifying the
// processSamples method to work in small chunks that you call from
//a timer so you don't lock up the UI during the processing)
_wavBytes.position = 0;
_recData.position = 0;
wavWriter.processSamples(_wavBytes, _recData, 44100, 2);

From there you can simply call:

//Start the encode
_oggEncoder.encode(_wavBytes, oggComments);

While its encoding OggEncoderEvent.ENCODE_PROGRESS events are dispatched. The “data” property on the event contains a number 0 – 1 which represents the percent complete.

Lastly an OggEncoderEvent.ENCODE_COMPLETE event will be dispatched when the encoding has finished.

If you don’t want to go through the OggEncoder class, you can directly access the exposed functions in the swc:

//do encoding
startAsyncEncode(onCompleteMethod:Function, clientObj:Object, wavBytes:ByteArray, oggBytes:ByteArray, quality:Number, numLoopsPerYield:int, commentObj:OggComments)
 
//get version number as String: "0.5"
getVersionNumber()
 
//get version label as String: "beta" 
getVersionLabel()

First import the encoder classes

import cmodule.oggvorbisencoder.CLibInit;

Then create an instance of the Alchemy Lib:

//Alchemy Loader object
private var _loader:CLibInit;

//Setup the alchemy library
_loader = new CLibInit;
_lib = _loader.init();

Lastly do some encoding:

/***************
* This is the actual call the the Alchemy Ogg Encoder.
* Parameters:
* 
* encodeComplete: 
* method called when encoding is complete
* 
* this: 
* the object passed in here is required to have a method called handleProgress.
* when there is progress, the method is called with the number of bytes read from the wav 
* ByteArray, and the length of the wav ByteArray is passed to it.
* (see below for implementation)
* 
* _wavBytes: 
* the 44.1kHz, 16Bit, 2 Channel wav encoded bytes (ByteArray)
* 
* _encodedBytes: 
* a ByteArray to store the Ogg encoded bytes in.
* 
* 0.5: 
* quality setting for Ogg (valid range is 0.1 to 1)
* 
* 1: 
* number of ogg pages before yielding back to flash player 
* (low numbers - flash player stays faster, high numbers - encoding faster)  
* I would really just stick with 1 here
* 
* $oggComments: 
* this is the comment value object for filling in the comment tags for the Ogg file.
****************/
 
trace("Wav Bytes: " + _wavBytes.length + " / " + _wavBytes.position);
trace("Enc Bytes: " + _encodedBytes.length + " / " + _encodedBytes.position);
 
trace("Version Number: " + _lib.getVersionNumber());
trace("Version Label: " + _lib.getVersionLabel());
 
_lib.startAsyncEncode(encodeComplete, this, _wavBytes, _encodedBytes, 0.5, 1, $oggComments);

You can also call getVersionNumber() and getVersionLabel() on the library and it will return the current version info of the swc as an ActionScript String.

That about wraps up the technical portion. If you are interested in the story behind the project keep reading

A quick history of the project
Off and on for the last few months I’ve been playing around with various parts of the audio world in Flash and Air. Eventually each project hit the same roadblock, saving out the final audio performance. Its fairly trivial to save out the raw byte data to a file and load that back in. But of course the issue with that is the file size. As it is, well, gigantic. At first I started looking around for MP3 encoders already built for flash. I came across this port of the Shine mp3 encoder as basically the only viable option. While its pretty awesome in its own right, its still fairly limited in terms of sound quality, and the encoding process is rather slow. There were a couple of other things that made mp3 less of an attractive option as well. The first issue is the odd licensing scheme for the mp3 format. Since I’m no lawyer, it was a bit scary trying to build an encoder from the published spec. Lines like this “Implementers of the standard were supposed to devise their own algorithms suitable for removing parts of the information from the audio input.” made me nervous, probably without warrant. However, there was another reason that mp3 wasn’t a good fit for the projects, frame padding. As discovered while we were building our Sequencer mp3’s won’t loop smoothly. It seems that if a frame of the mp3 is not full, it gets padded. This padding causes a very noticeble gap in playback. Therefore smooth looping without some sort of gapless playback support from the encoder and decoder is impossible. Thus it was time to look for another format. Ogg Vorbis be thy name.

Ogg Vorbis is completely open, and is of very high quality. From the Xiph.org page:
“Ogg Vorbis is a fully open, non-proprietary, patent-and-royalty-free, general-purpose compressed audio format for mid to high quality (8kHz-48.0kHz, 16+ bit, polyphonic) audio and music at fixed and variable bitrates from 16 to 128 kbps/channel. This places Vorbis in the same competitive class as audio representations such as MPEG-4 (AAC), and similar to, but higher performance than MPEG-1/2 audio layer 3, MPEG-4 audio (TwinVQ), WMA and PAC.”

Yay!

An Ogg Vorbis file doesn’t have the same issues with gapless playback as mp3, and seems to make smaller files, at least from my initial testing, which isn’t super extensive. Additionally encoding performance is pretty good.

The problem was, I could only find an Ogg Vorbis Decoder for flash. Mind you its an excellent decoder written by Branden Hall at automatastudios.com, but that only gets us half way. Some further looking around revealed that Andre Michelle and Joa Ebert had ported a java version of the encoder to AS3. So I started trying to do that, but stopped almost immediately when I came across the use of 64bit ints in the Java code. Flash’s ints are only 32bits wide, and since the codebase was so big, I didn’t want to try and merry two 32bit ints together everywhere a 64bit integer was needed. So began the trip down Alchemy Lane. We will be doing a series of posts about Alchemy in the coming weeks, so stay tuned!