The Datafile PD-CD 5/DATAFILE_PDCD5.iso/utilities/f/frodo/!Help

Text File | 1997-05-25 | 19.1 KB | 545 lines

FRODO FOR ACORN RISC OS
=======================




This is the Acorn port of the C64 Emulator Frodo. General information and
legal issues are included in the Docs directory, this file deals with the
RISC OS aspects only.




System Requirements:
====================

Frodo needs a WimpSlot of about 1376k, FrodoSC manages with 832k. Both
require RISC OS 3 and a lot of processing power. Although they should
in theory run on any machine with enough RAM and a recent enough OS the
minimum spec where Frodo is _halfway_ usable is an A5000, FrodoSC should
be usable on a StrongARM only. If you want full frame rate and sound
you'll need a StrongARM even for Frodo. This is due to Frodo being
written in C++ so you really can't expect it to be as fast as the
Breadbox, for instance. Thus this is basically RiscPC only, StrongARM
_strong_ly recommended. Any joker out there with an ARM2 or 250 complaining
about the speed will feel my foot where mommy put the thermometer.





Using Frodo:
============

Simply start Frodo(SC) by double-clicking on its filer icon (the filer must
have seen the shared resources of Frodo and FrodoSC first!). Frodo will
install itself on the icon bar and open the emulation window (yes dudes,
Frodo is multitasking). You should know how to use a C64 from now on
because I won't start a course on that!




Configuration:
==============

There are two configuration windows:

a) The Preferences window: deals with all system-independent configurations.
   See the file "settings" in the Docs directory for more information.
   You can set drive paths by dragging the object in question (a directory,
   a D64- or a T64-image) onto the respective (writable) path icon. Frodo
   will automatically try setting the drive emulation mode accordingly.
   The reason the Preferences window is so big is that everything covered
   there is in a class in Frodo, so regarding portability and unwanted
   side-effects I decided to represent it as a unit rather than splitting
   it up.

b) The System Configuration window deals with system-specific aspects of
   the emulator. You can enter the keys used for the keyboard joystick
   here as well as timing aspects. The entries are

   Poll After:    Number of centiseconds after which the WIMP should be
           polled. This is never exact because the check whether
           to poll is only done after an entire frame has been built.

   Speed After:    Number of centiseconds after which the Speedometer should
           be updated. Don't use too small values because centiseconds
           are basically too coarse a unit for something like this. Like
           Poll After the check is made only once per frame.

   Poll Sound Lines: Number of rasterlines after which the sound system
           should be polled to determine whether a new sample is
           needed. For more see "Sound".

   Joystick Keys: You have to place the mouse pointer over the corresponding
           icon and press the key you wish to use for this until you
           see the icon change. For more see "Keyboard Joysticks"


In both windows changes are only passed on to the emulator if you click OK
or "save" (if present), drag the filer-sprite to a valid destination window
or press return in the file-path icon (the only exception is "Skip Frames").
"Cancel" in the "Preferences"-window will update the window with the currently
used settings. This is done with the System Configuration window every time
it's opened (i.e. to retrieve the current settings simply close the window and
re-open it). You can activate new settings in both cases by dragging the
corresponding files onto the window in question.




Sound:
======

Sound is off by default. Switch it on from the Preferences window (SID Type).

Frodo uses a polling system to playback samples. "Poll Sound Lines" determines
how often it should poll. If you don't poll enough (i.e. your machine is too
slow) sample buffers will overflow, creating a discontinuity in the sound.
The size of the sound buffer and the sample rate (22050Hz) are chosen in such
a way that the polling has to be done every 2cs to avoid buffer overflows.
Polling costs a little extra compared to an IRQ-oriented approach but it's
the only way for a multitasking RISC OS-application which is mapped out between
(WIMP) Polls. In this particular case it acually has its upsides because you
can determine yourself how good a sound you want and how much computing power
you wish to give to synthesis. Frodo's sound emulation is rather sophisticated
and thus needs a lot of power; but if all you do is play some shoot'em up
with laser-sounds overflowing sample buffers won't be all that noticable so
you can get a rather good approximation by polling once per frame (every
312 lines).
If you want to make sure no buffer overflow occurs you have to check how fast
your computer can manage the emulation with sound enabled and SkipFrames=1.
Then PollSoundLines = (speedometer percentage)*312/100 (i.e. for 100% speed
once per frame). Buffer overflows can still occur during WIMP polls so if you
want 100% accurate sound playback you have to force single tasking by pressing
ScrollLock (see "Keyboard"). But unless you have a StrongARM I wouldn't use
much sound at all.

