Contents of this document:

System Requirements

In order to use STonX, you will need:

Emulated System Components

At the moment, the following components of the Atari ST are emulated: There is also a VDI driver for X, which speeds up the GEM graphics routines by a factor of 20-100 (depending on the display) compared to the emulated VDI routines. The driver is "very beta" and doesn't support many of the VDI functions found in TOS-VDI.

Running STonX

STonX version 0.4 has the following command-line options:
Be Quiet - do not output warnings or debugging messages of any kind

-disk <X>:<File>
Map a disk image called File to BIOS drive X:. For example,
-disk A:Disk1
maps the disk image named Disk1 to BIOS drive A:. The default is to map Diskfile in the current directory to A:. See also Using disk files.

Selects the default "monitor type" to boot with. You can't switch between monochrome and color at run time (yet). The default is -mono.

-usec <X>
Set the base timer interval to X microseconds. On systems where the given interval is not supported, it is automatically scaled to the closest possible interval. However, STonX will use the given interval to calculate the VBL and Timer-C frequencies reported at startup time, so these may not always be correct. The default value is 10000 microseconds (10ms).

-vbl <X>
Set the number of base timer interrupts per VBL to X. The default value is 4, which results in a 25Hz VBL interrupt. For games, set this so that the VBL runs at 50 or more Hz!

-timer-c <X>
Set the number of base timer interrupts per Timer-C interrupt to X. The default is 1, meaning that Timer-C runs at 100Hz (which is half as much as in the ST, so you will have to multiply the measured times for benchmarks etc. running with the emulator by 2 to obtain the real time used).

-refresh <X>
Set the number of VBL interrupts for one screen update to X. The default value is 2. Decrease this and/or the -vbl argument to get less jerky screen updates.

Use the VDI driver for X. Note that this will not work with -color!. See also The VDI Driver for X.

The VDI Driver For X

The VDI driver is useful for running clean GEM programs at a high speed (compared to the emulated VDI). It will open a second window, where the VDI output goes, and whose contents needn't be copied and converted from the ST's screen memory periodically. Also, the mouse cursor is a true X mouse cursor.

Note that the "Main Window" is still updated if you move your mouse cursor into it. This is a feature I call "dual mode", and helps looking at output from unimplemented VDI functions such as the alpha mode commands (the desktop uses these to "Show" files). This will be removed in future releases, because it limits the VDI driver to the ST's graphics capabilities, while it should ideally use the full color and resolution of your X display.

In order to use the VDI driver, you need to install the Atari ST system fonts into a directory visible for your X server. The Makefile tries to do this, but this will not work e.g. for X Terminals. This results in typical X error messages during the font installation:

X Error of failed request:  BadValue (integer parameter out of range for operation)
  Major opcode of failed request:  51 (X_SetFontPath)
  Value in failed request:  0x7
  Serial number of failed request:  4
  Current serial number in output stream:  6
In that case, follow these steps:
1. Find out where your X server looks for fonts and copy the *.pcf files from the data subdirectory there. We will assume that the directory /usr/lib/X11/ncd/fonts/pcf/misc/ is world-writable and in the font path (check with xset q):
    cp data/*.pcf /usr/lib/X11/ncd/fonts/pcf/misc

2. Update the fonts.* files using mkfontdir:
    mkfontdir /usr/lib/X11/ncd/fonts/pcf/misc

As a side-effect, you will be able to use the ISO-Versions of the Atari ST system font for your xterm windows etc. (try xfontsel)

If the Makefile succeeded in installing the fonts in the data subdirectory of the STonX build directory (which we will assume is called /home/nino/STonX), you will have to add the following lines to your ~/.xinitrc:

    xset fp+ /home/nino/STonX/data
    xset fp rehash

Using Disk Files

Disk files are just raw images of an Atari ST disk. On Unix machines with disk drives, 720KB and 1.44MB disks can be copied to a disk file with
    cp /dev/fd0 Diskfile
or perhaps using a different device on exotic Unixes. In order to make your own "Diskfile" without having to resort to real floppy disks, you can use a patch for mtools (or get an already already patched version). You can use the provided "EmptyHarddisk.gz" file as a ST Harddisk partition if you uncompress it (it's 10MB - beware) and map it to e.g. C: with
    stonx -disk A:Diskfile -disk C:EmptyHarddisk

You can also use the "raw" disk device on some Unix systems to access disks directly. For example, on Suns with disk drives this can be done with the following argument to STonX:

    stonx -disk A:/dev/rfd0
Note that STonX expects a disk file named "Diskfile" in the current directory when started, which will be mapped to drive A:.
Marinos "nino" Yannikos, nino@mips.complang.tuwien.ac.at