                        WADPTR - WAD Compressor
                             Version 2.4
                   By Simon Howard and Andreas Dehmel

         Copyright(C) 1998-2011 Simon Howard, Andreas Dehmel

      This program is available for distributions under the terms of
      the GNU General Public License Version 2, as published by the
      Free Software Foundation. See the file COPYING for details.

                           Contents
                           --------
              [1] About WADPTR
                    [1-1] What is WADPTR ?
                    [1-2] How does it work?
                        [1-2-1] What is lump merging?
                        [1-2-2] What is SIDEDEF packing?
                        [1-2-3] What is Graphic squashing?
              [2] Using WADPTR
                    [2-1] List of command line options
                    [2-2] Compressing a WAD
                    [2-3] Uncompressing a WAD
                    [2-4] Listing a WAD
                    [2-5] Using wildcards
              [3] Remaining stuff
                    [3-1] Version History
                    [3-2] Bugs/suggestions/comments
                    [3-3] Thanks to..



[1] About WADPTR
================

[1-1] What is WADPTR ?
----------------------
WADPTR is a program designed to compress your WAD files. This can be a
great help for you, as modem speeds mean that transferring a smaller
file takes less time than transferring a larger file.

WADPTR was originally designed as an extension to DEUTEX (get it).
The latest version of it automatically reads a WAD, locates where it
can be compressed and does it, spitting out a brand new WAD which is
smaller than the original. This is a great advantage over previous
versions, which demanded the creation of text-files to tell WADPTR
how to make the WAD smaller. This latest version is fully automatic.

[1-2] How does it work ?
------------------------
WADPTR uses three seperate methods to compress WAD files: lump
merging, graphic squashing and sidedef packing. These actually
all work in quite similar ways. As well as compressing WADs, it
also removes unused data in WADs(information that exists but is
not part of any lump) and removes unused sidedefs(sidedefs that
exist but are not bound to any linedef).

[1-2-1] Lump merging
--------------------
Lump merging relies on the fact that quite often, people building
WADs put the same thing into it twice: for example: the same sound
for the door opening as for the door closing. What WADPTR does is
to find where this has been done and merge the data for the two
resources together. It all relies on how WADs work. This diagram
shows how a normal WAD is:

  WAD Directory                    Lumps


    DSDOROPN  ----------------> Door sound



    DSDORCLS  ----------------> Door sound


This is the same WAD after it has been run through WADPTR:

  WAD Directory                    Lumps


    DSDOROPN  ----------------> Door sound
                     |
                     |
                     |
    DSDORCLS  -------/

As the sound only has to be stored once, rather than twice, the
WAD is smaller.


[1-2-2] What is SIDEDEF packing ?
---------------------------------
WADPTR contains routines to pack the sidedefs in levels. This
works in a very similar way to the normal WAD compression. For
example, a normal level might be like this:


        LINEDEFS                        SIDEDEFS

                               /---------> 1
           1-------------------
                               \---------> 2

           2-----------------------------> 3


Assuming that sidedefs 2 and 3 are the same, a level with its'
SIDEDEFS packed might look like this:


        LINEDEFS                        SIDEDEFS

                               /---------> 1
           1-------------------
                               \---------> 2 <---\
                                                 |
           2-------------------------------------/


Identical sidedefs are shared amongst multiple linedefs. Of
course, in an average level, there may be hundreds of identical
sidedefs, so packing the sidedefs in levels can substantially
reduce thir size.

WADPTR also removes unused sidedefs in a level, that is,
sidedefs that exist, but are not bound to any linedef. These
just take up space.

[1-2-3] What is graphic squashing ?
-----------------------------------
Graphic squashing is again, very similar to sidedef packing
and lump merging. It works by merging identical columns in
a graphic lump. Doom graphic lumps are split up into 'columns'
which are vertical rows of pixels. There are also 'column
pointers' at the start of the lump, which hold the starting
location of each column in the lump. There is a column for
every pixel wide the image is. For example:

        Column pointers                 Columns

           1 ----------------------------> 1 

           2 ----------------------------> 2

           3 ----------------------------> 3

WADPTR combines identical columns. So a 'squashed' lump
might be like this:

        Column pointers                 Columns

           1 ----------------------------> 1

           2 ------------\
                          ---------------> 2
           3 ------------/


Columns are shared between multiple column pointers. As less
columns are needed, the lump is smaller.

However, graphic squashing works better on some images than
others. It works best on:

        * 'Pattern' images
        * Very simple images, eg. parallel lines, single colour
          etc.
        * Images which contain a lot of empty space, eg. ones
          with black backgrounds.
        * Images which do not use a very wide colour range

Images it does not work well with include:

        * Pattern images where each pattern is slightly
          different.
        * Complex images.
        * Images which use a wide range of colours.

Some graphics will b quite substantially compressed. Others
cannot be compressed and are simply identical in size to the
original graphic.


[2] Using WADPTR
================

[2-1] List of command line options
----------------------------------
WADPTR is a command line based utility. You give it commands
in the following order:

                WADPTR inputwad [outputwad] options

You must specify an input wad file, although WADPTR defaults
to "output.wad" for the compress and uncompress procedures
if you do not specify an output wad file.

