C&C95 Stretching Table Generator - created by Nyerguds
--------------------------------

Purpose:
~~~~~~~

This tool creates the tables used by C&C95 to generate in-between pixels
when stretching WSA animations. The files depend entirely on the colour
palette, and are simply a byte list of the best in-between colour indexes
to use for any two possible colours on the palette. This means it contains
all 256*256 possibilities, making it a 65536 byte file.

The tool was made to compensate the fact the WSA converter in Ultraq's
Red horizon utilities generates a basic stretching table that does nothing
but duplicating colours. This tool actually looks for the nearest match on
the colour palette, resulting in far smoother stretching.

NOTE THAT THIS TOOL IS ONLY USEFUL IF THE COLOUR PALETTE OF THE INPUT FILE HAS
BEEN MODIFIED FROM THE ORIGINAL. If you edit an existing WSA without changing
its colour palette, the stretching table doesn't need to be replaced.


Functions:
~~~~~~~~~

1. File types:

This tool was originally made for generating stretching tables for WSA files
of which the colour palette was modified. However, since some scenes in the
game are taken from a WSA file but shown with colours taken from an external
colour palette file, and the game uses different stretching tables for these
scenes, the tool also supports reading bare C&C colour palettes.
CPS support has been built in too, though there is only one CPS image in the
game (satsel.cps) that has a stretching table.


2. Automatic name linking:

The tool has an internal list of the filenames linked together inside the game,
and will suggest the correct stretching table filename for any C&C95 WSA, PAL
or CPS that uses a stretching table. Section 6 of the Additional Notes has the
complete list of these filenames.


3. Ignoring specific colour indexes:

You can tell the program to ignore fades to certain colour indexes.
This will make the generation code ignore ALL fades from and to these colours,
and simply fill them with the background colour (palette colour #0).

This system is rather rudimentary. You can only give palette indexes there,
not any preferred fade-to colour (it's always black), and there's also no way
to override the fade colour for specific colour index pairs. Still, for most
basic conversions, this should definitely suffice.

4. Saving colour palettes:

You can view any file's colour palette, and save it as C&C's colour palette
format.


Additional Notes:
~~~~~~~~~~~~~~~~

1. .pal and .pal

Both the stretching tables and the C&C colour palettes use a .pal extension.
This can be rather confusing. For that reason, the program and this file NEVER
refer to a stretching table as "palette". It ISN'T a palette, anyway.

There's a simple way to distinguish between the two file types: colour palette
files are always 768 bytes, while stretching tables are always 65536 bytes.
The program checks this, and will give an error if you try opening a stretching
table in the "Load colour palette" function.


2. Missing stretching tables:

Before C&C95 v1.06c revision 2 (which fixes this issue), there were some
stretching tables missing in the game.

The Nod missions progress overview (africa.wsa) and the dark screen of the
final Nod mission (dark_sa.pal on hbosnia.wsa) used the same stretching table
as their GDI counterparts, despite having different colour palettes.

For the missions, the two palettes are close enough to make this irrelevant,
but on the final dark scene of South Africa, the errors were quite visible.

This issue has been fixed in the newest patch though, so this should no longer
be a problem. See item #5 in these notes for the new filenames.


3. The Ion Cannon targeting scene:

The ion cannon attack choice scene at the end of the Nod campaign, satsel.cps,
has an internal palette, and yet an external colour palette file, satsel.pal,
exists in the game files. I don't know if this palette is used in any way.
The palette file is identical to the internal palette in the CPS. If you would
replace this CPS, I would advice testing out if the colour palette file needs
to be replaced too.


4. Multiplayer score screen:

The multiplayer score screens for all languages use the same stretching table,
since they all have the same colour palette.
If you are using the WSA converter for making a multiplayer score screen for a
language pack, you should not change the WSA's colour palette at all, so the
original stretching table can still be used for all languages.


5. List of all C&C files which use stretching tables:

These filenames will automatically be detected by the program, and the
correct name will be suggested when saving the stretching table.

 Paletted file | stretching table
---------------+------------------
 e-bwtocl.wsa  | map_locl.pal
 europe.wsa    | map_prog.pal
 africa.wsa    | map_prob.pal (since 1.06c revision 2; was map_prog before)
 greyerth.wsa  | map1.pal
 hbosnia.wsa   | lastscng.pal
 hsafrica.wsa  | lastscnb.pal
 hearth_e.wsa  | map_gry2.pal \_ These two have the same colour palette
 hearth_a.wsa  | map_gry2.pal /
 s-gdiin2.wsa  | scorpal1.pal
 scrscn1.wsa   | snodpal1.pal
 struggle.wsa  | sides.pal
 mltiplyr.wsa  | multscor.pal (note: no longer used in C&C95 v1.06)
 mltsceng.wsa  | multscor.pal
 mltscfre.wsa  | multscor.pal
 mltscger.wsa  | multscor.pal
 dark_e.pal    | map_loc2.pal (there is no dark_a palette for Africa)
 dark_b.pal    | map_loc3.pal
 dark_sa.pal   | map_loc4.pal (since 1.06c revision 2; was map_loc3 before)
 satsel.cps    | satselin.pal
 satsel.pal    | satselin.pal (see note on Ion Cannon targeting scene)


Thanks To:
~~~~~~~~~

-Ultraq, for actually making a working WSA converter

-Vladan Bato and his C&C file formats description document, which helped me
 to correctly extract the palette from the WSA and CPS files



That's all, folks. I know this tool is pretty much a niche product,
but I do hope it can prove useful to someone for modding purposes.

-Nyerguds