MAME for OS/2 (version .34 final)
==================================
OS/2 port by Martin Amodeo (mta3206@grace.isc.rit.edu)



Getting started quickly
-----------------------

[[ IMPORTANT NOTE!! ]]:  If you are upgrading from a previous version of MAME,
your previous favorites list may not point to the correct games.  I would 
suggest doing a scan immediately the first time you run this version, which
should remove your favorites list, or deleting your previous MAMEOS2.INI file.

[[ A MORE IMPORTANT NOTE!! ]]:  If you scan for ROMs, some games that were 
approved by previous versions of MAME may be rejected now.  This is because
some games now require some more files.  If MAME complains about a file 
missing, you will have to look for a more up to date version of the ROMs.

[[ ANOTHER IMPORTANT NOTE!! ]]:  A new version of SEAL has been included with
this release of MAME for OS/2.  The new DLL is called AUDIO.DLL.  You may
delete your previous version called SEAL.DLL.  The new DLL will not share the
audio device with other applications by default.  If you wish for it to share
the audio device, set the environment variable SEAL_AUDIO_SHARE to 1 before
running MAME for OS/2.


If you're anything like me, you never read these stupid files and try to run
the executable and figure it out yourself.  If you'd like to try that, you're
more than welcome to, except you may miss out on some features.  Here's the
fastest way to get up and running:

1] Copy the MAMEOS2.EXE file into your normal MAME directory.
2] Run MAMEOS2.
3] Select "Scan and Create Quick List" from the File menu.
4] Select "Open Game from Quick List" from the File menu.
5] Select the game you want to play and press the "Run Game" button.

That's it.  During the game, press P to pause, TAB for settings, and other
normal DOS MAME operations, such as F3 to reset, F2 for self test, etc.


What's new? [Upgrading from MAME .34b3.2]
-----------------------------------------

The following is list of changes and bug fixes in MAME for OS/2 v.34b3.2:
* Upgraded the MAME core to .34 final (more than 1000 games supported).
* Added DART support to SEAL.
* Fixed the screen capture routine so that pasted bitmaps will always
  be rendered correctly.
* New MAME core user interface with more options.
  - The MAME core will not pause when you bring up the settings screen
    (using TAB) anymore.  You will have to explicitly pause the game.
  - Sound volume and picture brightness and gamma settings are available
    by pressing the ~ key.


What's new? [Upgrading from MAME .31.x]
---------------------------------------

What isn't??  The emulation core has been updated and many new games 
are now available.  You may find that many of your old games are 
marked as bad sets by the Scan procedure.  You will have to download 
an updated ROM set if this is the case.  I switched from my crappy 
Watcom compiler to GCC which offered MUCH better optimizations with 
FAR fewer quirks.


[[ STANDARD DISCLAIMER ]]:  This is by no means a mature product.  I
do not guarantee all or any of the functionality contained herein.
I, and everyone on the MAME team, take no responsibility and cannot
be held accountable for any loss, be it in the form of data or 
physical health, due to the use of this product.  I cannot and will
not be held accountable for any crimes that are committed, nor the 
destruction of any large landmasses during the use of this product.
Your use of this product marks your agreement to these terms.


Questions you may have
----------------------

* That startup logo is very pretty, but I get a little sick of it after a 
  while.  How do I get rid of it?
  Well, you don't have to get rid of it, but you don't have to sit there and 
  wait for 5 seconds for it to go away.  If you press a key, it will go away 
  and the main MAME window will open.

* Why does it crash on startup in DIVE.DLL with my Matrox graphics card?
  There is a bug in the Matrox unified driver in versions less that 2.20.055 
  which will cause MAME to crash on startup if you are in a 24 or 32 bit color
  mode.  If you upgrade to 2.21.055, MAME will start but you will not see the
  pretty colored gradient initial test pattern for some odd reason.  The rest
  of the program will work properly however.  Personally, I just keep it in 16
  bit color modes because the drivers themselves seem to be much more stable
  that way.

* Ok that information didn't help.  Why is it still crashing with my Matrox
  graphics card?
  Do you have EnDIVE enabled?  If so disable it immediately.  It breaks many
  (or in my experience EVERY) DIVE app.  Perhaps in future driver releases
  it will be less broken, but for now, disable it.  (You can find this setting
  on the "Advanced" page of your Matrox settings notebook.)

