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

Here is the latest version of Colour Emu. We have improved the emulator
itself, so that some (very nice !) programs run now that didn't run before,
e.g. Colour Kong, Meteor and Invaders. Enjoy !
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 2.1
***************************
- Harald Boegeholz games are working now (Colour Kong, Meteor etc.)!
- Quick load function (very useful !)
- Snapshot files
- Quick toggle between maximum and original speed (PgUp / PgDown keys)
- Nice Windows icons

New features of version 2.0
***************************
- Graphics mode
- Sound (using the SoundBlaster, enhanced noise generator, adjustable volume)
- New keyboard style for playing games (you can choose between the two styles)
- Better emulation of the CRTC (Chopper is working)
- Speed control
- Options menu (including keyboard help and register dump)
- Configuration file
- !IMPORTANT! New improved welcome tape, don't miss it!

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 2.1
COLORROM.DAT     The BASIC ROM of the Colour Genie (copyright April 1983)
WELCOME.CAS      A (virtual) welcome tape
README.TXT       This file
COLOREMU.ICO     Windows icon (coloured)
COLORBLK.ICO     Windows icon (black)

The emulator runs BASIC as well as machine code programs, even if they do take
advantage of special hardware. The speed is adjustable now, although it is
not yet perfect (we are working on this). Colour Emu works with
Windows 95 and even with Windows 3.1x (without sound), there should be no
problems with OS/2.
So enjoy playing with the emulator; try the test tape "WELCOME.CAS" which you
can find in your Colour Emu directory. (After starting the emulator, press
<ENTER> at the "MEM SIZE?" prompt, then <ESC> for the options menu and press
"L" to load the program. Enter the file name "welcome.cas" in the dialog box,
leave the options menu and enter "RUN"<ENTER>.
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
			  In automatic mode, a dialog box will appear if the
			  emulator detects tape access, which asks you to
			  enter a file name to use for the virtual tape.
			  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 tries to make the
			  emulator exactly as fast as the Colour Genie. This
			  mode is suggested for action games. Because this
			  mode does not work very well at the moment, you are
			  able to adjust this speed in the next option.
Control Speed           : When in original speed mode, you can adjust the
			  speed of the emulation. We found out that a lot of
			  programs are slower than they should be. A few were
			  a little faster. (We don't know why. If you have an
			  idea, please help us!)
			  Choosing a value of 100 % gives you a fair average
			  which should work with most of the programs. 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. The best way
			  to use this option is to reset the emulator, after
			  that pressing the <ENTER> key at the "MEM SIZE?"
			  prompt, and loading the program with the options
			  menu. Machine code programs are automatically 
			  started, BASIC programs have to be started using
			  the "RUN" command.
			  !Notice: Since the Colour BASIC commands are not
			  used in this function, the Colour Genie doesn't
			  "know" about the program being loaded. This may
			  cause some bad side effects. If you have problems
			  with the quick load function, please try to load
			  the program in the ordinary way using the BASIC
			  commands.
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.
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 :
********************
As another great new feature, 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. 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).

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 offer you a dialogue box for 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.
If you don't want to get bored, choose "Speed: maximum" in the options menu
while loading the tape.
In version 2.1, you can find a quick load function in the options menu. It
works in the way that a program is simply written into the memory without
using the Colour Genie tape commands. Machine code programs are automatically
started, BASIC programs have to be started via the "RUN" command.
Notice: the best way to load BASIC programs is to have a reset of the
emulator, quick load the desired program (after pressing <ENTER> at the "MEM
SIZE?" prompt) and immediately start it. Since the quick load function doesn't
use the normal BASIC commands, the system doesn't "know" about the program
being loaded. That's why (especially for BASIC programs) there could be some
problems with this function. It should work OK after a reset, still there is
no guarantee for it. 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 dialogue box. 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 dialogue box will pop up, and you can enter the file
name of the virtual tape.
Please notice that the dialogue box 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.

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 1996 ;-) )

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.
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 !
