General

Data types

Well first about the data types used in this tutorial. For one I'm on purpose not using the standard windows established names.

I had different names here before, but I changed it once again. (in source and in the documentation)
Why not call the things as they are instead of inventing words?

(In source I use the types 'byte' and 'int8' alternative, dependant from context. 'byte' if it's a pointer to a byte-buffer, and 'int8' if it's a simple 8 bit integer variable. However in the documentations I'll prefer BYTE as everybody immedatly knows what is ment.)

UNSIGNED BYTE (INT8)	unsigned 8 bit	0 ... 255
UNSIGNED INT16	unsigned 16 bit	0 ... 65535
UNSIGNED INT32	unsigned 32 bit	0 ... 4294967295

SIGNED BYTE (INT8)	signed 8 bit	-128 ... 127
SIGNED INT16	signed 16 bit	-32768 ... 32767
SIGNED INT32	signed 32 bit	-2147483648 ... 2147483647

One addition I'd like to place about signed and unsigned values. There is a lot of confusion about, and tons of bugs are the results of signed/unsigned mismatches. Some languages took this enough reason (java and VB in example) to completely strike out unsigned values at all, only allowing signed ones.

However if programming c(++) always use an unsigned type when an unsigned one will do. (But don't use it if it won't do :o)

Most important reason is that unsigned types are processed faster than signed ones.
Another side effect, it will strike out the possibility your code suddenly behaves completely different than expected just because one of the variables got negative, which you didn't expect to happen.

Endian

As the mul-files are optimized for Intel processors, and to direct File IO, all data is stored in little endian format. (least significant byte first)

This means if you are programming in some high level language (java in example) you'll have to swap them yourself. (or if you read byte-wise)

There are some exceptions where data is read in big endian in this tutorial.
I'll expectly say so if it happens. This has major historic reasons as we didn't know better and from the fact that human brains think in big endian. (at least mine does =)

Colors

All graphics are INT16 stored in the 5-5-5 format. Meaning 1 bit is unused (can be used for transparency), 5 bit red, 5 bit green and 5 bit blue intensity.

F	E	D	C	B	A	9	8	7	6	5	4	3	2	1	0
	red					green					blue

If you have to convert to true color, you can use this cute 'little' formula:
(I just noticed lately, this could also go a lot faster, without any '*' or '/' operations... however I'm not publishing an untested formula... ) (Arachnide keeps the 5-5-5 either way)

Color32 = ((((Color16 >> 10) & 0x1F) * 0xFF / 0x1F) << 16) |
          ((((Color16 >> 5)  & 0x1F) * 0xFF / 0x1F) << 8) |
          ((( Color16        & 0x1F) * 0xFF / 0x1F);

- finished, Ready to hit the (mul) Road?