
                      * * * * * * * * * * * * * * *
                      *                           *
                      *      S P E C T E M U      *
                      *                           *
                      *        Version 0.8        *
                      *                           *
                      * * * * * * * * * * * * * * *


This package contains a 48k ZX-Spectrum emulator for Linux, with full Z80
instruction set, comprehensive screen, sound and tape emulation, and
snapshot file saving and loading. It can run on a Linux console, or in an
X11 window. 

The program is copyrighted under the GNU General Public License.

Written by Szeredi Miklos
Email: mszeredi@eik.bme.hu

It can be downloaded by FTP from:
sunsite.unc.edu:/pub/Linux/system/Emulators/spectemu-0.8.tar.gz


Table of contents
=================

  1.   Requirements

  2.   Recommended

  3.   Features

  4.   Drawbacks

  5.   Compiling and installation

  6.   Using the emulator

  6.1    Using the Spectrum keyboard

  6.2    Keys that control the emulator

  6.3    Effects of changing frame frequency and sound buffer size

  7.   Where can I get ZX Spectrum games for this emulator

  8.   Tape files

  8.1    Loading a tape file

  8.2    Making a tape file from a real tape

  9.   Bug reports

  10.  Credits


1. Requirements
===============

At least i386 PC with Linux.
Color X11 server (depths 8, 16 and 32 bits are supported) 
        and/or 
SVGALIB console graphics library.

2. Recommended
==============

A sound-card for wonderful spectrum 1-bit sound.
And well, a fast enough processor... (Especially for the X11 version.)

3. Features
===========

 - X support (with MITSHM if available, optionally double size window)

 - Linux console graphics (with SVGALIB)

 - Sound support (through kernel sound-card driver)

 - Snapshot saving and loading ('.z80' format)

 - Tape emulation: loading from tape files

4. Drawbacks
============

 - Only i368 unixes (emulator code is in assembly) 

 - Only tested on Linux 1.2.x / Linux 2.0.x

 - X interface is slow (especially if it cannot use MITSHM)

 - Poor user interface

See the file TODO for a list of things which still need to be done (Maybe
by YOU)

5. Compiling and installation
=============================

To install the precompiled executables just run 'make install' as root.

If you want to recompile the programs, run 'make depend; make clean', and
then 'make'.

At the moment, there are two executable programs for running the emulator:

  xspect             the X11 version
  vgaspect           the Linux console version


'vgaspect' uses the SVGALIB library. If you do not have this installed on
your system 'vgaspect' cannot be started. It is recommended, that you get
SVGALIB version 1.2.10 or later . If you have a version earlier than 1.2.10
then uncomment the appropriate line in Makefile before remaking 'vgaspect'.

SVGALIB is available at:
sunsite.unc.edu:/pub/Linux/libs/graphics/

Even in SVGALIB 1.2.10 there is a minor bug in the raw keyboard handling;
this can be corrected with the patch found in
'patch/svgakey-1.2.10.patch'. No need to recompile the emulator, if you're
only replacing SVGALIB.

If in X you want a better performance at the cost of a smaller window, then
uncomment the appropriate line in the Makefile.

6. Using the emulator
=====================

After starting 'xspect' or 'vgaspect' you should get the '(C) 1982 Sinclair
Research Ltd' message, and after pressing a key, the flashing cursor. If
not, then all I can say, is hard luck to you (if you are ambitious, compile
the programs with debug information, and try to figure out what is causing
the problem). Do not start the emulator processes in the background, the
terminal is needed when loading or saving files. 

6.1 Using the Spectrum keyboard
-------------------------------

Those of you that have at some time used a Spectrum know, that the keyboard
of this little computer is something very strange, with a LOT of keywords
and symbols on and around each key. If you have not seen this keyboard (or
have somehow managed to forget some bit of information that is on it) we
produced quite a good copy of it, found in the 'spectkey.gif' file.

The mapping of the spectrum's keyboard to the PC's is the following:

The numbers, the letters, Enter and Space are the same. The left Shift on
the PC corresponds to the CAPS SHIFT key of the Spectrum, and the right
Shift corresponds to the SYMBOL SHIFT. This is quite simple and with these
keys you can get all the functionality of the original Spectrum (assuming
of course, you know how).

But...

To make life a bit easier, you can also use the Backspace, the arrow keys,
and the following symbols as on a PC keyboard: ,./;'-=<>?:"_+

To get a symbol which is written above the numbers on the PC, and not the
function or symbol that is on the Spectrum, press Alt instead of Shift.

6.2 Keys that control the emulator
----------------------------------

