Vice 1.3 for RISC OS
====================




For general information see the Vice documentation. This file only deals with
differences / specialities in the RISC OS version.



RISC OS NEWS since 1.1
======================

Basically I kept the port in sync, i.e. added icons for new resources and so on.
My main contribution to 1.2 was a restructuring of the drive emulation code which
now uses shared code and private data sections for both drives. That cut about
150kB off each executable and made the true drive emulation a little faster on
RISC processors.



RISC OS NEWS since 1.0.0.1
==========================

- Fixed bug concerning pause when the joystick window is open.
- Optionally display status line in full screen mode (toggle with F9)
- Support for multiple emulation windows; currently used by Vice128 (see below).
- Support for keyboard configuration files (see below)
- Message windows for License, Warranty and Contributors, available from icon
  bar menu.





RISC OS NEWS since 0.16.1.0
===========================

- Sound code more stable.
- Added freeze menu entry for modules like Action Replay.
- ROMSet support via ROMSet Archives (see System window).
- Imagecontents added: drag an image file (D64, T64, ...) to one of the drive
  icons or the drive paths while holding down shift and instead of attaching the
  image file a directory viewer will appear -- unless an error occurred. Also
  since RISC OS doesn't allow more than one open on a file that has been opened
  with write access you can't use this mechanism on an image that has already
  been attached. Double-click on an item to load it into the emulated machine.
- Option full screen mode operation (see below).
- Lots of small bugs and features.






Overview:
=========

1) What is it?
   Vice is a collection of emulators covering 5 CBM machines, the C64, the C128,
   the VIC20, the PET series and the CBM2 series.
   
2) Memory requirements: Huge.
   It's not possible to run any of these emulators on a 4MB machine. It's an
   extremely close shave on an 8MB machine if you can get around 5-6MB free,
   depending on which emulator you want to run. You should have more.

3) CPU requirements: Huge.
   Vice is cycle-exact, so if you compare it to Frodo you have to compare it
   to FrodoSC and relative to that Vice is very fast. That doesn't change the
   fact that you won't have much fun running Vice if you don't have a StrongARM.
   
4) Concluding:
   Vice is only recommended on StrongARM RiscPCs with 16MB or more.




Running Vice:
=============

Just double-click on the Vice-machine's filer-icon and it will install an icon
on the icon bar and open the emulation window. Make sure !ViceRsrc can be
written to if you want to save your Vice settings. The settings for each
emulator will be stored in !ViceRsrc.<machine-name>.vicerc.

IMPORTANT NOTE: Do not terminate any of the emulators by force using ALT BREAK
or something similar while sound (meaning the VIDC sound device) is active.
While this is no problem when (VIDC) sound emulation is off this will in all
likelyhood kill another one of your applications if it's on.




Troubleshooting:
================

If nothing happens after the double-click the reason is probably 1) not enough
memory or 2) !ViceRsrc has been moved so Vice$Path, the central variable pointing
to the shared resources for each emulator, is no longer valid. In that case just
double-click on !ViceRsrc and all necessary information will be updated.

If one of the emulators (not an emulated program!) should crash with sound
emulation enabled you'll keep hearing the last sample buffer and no other
program can use sound anymore. To remedy that you have to issue ``*DRenderOff''
at the CLI.




Vice configuration:
===================

There are a sh**load of configurations for each Vice. Check the general docs
for a description of what everything does. You won't need many of those in
everyday use.
A lot of the configurations are in the form of menus. I didn't put descriptive
labels next to those menus since that'd take up too much space. If you want
to know what a menu group does just open the menu and check the title. The
only menus that need a little extra explanation are probably the ones consisting
of menu icon + descriptive icon + value icon (e.g. ``DOS Name'' and ``Cartridge''
in the System configuration window). In the case of ``DOS Name'' the menu
selects the drive type whose ROM name should be displayed (and made editable)
in the writable icon, in the case of ``Cartridge'' the menu selects the type
of the cartridge file in the value icon.
Most configurations take immediate effect. Changes to writable icons only take
effect after pressing <Return>. Some changes only take effect when Vice is
restarted or the configurations are reloaded, however. Among those are the
names for the various system resources like ROMs or palette files, all of which
are found in the Configure->System window.



