Alchemy Series Part 4: D is for Data Manipulation

Alchemy Series Part 4: D is for Data Manipulation:

So far, we’ve gone though getting the environment setup, basic compilation and implementation of alchemy into a swf, and the standard Hello World example. So what next you ask? Well I answer with “More Contrived Examples!” Sadly its tough to make examples that don’t feel totally contrived, while also making those examples easy to understand while staying on point. Kind of like the old racing adage, “Cheap, Fast, Reliable, pick any two”. So I picked easy to understand and on point. Which means we are still in the land of contrived examples, and for that I apologize. Either way, on with the contrivedness!

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: [...]