                           Colour Emu 3.0                            30.5.97
*****************************************************************************
by Burkhard Lehner (b_lehner@informatik.uni-kl.de)
and Stephan Scholz (sscholz@student.uni-kl.de)
Colour Emu Homepage http://www.student.uni-kl.de/~sscholz/ColourGenie.html

Welcome to Colour Emu 3.0 ! For those of you having Helikopter among your
favourite games, this game is in the right speed now ! We integrated a new
speed control in the emulator and, as the doctor says in The Day of the
Tentacle: "It works ! I can't believe it !" :-)
All the software we tested works at the right speed now, with the exception
of Colour Kong which played some sounds too fast (we don't know where this
comes from, but it's no problem at the moment, for the game itself is at
the right speed).
A brand new feature is a direct load of virtual tapes and snapshot files.
This way, you can start the emulator in the way "COLOREMU KONG32", and it will
automatically load Colour Kong ! If you use Colour Emu with Windows (as Stephan
does :-) ), you can link the CAS and SNP extension to Colour Emu and start a
game by simply double clicking on its icon !
Moreover the virtual tape and snapshot files have been improved, so you can use
comments in them. You can browse in your tape directory and immediately get a
description of the file. We did this for all the software we got by now, and
you can download the latest version from the web site (don't miss the second
software package, by the way !). To put your own comments to the file, use the
COMMENT tool from the tool package which you can also find on the web site.
If you have any corrections to the comments we used in the CAS files, please
tell us and send us the correct version !

The menus of Colour Emu have been improved; the comments in the tape and
snapshot files are displayed along with characteristics of the files which
are analysed automatically (Load name, length, date).
The locations of your favourite tape and snapshot file directories
are stored in the configuration file, which gives you convenience and
flexibility. We suggest, however, that you use a directory called "TAPE" for
the virtual tapes, and one called "SNAP" for the snapshots.

The Colour Emu is freeware, so you can pass it on to other Colour Genie fans,
if you make sure that you give away the whole package consisting of the files
mentioned further down.

New features of version 3.0
***************************
- The emulator really works at original speed now !
- Direct load of virtual tapes and snapshot files in the command line
- Comments are allowed in CAS- and SNP-Files now
- New and much improved options menu with comfortable Load and Save menus
- Improved configuration file; you can use comments in it, and tape and
  snapshot file directories are stored in the file.
- Reset function works much better now
- Of course: a new and improved welcome tape :-)

Known problems with Colour Emu
******************************
- After using the CSAVE command, the tape directory is changed.
- Sometimes a saved BASIC program is corrupted.
- Windows 95 causes keyboard problems with a few programs (e.g. Eis)
- Windows 3.1x causes wrong directory entries in the Load/Save menus, at least
  on Burkhard's drive D (wrong names are shown and the emulator crashes; this
  is definitely a Windows 3.1x bug ! Fortunately no damage is caused on the
  hard drive)
- A VOC file written by CASSSAVE cannot be loaded by CASSLOAD any more. But who
  would want such a thing anyway ? ;-)
If you have any other problems, please let us know !

The Colour Genie is a machine based on the Z80 CPU and was sold in the early
eighties. In Germany, the company TCS (Trommeschlaeger Computer GmbH) was
the official distributor, in other countries it was EACA (to our knowledge).
These companies don't seem to exist any more, for we wrote to TCS and got the
letter back. If a copyright on the BASIC ROM still exists, we assume that the
owner is pleased that people are still interested in this machine. If you
are the owner and don't want the ROM to be distributed, please let us know,
and we'll immediately remove it from this package.

With this package, the following files should be included:
COLOREMU.EXE     Colour Emu 3.0
COLORROM.DAT     The BASIC ROM of the Colour Genie (copyright TCS, April 1983)
WELCOME.CAS      A (virtual) welcome tape
README.TXT       This file
COLOREMU.ICO     A nice Windows icon (in colour !)
COLORBLK.ICO     A black and white Windows icon
QUICKBAS.SNP     Snapshot file for direct load of BASIC programs
QUICKSYS.SNP     Snapshot file for direct load of machine code programs.
                 Please leave these two files in your Colour Emu working
                 directory, for the quick load won't work without them.

The emulator runs BASIC as well as machine code programs, even if they do take
advantage of special hardware. The speed is adjustable, if you wan't to
cheat in some games :-).
Colour Emu works with Windows 95 and even with Windows 3.1x (without sound),
though we had some minor problems with directory access in Windows 3.1x and
sometimes keyboard problems with Windows 95. If you are using Colour Emu with
OS/2, please let us know about your experiences.
So enjoy playing with the emulator; try the test tape "WELCOME.CAS" which you
can find in your Colour Emu directory: Just enter
COLOREMU WELCOME <ENTER>
and sit back & relax...
Let us know if any problems occur with your hardware. If you have software,
technical information or anything interesting for the further development of
Colour Emu, we'll be glad to hear from you !

