sz81   - a ZX81 and ZX80 emulator using SDL

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.


************************************************************************
* Contained within this document is information specific to sz81 only. *
* Please see README.z81 for information about [x]z81, zx81get and the  *
* contents of the games-etc and saverom folders.                       *
************************************************************************


Table of Contents
=================

1.Description
    Features
2.Controls
    For the PC
    For the Amiga
    For the Sharp Zaurus
    For the GPH GP2X/Wiz
3.Operation
    General GUI Navigation
    Loading a Program File
    Saving a Program File
    Saving and Loading State Files
    Configuring a Joystick
    Remapping Joystick Controls
    Using the ZX Printer
    The Configuration File
      show_input_id
      ctrl_remap
    Exiting sz81
4.Compilation and Installation
    For desktop Linux
    For the Amiga
    For the Sharp Zaurus
    For the GPH GP2X/Wiz
5.Porting to Other Platforms
6.Thanks
7.Contacting Us


1.Description
=============

sz81 is a Sinclair ZX80/ZX81 emulator very much based upon the work of
Ian Collier's xz80 and Russell Marks's z81 but employing the highly
portable SDL and including additional functionality and features for
desktop computers and portable devices.

Features:
 * Virtual keyboard with several adjustable properties
 * Control bar with icons for regularly used features
 * Load anytime file dialog (no need to use LOAD)
 * Save state system with 9 slots for each program
 * Runtime options including a joystick configurator
 * RAM configurations of 1 to 4, 16, 32, 48 and 56K
 * Quicksilva, BI-PAK ZON X-81 and VSYNC-based sound
 * Screenshot saving using the bitmap image format
 * Joystick control remapping within the emulator
 * Full keyboard, mouse and joystick support throughout
 * 3x runtime switchable scaling on supported platforms
 * Window and fullscreen toggling on supported platforms
 * Portrait orientated resolutions such as 240x320
 * The ability to run centred within any resolution
 * Source code support for *nix, AmigaOS4 and Win32
 * Maximum porting potential since it only requires SDL


2.Controls
==========

For the PC:

    Click screen  - Toggle virtual keyboard and control bar
    Backspace     - Rubout i.e. equivalent to using SHIFT + 0
    Comma         - Equivalent to using SHIFT + .
    Cursors       - Equivalent to using SHIFT + 5, 6, 7 and 8
    -/=           - Decrease/increase the volume (if supported)
    ALT + R       - Cycle between 960x720, 640x480 and 320x240
    F11           - Toggle between fullscreen and a window
    F9            - Activate the control remapper for remapping
                    joystick controls to keyboard controls
    PrtScn        - Save a screenshot to the local scnsht folder
    Pause         - Place emulation on hold but not the GUI

    Clicking the screen (or F1) brings up the virtual keyboard and the
    control bar enabling access to several very useful features. These
    are listed below alongside their keyboard equivalents :-

    Exit          - Exit emulator (F10)
    Reset         - Reset emulator (F12)
    Autohide      - Toggle vkeyb between autohide and don't hide (F6)
    Shift Type    - Toggle between sticky shift and toggle shift (F7)
    Opacity DN/UP - Reduce (HOME) or increase (END) vkeyb opacity
    Invert Screen - Toggle between not inverse and inverse video (F8)
    Save State    - Toggle the save state dialog if available (F4)
    Load State    - Toggle the load state dialog if available (F5)
    Load File     - Toggle the load file dialog (F3)
    Options       - Toggle the runtime options (F2)

For the Amiga:

    As above section "For the PC" plus:

    Tooltypes
    ---------

    sz81 can be configured using tooltypes:

    FULLSCREEN
    XRES=<240+>
    YRES=<240+>

    LOCALDATA=<dir to save user data> (default: PROGDIR:save)
    STATICLOADDIR - LOAD/SAVE always uses <LOCALDATA>/progrm (default is
                    to LOAD/SAVE from the directory last used)

    File Selector
    -------------

    The Amiga build uses standard ASL requesters instead of sz81's
    built-in file selector.

For the Sharp Zaurus:

    Click screen  - Toggle virtual keyboard and control bar
    Backspace     - Rubout i.e. equivalent to using SHIFT + 0
    Comma         - Equivalent to using SHIFT + .
    Cursors       - Equivalent to using SHIFT + 5, 6, 7 and 8
    -/=           - Decrease/increase the volume (if supported)

    See PC controls for an explanation of the control bar.

