z81.1

.\" -*- nroff -*-
.\"
.\" z81/xz81, Linux console and X ZX81/ZX80 emulators.
.\" Copyright (C) 1994 Ian Collier. z81 changes (C) 1995-2004 Russell Marks.
.\"
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or (at
.\" your option) any later version.
.\" 
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
.\" General Public License for more details.
.\" 
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software
.\" Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
.\"
.\"
.\" z81.1 (and xz81.1) - man page
.\"
.TH z81 1 "1st October, 2004" "Version 2.1" "Emulators"
.\"
.\"------------------------------------------------------------------
.\"
.SH NAME
z81, xz81 \- ZX81 and ZX80 emulators for the Linux console and X
.\"
.\"------------------------------------------------------------------
.\"
.SH SYNOPSIS
.PD 0
.B z81/xz81
.RB [ -hilLosSTuV ]
.RB [ -a
.IR sound_addon_type ]
.RB [ -p
.IR printout.pbm ]
.RB [ -r
.IR refresh_rate ]
.RI [ filename.p ]
.P
.PD 1
.\"
.\"------------------------------------------------------------------
.\"
.SH DESCRIPTION
z81 is a Sinclair ZX81 (TS1000) and ZX80 emulator using svgalib. It
supports most programs and games, the ZX81's pseudo-high-res mode, the
ZX Printer, and both kinds of sound (`normal' and AY-based addons). It
saves and loads programs in Xtender's \`.P' format, but can load
\`.81' format files if they are suitably renamed.
.PP
xz81 is a version of z81 for X.
.PP
Both emulate a 16k ZX81 by default; to get a 1k ZX81, use the `-u'
option. To emulate a ZX80, use the `-o' option.
.PP
For the most faithful ZX81 emulation which z81 can manage, try
e.g. `z81 -sLSVr 1'. But since that's not very useful (you can't load
or save anything and the sound is very annoying), a more practical `best'
emulation is e.g. `z81 -Vr 1'.
.PP
If you want to transfer old ZX81 programs from tape, try
.IR zx81get (1).
.\"
.\"------------------------------------------------------------------
.\"
.SH OPTIONS
.TP
.B -a
enable AY-3-8910/8912-based sound addon support. There were a few
different AY-based sound addons released for the ZX81, so you also
have to specify the addon type with one of the following (only two
currently supported):
.RS
.TP
.I q
Quicksilva sound board (as used by their Asteroids, Invaders, and
Defender)
.TP
.I z
Bi-Pak's Zon X-81
.PP
You can also enable ACB stereo (channel A on left only, B on right
only, C on both `in the middle') by adding an
.I s
suffix, e.g. `-a qs'.
.RE
.TP
.B -h
gives help on command line options.
.TP
.B -i
invert the screen, giving a white-on-black display.
.TP
.B -l
boot directly into the LOAD "" file selector. (If you press Space to
abort in this case, it exits the emulator.) See the note below about
.I filename.p
for the limitations of auto-loading like this.
.TP
.B -L
disable LOAD hook. (Not terribly useful.)
.TP
.B -o
emulate an `old ROM' machine, i.e. a ZX80.
.TP
.B -p
enable ZX Printer support. The printout is written as a PBM format
picture to the specified file. (Most picture viewers/converters can
handle PBM files.)
.TP
.B -r
specifies how often the screen is redrawn, in 1/50th-sec `frames'. A
value of 1 would redraw every frame, 2 would redraw every other frame,
etc. The default value is 2 in both versions. The screen is updated
incrementally, so the default setting should be reasonable on just
about any machine, for most programs.
.TP
.B -s
enable VSYNC-based sound support. This is essentially a less-noisy
version of what you'd hear through the TV. You probably don't want to
enable this unless you have a specific need for it, as it makes an
annoying hum in SLOW mode.
.TP
.B -S
disable SAVE hook. Useful if you want to hear what SAVE does when
sound is enabled. :-) (Just don't expect it to be saved as a file!)
.TP
.B -T
toggle the leftmost bit of characters generated by the ULA (mainly for
debugging, but also useful for checking the display's `shape').
.TP
.B -u
emulate an unexpanded machine, e.g. a 1k ZX81. The default for both
machines is to have 16k of RAM.
.TP
.B -V
emulate VSYNC visuals - the black screen when busy in FAST mode, the
patterns you get when you LOAD or SAVE on the real machine, and the
little flicker you get when typing in a program line. (This tends to
be a bit annoying when typing in a program, which is why this is
disabled by default.)
.TP
.I filename.p
specifies a program to load. (Whether it auto-runs or not depends on
how it was saved - just like on the real ZX81, the save command has to
be run as part of the program for the resulting .P file to auto-run.
Most .P files you'll come across will auto-run, though.)
.PP
Note that the auto-loading feature is not supported when emulating a
ZX80, or a 1k ZX81. On those you have to do a LOAD command manually.
.\"
.\"------------------------------------------------------------------
.\"
.SH "KEYS AND KEY MAPPING"
.TP
.I Esc
reset the emulator.
.TP
.I F1
display a help screen showing the ZX81 (or ZX80) keyboard layout. Note
that you can still type while this help screen is displayed (the
emulated machine is still running), and to return to normal you must
use
.I F1
again.
.TP
.I F10
quit z81/xz81. You can also quit (when emulating a ZX81) with
`LOAD " STOP "', where `STOP' is the keyword given by shift-A rather
than `stop' typed out.
.PP
The alphanumeric and `.' keys are mapped as-is to the ZX81 (or ZX80)
keys, with other mapped keys being:
.TP
.I Space
emulated as break/space
.TP
.IR Shift " or " Ctrl
emulated as shift (Alt/Meta is similarly mapped on xz81)
.TP
.I Enter
emulated as newline
.PP
No other keys are mapped. If you can't remember how to get things like
INKEY$ on a ZX81 keyboard, you'd better check out the help screen. (If
you can't remember how to get INKEY$ on a
.I ZX80
keyboard, that's not too surprising. :-))
.PP
A list of keys applicable when using the file selector is given in the
.B "FILE SELECTOR KEYS"
section below.
.PP
xz81 has a curious problem with shifts. If you use the real shift key,
you seem to get incorrect results with the number keys (other keys
being ok). Until this is fixed, use either control or alt/meta as
shift - these work for all keys.
.\"
.\"------------------------------------------------------------------
.\"
.SH "THE EMULATED ZX81 OR ZX80"
For those with hazy memories :-), the delay when a 16k ZX81 boots is
normal (most of this time is devoted to enlarging the display file,
try running with `-T' to see this in action), not some problem with
the emulator. You can only avoid this delay by auto-loading a program;
see
.B OPTIONS
above.
.PP
That apart, the emulated machine loads/saves programs with the LOAD
and SAVE commands as usual. For example, `SAVE "FOO"' saves `foo.p' in
the current directory. An extension to this is that if you do `LOAD ""'
you get a file selector which lets you choose which file to load,
navigating between directories if needed. (The last dir visited in
this way (initially the current directory) is also the dir used for
subsequent non-interactive LOAD/SAVE operations.)
.PP
At least, the above applies when emulating a ZX81. In ZX80 mode,
things are complicated by the fact that the ZX80 didn't support
filenames. The LOAD and SAVE commands are just plain `LOAD' and `SAVE'.
So I'm afraid that, for the time being at least, the emulated ZX80 can
only load or save a file called `zx80prog.p'.
.PP
Unless you use the `-V' option, there's no visual indication of FAST
mode - the emulator simply keeps displaying the last SLOW mode frame.
Even with `-V', you get a black screen rather than the `noisy' screen
the real thing would give.
.PP
The PBM written for printer output is updated whenever a new line of
characters is printed, but you shouldn't move or delete the file until
you exit the emulator (it's ok to read or copy it, of course).
.\"
.\"------------------------------------------------------------------
.\"
.SH "FILE SELECTOR KEYS"
Most of the keys available in the file selector are shown onscreen,
but since some aren't (no room), here's a full list:
.TP
.I q
move cursor up.
.TP
.I a
move cursor down.
.TP
.I Shift-q
move cursor up a page.
.TP
.I Shift-a
move cursor down a page.
.TP
.I Enter
load the file currently selected (or change to the directory).
.TP
.I Space
exit without loading.
.PP
Note that for `shifted' keys above, you can use anything the emulated
ZX81 would consider a shift, including e.g. Ctrl. But unlike the
emulated ZX81, the keys will auto-repeat if you hold them down.
.\"
.\"------------------------------------------------------------------
.\"
.SH BUGS
Some hi-res displays (all of which seem to be the `true hi-res' ones
rather than the more common pseudo-hi-res type) aren't displayed
properly - they kind of wrap around the screen. Also, true hi-res
displays depend on very precise timing at the sub-instruction level,
and wouldn't currently work in any case.
.PP
Overscanned displays (e.g. QS Defender) tend to be larger than the
screen area normally displayed, which can be awkward.
.PP
The emulated ZX80 may have some problems, especially as I've never
used a real ZX80 and wouldn't necessarily notice. But in particular,
while doing `SAVE' as a command works, doing `SAVE' from within a
program seems to result in the program being corrupted.
.PP
The ZX80's display is shifted right quite noticeably. There seems to
be some sort of VSYNC-related timing problem, but I'm not sure what
exactly.
.PP
The sound support is currently for OSS (e.g. Linux) only.
.PP
The VSYNC graphics given by `-V' only draw to pixel-line accuracy,
rather than attempting any horizontal resolution.
.\"
.\"------------------------------------------------------------------
.\"
.SH SEE ALSO
.IR zx81get "(1)"
.\"
.\"------------------------------------------------------------------
.\"
.SH AUTHOR
Ian Collier wrote the Z80 emulation, the printer emulation, and much
of the X code; I lifted it from his `xz80' Spectrum emulator.
.PP
Russell Marks (rus@svgalib.org) wrote the ZX81 and ZX80 emulation and
svgalib code.