home *** CD-ROM | disk | FTP | other *** search
/ Quake 'em / QUAKEEM.BIN / quake / programs / qeu03 / formats < prev    next >
Encoding:
Text File  |  1996-03-03  |  7.8 KB  |  256 lines
  1. Quake data formats
  2. ==================
  3.  
  4. Here is a list of the various data structures used by Quake, and a guide to
  5. the functions of the QEU library that can be used to work on these structures.
  6.  
  7. PACK (magic: "PACK", extension: ".pak")
  8. ---------------------------------------
  9.  
  10. This is a simple archive file, which includes other files.
  11.  
  12. * Files: f_pack.h, f_pack.c
  13.  
  14. * Status: Completely understood.
  15.  
  16. * Reading PACK files:
  17.  
  18.   ReadPACKDirectory()
  19.   Reads the directory of a PACK files and stores it in memory.  The individual
  20.   files in the archive can be read with the appropriate Read*() function, using
  21.   the offset found in the directory.
  22.  
  23. * Creating PACK files:
  24.  
  25.   WritePACKHeader()
  26.   Writes the header of the PACK file and creates an empty directory in memory.
  27.  
  28.   AddPACKEntry()
  29.   Adds a new entry to the PACK directory, after the data has been written to
  30.   the file using the appropriate Save*() or Write*() function.
  31.  
  32.   WritePACKDirectory()
  33.   Updates the PACK header and writes the directory to the file.  Like the
  34.   other Save*() and Write*() routines, it returns the total number of bytes
  35.   taken by the whole PACK data (header + all entries + directory).
  36.  
  37. * Other functions:
  38.  
  39.   FindPACKEntry()
  40.   Returns the index in the PACK directory of the first entry matching a given
  41.   name.
  42.  
  43.   DumpPACKDirectory()
  44.   Prints the contents of the PACK directory in a human-readable form.  Useful
  45.   for debugging.
  46.  
  47.   UnPACKFile()
  48.   Creates individual files from a PACK archive.
  49.  
  50.  
  51. WAD2 (magic: "WAD2", extension: ".wad")
  52. --------------------------------------
  53.  
  54. The WAD2 format is also an archive format, which includes several chunks.
  55. Each chunk has a type (raw data, bitmap with header, raw bitmap) and an
  56. optional compression method, although none of the chunks are compressed in
  57. the test version of Quake.
  58.  
  59. * Files: f_wad2.h, f_wad2.c (+ f_bitmap.h, f_bitmap.c)
  60.  
  61. * Status: Completely understood.
  62.  
  63. * Reading WAD2 files:
  64.  
  65.   ReadWAD2Directory()
  66.   Reads the directory of a WAD2 files and stores it in memory.  The individual
  67.   chunks in the archive can be read with the appropriate Read*() function,
  68.   using the offset found in the directory.  Most of the chunks are bitmaps that
  69.   can be read with ReadBitmap().  Two chunks (CONBACK, CONCHARS) are raw
  70.   bitmaps that can be read with ReadRawBitmap(), using the appropriate width
  71.   and height.  The palette (PALETTE) is stored as raw data and can be read with
  72.   ReadBytes() or copied to a file with CopyBytes().
  73.  
  74. * Creating WAD2 files:
  75.  
  76.   WriteWAD2Header()
  77.   Writes the header of the WAD2 file and creates an empty directory in memory.
  78.  
  79.   AddWAD2Entry()
  80.   Adds a new entry to the WAD2 directory, after the data has been written to
  81.   the file using the appropriate Save*() or Write*() function.
  82.  
  83.   WriteWAD2Directory()
  84.   Updates the WAD2 header and writes the directory to the file.  Like the
  85.   other Save*() and Write*() routines, it returns the total number of bytes
  86.   taken by the whole WAD2 data (header + all entries + directory).  If the WAD2
  87.   file is included in a PACK file, this number can be given to AddPACKEntry().
  88.  
  89. * Other functions:
  90.  
  91.   FindWAD2Entry()
  92.   Returns the index in the WAD2 directory of the first entry matching a given
  93.   name.
  94.  
  95.   DumpWAD2Directory()
  96.   Prints the contents of the WAD2 directory in a human-readable form.  Useful
  97.   for debugging.
  98.  
  99.   UnWAD2File()
  100.   Creates individual files from a WAD2 archive.
  101.  
  102.  
  103. BSP (extension: ".bsp")
  104. -----------------------
  105.  
  106. The BSP files contain the information about the maps (level data) and the
  107. static objects that can be included in the maps.  Each BSP file contains 14
  108. unnamed chunks of data which define a level and its contents.  More
  109. information about the contents of the BSP files can be found in the
  110. "Unofficial Quake Specs" by Olivier Montanuy.
  111.  
  112. Obviously, the hard part is not to work on the structure of the BSP file,
  113. but on its contents.  This will be done by other routines (not written yet).
  114.  
  115. * Files: f_bsp.h, f_bsp.c
  116.  
  117. * Status: Structure of the file completely understood, but the format of the
  118.           14 entries is still unknown to me.  Some of them are easy to
  119.           understand (the first entry is plain text), but the other ones are
  120.           more complex.  I have a rough idea of what each one does, but I
  121.           haven't had the time to investigate this in detail.
  122.  
  123. * Reading BSP files:
  124.  
  125.   ReadBSPDirectory()
  126.   Reads the directory of the BSP file and stores it in memory.  It seems that
  127.   all BSP files in Quake contain 14 entries, but this could change in future
  128.   versions of the game (the first 4 bytes of the BSP files contain a version
  129.   number).  This function only reads the offsets to the individual data
  130.   chunks, which have to be read with an approriate Read*() function (not done
  131.   yet).
  132.  
  133. * Creating BSP files:
  134.  
  135.   (not done yet, although it's rather simple).
  136.  
  137. * Other functions:
  138.  
  139.   DumpBSPDirectory()
  140.   Prints the contents of the BSP directory in a human-readable form.  Useful
  141.   for debugging.
  142.   
  143.   UnBSPFile()
  144.   Creates individual files from a BSP file.  Useful for debugging.
  145.  
  146.  
  147. Models (magic: "IDPO", extension: ".mdl")
  148. -----------------------------------------
  149.  
  150. These 3D models define the animated objects (players, monsters and moving
  151. objects).  They contain the skin texture of the object (flat picture), a
  152. set of triangles defining the object and a sequence of frames for the
  153. animation.
  154.  
  155. * Status: I'm still working on that.  I have understood most of it, but I
  156.           didn't include the source code because there are still some bugs
  157.           in it.
  158.  
  159.  
  160. Sprites (magic: "IDSP", extension: ".spr")
  161. ------------------------------------------
  162.  
  163. The sprite files are simplified models (flat 2D pictures).  They contain
  164. multiple frames, which can contain several pictures.  I understand the format
  165. of the sprites, but not the purpose of the multiple pictures.
  166.  
  167. * Files: f_sprite.h, f_sprite.c (+ f_bitmap.h, f_bitmap.c)
  168.  
  169. * Status: Almost completely understood.
  170.  
  171. * Reading sprite files:
  172.  
  173.   ReadSprite()
  174.   Reads all the frames for a sprite and stores them in memory.
  175.  
  176. * Creating sprite files:
  177.  
  178.   SaveSprite()
  179.   Saves a sprite to a file (all frames).
  180.  
  181. * Other functions:
  182.  
  183.   NewSprite()
  184.   Creates a new, empty sprite.
  185.  
  186.   FreeSprite()
  187.   Discards a sprite and frees memory.
  188.  
  189.   AddSpriteImage()
  190.   Adds an image (bitmap) to a sprite.
  191.  
  192.  
  193. Sounds (magic: "RIFF", extension: ".wav")
  194. -----------------------------------------
  195.  
  196. These are standard WAV files, which can be read and saved by most sound
  197. editors.  I do not intend to re-invent the wheel and include a sound
  198. editor in QEU.
  199.  
  200.  
  201. Bitmaps
  202. -------
  203.  
  204. These are "flat" bitmaps, consisting of an array of 8-bit pixels (using a
  205. palette of 256 colors).  The bitmaps are included in the WAD2 file (gfx.wad)
  206. and are part of some other structures, such as the frames for a sprite or an
  207. alias model.  In all these bitmaps, the reference to the Quake palette is
  208. implicit.  This is probably the simplest data structure in Quake.
  209.  
  210. * Files: f_bitmap.h, f_bitmap.c
  211.  
  212. * Status: Completely understood (that was simple enough!).
  213.  
  214. * Reading bitmap files:
  215.  
  216.   ReadBitMap()
  217.   Reads a bitmap, including its width and height.
  218.  
  219.   ReadRawBitMap()
  220.   Reads a raw bitmap (without header).  The width and height of the bitmap
  221.   must be supplied to this function, since they are not included in the file.
  222.  
  223. * Creating bitmap files:
  224.  
  225.   SaveBitMap()
  226.   Saves a bitmap to a file, including its width and height.  The number of
  227.   bytes written is returned, so that it can be given to AddWAD2Entry() if the
  228.   bitmap is included in a WAD2 file.
  229.  
  230.   SaveRawBitMap()
  231.   Saves a bitmap to a file as raw data, without its width and height.
  232.  
  233. * Other functions:
  234.  
  235.   NewBitMap()
  236.   Creates a new, empty bitmap.
  237.  
  238.   FreeBitMap()
  239.   Discards a bitmap and frees memory.
  240.  
  241.   DumpBitMap()
  242.   Prints the contents of the bitmap in a human-readable form.  Useful for
  243.   debugging, although not practical for large bitmaps.
  244.  
  245.   SavePPM()
  246.   Saves a bitmap as a PPM file (uses the Quake palette).
  247.  
  248.   SaveBMP()
  249.   Saves a bitmap as a BMP file (uses the Quake palette).
  250.  
  251.  
  252. Other formats
  253. -------------
  254.  
  255. To be added later...
  256.