ew (Examine Wad) v1.02 by Tormod Tjaberg (tormod@sn.no)

Copyright (C) 1996 Tormod Tjaberg

ew is free software, distributed under the terms of the
GNU General Public License. ew comes with no warranty at
all. For details see the file COPYING.

ew
==

ew is a program which allows you to view images and export sound effects 
(wav), music (mus) and images (pcx) from Doom, Doom II, Heretic, Hexen or 
any other wad/pwad in the "Doom" format. ew is an interactive program and 
runs under DOS or UNIX (little endian machines only). Only the DOS version 
can display the images directly from the program. Full source and a DOS 
extender executable is included.

synopsis
========

Using ew is easy all you require is a "palette" file and a wad to examine. The
"palette" file is only required if you want to look at a wad which contains
images. It is not required if the wad only contains sound effects and/or
music files.

The palette file must be a 256 colour pcx file the image size does not matter.
All I need is the palette. A palette file must be used since not all wad's
contain palette entries and in some cases the palette entries have "holes" in
them. For example the "doom -devparm" parameter and F1 will generate a pcx 
file but it will not display all wad images correctly. I've included a set of 
palette files suitable for Doom, Doom2, Heretic and Hexen. If you want to 
make your own palette file I recommend the excellent PcxDump by Jesper 
Frandsen. It is available from most SimTel mirrors.

export
======
ew allows you to export the following wad entry types:

     Sound effects are exported as WAV files.
     Music entries are exported as MUS files.
     All image entries are exported as PCX files.

ew also allows you to listen to sound effects, music and to view images with
your favourite image viewer. This is accomplished by using an ini file. The ini
file specifies which program should be called for each export type. I.e. when
you're standing on a sound effect entry and hit Enter (and you have a WAV entry
in you ini file) ew will generate a WAV file and call the program which is
specified in the ini file. This makes ew very platform independent just specify
you platform's utility for playing a WAV file, MUS file or viewing a PCX file.

ini file
========

The ini file is called "ew.ini" and it is searched for using the following
rules. First ew looks in the current directory, then the execution directory,
along the PATH. If we're on a UNIX box ew just look's in HOME.

The ini file has the following layout:

; This is a comment
WAV command %s
MUS command %s
PCX command %s.

"command" is the program to call for each entry type and "%s" is where ew will
insert the filename when invoking the "command". The ini file may also include
comments. All lines which start with a ';' are regarded as comments. See the
example ini file for examples of usage.

using ew
========

Start ew by something like the following:

c:\src\ew>ew -p doom_g1.pcx \games\doom2\doom2.wad 

Graphics adapter found...
Ini file "./ew.ini" found
WAV : "plany %s"
MUS : "musplay %s"
PCX : "picem %s."
Palette file 'doom_g1.pcx' loaded successfully
Number of wad entries: 2919
Wad directory offset: 0xde4260
Building wad directory ........................................
MUS   entries: 35
SFX   entries: 103
FLAT  entries: 140
FULL  entries: 0
IMAGE entries: 2113
HIRES entries: 0

Use the cursor keys or keypad to navigate throught the wad.
Hit escape to quit, 'e' to export entry, enter to spawn external program.
Hit space to toggle graphics mode...

WALL40_1 (image)  268
...

The three colums are as follows:

1:   The name of the wad entry. This is used as a basis when exporting files.
2:   The type of entry:
          flat  : A wall texture 64*64 pixels
          full  : A 320*200 raw image
          hires : A 640*480 16 colour splash screen
          image : An image in in the Doom "post" format
          mus   : A music entry
          sfx   : A sound effect entry
3:   The index number of this entry in the wad file.

While positioned on an entry you may hit 'e' to export this entry. This will
create a file in the current directory with the appropriate extension. I.e. if
your're standing on the following entry and hit 'e':

WALL40_1 (image)  268

You will get a file called "WALL40_1.pcx" in your current directory.

Note:
By cursor keys I mean up, down, home, end, page up and page down, but you may
also use the following keys (the keypad or the normal ones):

1 - End
2 - Down
3 - Page Down
7 - Home
8 - Up
9 - Page Up

You may only view images directly in the DOS version. To view an image you must
hit space while positioned on an image entry. While in "viewing" mode you may
scroll up and down the available images using the cursor keys. You may also
export an image while viewing it ('e').

A note on images
================

ew does not assume anything at all about the wad file. It tries to determine 
the type of entry by analysis. Therefore certain wad entries might appear as
weird images. In the doom2.wad a REJECT entry has the same size as a flat. 
Naturally the image looks slightly garbled.

compiling ew
============

If you make any changes to ew or port it to a different platform.
I would be very grateful if you could email me the new source with 
a few comments. Maybe I'll include your changes into the next version... 

ew will automatically default to MS_DOS compilation.

ew has been tested with the following DOS compilers:

Zortech C/C++ (3.02 & 3.10), Symantec C/C++ (7.2), Borland C (3.0)

Here are the results of the different DOS compilers:

BCC      3.00   LARGE MODEL   Spawn works, Graphics mode Work
Zortech  3.10r2 LARGE MODEL   Spawn works, Graphics mode Work
Zortech  3.10r2 DOS EXTENDER  Spawn works, Graphics mode Work
Zortech  3.02   DOS EXTENDER  Spawn FAILS, Graphics mode Work
Symantec 7.22   DOS EXTENDER  Spawn works, Graphics mode Work

Note:
Under DOS you have to compile under the large model or use a DOS
Extender. The graphics code in ew.c is specifically tailored for 
use with the DOSX extender it does NOT work with other DOS Extenders
like Pharlap (You are more than welcome to port it to GCC or DOS4GW). 
Under the large model you are only allowed to view images that are less 
than 64K in size. 

I've compiled ew with the DOS Extender in Zortech C/C++ ver 3.10r2:
     ztc -mxi -3 ew.c

See the file unix.txt for UNIX compilation notes.

Credits
=======
. ID Software for creating DOOM
. Matt Fell for the undocumented DOOM specs
. Hans Peter Verne for the UNIX stuff
. Annette for being what she is...