* I disabled EnDIVE.  Why does it still crash with my Matrox card?
  Hopefully it shouldn't.  I have changed the initial background from an
  RGB (24 bit color) image which DIVE seemed to choke on sometimes, to a
  16 bit color one (and also changed it from flowery rainbow colors to a 
  "manly" greyscale).  If you still can't even get MAME started, e-mail me
  with a full description of your system including:  processor type/speed,
  video card, driver version, OS/2 version, and any FixPacks you've installed.

* Why doesn't game xxx run properly?  I thought you said this was MAME .34.
  Probably an error on my part somewhere, but it could be a DIVE or MMPM
  quirk of some sort.  Also note that not all of the supported games work
  in the DOS version either.  If you notice a problem that I did not mention 
  in BUGS.TXT and it works fine in the DOS version, please mail me about it.

* What did you do to my mouse and how do I stop that from happening??
  By default, MAME will grab control of the mouse and the mouse pointer will 
  disappear.  If you would like to change this, change the input options.  
  You can change the defaults or on a game by game basis.  To make the mouse 
  re-appear if it is "grabbed", just pause the game (with the P key).

* So where's the sound?
  Can't you hear it?  Use OS/2's standard volume control or your favorite
  mixer to change the volume.

* My volume is at max!  I still don't hear anything!
  Do you have a WinOS/2 or DOS session running that is using the sound
  card?  Close any non-OS/2 native applications that may utilize
  digital audio.

  Another possibility is that you have picked settings that are not
  supported for your sound card.  MAME does NOT auto-detect ANYTHING
  related to sound.  It will blindly accept any parameters you pass it,
  so choose correctly or disable sound.

* When I start up a game, I get an MCI error.  Why?
  Please record the MCI error(s) and e-mail me.

* Why does/doesn't my game's sound get interrupted when another part
  of the system makes a noise?
  It should not anymore.  If you would like it to, set the SEAL_AUDIO_SHARE
  environment variable to 1 prior to running MAME.

* I don't like the screen size.  How do I change it?
  Just resize the window.  If your mouse pointer is "grabbed", you have to
  pause the game first.

* Why is the emulation SO much faster than MAME .31?
  Because my previous compiler (Watcom 10.0) was a piece of garbage.  To
  amend this problem, I upgraded to Watcom 11.0.  The problem persisted
  (if not worsened!).  I have now decided to dump Watcom altogether and
  use a real compiler.  I'm using EGCS with all of the optimizations 
  enabled.  Big difference huh?

* The emulation is slower than I'd like it to be.  How can I speed it up?
  Perhaps you have the sound quality set very high.  Try reducing the
  frequency and quality of the sound to increase speed.  You may also
  disable the sound for a big speed boost.

* I'm at 8KHz 8-bit audio.  Why is the emulation is STILL really slow?
  Perhaps your computer doesn't have the necessary "horsepower" to run
  this version of MAME.  Try disabling the sound altogether and 
  allowing some frame skipping to occur.

* The DOS version doesn't slow down that much with sound enabled.  Why?
  The DOS version makes use of the FM synthesis capabilities of your
  sound card.  MAMEOS2 does not and has to use your main CPU to 
  synthesize FM.  This requires a lot more overhead.  Perhaps in a
  future release, I'll figure out how to use the MIDI subsystem to
  synthesize FM.

* Why is the sound really bad?
  Perhaps you have the sound quality set very low.  Try increasing
  the frequency and quality of the sound.  The sound may also be
  of poor quality if you are not operating at full emulation speed.
  Try increasing your frame skip or allowing automatic frame
  skip regulation.  If you are operating at full speed and it
  still sounds bad, then this may be a bug.  Write to me about it.

* MAME crashes when I do xxx.  Why?
  Congratulations!  You found a bug.  Check the BUGS.TXT file to see if I 
  already knew about it and if not, write me.

* Reading some of these questions makes me nervous.  Is this thing really 
  unstable?
  Not at all.  In all of my work and testing on this program I have NEVER had 
  an unrecoverable system crash resulting from MAME.  The worst that will 
  happen is that the application itself will crash and since OS/2 actually 
  has some memory protection, etc., your system will come back to you 
  unharmed.  All of the situations where the application itself crashes have 
  been reproducable in my experience.  So, if you find that doing a certain 
  sequence of things or starting a certain game results in a crash, don't do 
  it! (and tell me about it)