Keyboard :
**********
At the moment the Colour Emu is designed for German keyboard layout, it should
work with other countries' layouts as well. There are two different keyboard
styles, one takes advantage of the PC possibilities (character buffering, auto
repeat), the other one is very close to the original Colour Genie functionali-
ty (this is meant for playing games; the auto repeat would be bad for that).
For the text style keyboard, you don't have to use a "translation table" for
the keys. Rather when symbols which the Colour Genie used could be found on
the PC keyboard, we simply used the PC keys. However, there are some special
keys which will be explained now. The key next right to P is the @-Key of the
Colour Genie. In German keyboards this is the "ue"-key. You can also get the
@-Symbol by pressing AltGr-Q.
For the game style keyboard we tried to use the same layout as on the Colour
Genie. You can find a picture of this layout on the emulator homepage. Thanks
to Juergen Buchmueller for providing it ! If you use an American keyboard,
most of the keys should match, on a German keyboard there are a few 
differences: The Y and Z keys are swapped, and the special characters have 
different positions. In game style keyboard you don't have autorepeat. 
Instead, the TAB key represents the RPT (REPEAT) key of the Color Genie.
In order to see which style you are using at the moment, the Scroll Lock LED
indicates the use of game style.
You can switch between the two keyboard styles either by the options menu or
by pressing the key F5 while the emulator is running.

Other special keys:

F1...F4     Same as the F-keys on the Colour Genie. They contain frequently
            used commands (LIST, RUN, AUTO, EDIT), together with the SHIFT-key
            you get more commands (RENUM, SYSTEM, CLOAD, CSAVE).
F5          Toggle between the two keyboard styles.
F6          Same as the CLEAR key on the Colour Genie
F7          Same as the BREAK key on the Colour Genie
F8          Same as the RESET keys on the Colour Genie
PgUp        Set emulation to maximum speed
PgDown      Set emulation to original speed
Arrow keys  Same as the arrow keys on the Colour Genie
Backspace   Same as left arrow key on the Colour Genie
ALT,ALT Gr  Same as the MOD SEL key of the Colour Genie to toggle between text
            and graphical symbols.
CTRL        Same as the CTRL key on the Colour Genie

End         Quit the emulator (you won't need this :-) !)
ESC         Enter options menu

Options menu :
**************

Keyboard style          : Switch between game / text style (see "keyboard")
Display style           : Switch between original / advanced text appearance
                          We found out, that on the Colour Genie there was a
                          poor TV module resulting in bad quality: When a
                          pixel was set, the pixel next to it was also on.
                          Using the "original" option shows this behavior,
                          "advanced" is the only way to distinguish N, M
                          and H :-)
Tape emulation          : Switch between automatic / ignore cassette I/O
                          In automatic mode, a menu will appear if the
                          emulator detects tape access. You can choose the
                          right directory to store the file. By pressing SPACE,
                          you can enter the name of the file.
                          However there are some games that access the tape
                          port without the purpose to write or read a tape.
                          If you have this problem with a game, switch to
                          ignore mode after loading the game.
Speed                   : Switch between original / maximum speed
                          Switching to maximum speed makes the emulation as
                          fast as possible. This is suggested for loading
                          tapes and running text-based programs. By the way,
                          on slow machines ( < 486, 66 MHz) this can still be
                          slower than the original Colour Genie.
                          Switching to original speed makes the emulator
                          exactly as fast as the original Colour Genie. This
                          mode is suggested for action games. If a game is too
                          hard, so you want to cheat, you can use the speed
                          adjustment to slow down the emulation:
Control Speed           : Choosing a value of 100 % gives exactly the orginal
                          speed. Using lower values slows down the emulator,
                          higher values speed it up.
Music                   : Switches sound emulation on / off
Volume                  : Sets the volume of the sound emulation
                          A value of 0 is very quiet, 63 is maximum volume
Noise quality           : Switches between two different noise generators
                          The bad one uses the AdLib noise generator.
                          The good one was implemented by interrupts and
                          digital sound output of the SoundBlaster. It
                          produces much better noise, but slows down the
                          machine a little ( < 1 %). If this option is not
                          available, maybe the BLASTER environment variable
                          isn't set correctly.

Reset emulator          : Memory and registers are erased and the emulation
                          starts from the beginning
Load and Run Cass. File : Loads a virtual tape directly into the emulator
                          without using Colour BASIC functions.If you have
                          problems with the quick load function, please try to
                          load the program in the ordinary way using the BASIC
                          commands.
                          Note that the two files QUICKBAS.SNP and QUICKSYS.SNP
                          are necessary for the quick load function, for the
                          emulator is initialised with them.
                          The easiest way to automatically start programs,
                          however, is by using the command line option of the
                          Colour Emu:
                          COLOREMU <CAS-file>
Write Snapshot File     : Writes the whole machine state to a file. This 
                          consists of the memory, the CPU registers and the
                          registers of the sound and graphics chips. You may
                          want to use snapshot files for programs that have
                          trouble with the quick load function - just load
                          the program in the normal way using BASIC commands,
                          then write the snapshot file.
Use Snapshot File       : Sets the machine to the same state as it was when
                          the snapshot file was written.
                          The snapshot files can also be directly loaded into
                          the emulator using the command line:
                          COLOREMU <SNP-file>
Print register contents : Shows the values in the Z80, CRTC and PSG registers
                          This is for hardware freaks only :-)
