
                             Format of a GRF File

   A GRF file is a collection of "sprites", defining pretty much everything
   that you can see in the game. The sprites can be graphics, but also define
   many non-visual properties of the game entities like vehicles.

   There are two different file formats defined. The older format 1 simply
   consists of one sprite following another until the end of the file,
   with no header or other meta-information, except for a checksum at the
   very end of the file.

   Format 2 consists of a header, followed by a data section containing all
   non-image sprites, followed by a sprite section containing the actual
   graphics.

   All numbers in a GRF file are stored in little-endian byte order.


File header (format 2 only)

   A format 2 GRF starts with a header with the following bytes:
          00 00 47 52 46 82 0D 0A 1A 0A

   DWORD sprite_offs
          Number of bytes to skip after this DWORD to reach the start of
          the sprite section.

   BYTE data_compr
          Compression format of the data section.

     00     No compression
     others Not defined

Data section (formats 1 and 2)

   The data section consists of sprites with the following format:
   
   WORD  size (format 1)
   DWORD size (format 2)
          The size of the current sprite, not including itself. The meaning
          depends on the info byte that follows.

   BYTE info
          Bitcoded value that determines what type this sprite is.

     FF     Pseudo sprite that contains non-image data, see the
              NewGraphicsSpecs for details. For a pseudo sprite, the
              size does *not* include the info byte.
     FD     (Only valid in format 2) Reference to sprite section. Size does
              *not* include the info byte.
     others (Only valid in format 1) Normal sprite with image data, see the
              section "Normal sprites" for details. If bit 2 is set, size
              is the length of the sprite in the file including the info byte.
              If it is not set, you have to decode the image data to find out
              where the next sprite starts.

   DATA data
          The length of the data depends on size and info.

          If the info value is FD, this is a single DWORD containing an ID
          that is looked up in the sprite section and processed instead of
          this sprite.

   The data sections is termindated by a WORD (format 1) / DWORD (format 2)
   of value 0.

   For format 1 GRFs, a four byte checksum follows. The algorithm to calculate
   it is unknown, but it is never processed by the game anyway.

Sprite section (format 2 only)

   The sprite section consists of entries with the following format:

   DWORD id
          ID used to reference the entry from the data section.

   DWORD size
          Length of the following data in the file.

   BYTE info
          Bitcoded value that determines what type this sprite is.

     FF     Non-image data, for example sounds. See the NewGraphicsSpecs
              for details.
     others Image data, see the section "Normal sprites" for details.

   DATA data
          size-1 bytes of data.

   Multiple entries with the same ID are allowed. IDs must be ordered
   ascending.

   The sprite section is terminated by a DWORD of value 0, which means
   that 0 is never a valid ID.

Normal sprites

   Normal sprites contain the visible graphics of the game. The exact format
   depends on the file format. For format 1 files, normal sprites occur in
   the data section, while for format 2 files they are found in the sprite
   section.

   For format 1 GRFs, the info byte has the following meaning:

   Bit Val Meaning
    0   1  Color index 0 is transparent (should always be set).
    1   2  Size is compressed size if set.
             If this bit is set, the given size is simply the size in the
             file. If it is unset, you *must* decompress it to find out
             how large it is in the file.
    3   8  Has transparency (i.e. is a tile), see below.
    6  40h The exact size of this sprite is significant. If not set,
             grfcodec may attempt to remove extraneous transparent pixels.
    others Undefined.

   For format 2 GRFs, the info byte has the following meaning:
   
   Bit Val Meaning
    0   1  Pixel format contains RGB components.
    1   2  Pixel format contains alpha component.
    2   4  Pixel format contains mask/palette component.
    3   8  Has transparency (i.e. is a tile), see below.
    6  40h The exact size of this sprite is significant. If not set,
             grfcodec may attempt to remove extraneous transparent pixels.
    others Undefined.

   Pixel components are ordered R, G, B, A, M, with not present components
   skipped without padding. For file format 1, pixel format is implicitly
   defined to be only the palette component.

   BYTE zoom_level (format 2 only)
          Zoom level of the current sprite, the following values are defined:
            00  normal zoom
            01  4x zoom-in
            02  2x zoom-in
            03  2x zoom-out
            04  4x zoom-out
            05  8x zoom-out

   BYTE ydim (format 1)
   WORD ydim (format 2)
          How many lines there are in the sprite (y dimension)

   WORD xdim
          How many columns there are (x dimension)

   WORD xrel
          Horizontal offset. The offset is counted from the base
          coordinate for each sprite.

   WORD yrel
          Vertical offset.

   DWORD uncomp_size (format 2, only if info bit 3 is set)
          Uncompressed size of the tile encoded image data.

   After this follows the actual compressed data. If info bit 3 is not
   set, the data is simply a stream of bytes from left to right, and
   from top to bottom, making up xdim*ydim pixels.

Tile sprites

   If info bit 3 is set, the sprite is a tile and has some special
   transparency information that is encoded like follows. Each line is
   encoded separately and split into "chunks". Each chunk contains
   pixels, but the chunks may skip a few pixels which are then
   transparent.

   The sprite data first starts off with a list of WORD offsets for
   format 1 GRFs and format 2 GRFs with an uncompressed size below 65536
   bytes. If the size is bigger in a format 2 GRF, the sprite starts
   with a list of DWORD offsets. There is one offset for each line. These
   determine at which offset each line starts, counted from the first data
   byte.

   Then follow the chunks for the lines:

   BYTE cinfo (format 1)
   WORD cinfo (format 2 if width > 256)
          The high bit is set if this is the last chunk in the line. The
          line need not be filled entirely, any remaining pixels are
          simply transparent. The lower seven/fifteen bits give the length of
          this chunk in pixels.

   BYTE cofs (format 1)
   WORD cofs (format 2 if width > 256)
          x offset at which this chunk starts. The pixels between this
          chunk and the last one will be transparent.

   After this follow (cinfo & 0x7f or cinfo & 0x7fff, respectively) bytes
   of pixels.

Compression algorithm

   The compression used is a variation on the LZ77 algorithm which
   detects redundancy and losslessly reduces the size of the data. Here's
   how the compressed data looks in a GRF file.

   The compressed stream contains either a pointer to an earlier location
   and a length, which means that these bytes are copied over from the
   given location, or it contains a length and a verbatim chunk which is
   copied to the output stream.

   BYTE code
          The high bit of the code shows whether this is a verbatim chunk
          (not set) or a repetition of earlier data (set).

   The meaning of the following bytes depends on whether the high bit of
   code is set.

   If the high bit is not set, what follows is code&0x7f bytes of
   verbatim data.

   If the high bit is set, the code has a slightly different meaning.
   Bits 3 to 7 are now three bits to a length value, stating how much
   data should be copied from the earlier location. Bits 0 to 2 are the
   high bits of an offset, with the low bits being in the next byte.

   BYTE lofs
          Low bits of the offset

   Use this to extract length and offset:
unsigned long length = -(code >> 3);
unsigned long offset = ( (code & 7) << 8 ) | lofs;

   It's important that the variables are unsigned and at least two bytes
   large.

   The offset is counted backwards from the current location. So you
   subtract the offset from your position in the output stream and copy
   the given number of bytes.

   And that's pretty much all you need to know about a GRF file!
   ______________________________________________________________________

   Copyright © 1999-2012 by Josef Drexler.
