The file starts with a 4 byte string: "1.40". This is assumed to be the file version, which is why i was surprised the unpacking routine worked: WC3 files were version "1.11". You'll find on offset 4 a dword (4 bytes), which indicates the number of images stored in this SPR file. Afterwards, you'll find what seem to be 8-byte offsets that indicate where in the file each image starts.
Image data holds (most of the times, although not always) image information, such as image dimensions. More specifically:
37 00 47 00 01 00 01 00 09 00 00 00 01 00 00 00
35 00 00 00 2D 00 00 00 01 1B 09 BE 04 55 67 00
01 19 11 67 29 29 04 29 29 BE BE 00 01 18 15 10
The first 8 bytes are unknown and are being ignored right now. 8 bytes after the start of the block, you'll find 2 dwords indicating where the image should be drawn (in this case 9 pixels to the right and 1 pixel down). Then you'll find 2 more dwords which specifies the image dimensions, but you'll have to add 1 to their value (so in this case the image size is 54x46). The rest is compressed data that'll have to be passed to the unpacker.
After the data is unpacked, you'll have an image with an 8-bit color depth, so you'll have to load a palette so it'll look good. As far as ship targetting images go: software versions (soft_*.spr) use the palette stored in softpal.tga. The hardware ones use a palette that wasn't found in any TGA file, so thanks go to Dustin Evans, who was able to come up with a palette based on screenshots and on the software palette (Dustin's palette is the one used on BMPs created by spr2bmp).
A small detail: the dimension of the image you have to unpack is not 54x46, which would be logic. Instead, it is 54-9 x 46-1 (because you're not drawing a rectangle starting at 0,0 , it's starts at 9,1). In the spr2bmp utility, i made this subtraction and the image fits perfectly on these dimensions. It's important to understand this since you may have to play with these 4 values if the image doesn't appear in the game exactly where you'd want it to be.
The unpacking algorithm:
The algorithm unpacks the image a row at a time, so you'll have to keep a counter with the number of rows to unpack (there are some more variables you'll need to have, but they should become obvious as the algorithm is described).
Assume that it begins executing in "Begin" and finishes working in "End":
- Begin
- Read a byte
- Remove the less significative bit (LSB) from the read byte, but keep it in memory
- If LSB is zero
- If the rest of the byte is 0, this row has no more bytes. If there aren't any more rows to unpack, End. Otherwise, increase row counter (and adjust the row offset) and go to Begin.
- If the rest of the byte is not 0, use the value of the byte currently in memory as a counter (x). Read one more byte, write it x times and go to Begin.
- If LSB is one
- If the rest of the byte is 0, read one more byte, add it's value to the output pointer (skipping a given number of bytes) and go to Begin.
- If the rest of the byte is not 0, use the value of the byte currently in memory as a counter (x). Move x bytes from the "compressed" zone of memory to the "uncompressed" zone.
That's pretty much it. I'm including the source code i created that implements it:
-----------------------8<------------------------------------
// value subtraction on xDim and yDim done before calling
void _unpack(BYTE * in, BYTE * out, DWORD xDim, DWORD yDim)
{
BYTE b;
int inPtr=0, outPtr=0, i, rowCounter = 0, counterX;
char lsb = false;
while (1)
{
// read byte
b = in[inPtr++];
lsb = (b & 1);
b >>= 1;
if (!lsb) // if lsb == 0
{
if (!b) // if lsb == 0 and byte == 0
{
// increase row counter
rowCounter ++;
// setup correct row offset
outPtr = rowCounter * xDim;
if (rowCounter >= yDim) // are we done?
return;
}
else // if lsb == 0 and byte != 0
{
// setup counter
counterX = (int) b;
// read another byte
b = in[inPtr++];
// write the byte X times
for (i=0; i<counterX; i++)
out[outPtr++] = b;
continue;
}
}
else // if lsb == 1
{
if (!b) // if lsb == 1 and byte == 0
{
// read a new byte and add it to outPtr
outPtr += (int) in[inPtr++];
continue;
}
else // if lsb == 1 and byte != 0
{
// setup counter
counterX = (int) b;
// copy string
for (i=0; i<counterX; i++, inPtr++, outPtr++)
out[outPtr] = in[inPtr];
continue;
}
}
}
}
-----------------------8<------------------------------------
It's been a while since i participated on game modding discussions there. I helped them out sorting some LB2 file formats a few years back, and then noticed they used the same SPR format as StarLancer as well. The spr2bmp program in Flyboy's site is the same one we used for StarLancer with no modifications.