The command line options are:

         -help                 Displays a list of command line
         -h                    options. Useful if you can't
                               be bothered to load up this file
                               again to find what they are.

         -list                 List the WAD directory of a file,
         -l                    along with the size of the lumps,
                               what compression they use, whether
                               they share lumps and various other
                               information.

         -compress             Compress a WAD file, creating a
         -c                    new wad file that is smaller than
                               the original.

         -uncompress           Uncompress a WAD file, creating a
         -u                    new WAD file that is the same size
                               (or very close) to the original.                                

         -nomerge              Option not to merge identical lumps.
         -nosquash             Option not to squash graphic lumps.
         -nopack               Option not to pack the sidedefs in levels. 

[2-2] Compressing a WAD
-----------------------
Compressing a WAD file in this version of WADPTR is easy. To
compress, for example, a WAD called sf.wad:

        WADPTR -c sf.wad

WADPTR will then read the WAD, and rebuild it, but smaller(if
possible). It will pack every level, squash every graphic,
and combine identical lumps. It will also remove unused data
from the WAD(data that exists in the WAD but does not form
part of any of the lumps in the WAD), and unused sidedefs
(sidedefs that exist but are not bound to any linedef).

[2-3] Uncompressing a WAD
-------------------------
WADPTR also has an uncompress option. This is mainly because
it can be difficult to edit levels with packed sidedefs. When
you change one linedef, all the others change at the same time.
Uncompressing is easy:

        WADPTR -u sf.wad

WADPTR rebuilds the WAD, unpacks every level and unsquashes
every graphic. In the new WAD, identical lumps are not
combined. The result is a WAD which is almost identical to the
original, uncompressed version. However, it may be slightly
different, as some changes WADPTR makes(removing unused
sidedefs and unused WAD data) cannot be undone.


[2-4] Listing a WAD
-------------------
The WADPTR -l (list) option allows you to find detailed
information about a WAD file. It lists every entry in the
WAD directory, and shows the following information:

        * Entry number : The position of that entry in the
                         directory.
        * Length       : The length of the lump that entry
                         points to
        * Offset       : The location in the file of that
                         lump.
        * Method       : The method which has been used to
                         compress that lump. These are:
                         squashed/unsquashed(for graphics),
                         packed/unpacked(for levels), and
                         stored(for any other lump).
        * Name         : The name of the entry.
        * Shared       : The name of another entry that this
                         entry shares its lump with.

[2-5] Using wildcards
---------------------
This latest version of WADPTR includes support for wildcards! This
means that, if you want to compress a large number of .WAD files,
you can do it easily without having to type in hundreds of command
lines. So, you can type in, for example:

        WADPTR *.wad -c (Compress every WAD in a directory)
        WADPTR deca*.wad -c (Compress every file with a .wad
                               extension beginning "deca".)

You can also use the '?' question mark wildcard sign, eg.

        WADPTR -c sf??b1.wad   (Every WAD beginning sf and ending b1).
        WADPTR -c abc?12?3.wad

Using wildcards, it is possible to compress every WAD in your doom2
directory quickly and easily (though it is not recommended you compress
your IWAD).

[3] Remaining Stuff
===================

[3-1] Version history
---------------------

v2.4    -     (2011-08-05) Fixes from Jan Engelhardt:
                - fix 64-bit compilation.
                - fix progress bar.
                - add .spec file for RPM build.
18/7/2001 -   Re-released under the GPL.
v2.3    -     Enhancements by Andreas Dehmel <dehmel@forwiss.tu-muenchen.de>.
              Removal of another limit, slightly better graphic squashing.
              More portable code: UNIX/RISCOS/Linux version. -o (output file)
              option.
v2.2    -     Removed limits on level sizes(more-or-less). Building of
              very large levels should now be possible. Also support for
              levels without the standard 'MAPxy'/'ExMy' format for use
              in SMMU wads. Added percent-done counter to level building
v2.1    -     Added wildcards, better file-offset in -l(list) option.
              Old wad files are not kept after compress/uncompressing.
              -nomerge, -nosquash, -nopack options. Warning before
              changing IWAD.
v2.0    -     Removed all old options, added new all-in-one
              -compress option. Added uncompressing and
              graphic squashing. New PKZIP style interface
              rather than DEUTEX interface. More detailed
              -list option. Code can now be easily
              incorporated into other programs if neccesary.

v1.4    -     Added '-pack' sidedef packing option and
              '-works' "do the works" option.
v1.3    -     Added '-rebuild' option. WAD compression is
              now completely automatic. '-list' option is
              now default if no option is chosen, but WAD
              is still specified. '-help' appears if no
              WAD is specified. Old 'DMWAD' code removed.
v1.2    -     Added '-suggest' option to make use of the
              '-tweak' option easier.
v1.1    -     Original release, only options are '-list',
              '-help' and '-tweak'.

[3-2] Bugs/Suggestions/Comments
-------------------------------

I can be e-mailed on the Internet at:
        fraggle@gmail.com
Also, check out my homepage at:
        http://www.soulsphere.org/
Updates and bug fixes of WADPTR will be placed here if
neccesary.

The Commented C source code is available free from my site.
It should be fairly easy to incorporate into other programs
if neccesary.

[3-3] Thanks to..
-----------------

* Andreas Dehmel <dehmel@forwiss.tu-muenchen.de> for cleaning
  up the code to make it more portable and creating a
  UNIX/RISCOS version
* Tom Robinson 'Mystican' deserves a mention, as WADPTR
  originally used code from his DMWAD program. Although
  99% of the original DMWAD code has now been removed and
  replaced, tiny bits of code still haunt my source files.
* Luke Cama 'Spike', who told me about SIDEDEF packing and
  lead me to incorporate it into WADPTR.
* Id for Doom
* Matt Fell, Doom Specs
* The error 'beep' sound is from DEU :)
