OutcaST/gp2x
------------
Atari ST emulation in your pocket!
Jeff Mitchell

For more details and future updates, hit up the OutcaST website here:
http://www.codejedi.com/outcast

For additional documentation, see the manual for the GP32 version, which
shares many similarities.

Installation
------------

Application:
  Copy OutcaST.gpe to your GP2X's SD card -- the root of the card, or anywhere
  you deem appropriate.

ROMS (Atari ST Disk Images):
  Create a directory on your SD card: /roms/atari-st - all lowercase!
  Copy .ST and .MSA disk images to this location; .zip versions of these files
  should be okay as well (though I'm not sure if they work in the first alpha
  of the emulator :)

TOS Operating System ROM:
  The Atari ST has an operating system - one of the first GUI OSes, that
  predated MSWindows by a long mile. This file could be of various versions
  so we're looking for TOS 1.02 (sometimes called 1.20) ideally, best the
  American or UK versions. TOS 1.04 (1.40) may work, as should 1.0 .. but
  1.02 is the best. It might be called TOS.ROM or TOS.IMG or any number
  of variations... but for our needs, call it TOS.ROM and drop it into
  your /roms/atari-st folder on your SD card.

Features
--------

Things should be working very well by now, though with a few oddities.

Load/save states working
Chipmusic working pretty well
Disk menu working
Frameskip menu working
Throttle menu working
Virtual keybord working
etc..
Runs fast :)

Things are good :)

Controls
--------
Controls vary by control mode; some things to note..

Menus:
Joystick up/down - move selection bar up and down
Joystick left/right - page selection bar up and down
X - usually means cancel, though varies by menu
B - usually means select option, though can vary
Read the menus and screens for details.

Gameplay:

Default control mode is "Both" Joystick and Mouse at the same time; works
pretty well in most cases, but you may need to fine tune into other modes.

In both-mode, gp2x joystick operates mouse and joystick simultaneously, while
X is fire and A/B are left/right mouse buttons.

In joystick mode, only the joystick is operated and thus X is fire.

In mouse mode, only the mouse is operated and thus A/B are left/right click.

In cursor mode, the gp2x joystick and shoulder buttons operate the ST
cursor keys -- handy for games like Captive and Dungeon Master.

Custom mode is not yet built.

SELECT brings up and dismisses the virtual keyboard; use it for entering
keys or typing into the ST.

START toggles the main runtime options menu.. very important!

------
ENJOY!
------

Release 010 - Minor fixes for 009
-----------
CHG: The mouse hack improves things for some games, but can make the
  mouse pointer jump around in some cases; as such, the mouse-hack is
  now togglable, and defaults off.
  o Toggle the mouse-hack on and off in the Mouse Speed submenu from
    the main menu

Yes, I'll add a config file very soon so you can set which options you
want which way at load-time. (ie: Mouse speed, mouse hack, control mode,
custom controls, etc etc.)

Release 009 - Getting back into the swing
-----------

NEW: Aesthetics
  o ripped Atari TOS font
  o disk picker menu now uses a "GEM" theme so looks more authentic
  o disk picker menu and options menu now use TOS font
  o 'unpack demo' on load uses TOS font
  o 'FIRING UP..' is now using TOS font
NEW: Mouse hack is always active; if a problem (let me know!) I
  will make it a config file or menu controllable setting to enable/disable
  o makes a few games more playable (hard drivin' for instance, among others)


Beta 008 - Hope I didn't break anything
--------

CHG: When you 'queue up' some menu movement (such as hitting 'right' to
  scroll a page down in the disk listing), hitting a A/X/Y/B will clear
  the queue so that entering a submenu won't accidentally scroll somewhere
  unintended

FIX: In A/B/remove submenu after picking disk image, hitting 'X' just
  exits as it was meant to (B activates); used to also activate so there
  was no cancel option, which could lead to accidental disk deletions :/

NEW: Mouse+Cursor control mode; when you are in this mode, the joystick
  operates the mouse and the shoulder buttons are left/right mouse-click.
  The A/B/X/Y buttons are the 4 cursor keys, and the volume up/down buttons
  do Insert/Home -- this should make Dungeon Master and similar games
  much more playable .. mouse and cursor all at once!


Changes for Beta 007 - really getting sweet :)
--------------------
REM: Sampled audio was not half bad (not half good) in 006, so the stretching
  or playback frequency is definately a way to go; perhaps theres clipping
  too -- not in the shifter code of the audio, but in the ST emulation
  itself and not the GP2x-feeder.. hmm..

CHG: Futtled with the balance between YM and sampled-playback and I think
  I've gotten it much better (though still not perfect for samples.)
  Xenon 2 loader, Starglider 1 loader, Turrican 2 intro, all sound not
  too too bad and no crashing. Xenon 2 YM demo and such all sound great,
  so things are much better.
  o StarGlider sounds amazing :)
  o Spherical.. love that game :)

FIX: If the filename would overlap into the database display column,
  truncate the display of the filename so as not to cause too much trouble

NEW: Added fullscreen scaling (disabled by default); the runtime menu has
  the option to toggle this on and off.
  o Scaling is temporarily disabled while virtual keyboard is present

REM: Yes, I'll add config files soon, so that you can specify to default to
  fullscreen ;) <-- For non-DaveC I bet ;)

NEW: Floppy access indicators; when a floppy drive (A or B) is read, an
  indicator will show in the bottom right so you know what happened; this
  can help .. some games might take forever to load, so if you see a disk
  indicator up, you know its not crashed.. its just loading :)
  o Fullscreen scaling is disabled while the indicators are showing, so if
    you have scaling on, and disking is going on, the screen will jump up
    to make room for the indicator

NEW: Floppy Drive menu; its in the runtime menu (not the Disk Management
  menu), which you mind find confusing at first..