* Why did you bother porting MAME to OS/2?  The DOS version works just fine 
  in OS/2.
  Why not?  I feel that I've offered some nice enhancements that the DOS 
  version doesn't have.  Now I also have nearly comparable speed and 
  comparable sound quality.

* What are those goofy looking happy faces?
  They indicate the state of the LEDs on the coin slots or start buttons of 
  various arcade machines.  If you don't like them, you can have your 
  keyboard LED's flash instead.  Select the option under Game->OS/2 Specific
  Options.

* I have a joystick, but MAME doesn't detect it.  Why?
  You probably have not installed the joystick device driver. Unzip the
  JOYSTICK.ZIP file and read the README file.

* I have my joystick configured, but I can't move all the way to the
  << INSERT A DIRECTION HERE >>.
  Sounds like you need to recalibrate the joystick.  Go to the input options
  and click the Recalibrate button.  Then move the joystick to all extremes.

* Why does my Warpcenter CPU meter or other CPU meter say that my processor
  is being 100% utilized while MAME is running?
  Probably because it is, but maybe not.  In order to get accurate timing,
  to regulate to 60 fps, I had to use a busy wait loop because the 
  DosSleep function has a granularity of 32 ms.  My busy wait loop is not
  wasteful or a complete processor hog, however.  In my loop, it calls 
  DosSleep with a parameter of 0 which will allow another program of equal
  or higher priority to execute.  If there is no such program, then MAME
  will continue to execute.  You will notice that although your trusty CPU
  meter is pegged, your system is still very responsive.  If this bothers
  you however, you can use TIMER0 for timing.

* I still don't understand why my CPU meter is pegged.
  Most of the CPU meters measure utilization by idle time.  They do this by
  creating a thread of idle priority class and tallying up how much time it was
  allowed to execute.  MAME will not allow any threads of idle priority to 
  execute while the emulator thread is running because it is never idle.

* What is TIMER0?  Do I want to use it?  Do I need any special software?
  TIMER0 is a device driver present in Warp 4 and (don't quote me on this)
  Warp 3 Fixpack 26 and higher.  It allows me to block my emulator thread for
  a much finer measurement of time than the standard OS/2 functions.  This 
  allows MAME to give some CPU slices back to the operating system (and
  other applications) for a period less than 32ms.  The drawback is that there
  are some DOS applications, including WinOS/2 itself, that cannot function
  while this driver is being used by an OS/2 application.  If you need to run
  any DOS or WinOS/2 applications while running MAMEOS2, do not enable this
  option.  Otherwise, I recommend it.

* When are you going to implement full screen support?
  When SciTech releases their port of the MGL library for OS/2.

* Are you going to keep up with the latest DOS versions?
  I'm certainly going to try!  The MAME team moves very quickly, but given
  enough time, I'll be able to get the OS/2 version out at around the same
  time as the DOS and Windows and Unix versions.

* These games are too hard.  How do I cheat?
  Under the game menu, select the Cheat option.  This option will be 
  marked when cheating is enabled.  Next go to the MAME settings with
  the TAB key and pick the appropriate cheating options.  This can
  be enabled or disabled at any time, while a game is running or not.

* What happened to the pretty rainbow colors?
  I decided to change it, partly to easily identify different versions of
  MAME, partly to look less "frilly" and more "business-like". ;)

* My quick list / favorites list doesn't look the way I remember it.  Why?
  Did you re-create it?  You should.  The indicies that I used to look up
  the games have changed since previous versions of MAME and your quick 
  list probably points to garbage by now.  Also, you may have noticed that 
  the full game names are now displayed. :)


Front-end interface
-------------------

Command line-
  This version of MAME does not have command line parameters like the DOS 
  version.  The only parameter that is accepted is the name of the initial 
  game to run or a diagnostic switch "-diag".  Anything else is ignored.

Diagnostic mode-
  If you are having a specific problem that is not documented in the BUGS.TXT
  file, I may ask you to run MAME in diagnostic mode.  If you do, MAME will
  test your TIMER0 capability, joystick driver, and DIVE capabilities and
  write the results to what should be a very informative DEBUG.LOG file for
  me.  When you run in this mode, you will see one window pop up with the
  16 bit greyscale pattern.  Close this window.  Another one will pop up
  with vertical bars of different colors.  Close this and the test is complete.

