BLB

From MultimediaWiki
Jump to: navigation, search

Credit

The information on this page was originally based on one of the many format documents written up by Valery V. Anisimovsky, available on wotsit.org and many other sites across the internet.

BLB Resource Files

All game files of The Neverhood are stored in BLB resource files. Each BLB file has the following header:

struct BLBHeader
{
 DWORD	id1;
 WORD	id2;
 WORD	extDataSize;
 DWORD fileSize;
 DWORD fileCount;
};

id1 -- is always 0x02004940.

id2 -- is always 0x07.

extDataSize -- the size of the shift array of the BLB file (see below).

fileSize -- the size of BLB file.

fileCount -- the number of files stored in BLB file.

After the header comes the array of (fileCount) file IDs. Each file ID is a DWORD identifying a file in BLB archive.

After the file IDs array comes the array of (fileCount) resource entries. Each resource entry contains the info on a file in BLB archive. Each such entry has the following format:

struct BLBDirEntry
{
 BYTE	type;
 BYTE	comprType;
 WORD	extDataIndex;
 DWORD timeStamp;
 DWORD offset;
 DWORD diskSize;
 DWORD outSize;
};

type -- the type of the file:

0x02 -- sprite/graphic file
0x03 -- palette file
0x07 -- sound effect
0x08 -- music
0x0A -- video file (SMK -- Smacker video, www.smacker.com)

there're some more types, which are still to be figured out.

comprType -- defines the compression state of the file:

0x01 -- the file is not compressed, and can be used as-is,
0x03 -- the file is compressed using the PKWare DCL (see below),
0x65 -- the file is a dummy, that is no file is really present (see below).

extDataIndex -- the index in the shift array for the byte correspondent to the file.

offset -- the position of the file relative to the beginning of the BLB archive.

diskSize -- the size of the file as it is found in the BLB archive. For non-compressed files this is the same as outSize.

outSize -- the output size of the file. For non-compressed files this is the same as diskSize, for compressed files this is the size after is has been decompressed.

After the array of resource entries comes the "shift array". This is an array of (extDataSize) bytes, each called a "shift". The shift value for the file may be obtained by getting the byte with index (extDataIndex) (see above) from the shift array (indices are zero-based). If the index value is too large (not less than shift array size (extDataSize)), the shift value should be set to default (0xFF).

After the shift array comes the actual file data contained in BLB archive.

Compressed Files

Files compressed in BLBs are compressed using PKWare's Data Compression Library. There are two ways that these can be decompressed:

1) The first method is using the PKWARE.DLL library. This file is supplied with GAP (Game Audio Player) (which can be downloaded here) and is found in its root folder.

Here's some sample C code to decompress files (using Win32 API):

// decompression function -- returns zero on success
DWORD (__cdecl *Uncompress)
(
 char	*outputBuffer,
 DWORD *pOutSize,
 char	*inputBuffer,
 DWORD  dwSize
);

// first, load the library
HINSTANCE hDllInst=LoadLibrary("pkware.dll");

// get the decompression function address
Uncompress=(DWORD (__cdecl *)(char*, DWORD*, char*, DWORD))GetProcAddress(hDllInst,"Uncompress");

// decompress file -- it's assumed here that input buffer contains compressed
// file loaded from BLB archive and output buffer is allocated and has proper
// size (that is, (outSize) value from the corresponding directory entry)
Uncompress(outputBuffer,&outSize,inputBuffer,dwSize);

// now (outputBuffer) contains decompressed file and (outSize) is set to
// decompressed file size (you should use directory entry value of output
// size for output buffer allocation)

2) The second method uses the blast library. This is a useful alternative to PKWARE.DLL as it can be compiled for platforms other than Windows, and can also be potentially ported to other languages. The blast.c file contains an example program at the bottom which shows how it should be used.

BLBSFX Sound and Music Files

As was pointed out above, files with type bytes 0x07 and 0x08 are sound and music files. All of them are of the same format which I refer to as BLBSFX. BLBSFX file has no header, it's just compressed (or non-compressed) waveform stream. All sound/music files in The Neverhood are 16-bit mono 22050 Hz. If the shift value for the BLBSFX file is 0xFF, the file in not compressed and in this case, it's just PCM waveform stream (signed 16-bit). Otherwise, if the shift byte differs from 0xFF, BLBSFX file is compressed using DW ADPCM compression algorithm. Refer to the following section for the description of DW ADPCM decompression scheme. Note that most of sound files in The Neverhood are PKWARE-compressed, that is you should first decompress them (e.g. using PKWARE.DLL and the approach described above) and then apply DW ADPCM decompression scheme (if needed). All music files are not PKWARE-compressed, but most of them are DW ADPCM compressed.

DW ADPCM Decompression Algorithm

During the decompression SHORT variable should be maintained. Decompression uses shift value, so it should be obtained first.

Here's the code which decompresses DW ADPCM compressed BLBSFX file:

BYTE  bShift; // shift value
char *inputBuffer[dwSize];

SHORT iCurValue;
DWORD i;

iCurValue=0x0000;

for (i=0;i<dwSize;i++)
{
 iCurValue+=(signed short)inputBuffer[i];
 Output(iCurValue<<bShift);
}

Output() is just a placeholder for any action you would like to perform for decompressed sample value.

BLB Image Files

The images used in the BLB file seem to be of several different types types. One type is a 256 color bitmap, using a color palette, the other seems to be a varient of RGB332. Both files use the following 3 word header and are little endian. There is at least one other format which I have not investigated yet.

struct BLBImageFileHeader
{
 WORD	bFileType; //1A = Paletted, 12 = RGB332? 17 = Unknown.
 WORD	bXRes;
 WORD	bYRes;
};

bXRes contains the X resolution (in pixels) of the image bYRes contains the Y resolution (in pixels) of the image

Paletted graphic files

For graphics with a palette, there then follows a 256 item long array, containing the color palette used in the image.

struct BLBImageFilePaletteItem
{
 BYTE bRedValue
 BYTE bGreenValue
 BYTE bBlueValue
 BYTE bPadding //always zero.
}

The total size of the header+palette is 1030 bytes.

Then comes the pixel data. This should be exactly XRes*YRes bytes. Each byte is an index for the palette, and the color from the palette is then used to color that pixel. I.e. A pixel value of 2A means that the pixel color is that of the 42nd element in the palette array.

Non paletted graphic files

As mentioned earlier, these seem to be some form of RGB332, so far the author has been unsuccessful in converting them to bitmaps with correct color information. Seems more likely that this is paletted using the Safety Palette present in Windows.

After the header, there is simply an array of bytes of size equal to XRes*YRes that contain the value for each pixel in the file. This is assumed by the author to be RGB332 or a varient thereof, but the values could also be indexes to a windows default palette.

PC Games Using BLB

The Neverhood