RISC OS specifics:
==================

System and Video window:
------------------------

Auto Pause:	automatically pause the emulator when the emulator window is
		closed.
Poll cs:	Minimum number of centiseconds between polls. Increase the
		value to make Vice faster but the desktop less responsive.
Speed cs:	Evaluate the emulation speed with this frequency.
Sound cs:	Poll the sound hardware with this frequency. This value should
		always be smaller than the configured sound buffer size. Using
		a value of 0 defaults to half the buffer size.

ROMsets:	These are handled via ROMset archives (*/vra). The menu to the
		left lets you choose one of the ROMsets currently available,
		the one to the right lets you edit them. Create: add the current
		ROM configuration to the ROMsets (give it a name first). Delete:
		delete the currently selected ROMset. Save: save the currently
		selected ROMset (not all of them). Dump: save entire ROMset
		archive as ``romset/vra'' to the current machine's folder in
		!ViceRsrc. Clear: remove all ROMsets, emptying the archive.
		Restore: reload the ``romset/vra''-File mentioned above.
		You can add a romset archive file to your current archive by
		dragging this file (named */vra) to the System & Video window.



Pane icons:
-----------

At the top are the 4 icons for each of the possible 4 disk drives. Immediately
below that (initially blank) is an icon that'll display the current halftrack
for drive 8 or 9 when in True Drive Emulation mode. You can toggle the drive
whose halftrack you want to see by clicking on this icon. Below that icon is
the Pause/Resume icon which should be self-explanatory. The Reset-icon will
reset the emulated machine; click with select for a soft reset, adjust for a
hard reset (which will also clear memory). The icon at the bottom can be used
for toggling the size of the emulation window.
In contrast to other platforms the drive LEDs also work when not in True Drive
Emulation mode.



Multiple emulator windows:
--------------------------

You can have multiple emulator windows for a machine (ATM C128 only). In this
case only one of the windows will have a pane attached to it (this is the
''active emulator window'') and you can use the pane to toggle its size. You
can transfer the pane to another window by either pressing F10 or using the menu
entry ``MovePane'' in the emulator menu. In full screen mode you can use F10 to
select the emulation window you want to display.
Opening & closing: clicking select on the icon bar icon will always affect
the last active emulator window, i.e. the one with the pane will be either
opened or raised. You can open the other emulator windows by moving the pane
(i.e. F10 or menu).
Note: the 40/80 key of a C128's keyboard is ``emulated'' in the C128 config
window.





Data IO:
========

On RISC OS we use drag and drop, so forget all references to file selection
dialogue boxes and similar bullshit.

Attaching disk images / directories to drives:
Drag the directory or disk image icon to the drive's LED on the EmuWindow's
pane or the corresponding writable path icon in the Configure->Drives window.
Disk images should be typed &164 (D64Image). If everything went well the
writable path icon will be updated to show the new path afterwards, otherwise
it'll remain unchanged (for instance when trying to attach a disk image to a
drive that has drive type ``none'').

Selecting the files for RS232/Printer/Sound devices:
The groups {OK-Button, writable path icon, draggable sprite} in the corresponding
Configuration windows behave like in aSave As box.

Saving snapshots:
Open snapshot savebox via the emulator window's menu. From then on it's exactly
like a standard savebox. Note that when making a snapshot the emulator will
run for a little more until it's ready. So even though you've got the emulator
paused it'll progress a little -- this can't be helped.

Loading snapshots:
Drag snapshot file icon to EmuWindow. The file must be typed ``Data'' (which
it is by default) and of course be for the correct (virtual) machine.