Game control-
  While in a game, use the controls defined for that game to play.  Press TAB 
  to view or change these settings.  Press P to pause or resume.  Press ESC 
  to stop the game (must be unpaused).

The Quick List-
  MAME will maintain a "quick list" of games that it can find that have a 
  full, valid set of ROMS.  When it searches for ROM images, it looks first 
  in a directory with the name of the game, next in a directory with the name 
  of the game in a subdirectory named ROMS, next in a ZIP file of the name of 
  the game in the current directory, next in a ZIP file of the name of the game
  in a subdirectory named ROMS.  If a game does not show up on your quick 
  list it is because 1] MAME .34 beta 3 does not support this game, 2] the 
  directory or ZIP file is not named properly, or 3] the ROMs are incomplete 
  or corrupt.  Any errors are reported in Debug.Log during the scan.

  The Quick List is an exhaustive list of everything that you can run with
  MAMEOS2.  This list can get to around 800 or more entries.  This can be 
  very inconvient to search through especially if you mainly only play a
  handful of games.  Because of this, I created a Favorites List.  You may
  add to or remove from this list and select and run games from it.  You
  can still run games from the Quick List itself (a game does not have to
  be on the favorites list in order to run).  This is just (hopefully) a 
  convenient way of getting to games you like best.

Input Options-
  If no game is running, you will be able to access and change the default 
  input options.  If a game is running, the options you change will apply 
  only to that game.  You can select keys (CTRL-Left click for multiple 
  selections) from the "Rapid Fire Keys" list box to make these keys 
  automatically repeat at the specified interval.  This is nice for games 
  like 1943 where you have to fire many shots very quickly.  Mouse input can 
  be enabled or disabled here also.  You can choose whether or not MAME can 
  grab the mouse pointer while the games are running (I recommend that you let
  it).  Also if some game has weird X or Y axis settings, you can flip these 
  axises.  You can choose to emulate an analog joystick with the mouse if you
  don't have (or want to use) a real joystick for games that require one (like
  Star Wars and others).  If your joystick calibration is off, you can 
  recalibrate it here by clicking the "Recalibrate" button and moving the 
  joystick to all extremes.  The crosshair will move as you move the joystick.
  You can also disable joystick input altogether here.

Scan lines-
  You can enable scan lines in the Display menu.  You will have to restart 
  your emulation (using Game->Reset) or start a different game for the 
  setting to take effect.  To actually see the scan lines, you will need to 
  scale the window to double size at least.  Scaling to "actual size" will 
  guarantee that you will not see any scan lines.

Frame counter-
  You can enable a frames per second indicator using this menu option.  The
  indicator will appear in the game window itself and will update four times
  per second, also showing the current value of frame skipping.

Enable TIMER0-
  See questions section above.

Frame rate regulation-
  These options allow you to choose how your frame rate is regulated (if at
  all) by MAMEOS2.  I added these options now because the sound will sound
  horrible if you are not emulating 100% of the CPU cycles in the proper
  time.  Frame skipping allows one of the most time consuming parts of the
  emulation process to be bypassed from time to time.

  You can choose to automatically regulate the frame skipping if you want
  MAMEOS2 to determine on-the-fly what it would need to operate at 100%.
  This setting will lead to the best audio quality, regardless of your
  audio settings.  If you see that this rate tends to fluctuate too much,
  making it difficult to play the game, you can manually set the skip
  rate yourself by disabling this option.  You can also specify the
  maximal amount you want the automatic skipper to go in these options.
  A game is probably unplayable if you have to skip more than about 3
  frames.

  You can also choose to enable or disable the automatic slowing down of
  the emulation when it is needed.  This option will only kick in if the
  frame rate is more than the game's desired frame rate and will give 
  back some CPU slices to the OS if TIMER0 is used in conjunction with it.
  This can be (and probably should be) used in conjunction with the frame
  skip options.  I highly recommend it for the best speed regulation.


That's it!
----------
  I hope you enjoy this version of MAME.  If you have any questions, 
  suggestions, or comments, feel free to e-mail me (mta3206@grace.isc.rit.edu).