The sound is known to work on a StrongARM RiscPC with the standard RO3.7 sound
modules. It also works on an A5000 albeit very slowly.

You can alter the volume via the menus. A click on the volume bar will alter
the volume immediately to that value, a drag will only alter the volume once
it's completed.

Frodo for RISC OS uses 8 bit logarithmic samples. I don't have documentation
about 16 bit linear and also have serious doubts it would make a hell of a lot
of difference here.

Technical note:
    The module "DigitalRenderer" provides the interface between Frodo's
    sound system and RISC OS. Since Acorn's documentation of the DMA- and
    Channel-Handlers is basically non-existant there might be problems
    with future versions; if you experience problems try using older
    versions of the modules "SoundChannels" and "SoundDMA". Sorry about
    the inconvenience but I ABSOLUTELY REFUSE TO IMPLEMENT SOMETHING LIKE
    THIS VIA VOICE GENERATORS!
    Avoid activating new SoundDMA or SoundChannels modules while the
    DigitalRenderer is active. You DON'T have to rmkill the DigitalRenderer
    for this, but turn off sound emulation first, otherwise there might
    be some confusion, although there shouldn't be any nasty crashes.
    The DigitalRenderer module is documented in the resources directory.
    It's registered and you may use it in your own programs.

More than one Frodo:
    You can run more than one copy of Frodo / FrodoSC simultaneously. Only
    one copy can have sound emulation enabled, though. But that much should
    be obvious...







Display and screen modes:
=========================

The screen plotters are customized assembler jobs. Since I really have far better
things to do than write thousands of drivers for all manner of exotic cases
there are some restrictions:

- Modes with eigen_x > eigen_y are not supported (none of the standard modes fall
  into that cathegory).

- In modes with eigen_y > eigen_x lines are left out rather than columns being
  doubled. You can get the columns-doubled display by doubling the display size.
  This mode will be rather slow, however, since I only optimised the plotters to
  the full for square pixel modes.

So to run Frodo use a square pixel mode. If you still run non-square pixel modes
your computer is probably much too slow for Frodo anyway. All colour-depths and
resolutions are supported. 16 and 32 bpp modes will take longer to plot because
colour-lookup couldn't be avoided there and of course we're seriously struggling
for bandwidth there. The window will always be scaled to such a size that one
(horizontal) pixel of the C64-image corresponds to <zoom_factor> pixels of the
screen. Thus the display size is only dependent upon your physical pixels, not the
eigen values.

The reason SkipFrames affects the emulation speed so much lies not with my
plotters (which are more or less as fast as possible) but with Frodo being
intelligent enough not to build a frame if it won't be displayed anyway.

If you switch to a screen-mode with a different colour-depth you'll notice that
the image Frodo plots looks completely off. The reason is that the frame stored
internally is still calculated for the previous mode. Only when the next frame
is built does the image revert to normal. Usually you should hardly notice this,
but it's clearly visible if Frodo is paused. This is not a bug.




Keyboard:
=========

I implemented the keyboard emulation on a low-level basis. That way you can
emulate more than one key being pressed at the same time. The downside of this is
that the host machine's key-buffering cannot be used, so you have to keep a
key pressed until the emulator recognizes it. This becomes frighteningly apparent
in FrodoSC.
The emulator window needs the input focus for keys to be passed to the emulator.
The keyboard layout is basically like a real C64's; some keys had to be remapped,
though.


C64 keys:
---------

Alt        - CBM
"="        - "=" (Remapped? Yes. On a real C64 this would be "+")
"\"        - <Arrow up>
Insert        - <Insert> (shift+del)
Delete        - Guess...
Home        - Ditto. (with shift: <Clear>)
Esc, Break    - <Run/Stop>
num"+", num"-"    - "+", "-"
F1-F4        - F1, F3, F5, F7 (like on a real C64 you get F2, F4, F6, F8 by
          pressing shift);

Everything else should be obvious.


Frodo control keys:
-------------------

F5        - Toggle sound emulation (between None and Digital)
F6        - Enter SAM
F7        - "Restore"
F8        - Issue Reset

PageUp        - Increase SkipFrames
PageDown    - Decrease SkipFrames

num"/"        - Toggle 1541 emulation state
num"*"        - Toggle speed limiter

