F1RSPal, F1RS palette creation utility v1.0
-------------------------------------------

This program is Freeware. Use at your own risk. I do not accept any
responsibility for anything that happens to your system.

Synopsis
========

F1RS implements each car's texture image as a 256 by 256 pixel
image containing all the parts of the car's surface stored as a 256
colour image, 8 bits per pixel. Thus each car can have it's own
palette of 256 colours.

The each car also shares another texture image of the same format
which contains parts of the car that are the same for all cars: the
wheels, engine parts, etc. However for each car this image uses the
car's palette. For this shared image to produce the correct colours
when displayed for each car, it uses only the top 63 colours of the
256 colour palette, and these 63 colours are expected to be the
same 63 colours in all 11 cars' palettes. Also, colour 193 is the
transparent colour, a pixel which is coloured with this transparent
colour will not be rendered. This is how F1RS draws a nice round
tyre from the side view - it just draws a big square where the
square around the round shape of the tyre is coloured with colour
193 and that does not get drawn.

Thus only the lower 193 colours are  available for free selection
for each car's own texture colouring.

Of course this is a fairly painful restriction on the palette if
you are trying to paint a car. Personally, I hate trying to paint
cars in 256 colour mode, I prefer just jumping up to 24 bit mode
and taking to the car with wild abandon and ending up with all
sorts of wild colours and shading via that lovely little spray
can:) Trying to do that in 256 colour mode never quite seems to
work. But trying to get all the different paint programs I have to
convert my resulting image back down to 256 colours while
conforming to the strict palette guide that F1RS imposes just never
works, the idiot programs just aren't designed to cope with bizarre
requests like this. Solution: write my own utility to do this:)

Now I just spray up a car in 24 bit mode, save the image as a 24
bit BMP file, and run it through F1RSPal. This scans the input
image and extracts a close to optimal palette of 193 colours. Then
it attaches the fixed 63 colours to the palette, and does a
closest-colour conversion from 24 bit to 256 colours using the
resulting palette. F1RSPal also keeps track of the transparent
colour for you, making sure it gets put into colour 193. The
resulting image is saved as a 256 colour BMP file complete with
palette, which is now in the right format to be installed into
F1RS.

Painting a car is now a MUCH more fun, since the hassle of not
being able to get my image into the right palette is removed
entirely.


Usage
=====

  f1rspal in.bmp out.bmp [r,g,b] [depthlimit]

in.bmp:        Input image
    This is a required argument. Please make sure it's a 256 by 256
    pixel 24 bit BMP file! My program does zero checking for this,
    and just assumes the file is fine :)

out.bmp:       Output image
    This is a required argument. It will be a 256 by 256 pixel 8
    bit BMP with palette.

r,g,b:         Transparent colour (0-255,0-255,0-255)
    This is optional. The program defaults to using bright purple
    (rgb of 255,0,255) as the transparent colour, as this is the
    usual colour in the F1RS default palettes. However, if you are
    painting a purple car (eeewwwww) you will want to use a
    different colour for the transparent parts of your image. Pick
    a bright colour that is not used in your image, and fill all
    the purple bits to the new colour, then specify the red, green
    and blue components for this parameter.
    Note: only this EXACT colour is converted to the transparent
    colour of 193 during the 24 bit to 8 bit conversion.

depthlimit:    Depth limit of the RGB colourspace tree (4-8)
    This is optional. Default is 6. Sounds technical? Yep! But to
    put it simply this specifies the colour resolution to use when
    scanning in the 24 bit image. A value of 8 gives 2^8 or 256
    possible values of red, green and blue, at the cost of using
    a LOT of ram in the subsequent data structure if your picture
    uses many thousands of colours. The default depth of 6 gives
    64 shades of red, green and blue so a maximum number of colours
    of 260 thousand colours which is easily enough colour
    resolution so that our eyes will not notice anything once in
    the game where the 3DFX card only displays at 16 bit colour
    anyway (depth of 5 for red and blue, depth of 6 for green,
    giving 65536 colours). And doesn't use TOO much ram, I've seen
    it use 2.5mb to hold 20,000 colours. If you run out of ram at
    this setting you might want to try shallower depths, of 5 or 4
    however (giving 32 and 16 levels of RGB, with 30 thousand and
    4 thousand possible colours, respectively), but I personally
    object to using that coarse a resolution:)
    There is no real need to use a setting over 6.
    Note: in certain circumstances I have seen a depth limit of 4
    give a better spread of chosen colours than depth limits of
    higher values.


History
=======

V1.0     18/1/1998
    First release.


Contact details
===============

Author: Grant Reeve
Email:  magefire@ihug.co.nz