NEW: In floppy menu, you can now 'eject A:' or 'eject B:'; ie: Pull up
  runtime menu, hit Floppy menu.
  o Naturally, inserting a floppy while one is already in, implicitly
    ejects it as it always has.
  o This is really just in case you want to eject a disk and reboot, say..
    normally you'd never use this option

NEW: In floppy menu, you can now save drive A: or drive B: to a disk
  image file on your SD card; ie: pull up the runtime menu, hit the floppy
  menu; if you save the current disk it'll get named FILENAME-save.ST --
  if you had loaded GAU_11.MSA and then save it out, it'll be
  GAU_11-save.ST when saved.
  o if disk name already has "-save" in it, don't append that; so you
    don't get GAU_11-save-save-save.st :)

NEW: Changed menu key-repeat handling; right/left on joystick still queue's
  up a page up/down, and those work pretty quickly; normal up/down on
  joystick will do key-repeat so that you can scroll up and down quickly,
  but not as quick as the right/left paging (ie: so that you can still
  pick disks accurately without sliding all around the one you want.)

NEW: In mouse-mode (or both-mode), the mouse-speed can be double by
  holding down the left-trigger while using the gp2x joystick to maneuver
  o perhaps this should be a toggle, so you don't have to hold it down?

NEW: Mouse speed menu; use it to set the default mouse-speed, that gets
  doubled when you hold left-trigger down


Changes for Beta 005
--------------------
ToDo: Occasional shimmering displays .. the Pawn loader, Time Bandits player
Known issue: sample playback bad; YM audio pretty good
Known issue: CPU clock speed not yet settable

FIX: Medium resolution now displays with correct colours
CHG: Using DaveC's type-2 control scheme to map 16-way control to 8-way
  o http://www.geocities.com/dcancilier@sbcglobal.net/joystick.png
  o ie: No dead zones; ordinals count as ordinals always; only a pure
    diagonal counts as a diagonal.
  o Added a runtime menu to select which bias mode you want

Changes for Beta 004
--------------------
NEW: Volume buttons now actually work
FIX: .MSA (ST-compressed) disk images now work fine; took hours to
  bloody find it, and its one of those stupid-but-invisible buglets :/
FIX: Medium resolution should now work
NEW: In joystick mode, 'Y' is now keyboard SPACEBAR, so that Turrican
  Xenon 1 are happier ;)
NEW: Sorts the disk picker display (by filename)
NEW: The games database is now auto-scanned and the results cached; ie: when
  it loads up the picker, it scans the cache and looks up all the games
  for you; uncached files are scanned and cached. A second column shows
  the gamenames in the picker.
  - I've got a few hundred disks, and the first load took a minute or
    two, but subsequent scans (from the cache) took only 2s or so.. a
    win I think.
NEW: Quitting the emu via the runtime (START) menu will return to the
  gp2x launcher properly.

Changes for alpha 003
---------------------
With the virutal keyboard working now, the emu shoud be getting really quite
useful! Now if only I get a moment to clean up sound and add some more
finesse..

NEW: Virtual keyboard -- needed for entering text or function keys etc of
  course, but also to get into a lot of games; the crack groups often put
  loader demos, or multiple games on a disk, and so you sometimes need to
  hit spacebar, or a number, of function key. Of course, some games require
  keyboard controls, too.
  o hit SELECT to toggle keyboard mode on and off
  o in live mode keyboard will show only 3 rows at a time; scroll the
    key press selection up or down to scroll the keyboard display!
  o hit 'X' to pick a key; while the keyboard is active, the mouse and
    joystick are disabled, but the emu runs along full speed
NEW: Input modes a little more defined
  o Select a mode using the runtime menu (hit START to bring it up)
  o Joystick mode - for using the ST joystick with gp2x stick
    o X for fire
  o Mouse mode - for using the ST mouse with gp2x stick
    o A and B for left and right mouse clicking
  o Both mode - for using both ST mouse and joystick at once using gp2x stick
  o Cursor mode - for operating ST cursor keys using gp2x stick
  o Custom mode - for customizing all the buttons; to be done.
  o While keyboard is active, most modes will be disabled
FIX: YM chipmusic is pretty good now, though sample playback is still
  asshat; I'll work on that more. Always running out of time ;)
NOTE: Most of the START runtime menu should work fine now; CPU Mhz setting
  isn't yet available, but throttle and frameskip and disk management and
  savestates and control modes should all be working!
CHG: Welcome screen text

Changes for alpha 002
---------------------
FIX: Flicker in the menus nolonger exists.
  the real display after each draw. Not efficient or using hardware
  buffering, but hell with it.. menus can be slow.
CHG: Clears the screen and shows a message when firing up the emu, so you
  know to wait a moment and whats going on, and no junk at bottom
NEW: Enabled throttling by default, to approximately 60Hz though the menu
  lets you specify 60, or 50 Hz, or even 30Hz to slow things down.. to
  no throttle at all for max speed (like in alpha 001 default)
CHG: Added a lame comment to loader to make it feel more authentic; I really
  need to add a sin-boncey-text intro for the real deal :)
NEW: Theres an operational ST keyboard for entering text, that is used for
  the Make a Savestate operation in the menu, and a few other spots
NEW: Savestates and loadstates should work; while in the emu, hit START
  to bring up the runtime menu, and hit Make a Savestate; there you can
  enter a filename with the ST keyboard, and save out the state. You can
  load the savestate (.ss file) from the Disk Picker just like loading
  a floppy into the machine is done.

Remember, the run-time menu is toggled on and off with the START button. Use
that menu to swap floppies during runtime, play with frameskip, drop out
savestates, etc; the disk picker in there can also load savestates and look
up what games are on most floppies, etc.
