Virtu Options
=============

Overview
~~~~~~~~
    The appearance and behaviour of the emulator can be controlled using a
range of options. A subset of the more commonly used options can be toggled at
any time while in the emulator by pressing certain function keys, provided the
debugger is not being used as it remaps the function keys (see the debugger
documentation). All options can be controlled using the options dialog box
available outside of the emulator. This document details those options in the
order they appear in the options dialog box that follows.

+----------------------------------+----------------------------------+
|            Processor             |       Sound          Keyboard    |
| (x) 6502   (x) 65C02   [x] 1 MHz |    Volume   xxx   [x] Caps Lock  |
+----------------------------------+----------------------------------+
|          Disk ][ Drives          |              Video               |
| Drive  Image File  Vol  WP   Up  |     Mode    (x) Color  (x) Mono  |
|  1A    xxxxxxxxxx  xxx  [x]  (x) |     Misc    [x] VSync  [x] Icons |
|  1B    xxxxxxxxxx  xxx  [x]  (x) |    Text Colors      Mono Colors  |
|  2A    xxxxxxxxxx  xxx  [x]  (x) |  Foreground   xx   xxx  xxx  xxx |
|  2B    xxxxxxxxxx  xxx  [x]  (x) |  Background   xx   xxx  xxx  xxx |
+----------------------------------+----------------------------------+
|         Game Port Input          |         Joystick Output          |
| (x) Keyboard  xxx  xxx  xxx  xxx | [x] Keyboard  xxx  xxx  xxx  xxx |
| (x) Joystick  xxx       xxx  xxx |               xxx       xxx  xxx |
| [x] Paddles   xxx  xxx  xxx      | [x] Corners   xxx  xxx  xxx      |
+----------------------------------+----------------------------------+

Processor
~~~~~~~~~
    Two main processors are supported. The 6502 supplied with the Apple ][+ and
standard Apple //e, or the 65C02 supplied with the enhanced Apple //e. Some
*relatively* new Apple //e software requires a 65C02 processor. The original
6502 was buggy and had some undocumented opcodes which software sometimes
exploits, so Virtu emulates the 6502 as it was, bugs and all. The 65C02 fixed
the bugs in the 6502 and improved the instruction set, adding new opcodes and
addressing modes while making the instruction set more orthogonal. We recommend
using a 65C02 which should run most older software, using a 6502 only if
necessary.

    As well as selecting the main processor you can also choose whether or not
to limit the processor to its original speed of 1 MHz. Pressing function key
<F2> toggles enabling/disabling this limit. We recommend enabling the 1 MHz
limit for games which are typically timing critical eg. arcade games, and
disabling it for anything else. Note however that during disk access this
option is ignored so that software will always load/save as fast as possible.

Sound
~~~~~
    The sound volume (as output on the host) can be a value between 0 and 127.
We recommend choosing a value that reflects the time of day one is playing that
classic game. Note that the desktop sound settings are saved upon entry to the
emulator and restored upon exit.

Keyboard
~~~~~~~~
    The keyboard caps lock can be forced on/off upon entry to the emulator.
This is useful when booting to an old disk operating system (eg. DOS 3.3) which
does not support lower case in commands. Note that the desktop keyboard
settings are saved upon entry to the emulator and restored upon exit.

Disk ][ Drives
~~~~~~~~~~~~~~
    Two 5.25" floppy disk drives are supported. Furthermore, since a floppy
disk can be double-sided, each disk drive allows selecting both a top side (A)
and a bottom side (B), effectively giving convenient access to four floppy disk
sides (through disk flipping). Pressing function keys <F3> and <F4> toggles
which side is up for disk drives 1 and 2 respectively.

    Each disk drive allows the selection of an image file (when that drive is
_not_ being used) , its volume number, write-protect status and which side is
currently being accessed, ie. facing up. The image file is the full pathname of
the captured disk image and the volume number is a value between 0 and 255. We
recommend using the default of 254 used by most DOS 3.3 disks. The "Tech"
document has more on this topic.

Video
~~~~~
    The video output can be displayed in either color or monochrome. Pressing
function key <F9> toggles this mode. Furthermore, when in color mode the text
foreground and background colors can be selected from the double-hires palette
with a value from 0 to 15, enabling control of the text colors as on the Apple
IIgs; in monochrome mode the overall foreground and background colors can be
selected as an RGB-tuple with each component ranging from 0 to 255.

    The double-hires colors are as follows: 0=black, 1=dark blue, 2=dark green,
3=medium blue, 4=brown, 5=light gray, 6=light green, 7=aquamarine, 8=deep red,
9=purple, 10=dark gray, 11=light blue, 12=orange, 13=pink, 14=yellow, 15=white.

    Other miscellaneous video options include whether or not to synchronise
hardware page flipping with vsync on the host, and whether or not to show the
drive icons. Pressing function key <F10> toggles enabling/disabling vsync and
function key <F11> toggles showing/hiding the drive icons. We recommend using
vsync to reduce flicker and tearing effects on games that use page-flipping.

Game Port Input
~~~~~~~~~~~~~~~
    The game port input can be sourced from an actual joystick or emulated by
the keyboard. Pressing function key <F5> toggles this. When using the keyboard
the given internal key codes can be selected with a value from 0 to 255, and
are used for direction (including diagonals or corners) and the standard two
buttons.

    Finally, the game port input device can be used in a relative (paddles)
mode. This is useful for games that expect paddles or a non-centering joystick
as an input device. Pressing function key <F6> toggles enabling/disabling
paddles mode.

Joystick Output
~~~~~~~~~~~~~~~
    The joystick output can be used to emulate pressing the keyboard. Pressing
function key <F7> toggles enabling/disabling keyboard output. This is useful
for playing with a joystick games that only allow for keyboard input. When
enabled, the external key codes to output can be selected with a value from 0
to 255, and are used for direction (optionally including corners) and the
standard two buttons. Pressing function key <F8> toggles enabling/disabling
corners.

Loading/Saving Options
~~~~~~~~~~~~~~~~~~~~~~
    All of the above options can be saved to a script file (of editable text)
using the "Save" menu option, and later restored by dragging a script file to
the Virtu iconbar icon or Options window. Furthermore, the emulator memory and
CPU registers can also be dumped. This can be thought of as the ultimate save
game feature.

    At startup Virtu checks for, and loads if it exists, a default script file
"Default" (and its memory dump "Default+", if included) from the data directory.

Function Key Summary
~~~~~~~~~~~~~~~~~~~~
<F1>  debugger enter/exit
<F2>  processor 1 MHz limit enable/disable
<F3>  disk ][ drive 1 flip up/down
<F4>  disk ][ drive 2 flip up/down
<F5>  game port input keyboard/joystick
<F6>  game port input paddles on/off
<F7>  joystick output keyboard on/off
<F8>  joystick output corners on/off
<F9>  video mode color/mono
<F10> video vsync on/off
<F11> video icons show/hide
<F12> return to desktop
