F1RSCkpt; F1RS cockpit image extraction and replacement utility v1.2
--------------------------------------------------------------------

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

Synopsis
========

F1RS has a different cockpit for each team in the game. These
cockpits are stored as 640 by 161 pixel images in 16bit colour.
F1RSCkpt will extract these images as 24 bit images, for you to
mangle as you see fit in your favorite paint program.

You can now move around the positions of all the dashboard
instrumentation too. F1RSCkpt will create two files when you
extract a cockpit - a .bmp file containing the 24bit image, and
a .cp (short for CockPit) file which is just a text file that
contains the coordinate locations of each of the dashboard
instruments. You can edit this file to match your new cockpit
.bmp file, and when F1RSCkpt goes to replace the cockpit it will
refer to this file and install the new instrument locations.
See the section further on regarding more details about this.

I recommend that people who are distributing new cockpits should
include their matching .cp file, even cockpits that still have
the original dashboard instrument arrangement.

F1RS likes to use bright purple as its transparent colour, with
red = 255, green = 0, blue = 255. Use this colour for areas that
will be seen through.

IMPORTANT: Please make sure you have backed up the
  F1RS\F1datab\Voitures\cock.b (location of the cockpit images) and
  F1RS\F1datab\Scripts\forgrnd.rsb (contains the dashboard coords)
  before you go and mangle them with my program! Just in case, you
  can always just copy it back off the CD. As far as I am aware
  this program works, but I can't be held responsible if it goes
  and screws up the file or deletes your HD or tells your
  mother-in-law all your most embaressing secrets. I've tried to
  make sure it won't do anything unusual, but you never know!


Usage
=====

F1RSCkpt requires F1Crypt.dll version 1.2 by Martin Granberg. To
make sure F1RSCkpt is not finding earlier versions which aren't
entirely compatable, please make sure that the F1Crypt.dll in the
archive is in the same dir as you are running F1RSCkpt from. Thanks
Martin!!

To locate the F1RS dir:
-----------------------

  F1RSCkpt d f1rsdir

d:             Command that means "dir"

f1rsdir:       Location of the F1RS main directory.
    This is a required parameter.
    F1RSCkpt will then check to see if this dir is correct, and if
    it is, F1RSCkpt will create or update a file in the current
    directory called F1RSUtil.ini, where it will store this F1RS
    dir for future reference.
    You don't have to put a \ on the end of the directory path.
    F1RSCkpt shares this file with F1RSTex.


To extract cockpits:
--------------------
(parameters in [square brackets] are optional)

  F1RSCkpt e [f1rsdir] number/all [filename]

e:             Command that means "extract"

f1rsdir:       Location of the F1RS main directory.
    This is an optional argument.
    This is the directory where you installed F1RS. If you have
    previously configured the F1RSUtil.ini with the F1RS dir
    already (with the "d" command), then this parameter can be
    left out since F1RSCkpt already knows where to find F1RS.
    If the F1RS dir is not specified either on the command line
    or in F1RSUtil.ini, then F1RSCkpt will try to find cock.b
    in the current directory.

number/all:    Cockpit number to extract (0-10 or "all")
    This is a required argument.
    This tells F1RSCkpt which ccokpit to extract.
    Numbers 0 to 10 correspond to which cockpit you want to
    extract. See the table at the bottom of this document to see
    which numbers correspond to which Teams.
    If you use the word "all" instead, F1RSCkpt will dump out all
    11 cockpits in one go.
    If no [filename] is specified, F1RSCkpt will by default output
    the cockpits as files called "cockXX.bmp" and "cockXX.cp" where
    the XX is the cockpit number, such as "cock00.bmp" & "cock00.cp",
    "cock04.bmp" & "cock04.cp", "cock10.bmp" & "cock10.cp".

filename:      Filename to save output files as.
    This is an optional argument.
    This isn't really the whole filename. F1RSCkpt will
    automatically attach "XX.bmp" and "XX.cp" to the end of this
    filename parameter, so in effect this parameter is just the
    start of the final .bmp and .cp files' names. If you don't
    specify this parameter F1RSCkpt will use a default value of
   "cock", thus producing the "cock04.bmp" and "cock04.cp" type of
    filenames.
    If you specify, for example, a value of "frog" then F1RSCkpt
    will output files named "frog09.bmp" and "frog09.cp".
    If you put a ".bmp" on the end of the filename parameter,
    F1RSCkpt will strip that off before using it. ie: if you used
    "frog.bmp" as the filename parameter, then F1RSCkpt will remove
    the .bmp part and will end up with "frog" and the results will
    be just like my previous example.


To replace cockpits:
--------------------

  F1RSCkpt r [f1rsdir] number/all [filename]

r:             Command that means "replace"

f1rsdir:       Location of the F1RS main directory.
    This is an optional argument.
    This is the directory where you installed F1RS. If you have
    previously configured the F1RSUtil.ini with the F1RS dir
    already (with the "d" command), then this parameter can be
    left out since F1RSCkpt already knows where to find F1RS.
    If the F1RS dir is not specified either on the command line
    or in F1RSUtil.ini, then F1RSCkpt will try to find cock.b
    in the current directory.