Loading files directly into Vice64:
Files typed &64 are interpreted as raw C64 files with the load-address in the
first two bytes. These files can be loaded into Vice64 (not the other Vices!)
by dragging them to the emulation window. This has the same effect as if you
had loaded the file using ``LOAD "file",8,1'' from the emulator, except it's
a lot faster and you don't have to worry about overwriting the IO area at
$D000 for long files.


Joystick configurations:
------------------------

Each joystick port can be mapped to 5 ``devices'': None (inactive), two sets
of keys for emulation or two real (Acorn-compatible) joysticks. You can edit
the keys thus: 1) make sure the Joystick-configuration window has the input
focus by clicking inside it. 2) place the mouse pointer over the icon for
the direction you wish to change and press the key you want to map to this
direction. You may have to hold the key depressed for a while before it's
recognized. You can also use keys like shift/ctrl/alt here.


Keyboard shortcuts:
-------------------

F5: Toggle sound
F6: Activate monitor
F7: Restore-key (usually only has effect in combination with RUN/STOP=Escape)
F8: Reset emulator
F9: Toggle emu pane
F12: (when in full screen mode) Return to desktop
num/: Toggle True Drive Emulation. This will grey out drive icons 10 and 11.
Copy: Toggle pause
ScrollLock: When active, Vice goes into single tasking mode. This is 1) a
      bit faster and 2) ensures continuous sound playback.


Languages:
----------

The frontend is language-independent. All you have to do is provide a
file containing the label --> text translations and set up the variable
<Vice$Messages> to point to this file before startup. The english version
can be found at Vice:Messages.
This doesn't affect messages generated by Vice itself, however, which will
remain english. You'll have to complain to the Vice core team if you want
that changed ;-).



Full Screen Mode:
-----------------

You can now also run Vice in full screen mode, i.e. single tasking outside
the WIMP environment. You can enter full screen mode using the icon bar
menu and leave it again by pressing F12.
The screen mode to use is very dependent on your computer and the machine
emulated by Vice; therefore the mode is user-definable. The screen mode is
described by a string of the form ``mode:resx,resy,lddepth'' (no spaces;
lddepth is log2 of the depth, i.e. 2 for 4bpp, 3 for 8bpp, 4 for 16bpp, ...),
to accomodate both new and old style mode selection. If you're running
Vice on a RiscPC the second part of the mode descriptor string (resx,resy,lddepth)
will be used, otherwise it's the mode number. By default ``28:640,480,3''
is used because it's a standard mode and big enough to display all emulators;
but it's certainly not ideal for all emulators, so have a play yourself.
Also, if ``SetPalette'' is configured on, the screen mode has <= 8bpp and
can display enough colours for the emulated machine, the palette will be
reprogrammed, so when using a 4bpp mode with !Vice64 you'll get exact colours.
Depth issues: internally Vice uses 8bpp for the display. On older machines
it'll be more efficient to use an 8bpp mode because it minimizes computational
overhead. On a StrongARM RiscPC, OTOH, you'll be better off using a mode with
less colours (e.g. 4bpp for !Vice64) because that'll require less bandwidth.
Since the palette can be reprogrammed there's no reason whatsoever to use
a mode with more than 8bpp unless you think Vice is running too fast.
You can edit the full screen mode string in the system configuration window.
As far as configurations in full screen mode go: there are none. Neither can
you attach any images and so on, only the keyboard-shortcuts still work. And
I definitely won't re-program all the stuff that's available in the multi-
tasking version for the fullscreen version.





Keyboard configuration files:
-----------------------------