For the GPH GP2X/Wiz:

    Within the emulator (remappable)   | Within the GUI
    -----------------------------------+----------------------
    LTrigger      - SHIFT              | SHIFT/Page up
    RTrigger      -                    | Page down
    Joy Left      - O                  | Selector left
    Joy Right     - P                  | Selector right
    Joy Up        - Q                  | Selector up
    Joy Down      - A                  | Selector down
    Select        - Load file dialog   | Control remapper
    Start         - Virtual keyboard   |
    Button A      - Newline            | Select (selector hit)
    Button B      - Newline            | Newline
    Button Y      - Rubout (SHIFT + 0) | Rubout (SHIFT + 0)
    Button X      - Space              | Space

    See PC controls for an explanation of the control bar.


3.Operation
===========

    General GUI Navigation
    ----------------------
    Every component has a green selector that can be moved around using
    the cursor keys or the joystick (the virtual keyboard and control
    bar's selector will only appear if a joystick is detected). The item
    currently selected can be activated with the enter key, a joystick
    button (selector hit) or by clicking with the mouse. If you use the
    mouse then of course you are free to activate items directly and can
    ignore the selector. Page up and page down (or joystick equivalents)
    will flip between pages and scroll through lists. Escape operates as
    you might expect: it closes the topmost dialog or component and will
    continue to do so until the emulator window is reached.

    Loading a Program File
    ----------------------
    Typing the ZX80's LOAD ("W", newline) or the ZX81's LOAD "" ("J",
    SHIFT + "P" twice, newline) will show the load file dialog. There is
    a much easier way to show the same dialog and that's via the control
    bar icon or the F3 key (joystick select) but there is a fundamental
    difference in the way that these two methods work that you should be
    made aware of: a machine reset will occur if you load a program file
    by directly activating the dialog but not if you activate it via the
    machine's LOAD command. For the most part this won't matter at all,
    but if you are intending to set-up RAMTOP, load a program above it
    before loading another program then you will lose everything if you
    load a program by invoking the dialog directly.

    If you have an understanding of the ZX81 then you will know that it
    is possible to load a program by executing LOAD "PROG" in which case
    sz81's loading mechanism will search for prog.p or PROG.P within the
    last directory navigated to, or if you've yet to navigate anywhere
    then the start-up folder. If you'd like to load an .81 file instead
    then the .p extension can be overridden by appending an .81 suffix
    e.g LOAD "PROG.81".

    There are some additional ways to navigate and utilise the load file
    dialog that enhance its operability: directories can be opened and
    programs loaded with a single mouse or stylus click, the scrollbar
    is interactive and the list can be scrolled using a mouse wheel. It
    is also possible to select an item by typing its initial letter or
    number and then cycling to subsequent items with repeated presses.

    Saving a Program File
    ---------------------
    On the ZX80 saving is achieved by executing SAVE ("E", newline), but
    since there is no way to pass a filename and indeed no native sz81
    save file dialog either, a choice of two naming methods have been
    made available: the first and default method is to save the program
    into the last folder navigated to with the load file dialog (or the
    start-up directory) with a sequential filename e.g. zx80prog0123.o.
    The second funkier method is to embed a BASIC line somewhere within
    the program e.g. 9999 REM SAVE "PROG". The line number used is not
    important, but the use of the SAVE keyword is so you'll need to type
    9999 SAVE "PROG" and then move the cursor back before SAVE and add
    a REM. When the program is saved by executing SAVE, sz81's program
    saving mechanism will look for this embedded BASIC REM statement and
    extract the filename. The default .o extension can be overridden by
    appending a .80 suffix. Please note that if you are using a version
    of sz81 that's been ported to a non *nix platform, these filenaming
    methods may have been replaced with a save dialog native to your OS.

    Saving and Loading State Files
    ------------------------------
    sz81 supports the saving and later reloading of images that are most
    commonly known as save state files. They are simply files containing
    dumps of the emulated machine's memory and the emulator's variables
    to enable a program to be restored to the same state at some other
    point in the future. So, after loading a game and playing the first
    level or two you find that your lunch break is over and you'd like
    to save your current position within the game to continue with later
    when distraction beckons - simply activate the save state dialog by
    pressing F4 or selecting it from the control bar and choose a slot.
    Slots that are inverse have an existing state already stored there
    (from the same program) so either choose a new slot or overwrite an
    existing one. This can be achieved by clicking a slot with the mouse
    or stylus, moving the selector and pressing enter (selector hit) or
    pressing a number from 1 to 9.

    Loading a save state file requires that the original game is loaded
    first and then the load state dialog can be activated with F5 or via
    the control bar. Then simply choose one of the previous slots that
    you've saved to and away you go.

    Configuring a Joystick
    ----------------------
    If you have a digital or analogue joystick plugged in and you'd like
    to use it then open the runtime options (F2 from within the emulator
    or select the control bar icon) and employ the joystick configurator
    using either the cursor keys and enter, the mouse or stylus or the
    joystick once configured. Select a control on the graphical joystick
    representation (the selector will blink) and follow the instructions
    configuring as many of the controls as you possibly can for optimum
    usability.

    Remapping Joystick Controls
    ---------------------------
    With the virtual keyboard and control bar visible, position the
    selector over the function that you'd like to assign to a joystick
    control and press the control remapper (the selector will blink).
    Then press a joystick control to remap the function to the control.
    Existing controls that have been remapped are active within the
    emulator (you cannot remap GUI controls) whilst new controls are
    universally active. It is possible to include the SHIFT modifier
    within the control as long as it is active before you initiate
    remapping. To cancel remapping press the control remapper again.

    Using the ZX Printer
    --------------------
    Emulated printer output is currently written to sequentially named
    pbm image files stored within the local prtout folder. A new file is
    created when either of the ZX81's LLIST or LPRINT commands are used
    and then closed when the emulator is reset or sz81 exited.

    The Configuration File
    ----------------------
    Located within the local folder is the auto-generated configuration
    file sz81rc (or sz81.ini). It is possible to tweak sz81's operation
    by editing the contents of this file but the majority of people will
    leave it as is. Right at the top is show_input_id which can be set
    to TRUE to show input device id's (SDL_keysym's) which is useful if
    you are configuring an input device and would like to know the id's
    of the buttons. Additionally the entire control set is stored within
    this file and controls can be edited, added or removed. For example
    there is no print screen (SDLK_PRINT) key on a handheld device with
    no keyboard and so by default the user cannot take screenshots, but
    if they have a spare input button and they know its id then they can
    by adding the following ctrl_remap:

        ctrl_remap.components=COMP_ALL
        ctrl_remap.protected=TRUE
        ctrl_remap.device=DEVICE_JOYSTICK        // or DEVICE_KEYBOARD
        ctrl_remap.id=19                         // 19 is an example
        ctrl_remap.remap_device=DEVICE_KEYBOARD
        ctrl_remap.remap_id=SDLK_PRINT
        ctrl_remap.remap_mod_id=

    Simply put, this ctrl_remap active across all program components,
    protected from being modified by the control remapper, will cause
    the joystick button with the id of 19 to be intercepted and a PrtScn
    keyboard key event generated in its place. remap_mod_id can be used
    to generate an additional event and this is how backspace generates
    SHIFT + 0 within the emulator. I recommend looking at sdl_input.c
    and sdl_input.h to understand this system in more detail.

    Exiting sz81
    ------------
    Upon exiting, if you have modified any of the configurable options
    you will be presented with a dialog requesting that you confirm
    writing the changes to the configuration file (sz81rc, sz81.ini).
    If you choose "No" then the changes will be discarded. This is
    useful for when you have configured the emulator just how you like
    it and don't wish to disturb it with unimportant modifications.