number/all:    Cockpit number to extract (0-10 or "all")
    This is a required argument.
    This tells F1RSCkpt which cockpit image to replace.
    Numbers 0 to 10 correspond to which cockpit you want to
    replace. See the table at the bottom of this document to see
    which numbers correspond to which Teams.
    If you use the word "all" instead, F1RSCkpt will try to replace
    all 11 cockpits in one go. It will expect to find the files
    filename00.bmp and filename00.cp through to filename10.bmp and
    filename10.cp in the current dir, but it's OK if some are not
    there - F1RSCkpt will replace just the cockpits it can find,
    and leave any missing ones as they were. This is handy if you
    are just replacing a selected number of cockpits at once. You
    can install a cockpit .bmp without a matching .cp file, but
    the image had better match the instrument coordinates that were
    already in the game or the dashboard will not look so good.
    If no [filename] is specified, F1RSCkpt will by default try to
    load the images as files called "cockXX.bmp" and "cockXX.cp".

filename:      Filename of cockpit files to load
    This is an optional argument.
    This isn't really the whole filename, although it can be.
    If you are replacing just one single cockpit, F1RSCkpt will
    not attach "XX.bmp" and "XX.bmp" to the rest of the filename
    like it usually does - this is the one situation where it will
    only attach  to the filename ".bmp" and "cp". This allows you
    to load any filename at all into F1RS. So if for example you
    want used "F1RSCkpt r 4 mclaren" it would work fine loading the
    files "mclaren.bmp" and "mclaren.cp", it will not try to load
    files called "mclaren04.bmp" and "mclaren.cp".
    However if you don't specify this filename while replacing a
    single cockpit, F1RSCkpt will still look for "cockXX.bmp" and
    "cockXX.cp" by default, where XX is the number of the cockpit
    you are replacing.
    If you are replacing all images, F1RSCkpt will automatically
    attach "XX.bmp" and "XX.cp" to the end of this filename
    parameter.
    If you put a ".bmp" on the end of the filename parameter,
    F1RSCkpt will strip that off before using it.


Guide to the .CP file format
============================

When you open up a .cp file with your favourite text editor,
you will see many lines. Each line is formatted like this:

  key = x , y

where the key is the name of one of the dashboard components,
and the x,y values are its location. F1RS actually stores the
x,y values as full screen coordinates, offset from the top left
of the screen, but for ease of use I save the y coordinates to
the .cp file as offset from the top left of the cockpit image
itself, so the x,y values in this file match the x,y values of
your cockpit .bmp file.

The order of the lines does not matter. You can have spaces
in between the parts of a line, but not before the keyname, in
case you want to format the file all very nicely.

The way each component is located is not consistant. Some are
specified by the lower left corner of their screen area, some
are specified by the lower right corner, and the car damage picture
is specified by the top left corner, just to be different:)

Here's a table for each dashboard component. It gives the
reference point of each, bl = bottom-left, br = bottom-right,
tl = top-left. And a brief description of what it is.


  key      reference point   description

gear             bl        What gear the car is in.
idealgear        bl        Suggested gear for current corner.
speed            br        Speed. (Duh, did I need to say that?)
speedunit        bl        The little "KM/H" text.
revcounter       br        Current RPM.
revunit          bl        The "RPM" text.
revcoef          bl        The "x100" text.
fuel             br        Amount of fuel left.
fuelunit         bl        The "L" text.
revfuel          br        Fuel user per lap.
revfuelunit      bl        The "L/T" text.
radio            bl        For messages from the pit.
pitled           bl        To indicate that you are pitting.
revled1          bl        First RPM light.
revled2          bl        Second RPM light.
revled3          bl        Third RPM light.
revled4          bl        Fourth RPM light.
damage           tl        The car damage panel.


Warning: I implement no error checking whatsoever regarding the
x and y locations, so try not to do anything silly such as giving
negative coordinates or values that are off the screen!!!!! :)
Don't blame me if F1RS crashes or behaves similarly weirdly due
to this.


Reference: number to F1 team table
==================================

   number      team

      0        Ferrari
      1        Bennetton
      2        Williams
      3        McLaren
      4        Ligier
      5        Jordan
      6        Sauber
      7        Arrows
      8        Tyrrell
      9        Minardi
     10        Forti

*Note: You will notice that this list does not match the order of
teams in F1RSTex. This is because the order of car textures that
F1RSTex replaces are jumbled.


History
=======

V1.2     5/4/1998
  * Added the ability to rearrange the dashboard instruments'
    locations.

V1.1     31/3/1998
  * Fixed a totally pathetic little bug that would cause a screwup
    if you used a long path for the [filename] parameter, eg:
      F1RSCkpt r 1 q:\this\is\a\really\long\path\fiat_bambino.bmp

V1.0     29/3/1998
    First release.


Credits
=======

Many thanks to Martin Granberg for both his amazing little
F1Crypt.dll, without which none of us would be able to poke
around in the internals of F1RS with such freedom, and for
his "By the way, I just happen to know where the cockpit
instrument coordinates are" comment!


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

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