Help on keyboard layout : Shows a short summary of important keys
Quit                    : Leave the emulator (You won't need this :-))
Return to Emulation     : Press ESC to leave options menu and continue
                          emulation

Configuration file :
********************
The changes within the options menu are saved automatically when leaving the
emulator. So if you start the emulator again, you will find exactly the same
environment as before. As a new feature in version 3.0, even the directories
of the tape and snapshot files are stored in the configuration file. This way
you can choose your own directories and don't have to think about them later.
Unfortunately there seems to be a problem with the CSAVE command. After using
it, the tape directory is changed by accident :-( We're working on that...
The options are saved in the file COLOREMU.CFG. If you encounter any problems,
just delete this file, and the emulator will start with the default values
(this is also what happens if you start it for the first time).
NOTE: Due to a more flexible format of the configuration file, you can still
use your old configuration file, so you don't have to worry about that.
The ordering in the configuration file doesn't matter any more, and you can
use comments in it (any line beginning with a "#" symbol will be ignored).
At the moment this configuration file is simply overwritten when quitting the
emulator, so your comments are lost...but we guess you won't use any comments
anyway....:-)

Virtual Tapes :
***************
The virtual tape system of the emulator works with both BASIC and
SYSTEM (machine code) programs. If you use the CSAVE/CLOAD/SYSTEM commands,
Colour Emu will automatically let you choose the filename of the
virtual tape you want to use. (You will have to choose "Tape emulation:
automatic" in the options menu.) You may want to use the ".CAS" extension in
order to not getting confused with the different files in your Colour Emu
directory. This is also the default file name extension.
If you don't want to get bored, choose "Speed: maximum" in the options menu
while loading the tape.
Since version 2.1, you can find a quick load function in the options menu.
In this version, a snapshot file is loaded first (QUICKBAS.SNP for BASIC
programs, QUICKSYS.SNP for machine code) in order to set a stable environment
for the program. If you have trouble with the quick load function, you
may want to use the ordinary BASIC commands for loading the program, and
write a snapshot file afterwards.

Now for the Colour BASIC commands:
Basically there were only two different kinds of programs - COLOUR BASIC
and SYSTEM (machine code) programs. The BASIC programs had no checksum of any
kind, the machine code ones had a CRC checksum for each block.

You can load a BASIC program by entering 
CLOAD <ENTER>
and chosing a virtual tape file with the menu. To start the program,
enter "RUN"<ENTER> at the prompt.

Machine code programs are loaded by entering
SYSTEM <ENTER>
At the "*? "-prompt, you enter the name of the program as it is stored in the
file itself. With most programs, we used this name for the file name of the
virtual tape, in order to not getting confused with the two names. As soon as
you press <ENTER>, the menu will pop up, and you can choose the desired file
name of the virtual tape.
Please notice that the menu will only appear in the "automatic
cassette I/O" mode. If you simply press <ENTER>, Colour Emu will switch to
"ignore cassette I/O" until you switch on the automatic mode again.

Snapshot files :
****************
A snapshot file contains the state of the emulation - if you want to "freeze"
the machine as it is at the moment, you just write a snapshot file using the
options menu, and you can load it again afterwards to continue at the same
point of the emulation. Snapshots are also useful for programs that don't
work with the quick load function. You can load the program in the ordinary
(slow) way, and write a snapshot file when it is in the memory.
You may want to use the ".SNP" extension for you snapshot files, so you won't
get confused with all the different files in you Colour Emu directory. This
is also the default extension.

Graphics :
**********
For the text mode, use the "COLOUR" command to switch between different
colours (0...15). In graphics mode, there are four colours, one of them is the
background colour. You can choose with the "FCOLOUR" command (1...4). With
"BGRD" you get magenta as the background colour, "NBGRD" sets black as the
background colour. Now you know where the name for the machine came from : 16
colours in text mode, 4 in graphics mode - amazing ! :-)

Sound :
*******
You need a SoundBlaster in order to be able to hear the sound. Colour Emu
reads the DOS environment variable BLASTER, so please make sure it is set.
You can choose between two different noise generators in the options menu,
which are of different quality. As it is always the case with DOS programs
running with Windows 3.1x, sound is not possible; instead a warning is given
to the user ("Sound device is used by another application"). There are no
such problems with Windows 95 (even in 1997 ;-) )

Transferring software :
***********************
If you have old Colour Genie tapes, you can load them directly into the PC
using an ordinary tape recorder, the SoundBlaster and the CASSLOAD tool. 
You may have to adjust the volume and/or tape recorder header, but good tapes
should be readable. You can get CASSLOAD from our WWW site along with another
useful tool called ANALYSE. It analyses CAS-files and checks if there are any
errors. Moreover, there is a program called CASSSAVE which converts CAS-Files
to VOC-Files which can be used for loading programs into the Colour Genie
(the original machine) - you can even save them on tape. As a new feature, you
can also send the signal directly to the Sound Blaster without having to use
the VOC file.
If you have any Colour Genie software, please send it to us, so we can improve
the emulator and put the software on the web site to make it available for
other Colour Genie fans. Thanks a lot !