All control keys are produced by pressing the Ctrl key and another key.

 Ctrl-c         Quit the emulator immediately

 Ctrl-l         Load a snapshot file, you must type the path and 
                filename on the terminal where you started the emulator,
                eg. 'snap/chuckie2.z80'

 Ctrl-t         Save the current state of the emulator in a snapshot file

 Ctrl-q         Reset the Spectrum

 Ctrl-f         Fast mode

 Ctrl-n         Normal speed mode

 Ctrl-m         Toggle sound on/off

 Ctrl-h         Print help

 Ctrl-p         Play tape. Tape file, starting line and number of lines to
                play must be entered on the terminal; eg.: 'tape/tape1 0 4'

 Ctrl-s         Stop tape prematurely

 Ctrl-equals    Skip more screen frames

 Ctrl-minus     Skip less screen frames

 Ctrl-]         Increase sound buffer size 

 Ctrl-[         Decrease sound buffer size


6.3 Effects of changing frame frequency and sound buffer size
-------------------------------------------------------------

ONLY READ THIS IF YOU ARE NOT TOTALLY SATISFIED WITH THE EMULATOR'S
PERFORMANCE

This should be totally automatic, so I'm now programming you to do what
the emulator should. (Luckily you are much easier to program) 

Frame skipping determines, after how many frames the emulator displays one
on the screen. There are 50 frames in one second, and normally every other
frame is displayed (25 per second). If the emulator is too slow under X,
increasing frame skipping can have a good effect on performance, but at the
cost of poorer quality. But the interesting thing is, that increasing frame
skipping may cause a worsening of both performance and of picture quality
(I will not explain it here why).

Decreasing frame skipping has the opposite effect of the above.

If the emulator uses sound, but sound is not continuous, then experiment
with increasing sound buffer size, and increasing frame skipping. If you
are lucky you can make things a bit better. Increasing sound buffer size
has also the negative effect of delaying more the sound effects.

7. Where can I get ZX Spectrum games for this emulator
======================================================

Check out the WWW site: http://zx-museum.org.ru/

The fact is, that there were a lot of Spectrum games around on audio tapes,
and some of them are really good. There were always cracked and copyable
versions around, and nobody was interested in copyrights. Unfortunately the
big FTP archives do not allow non free software on their servers, so I
can't include any games in this distribution.

(Because Spectrums have died out, and perhaps some of the software
companies do not exist any more, probably some games could be distributed
freely. But I will not check on those things.)

I've included a program named 'spconv', written by Henk de Groot
(hegr@ensae.ericsson.se) which can convert between snapshot file formats.

Alternatively if you have some old spectrum tapes laying around, and you
are very brave, you can check out the following section.

8. Tape files
=============

DO NOT READ THIS IF YOU DON'T WANT TO BOTHER WITH TAPES AND TAPE FILES!

Tape files have the extension '.spt'. For example here is a tape file
'tape1.spt':

000 FF    14 OK 
001 00    17 OK   FLIGHT        68 00
002 FF    68 OK 
003 00    17 OK   d           6912 03
004 FF  6912 OK 
005 00    17 OK   c          27650 03
006 FF 27650 OK 
007 00    17 OK   C NAMEMAT     82 00
008 FF    82 OK 
009 00    17 OK   CNAME MAT  49076 03
010 FF 49076 OK 
011 00    17 OK   sir fred    1110 00
012 FF  1110 OK 
013 FF  5008 OK 
014 00    17 ERR          <A0>h   256 0C

The columns have the following meaning:

1) The serial number, and the extension of the corresponding data file
(eg. the header of the FLIGHT program is found in the file 'tape1.001')

2) The segment type in hexadecimal (00 - header, FF - data)

3) The size of the segment (and of the corresponding data file)

4) This is either 'OK' or 'ERR' depending on the success of the
digitization

The rest of the fields are only present if the segment is a header

5) The name of the file

6) The size of the file (should be the same as the next segment's size)

7) Type of file (00 - BASIC, 03 - CODE)


You can also insert a line like 'PAU 05' into this file, to make a 5 second
pause in the playing.

8.1 Loading a tape file
-----------------------

For example if you want to load the CODE NAME MAT program from this tape
file you must do the following:

In the Spectrum enter the command:
LOAD "" 

(It can be done by pressing 'j' then two double quotes, or alternatively by
pressing 'j' and then while holding down the right Shift pressing 'p' two
times. After this press Enter.)

Now the Spectrum is waiting for you to start the tape:

Press Ctrl-p

On the terminal enter:
tape1 7 4

And if you are lucky the Spectrum will now load CODE NAME MAT.

Pressing Ctrl-f can speed things up, but at the end you should press
Ctrl-n.

8.2 Making a tape file from a real tape
---------------------------------------

WARNING, ONLY TRY THIS IF YOU REALLY-REALLY WANT TO!

Well it's not so bad as that, I've digitized a lot Spectrum tapes with
ease, but I have the advantage of having played with tapes a lot on the
real Spectrum, and of being able to modify the code which does the
digitization.

First of all you must have a sound-card to do this. If you've got it, then
you have a small chance of succeeding.

First get the cassette player which you used to play Spectrum tapes. Then
plug it in your sound-card's 'line-in' or 'mic' inputs. Then somehow set the
sound driver so that it reads things form the input in which you plugged
your cassette (I use 'xmmix' the 'Motif Audio Mixer' to do this). And if
you've managed to get this far, go to the directory where you want to store
the tape files (remember, there will be a lot of little files: one for each
little segment!), and enter the following command:

  recs - 32000 | filt | spload tapefile

               or     

  recs - 32000 | spload tapefile

(The first type worked better for me)

Where 'recs', 'filt' and 'spload' are programs found in the utils
directory, and 'tapefile' is the name of the tape file without the '.spt'
extension.

(The contents of the utils directory can be remade by changing to that
directory and entering the command:  'make realclean; make')

Now you can put your favorite Spectrum cassette in the cassette player, and
press the Play button.

'spload' will write a lot of information on the terminal, of which you
might try to make some sense. Also you can do a 'tail -f tapefile.spt' in
another terminal, to see what is happening. Again if nothing happens, then
you are on your own (and most probably at first nothing will happen).

And remember that this digitizer is not better than the real Spectrum, so
if you cannot load a program with a Spectrum, you'll most probably will not
be able to load it with 'spload'.

Good Luck!

9. Bug reports
==============

Please send bug reports to:

mszeredi@eik.bme.hu

If you make any changes to the source, please mail me the 'diff -c' of the
file(s) changed, and also why were the changes needed.

Please also tell me if you would like to maintain, or to continue
developing spectemu.

10. Credits
===========

Szeredi Tamas, for testing the emulator, and for helping with the
'spectkey.gif'.

G.A. Lunter for a very good description of the Spectrum, the undocumented
features of Z80, and the '.z80' snapshot file format.
