Notes for memcard.c
-------------------

AUTHOR - JAMES CHOW
DATE   - 2 JULY 1998
ALTERATION WITHOUT EXPRESS PERMISSION PROHIBITED
email: james@chowfam.demon.co.uk

The library contains 7 functions.

cardInfoInit, cardValidate, cardFormat,
cardRead, cardWrite,
cardSetBuffer, cardGetBuffer.

cardInfoInit need only be called once. For example, during
the initialisation routines of the game.

cardValidate should be called at least once, prior to
performing an operation on a memory card.

cardFormat to be called, when an uninitialised card is
detected.

cardRead to perform a Load.

cardWrite to perform a Save.

cardSetBuffer to be called prior to cardWrite to set the
data to be saved.

cardGetBuffer to be called after cardRead to obtain a
pointer to the data read.

-------------------------------------------------------------

void cardInfoInit(char fname[20],int slots,GsIMAGE icons,
                  int numicons,char textname[20]);

   fname :- filename, format BESLES-12345FILENAME,
            read web-pages for exact make up.
   slots :- slots used/required on memory card.
   icons :- icons shown on the Memory Card Management
            screen by the Operating System.
            Each icon size is 16 x 16, using 4 bit CLUT.
            If 2 or 3 icons, draw them in vertical line.
   numicons :- Number of icons. From 1 to 3.
   textname :- Name of file as shown by the Memory Card
               Management screen.

int cardValidate(int slot);

   slot :- slot number where memory card expected.
           0 for slot 1, 1 for slot 2.

   returns :-  VALIDATEnone   - no memory card detected
               VALIDATEok     - memory card OK
               VALIDATEnew    - new memory card detected
               VALIDATEerror  - error accessing memory card
               VALIDATEuninit - uninitialised memory card

   An uninitialised memory card (and maybe a new memory
   card, not sure - someone please correct me), needs
   formatting.

int cardFormat(void);

   returns :- FORMATok    - format successful
              FORMATerror - format error

   This function uses the slot number as provided by
   cardValidate().

int cardRead(void);

    returns :- 0 to 100    - percentage of read complete,
                             100 is complete.
               READerror   - a read error
               READfileabsent - file not found on memory card

    The function uses the filename given in cardInfoInit(),
    and the slot number by cardValidate().
    Need to repeatedly call this until 100 returned for
    successful loading.

int cardWrite(void);

    returns :- 0 to 100    - percentage of write complete,
                             100 is complete.
               WRITEerror  - a write error
               WRITEcardfull - memory card does not have enough
                               free slots to perform save.

    This function uses the number of slots given in
    cardInfoInit(), and the slot number by cardValidate().
    Need to repeatedly call this until 100 returned for
    successful saving.

void cardSetBuffer(unsigned char* buff);

    This function uses the number of slots given by
    cardInfoInit().
    It copies (8192*number of slots)-512 bytes from
    buff to an internal buffer (for saving).

unsigned char* cardGetBuffer(void);

    This function return a pointer to the internal
    buffer. The data from this pointer is valid
    for (8192*number of slots)-512 bytes.
    This should be called after loading.
    DO NOT write to this pointer.