numLock        - Toggle keyboard joystick mapping
ScrollLock    - "on": make Frodo single-task, i.e. it takes over the machine
          and doesn't poll any more. "off": multitask (default). This
          will only work if Frodo is not paused.


If the emulator window has the input focus only F9-F12 with combinations of
Shift and Ctrl are passed on to other WIMP tasks. Everything else is claimed
by the emulator.


Keyboard Joysticks:
===================

Two joysticks are supported. If numLock is on only Joystick 1 is active and
mapped to port 2. If numLock is off Joystick 1 is mapped to port 1, Joystick
2 becomes active and gets mapped to port 2. Default settings are


Joystick 1:
-----------

num"1"        - Keyboard joystick left
num"2"        - right
num"3"        - up
num"."        - down
num<enter>    - fire


Joystick 2:
-----------

"z"        - left
"x"        - right
"f"        - up
"c"        - down
"g"        - fire


The settings can be changed in the Configuration window. Place the mousepointer
over the icon for the joystick's direction and press the key you wish to
map it to until it's recognized (this is a low-level key scan). Avoid mapping
the cursor-keys or any of the Frodo control keys (see above). The <Break>-
key is a special case: it maps the key to 255 which means "no mapping". This
can be used to turn a keyboard-joystick off (if for instance you need only
a joystick in port 1).
Since there are internal keynumbers for the mouse buttons you can also define
the mouse buttons as keyboard joysticks! This might be nice for some games
that only use three directions (like left/right and up). Since this would lead
to all sorts of events being triggered in multitasking mode you have to go
singletasking in that case. Frodo will clear the mouse buffer when multitasking
is resumed so no matter what you click during singletasking, there won't be
a cascade of mouse clicks reported afterwards.

The "Joystick Swap"-entry in the Preferences window does not affect keyboard
joysticks. Use numLock for that.




Real Joysticks:
===============

The Acorn joystick interface is supported. You have to make sure the driver
modules are loaded before Frodo is started. Apart from that the joysticks have
to be activated from the Preferences Window. If Frodo is already running at the
time you're loading the joystick driver modules you can still use joysticks if
you first disable, then enable joysticks from the Preferences window (don't forget
clicking OK after both operations).
The "Joystick Swap"-entry in the Preferences window applies to _real_ joysticks
only.





Loading files:
==============

Apart from the usual "LOAD..."-commands you can also load native C64 files (the
filetype is usally &064 as used by Breadbox) by dragging them onto the emulator
window. You can't avoid typing a "RUN" in the emulator window.




1541 Emulation:
===============

This is usually a waste of time in Frodo since Fastloaders won't work then either
(although there are some exceptions like for instance Hawkeye which will run OK
with Frodo + 1541 emulation ONCE THE ENTIRE GAME HAS BEEN LOADED, i.e. the levels
get loaded OK.)
In FrodoSC it works very well and most Fastloaders will work OK. Of course
emulating C64 and 1541 on a single cycle basis is slooooooow!
If you activate 1541 emulation the emulator will "hang" for a little while during
which the drive is reset. Apart from that the LEDs for drives 9-11 will be greyed
out. Even simple operations like loading a directory will take considerably longer;
it's not broken, just wait for it! You shouldn't access the drive while it's still
resetting (you can see when the drive becomes idle by watching the speedometer).





Drive Emulation:
================

RISC OS users can also use D64 images in DIR mode if they have D64FS loaded. The
advantage: you also have write-access that way -- the D64 drive emulation in the
current version of Frodo is read-only. Also I have a D64 image that doesn't work
OK in D64 mode but does in DIR mode with D64FS.





Setting drive paths:
====================

There are two ways to make images (D64 / T64) or directories accessible through
one of the four drives:

1) Drag the image/directory to the writable path icons in the preferences window,
   set the emulation mode (Frodo will try ruling out silly combinations like
   running a directory in D64 mode) and click OK.

2) Drag the image/directory to the drive icons in the emulator pane. This will
   update Frodo's configuration immediately, you don't have to press OK in the
   Prefs window or anything. The disadvantage is that the wrong drive emulation
   mode might be chosen (i.e. the previous one), so make sure you have the right
   type chosen for the drive before you do this.

If you have 1541 emulation enabled I strongly advise you to NEVER change the
drive path unless the program specifically tells you to.





Speedometer:
============