4.Compilation and Installation
==============================

Extract the sz81 source package and change into the extracted directory.

For desktop Linux:

    Comment/uncomment the PREFIX BINDIR DOCDIR PACKAGE_DATA_DIR group at
    the top of the Makefile depending on whether you want to do a local
    install, system-wide install or run from the source folder (default)
    and then type :-

    make clean
    make
    (If you're running from the source folder then that's it, but if
    you're installing this locally or system-wide then continue)
    (Installing system-wide requires that you login as root now)
    make install

For the Amiga (requires SDK):

    gmake -f Makefile.amigaos4

    To get all the required files together in RAM:sz81:
    gmake -f Makefile.amigaos4 install

    The directory can then be dragged to final location.

For the Sharp Zaurus (requires SDK):

    make clean
    make -f Makefile.zaurus

    Install sz81_2.1.x_zaurus.ipk using Add/Remove Software.

For the GPH GP2X/Wiz (requires SDK):

    make clean
    (For the GPH toolchain execute the following line only)
    make -f Makefile.gp2x
    (For the Open2x toolchain execute the following line only)
    make -f Makefile.open2x
    (For the OpenWiz toolchain execute the following line only)
    make -f Makefile.openwiz

    Extract sz81_2.1.x_{gp2x|open2x|openwiz}.tar.gz and copy the
    contents onto your SD card.


5.Porting to Other Platforms
============================

This project requires SDL only, runs centred within any resolution, can
be scaled-up up to 3x, can be operated entirely with a keyboard, mouse
or joystick, ships with *nix, AmigaOS4 and Win32 source code support by
default and should port easily to many different platforms and devices.


6.Thanks
========

Thanks go to Mr 2X and Neil L from the gp32x.com forums for assisting
with testing the Wiz build.


7.Contacting Us
===============

Please visit the project's support page at
http://sourceforge.net/projects/sz81/support

2011-02-13