This is a new feature (wasn't available on RISC OS in Vice 1.0.0.1 yet). It
allows you to change the keyboard mapping from your RISC OS computer to the
keys of the emulated machine. The files used by the Unix-Version of Vice
are unusable for this, therefore I made a new format. The RISC OS keyboard
mapping files have the name RO*/vkm in the corresponding machine's sub-
directory in !ViceRsrc (e.g. !ViceRsrc.C64.ROdflt/vkm). You have to edit
these files (it says they're for RISC OS in the first line), not the ones
for Unix.
Hacking these files is quite low-level and thus not for the faint-hearted.
On the RISC OS side you have to deal with _internal_ key-numbers which
have nothing to do with ASCII. On the emulated machine's side these keys
have to be mapped to row/column indices (see the Vice documentation for
keyboard layouts).
A line of this file has the format

intkey row col [s [srow scol [s]]] ["keystr"]

- intkey is the internal key number.
- row, col are the row and column of the keyboard matrix of the emulated
  machine. Use 15 for both to disable the key.
- if row/col are followed by an 's' this means that a pressed shift-key
  should also be emulated (e.g. for cursor left which is shift+cursor right
  on a real C64).
- if this is followed by another pair of numbers these are interpreted as
  mappings for this key if the shift key is pressed.
- at the end of each line is an optional string-representation of this key
  in double quotes (valid for an english keyboard).

The mapping for shifted keys will probably need additional explanation:
you DON'T have to (and shouldn't) define anything here if it's a trivial
shifting, e.g. a+shift --> a+shift (the default keyboard mappings don't
have any shifted mappings defined!). It should be used if the shifted key
doesn't obey the mapping <base key> + shift --> <base key> + shift, e.g.
mapping the asterisk (shift + '8' on an english keyboard) to the asterisk
on a C64 (an unshifted key which is located where the ']' is on an english
keyboard). For this example the mapping of the key '8' (internal key number
21) for a C64 would look like this:

21 3 3 6 1

As a general rule of thumb: don't screw around with this file and make a
backup copy before you do. It should also be noted that the more entries
you define in the shifted keymap and the more 's'-flags you use the more
likely problems arise (especially for games where a faithful mapping might
be required). Imagine for instance a program that uses shift and '*' for
two operations and you mapped the RISC OS '*' ( = shift + '8') to the '*'.
You could never use both operations at the same time which can be a real
nuisance if e.g. one of those operations is ``run'' and the other is
``fire''. You should therefore always strife to minimize both shifted
keymaps and 's'-flags. The default mappings don't define any shifted keymaps
and only 3 's'-flags, for instance. Also take care that you don't use keys
that have a special meaning for Vice, e.g. F5-F10 etc.
It's a dirty job but at some point I had to to it... ;-).

I didn't bother to make the filenames configurable; they're ROdflt/vkm
for all emulators except for PET where they're RObusi/vkm (for business
layout) and ROgrph/vkm (for graphic layout). Deleting these files will
run Vice with the default keymap. You can load a keymap at run-time by
dragging the file to the Kbd-icons in the System configuration window.
One of these icons also opens a menu from where you can save the currently
active keyboard mappings to a file.







Misc:
-----

- When turning on true drive emulation or dealing with snapshots, sound is
  suspended for a short time. This is not a bug, it has to be done.
- The default sound buffer size of 0.35s is only recommended when playing
  music. If you're doing anything interactive you should use a lower value,
  no higher than 0.1s.
- Attaching compressed images (disk/ROM/...) is not supported on RISC OS.
  Well, we have image filing systems for that.






Support Programs:
=================

c1541 and petcat are inside the !ViceRsrc directory and can be run using
vice:c1541 / vice:petcat. For a description of both check the general Vice
documentation. I didn't provide hacks to run either from one of the emulators,
though.







Thanks:
=======

- Richard Atterer (atterer@informatik.tu-muenchen.de) for creating a set of
  very nice looking icons.

- Stefan Bellon (bellonsn@trick.informatik.uni-stuttgart.de) for repeatedly
  compiling the CPU-files with optimization for me (some of those need over
  40MB).

- Richard Atterer, Stefan Bellon, Michael Kbel (Kuemmel@studbox.uni-stuttgart.de)
  for beta-testing.






Ported by:
==========

Andreas Dehmel
Am Schorn 18
82327 Tutzing
dehmel@forwiss.tu-muenchen.de
