I've been out of the REALBasic game too long - I've never heard of an RGBSurface...or maybe I've just forgotten...
In any case, since a few people are interested, I'll explain the whole thing here.
The idea behind tokens/multiframe animation is pretty simple. Each token is 4 bytes, a C long. The high word's high byte (the A in ABCD if you stick the four bytes together into a long) is the token type. The valid tokens are 00 (end of shape = end of frame), 01 (new line), 02 (draw pixels), 03 (skip pixels), 04 (single colour draw).
The above are all hex, by the way (one hex character = four bits)
The other six hex characters (the remaining 24 bits) tell you how different things depending on the token:
00: The other numbers shouldn't be there : )
01: The remaining 24 bits describe how many bytes (BYTES, not longs) until the next new line token, not inclusive.
02: The remaining 24 bits tell you that the next N bytes are pixel data, so the token 02000004 (in hex) would be followed by 4 bytes (8 hex characters) of pixel data. Of course, whether 1 byte = 1 pixel or 2 bytes = 1 pixel depends on whether you're using 8 or 16 bit rle's, but the same algorithm can be used for both with no modifications (lucky, hey!).
03: The remaining 24 bits tell you how many pixels to skip.
04: The remaining 24 bits is the number of pixels you should fill with colour described by the NEXT FOUR BYTES. So, on an 8 bit system, 04000010 000000FF would mean fill the next 16 pixels with the colour at index 255 in the colour palette used by the RLE. For the default palette this is black.
It's just as simple as that. I hope every developer can approach the EVN rle's without fear now. As AriosSW said, SpriteWorld uses exactly the same RLE format except that the resource name is different, so if you're using C, save yourself the time and effort.
By the way, each frame is delineated by an end of shape token, so using this and the numFrames field you can easily find where each shape begins and ends. The trick (and this is important!) is keeping your memory pointer aligned so that when it reads a LONG (4 bytes) it always reads, say 01000000 instead of 00000100. This is because whilst the tokens are 4 bytes, the pixels are either 1 or 2 bytes, and so the pointer can get misaligned during the draw and single colour draw operations.
Enjoy your programming!
Kane O'Donnell