Obviously this shows the speed of the emulation compared to a real C64. The border
type indicates whether the speed limiter is on or off: slab in means off (default),
slab out means on. It's also clickable, i.e. clicking on it will toggle the speed
limiter state.





SAM:
====

SAM can't be called when Frodo is in single tasking mode. Unfortunately no Task
Window can be used for this and I sure as hell won't rewrite SAM so you'll have
to put up with a non-multitasking VDU4-type window. Most of you won't ever use
SAM anyway.




REU:
====

This is a RAM extension unit. I have no idea how to use it (they must have come
up after my 8bit time...). The important thing is that activating a REU will
claim memory (of approcimately the size of the REU) so if you're low on memory
Frodo might fail and abort. So don't toy around with this in memory-tight
situations when aborting would lead to data loss.








ADDITIONS TO FRODO 4.0:
=======================


The Save RAM-entry:
-------------------

This is NOT a snapshot facility; but sometimes I find it rather useful to read the
C64's RAM. The first 64kB of the file are the normal 64kB RAM of the virtual C64,
the next 1024 bytes are the colour-RAM. If 1541 emulation was enabled the next
2048 bytes will be the 1541 RAM.



The Snapshot-entry:
-------------------

This will make a snapshot of the current emulation state. Or to be more precise,
the emulation is continued unto the next vertical sync, then the emulation state
is saved. Therefore if you make a snapshot from a paused emulator it will resume
operation first!
I'm not all that sure what I have to save and what not, quite frankly; but I seem
to have guessed rather well since everything I tried so far appears to work. One
of the most important issues to me was to make snapshots of Frodo and FrodoSC
work with either variant (i.e. you can run FrodoSC to satisfy a Fastloader, make
a snapshot when it's done and actually use the program with Frodo). That too is
not exactly trivial but it seems to work as well. Just don't make snapshots during
disk-operations! And unless you have 1541 emulation enabled you have to restore
the drive paths by hand because they're not saved in the snapshot.
The snapshot files might be system-dependent in their current form. The reason
is that on a number of occasions I dump an entire struct to file; the alignment
within the struct might differ on various machines. But since Snapshots are
only available on RISC OS at the moment it's hard to tell.

IMPORTANT NOTE:
    If you save a snapshot with 1541 emulation enabled the resulting
    snapshot will contain the pathname of the D64 image that was selected
    at the time. If the location (or the path syntax) of this file changes
    you have to change the snapshot file as well. One possibility would be
    to just load the snapshot, ignoring the error, selecting the correct D64
    image by hand, then making a new snapshot. The other would be changing the
    pathname in the snapshot directly. It's stored in a 256 byte block in the
    last 3kB of the file. You have to make sure you use overwrite-mode (DON'T
    CHANGE THE SIZE OF THE SNAPSHOT FILE!!!) and terminate the name with a 0.

How to load a snapshot? Just drag the file onto the emulator window. These are,
after all, not the dark ages...

Should you get a scrambled screen after loading a snapshot (I think I got that
problem under control now but "never say never...") you can usually cure that by
loading the snapshot again (without doing a reset or anything, just drag it onto
the emulator window again). I don't think this should happen any more but just
in case...







THANKS:
=======

- Christian Bauer for writing Frodo - a truly excellent emulator.
- Richard G. Hallas for testing, suggestions and drawing additional icons.
- Nick Burrett for porting GCC ;-)








LEGAL ISSUES:
=============

The source code I wrote during the Frodo port can be downloaded from the Frodo
homepage (when Christian Bauer gets around to adding it). It falls into the same
cathegory as the other bits of Frodo source code -- see "legalmush" in the Docs
directory.
One thing that does NOT fall into that cathegory are the screen plotters. These
are only provided in the form of an object file, no source code. You may not use
them in ANY program but Frodo, commercial or otherwise, without my explicit
permission!








Now enjoy!





Contact:
--------

Andreas Dehmel
Am Schorn 18
82327 Tutzing
Germany

email:    [e-mail]
    (but since I graduated last fall this account will run out soon;
    any Acorn-related jobs for a CS-graduate out there?)








"Everybody's doin' the Toxic Waltz
 Kick your friend in the head and have a ball
 Come on and do the Toxic Waltz
 And slam your partner against the wall
 Everybody's doin' the Toxic Waltz
 Good friendly violent fun in store for all
 Get up off your ass and Toxic Waltz
 If you hit the floor you can always crawl!"

        (Exodus - The Toxic Waltz)