	            extractor for pak-archive and media converter
	            ===============================================	
	                                (c) by Joachim Schiele 2001

License for using this tool:
============================
	                                
  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  
  Copyright (C) 2001   Joachim Schiele <js@dune2.de>

HOW TO USE THIS TOOL(S):
========================
 ... read on

in short:
 - copy all *.pak files to sandtools/data/pak
 - start the check script by ./check
 - next start ./shp or ./cps or ./wsa
 - you find the png's in sandtools/data/out

have fun


1. What are the tools for?
==========================

This tools "sandtools" are able to extract files out of some old games.
You got several tools in the directory and they all have a special function,
here in detail:

tool	| meaning (in short words)
----------------------------------
unpack 	| to extract the pak files (a bit like a tar-archive)
cps2png | cps is a graphic compression for single graphics
shp2png | shp is a graphic compression for multiple graphics
wsa2png | wsa is a graphic compression for multiple graphics xor'ed to each

2. To extract something out of the *pak files:
==============================================

"unpack --unpack pakfile.pak" or
"unpack --unpack data/out/*" would extract all pakfiles
-> the program will create a new dir in the same dir the *pak files are,
so /home/linus/file.pak will be extracted to /home/linus/file/

3. To convert cps/wsa/shp/... files to pngs:
============================================

cps2png -i seed.cps -o ./ 	(saves file.cps after convertion to same dir) 
wsa2png -i seed.wsa -o /home/ 	(saves to /home/)
shp2png -i seed.shp -o / 	(saves to /)

-> because shp-files usually do not only store one single graphic it's saved as
shp2png -i seed.shp -o /home/linus/
seed_0.png seed_1.png, seed_2.png, seed_3.png, ... (as many graphics as inside)

4. debugging
===========

If you want to debug something you have to set the "#debug -g" variable in the
Makefile to "debug -g" not "#debug -g" and you can use gdb for further
experiments. Also inside some single .c files you can set the DEBUG flag with
"#define DEBUG"

5. specifications about all this files?
=======================================


Specifications about wsa, shp, cps, pak and some other
formats are in ccfiles4.txt supplied with sandtools.
Notice: The specifications for dune2 differ from the ones for c&c

License:
===============================


This code is meant to be absolutely free and i don't mind anyone taking it 
for his projects or games without even giving me a note. It would be nice
to hear if someone is using it or takes some benefit of it ;-)
It took me hours to write this all down and to hack all the stuff.


6. what image types does dune2 contain?
=======================================


All 26 shp files contain 465 images
    type 0: 270  (all decode correct)
    type 1: 113  (all decode correct)
    type 2: 71   (all decode correct)
    type 3: 8    (none decode correct, seems to be an offset problem)

All 75 wsa files contain 859 images
 - Those files don't decode correct:
   * mentat/harktank.wsa 
   * intro/intro10.wsa 
   * dune/lostvehc.wsa 
   * mentat/repair.wsa 
   * mentat/trike.wsa  
   * dune/win2.wsa
   The problem is that the files contain only diffs
   but not the initial image where the diffs should
   be applied to. Diffs are xor'ed over the initial 
   image.

All 15 cps files contain 15 images 
 - correct cps images decode rate is 100%
 - however one or more image(s) use the wrong palette


7. little notice about this code
=======================================


I've written this code for educational purpose. It last
very long to finish this project but a few weeks ago
I felt unhappy about the status of this project. So I
decided to finish it.

Many thanks to all ppl who helped me.
Not to forget the dunelegacy ppl!

Code cleaned up in 2.1 release by Per Øyvind Karlsen/Dvalin :)

8. TODO
==========


cps:
- mentatm.png palette problem
- maybe others might have some small impact
  on color changes when changing palettes, too! 

wsa:
- westwood.wsa palette problem
Other wsa problems:
- those file don't decode correct because the
  need to load a main picture from another file
  and i don't want to implement that 
  * data/pak/intro/intro7b.wsa
  * data/pak/intro/intro8b.wsa
  * data/pak/intro/intro8c.wsa
  * data/pak/finale/hfinalc.wsa
  * data/pak/finale/ofinalb.wsa
  * data/pak/finale/ofinalc.wsa
a solution would be to add some code for loading 
pictures from intro7a.wsa and then xore the diffs
from intro7b.wsa over it. I'm not sure how this
works exactly but i managed to decode some by
hand .... however this is ugly



==============
so:
happy hacking

qknight
