home *** CD-ROM | disk | FTP | other *** search
/ Demon Gate Mega Collection / DemonGateMegaCollection.bin / text / cleanwad.txt < prev    next >
Text File  |  1995-09-26  |  12KB  |  246 lines
  1.  
  2.  
  3.                             CLEANWAD v1.0b
  4.              WAD file cleaner and optimizer by Serge Smirnov
  5.                          (sxs111@po.cwru.edu)
  6.  
  7.                     Comments and suggestions welcome.
  8.  
  9.                         Cleanwad 1.0 is freeware.
  10.  
  11.  
  12.  
  13. Overview
  14. --------
  15.  
  16. This is my second doom programming effort, and it is intended for a much
  17. wider range of users than my first one, CUSTMWAD (a set of two very low
  18. level WAD tools).  This program owes much of its existence to Olivier
  19. Montanuy, the author of DeuTex and WinTex, who flamed me for CUSTMWAD,
  20. but ended up asking me to write a WAD cleaner :-)
  21.  
  22.  
  23.  
  24. Features
  25. --------
  26.  
  27. Cleanwad simply copies a WAD file to a file with another name, rebuilding
  28. it as it goes.  This procedure includes the following:
  29.  
  30.    * sorting directory entries by type;
  31.    * eliminating any repeated entries;
  32.    * eliminating 'null' entries (i.e., entries with "\0\0\0..." for name); 
  33.    * truncating WAV resources whose length exceeds their number of samples;
  34.    * rebuilding pictures and (optionally) blockmaps;
  35.    * lossless picture and blockmap compression/decompression (optional).
  36.  
  37. What you should end up with is a cleaner, smaller copy of your WAD file,
  38. which is identical in functionality to the original.  The amount of space
  39. saved will vary, but may be quite significant.  Here are the results of
  40. running cleanwad on some well known WADs with the following switches:
  41.  
  42.      cleanwad <source.wad> <destination> +rb +pb +rp +pp +is.
  43.  
  44. WAD file                 | Original size |  New size  | Space Saved | Ratio
  45.                          |               |            |             |
  46. DOOM2.WAD (1.9)          |  14,604,584   | 14,317,392 |    287,192  |  2.0%
  47. DOOM.WAD (Ult. doom 1.9) |  12,408,242   | 11,363,608 |  1,066,634  |  7.2%
  48. HERETIC.WAD (1.2)        |  11,095,516   | 10,905,856 |    189,660  |  1.7%
  49.                          |               |            |             |
  50. TRINITY.WAD              |     882,464   |    877,040 |      5,424  |  0.6%
  51. ALIENGFX.WAD (v2.2)      |   3,035,383   |  2,813,260 |    222,123  |  7.3%
  52. ALIENLEV.WAD (v2.2)      |   1,245,357   |  1,228,196 |     17,161  |  1.4%
  53. ALNSND2.WAD  (v2.2)      |     738,510   |    678,608 |     59,902  |  8.1%
  54. ALITCSF.WAD  (for 1.9)   |   1,168,480   |  1,154,800 |     13,680  |  1.2%
  55. ALITCSND.WAD (for 1.9)   |     687,862   |    682,810 |      5,052  |  0.7%
  56. ALITCWAD.WAD (for 1.9)   |   3,601,904   |  2,880,188 |    721,716  | 20.0% 
  57. OBTIC1.WAD               |   4,204,061   |  4,032,742 |    179,319  |  4.1%
  58. OBTIC2.WAD               |     403,927   |    385,988 |     17,939  |  4.4%
  59. OBTIC3.WAD               |     210,047   |    207,721 |      2,326  |  1.1%
  60.                                                                     
  61. Cleanwad requires about 285K of conventional memory to rebuild DOOM2.WAD
  62. with picture optimizations on.
  63.  
  64.  
  65.  
  66. Usage
  67. -----
  68.  
  69. The basic command line for cleanwad is very simple:
  70.  
  71.   cleanwad.exe <input-file> <output-file>
  72.  
  73. The original file is left intact, the output goes to output-file.
  74. If output-file already exists, it will be OVERWRITTEN WITHOUT ANY
  75. QUESTIONS, so please be careful.  if you use any of the optional
  76. command line switches, male sure that <input-file> and <output-file>
  77. preceed them.
  78.  
  79. While cleanwad processes a WAD file, it will occasionally spit out
  80. 'progress' messages.  These fall into 4 categories:
  81.  
  82.   1) Warnings (something in the input file looked suspicios);
  83.   2) Completion of large steps (only a few of these);
  84.   3) Successful optimizations (saved space);
  85.   4) detailed progress (way excessive for most people's needs).
  86.  
  87. You can to some extent control which of these are displayed by setting
  88. the "verbosity level" to a number from 0 to 4.  4 means "all", 0 means
  89. "nothing".  3 (default) displays everything except 4.  Here is an example
  90. of how this switch can be used:
  91.  
  92.   cleanwad a.wad b.wad v2.
  93.  
  94. You might want to do this if cleanwad generates more optimization
  95. reports than you want to see while it runs.
  96.  
  97. You can set certain optimization options by using the following
  98. command line switches.  These switches must be preceeded by a plus
  99. or a minus, depending on whether you want to enable or disable
  100. them.  The following turns the 'rp' option off, while enabling
  101. 'rb' and 'pb' (stay tuned for an explanation of what these do):
  102.  
  103.   cleanwad a.wad b.wad -rp +rb +pb
  104.  
  105. Some switches are on by default.  They're the ones suggested
  106. by Olivier, and are thus considered part of the cleanwad design spec.
  107. The rest are what I implemented just for the fun of it.  A list of
  108. all switches follows.  To see which ones default to ON, run cleanwad
  109. with no arguments.
  110.  
  111. +rr (or -rr) stands for 'remove redundant entries'.  Turning this option
  112.     on causes cleanwad to check for a previous occurrence before adding
  113.     an entry to the output file.  If an entry with the same name already
  114.     exists, it is replaced with the latest one.  This happens as many
  115.     times as necessary to insure that the output file contains no redundant
  116.     entries.  Maps are handled the same way, i. e., a second occurrence
  117.     of E1M1 causes the first one, including all the map data following it,
  118.     to be removed.  Of course, a second occurrence of THINGS in the same
  119.     WAD isn't considered redundant.
  120.  
  121. +al (or -al) stands for 'align'.  It causes every single directory entry in
  122.    the output file to start at a 4-byte boundary.  I've been told that it
  123.    has significant effects on the speed of 32-bit applications, but I haven't
  124.    noticed it.  You can turn the option off to save a little space.
  125.  
  126. +is (or -is) stands for 'ignore WAD syntax'.  Some wads have misplaced and/or
  127.    mismatched .._START/.._END entires.  Normally this causes cleanwad to exit
  128.    with a 'parse error'.  If you have one of those wads and want to use
  129.    cleanwad on it anyway, you may try this option.  Cleanwad will then assume
  130.    that any .._END it encounters is appropriate wherever it is.  This works
  131.    nicely if a SS_START is (incorrectly) paired with a S_END.  However, when
  132.    you use this option there is a chance that cleanwad will misinterpret the
  133.    type of some entry and crash.  The best way to use cleanwad is to have a
  134.    wad that uses proper .._START/.._END syntax.
  135.  
  136. +tw (or -tw) stands for 'truncate WAV resources'.  Some editors create WAV
  137.    entries that take up more space than is necessary for the number of
  138.    samples.  Cleanwad can truncate such sounds.
  139.  
  140. +rp (or -rp) stands for 'rebuild pictures'.  The structure of DOOM picture
  141.    resources allows empty holes within such resources.  Leaving this option
  142.    on gets rid of them.  You must NOT disable this option if you want to
  143.    utilize either 'pp' or 'up'.
  144.  
  145. +pp (or -pp) stands for 'pack pictures'.  A more radical approach to saving
  146.    disk space.  Cleanwad can compress picture resources up to 8 times (though
  147.    ratios between 1.1 and 1.6 are much more typical), without changing their
  148.    functionality in any way.  I got the idea from some node builders, which
  149.    do blockmap compression.  Such compression is completely lossless, and
  150.    I do not see any rational reason for why it could slow down the game.  If
  151.    anything, it might reduce the amount of memory required by the doom
  152.    refresh daemon during initialization.
  153.  
  154. +up (or -up) stands for 'unpack pictures'.  If you have compressed the
  155.    pictures in your WAD with '+pp', but for some reason want to bring them
  156.    back to normal, cleanwad can uncompress them for you.  An attempt to
  157.    uncompress a picture that was not compressed should do no damage.
  158.    Similarly, you can compress a picture more than once -- its length will
  159.    simply not change after the first time.  Note that some pictures don't
  160.    compress at all to begin with.
  161.  
  162. +rb (or -rb) stands for 'rebuild blockmaps'.  Very similar to 'rp';
  163. +pb (or -rb) stands for 'pack blockmaps'.  Very similar to 'pp';
  164. +ub (or -rb) stands for 'unpack blockmaps'.  Very similar to 'up'
  165. ('pb' and 'ub' require 'rb' to be ON to work).
  166.  
  167. For more information on what the last six switches do, look at the source
  168. code.
  169.  
  170.  
  171.  
  172. Known problems
  173. ----- --------
  174.  
  175. Certain Heretic pictures.  Apparently, they are not in the standard doom
  176. picture format, so when cleanwad tries to process them it generates warnings
  177. like
  178.  
  179.   WARNING: picture CREDIT has an invalid heaader -- not processed
  180.  
  181. (here, CREDIT can also be HELP1 or HELP2).  These warnings can be safely
  182. ignored with Heretic.  The reason I can't get read of them is that
  183. doom.wad and doom2.wad have similarly named resources that ARE real doom
  184. pictures.
  185. Another problem encountered when processing heretic.wad is this:
  186.  
  187.   WARNING: WAV sound GFRAG has an invalid header -- not processed.
  188.  
  189. A hex dump of GFRAG shows that it indeed does not resemble a standard WAV
  190. resource; in fact, the first half of it is just one character repeated
  191. over and over.  However, GFRAG is in the middle of other sounds, so it
  192. may be a sound.  Anyway, the GFRAG warning means nothing.
  193.  
  194. Another issue that may cause confusion is how cleanwad handles entries like
  195. S_START, FF_END, etc.  My assumption is that the '_START's and '_END's in
  196. a WAD must form something similar to a set of matched paranthesis.  In other
  197. words, if every type of _START/_END is assingned a unique type of paranthesis,
  198. based on the characters that preceed the underscore, then the WAD must look
  199. like a proper algebraic expression, with data entries for variables and
  200. operators.  While testing cleanwad, I found that this rule is broken all the
  201. time, and since I haven't seen a document describing the rules for using
  202. _STARTs/_ENDs, I'm at a loss as to what's right and what's wrong.  If
  203. anyone can enlighten me on this, please do.  For now, I am just providing the
  204. '+is' option, so that if my understanding is wrong you can still use cleanwad.
  205.  
  206. If you think this section is missing something, please let me know.
  207.  
  208.  
  209.  
  210. Bug reports
  211. --- -------
  212.  
  213. Cleanwad may crash if the input file contains garbage (i. e., pointers to
  214. places past the end of file, or entries whose names imply a certain type
  215. but contain something else).  It will exit to DOS with either a
  216. 'file IO error' or an 'out of memory' message.  I consider such crashes
  217. normal behavior if the input file is corrupt.  If cleanwad crashes while
  218. processing a file that you believe is a valid WAD file, send it my way and
  219. I'll attempt to figure out what's wrong.
  220.  
  221. Cleanwad should never write to uninitialized places in memory, no matter
  222. what the input file is.  I realize this is a very abmitious claim, but I
  223. have put some effort into making cleanwad bullet proof in this sense, so
  224. if it locks up your computer, let me know and I'll try to fix it.
  225.  
  226. I have made every effort to ensure that whatever cleanwad produces works
  227. exactly like the original file.  I realize that it won't take long until
  228. somebody finds a WAD that would be damaged by cleanwad.  If you're one 
  229. such lucky person, don't hesitate to Email me.
  230.  
  231. Finally, feel free to report anything you find annoying about using
  232. cleanwad.  This includes things like excessive output to screen,
  233. confusing error/warning messages, bad command line design, anything
  234. that you think can be improved.  If/when I receive a sufficient
  235. number of complaints of adequate seriousness, I will release another
  236. version of cleanwad, provided I have time.
  237.  
  238.  
  239.  
  240. Credits
  241. -------
  242.  
  243. Id software      -- wrote doom
  244. Matt Fell        -- wrote The Unofficial Doom Specs
  245. Olivier Montanuy -- gave me the idea and suggested some of the design
  246. me               -- spent long hours optimizing blockmap/picture compression %-)