ArmPalmSpec - A spectrum emulator for ARM based PalmOS computers.

(Written by Matan Ziv-Av, matan@svgalib.org)


Version 0.2
===========
Tested on Tungsten E only.
Emulates spectrum 48.
Sound is not perfect.
Read snapshots (.sna and z80 format) from databases, or 
 from /Palm/Programs/Spec directory on memory card.
On screen (Spectrum+) keyboard.
9 Hard keys can be defined to any spectrum key
 or kempston joystick key.


Loading
=======
To load the game to the Palm, you need to transfer the files armpalmspec.prc
and pdbs/spectrum.pdb. This can be done with the pilot-xfer program from
pilot-link package:
pilot-xfer -m armpalmspec.prc -m pdbs/spectrum.pdb
Or using the palm desktop software by dragging those files to the right place 
and then synching.


Using
=====
In the main screen: 
Load   -   loads the selected snapshot and starts running.
Cont   -   continues running from current position (reset spectrum after 
           loading program).
Speed  -   selects speed (0 means max possible, 1 means twice normal, 2 means
           normal).
Sound  -   enables/disables sound (a bell is displayed when sound enabled).
Define -   define the meaning of the nine hardware keys.
SvKey  -   saves the defined keys for the selected snapshot name.  

In emulator:
The blue dot in the blue square (left of the keyboard) is the reset button.
To hide the keyboard, tap left to the keyboard on the top part (near the TRUE
VIDEO and DELETE keys). To redisplay, tap again in the same place.
To return to main screen, tap right to the keyboard (near the BREAK and ENTER
keys).


Converting snapshots to PDBs
============================
Using par tool by David Williams, it can be done with the command:

par c -v 1 hskiing.pdb hskiing Data PSPe hskiing.sna
par c -v 2 xeno.pdb xeno Data PSPe xeno.z80

Or using Java program files2pdb:

java files2pdb -n maziacs -t Data -c PSPe maziacs.pdb maziacs.sna


Hard keys definition
====================
The meaning of the the hard keys is decided in this order:
1. If the keys were defined in the current session, then this definition is 
   used.
2. Otherwise, when a snapshot is loaded, if it contains key definitions, they 
   are used. 
3. Lastly, If the snapshot does not contain key definitions, the list of saved 
   key definitions is searched for a definition.

Key definitions can be added to a snapshot (.sna) format by appending extra 9 
bytes a the end (so that its length becomes 49188=27+49152+9). Those 9 bytes 
are interpreted in order: First the application keys, from left to right, and 
then the Navigator in order right, left, down, up, middle. A number or letter 
(or space) gives the corresponding spectrum key, enter is represented by 
character value 10 or 13, symbol shift by 24 and caps shift by 22. The kempston
joystick is represented by values 1 to 5 (right, left, down, up, fire).

The saved key definitions are saved in a filee named "ArmPalmSpecKeyDef". Each
record is exactly 26 bytes long, first 16 include the snapshot name (zero
terminated, so maximum 15 characters long), the next 9 are the key definitions,
and the last byte must be 0.

In the hard keys redefining screen, select which key is to be redefined by
tapping the correct place on the screen (the key is coloured in red). Then, 
select which key it sends by tapping on the displayed keyboard (or kempston
joystick). Tapping the "kempston" button changes the meaning of all five 
navigator keys. In the keys, space is represened by underline (_), caps shift
is represented by by copyright symbol (circled c), symbol shift by funny
symbol, and enter by tilde (~). The kempston direction are represented by 
>, <, V, ^, and fire by diamond.


Compiling
=========
On a Linux computer, install pilrc, prc-tools and prc-tools-arm. Then download
the palm SDK from palmsource developer site. If all is installed correctly make
should compile the file armpalmspec.prc.


History/Credits
===============
This program is a port of PalmSpec by Alex Bassas Serramia
(which is written mostly in 68K assembler) to C.

The z80 emulator was written by Ian Collier, but I got it by way of
Russell Marks' zx81 emulator called z81.
