  XMAME/XMESS DOCUMENTATION
  Juan Antonio Marmnez jantonio@dit.upm.es <mailto:janto-
  nio@dit.upm.es> and Hans de Goede hans@highrise.nl
  <mailto:hans@highrise.nl> and Rene' Herrmann (4 doc/sgml)
  rene.herrmann@berlin.de <mailto:rene.herrmann@berlin.de>
  v2.1, xx. July 2000

  xmame/xmess documentation with an installation guide, the faq (fre-
  quently asked questions), hints, tips and tricks, the changes on the
  code and many more!
  ______________________________________________________________________

  Table of Contents





















































  1. Introduction and Links

     1.1 Keep everything up-to-date!
     1.2 Some Links
     1.3 Pending Jobs - or TODO

  2. Compiling, Setting Up and Starting xmame/xmess

     2.1 Requirements
     2.2 Follow these steps to compile xmame/xmess
     2.3 If you have problems compiling, installing and starting xmame/xmess...
     2.4 Compile Notes for Specific Operating Systems
        2.4.1 Linux i386
        2.4.2 Linux powerpc
        2.4.3 IRIX
        2.4.4 HPUX
        2.4.5 ULTRIX
        2.4.6 SunOS & Solaris
        2.4.7 Openstep

  3. Xmame frequently asked questions

     3.1 What is mame?
     3.2 What is mess?
     3.3 What is xmame/xmess?
     3.4 What are the differences between mame/mess and xmame/xmess?
     3.5 What hardware and operating systems are supported?
     3.6 My system is supported but xmame/xmess give me errors and fails. Why?
     3.7 What is the role of the xmamerc/xmessrc file?
     3.8 What is the syntax of the xmamerc/xmessrc file.
     3.9 Where do roms, images, samples, highscores, configfiles, etc go?
        3.9.1 Roms/Samples
        3.9.2 Read/write Diskette Images
        3.9.3 Rom Cartridges/Read Only Diskette Images
        3.9.4 Artwork
        3.9.5 Xmame configuration
        3.9.6 Game configuration
        3.9.7 Game state
        3.9.8 NVram
        3.9.9 Mem cards
        3.9.10 Screenshots
        3.9.11 Highscore's
        3.9.12 hiscore.dat
        3.9.13 cheat.dat
        3.9.14 history.dat
        3.9.15 Input logs
        3.9.16 Xmame/xmess still can't find file's / store highscore's
     3.10 How do I start xmess/xmame ?
     3.11 What are the command line parameters for xmame/xmess?
     3.12 What keys does xmame/xmess use?
     3.13 Why doesn't a game have sound?
     3.14 My sound seems lagged? / My sound Clicks? / What does -bufsize do?
     3.15 Why doesn't a game work?
     3.16 What are PROMs?
     3.17 Why is xmame/xmess slow?
        3.17.1 SPEEDUP # 1 - Inline compiling
        3.17.2 SPEEDUP # 2 - Direct Graphics Access
        3.17.3 SPEEDUP # 3 - NASM
     3.18 I've got a dual processor machine. What can I do to take full advantage  of this?
     3.19 Why doesn't my joystick handle diagonal movement correctly on my Intel  x86 system?
     3.20 How do I enable XinputExtensions X11 based joystick in Xfree86?
     3.21 How do I read a manual page?
     3.22 Why do I get gz_open symbol not found while compiling?
     3.23 Why do I get zlib.h not found?
     3.24 Where can I get the latest version of xmame/xmess?
     3.25 Where can I send fixes, bug reports, suggestions, or money?  :-)
     3.26 What if my question is still not answered?

  4. Display subsystem specific comments & notes

     4.1 FX-Mame a glide driver for xmame
        4.1.1 Requirements
        4.1.2 Compiling and Installing
        4.1.3 Running
        4.1.4 Common Questions (FAQ)
        4.1.5 Present Limitations/Bugs
        4.1.6 Future Work
        4.1.7 License
        4.1.8 Version History
        4.1.9 Author
     4.2 GL-Mame a OPENGL driver for xmame
        4.2.1 Requirements
        4.2.2 Compiling and Installing
        4.2.3 Running
        4.2.4 Cabinet Models
        4.2.5 Common Questions (FAQ)
        4.2.6 Present Limitations/Bugs
        4.2.7 Future Work
        4.2.8 License
        4.2.9 Version History
        4.2.10 Author

  5. contact information and credits

     5.1 Mail
     5.2 credits

  6. Legal issues and copyrights concerning mame/mess

  7. ChangeLogs

     7.1 The mame/mess ChangeLogs
     7.2 The Unix ChangeLog


  ______________________________________________________________________

  1.  Introduction and Links

  1.1.  Keep everything up-to-date!

  The most recent copy of this guide, the xmame-sources and many more
  can be found on the xmame project homepage at http://x.mame.net/
  <http://x.mame.net/>

  1.2.  Some Links


  o  The official M.A.M.E home is at http://www.mame.net
     <http://www.mame.net>

  o  The realy best ROM site on this planet is at http://www.mame.dk/
     <http://www.mame.dk/>

  o  grustibus the very good frontend (if you gnome)
     http://grustibus.sourceforge.net/
     <http://grustibus.sourceforge.net/>

  o  Mame Action Replay Page for those who want to have a  look at other
     monitors at http://marp.retrogames.com/
     <http://marp.retrogames.com/>

  o  and of course dont forget our project homepage at
     http://x.mame.net/ <http://x.mame.net/>

  1.3.  Pending Jobs - or TODO

  If you think you can help with the todo list or you can make a
  contribution that you feel is interesting, please send mail to the
  xmame/xmess coordinator.  See ``Mail'' for contact information.


  o  optimise mouse warping

  o  remove osd_input_init_post, add display ready flag

  o  updating of fps is off (dirty marking problem) with vector games

  o  update porting.txt

  o  convert all remaining sound-drivers to plugins

  o  rewrite display/input code to be more modular, oo-ish and usable as
     a seperate library.

  o  split -[no]scanline option in emulated and real scanline options

  o  add an option to specify which resolution to use, add clipping and
     panning if it doesn't fit and use it anyway.

  o  use pentium TSC for uclock where available

  o  network:

  o  fix since the dos team broke it, find out if the dosnet team is
     still alive

  o  add mouse / joystick support to network play

  o  try converting networksupport to tcp, currently we have no error
     correction

  o  make network code more robust, version check, input settings check
     etc.

  o  check x11-joystick rumors have it it's broken, then again only one
     bug-report so it seems no-one is using it.

  o  fm soundhack for linux-i386

  o  Make which messages are emitted and when configurable. (log-type's
     and log-level), make fileio emit messages about which files it
     tries to open, to help debugging rom-loading problems, and walk
     through all messages xmame emits giving them all a standard format
     like:

     OSD:        Info:    bla
     X11-window: Warning: bla
     Svgalib:    Error:   bla




  o  add scancode 128-255 for none pc keys like F13-F24, more keypad
     keys etc, update all display targets to use this.

  o  Also see the text todo file, kept around to quickly enter stuff
     while hacking: todo <todo>.
  2.  Compiling, Setting Up and Starting xmame/xmess

  Note: This section is not a Unix tutorial. You need to know some basic
  Unix commands to compile and install xmame/xmess.

  2.1.  Requirements


  o  GNU make is MANDATORY in ALL Systems, even if you use a different
     compiler.


  o  On all platforms zlib is now needed since the core uses it, if you
     don't have zlib a stripped version is included with xmame see:
     ``FAQ: Why do I get gz_open symbol not while compiling?'' and
     ``FAQ: Why do I get zlib.h not found?''

  o  You are encouraged to use GNU development environment gcc, gmake
     gnu- ar.  Lots of problems found due to the very permissive syntax
     in gcc, so if you use a strictly ANSI C compiler, you'll get lots
     of warnings, and if the version of xmame/xmess is not fully
     debugged, compilation errors.

  o  Xmame compilation breaks when using egcs-1.1.x or gcc-2.95, use
     -fno-strict-aliasing to fix it. gcc-2.95.1 does work with -fstrict-
     aliasing, and gives a nice speed increase.

  2.2.  Follow these steps to compile xmame/xmess


  1. See ``Compile Notes for Specific Operating Systems'' for platform
     specific compiling information.

  2. See ``Display subsystem specific comments and notes'' for special
     display methods information.

  3. Download the xmame/xmess source files archive.

  4. Move the xmame/xmess source files archive to a suitable work
     directory.  When you extract the archive, sub directories will be
     created under the  work directory.

  5. Rename the source files archive so its extension is .gz, so that
     gzip doesn't complain. For example, change xmame-0.34b1.1.tgz to
     xmame-0.34b1.1.tar.gz

  6. Use gzip -d to uncompress the archive. For example, type:

     gzip -d xmame-0.34b1.1.tar.gz




  7. Extract the files with tar. For example, type:

     tar xvf xmame-0.34b1.1.tar




  8. After extracting the archive, change to the subdirectory created by
     the extraction process. For example, after extracting the xmame-
     0.34b1.1.tar archive, a directory named xmame-0.34b1.1 is created.
     Change to it. This directory is the top of the source tree.


  9. Copy makefile.unix to Makefile, the distributed Makefile is used
     for development and is not a good starting point!

  10.
     Edit the Makefile and change the settings according to your system.
     The default makefile.unix is pre configured to run under X11/Linux.
     Be careful editing this file.

  o  If you intend to compile in X11 joystick support, type the
     following to see the available Xdevice list:

     make xlistdev; ./xlistdev




  o  Choose the desired device and re-edit Makefile, setting the option
     X11_JOYNAME to the correct device.

  11.
     Compile xmame/xmess by typing:

     make




  12.
     If the compile fails, report the problem to the author.

  13.
     *** YOU MAY NEED TO BE root TO PERFORM THIS STEP *** To install
     xmame/xmess, type:

     make install




  14.
     If you want you can now build xmame / xmess for another target /
     display-method, otherwise skip to the next step.

     a. If you want to also build for another target repeat repeat the
        "make" and "make install" steps adding "TARGET=<target>" to the
        make command for example:

        make TARGET=mess
        make install




     b. If you want to also build for another display method repeat the
        "make" and "make install" steps adding "DISPLAY_METHOD=<method>"
        to the make command for example:

        make DISPLAY_METHOD=svgalib
        make install




     c. You can also combine the 2 above for example:


        make TARGET=mess DISPLAY_METHOD=svgalib
        make install




  15.
     In your home directory, create a subdirectory called .xmame.

  16.
     From the top of the source tree, copy the file doc/xmamerc.dist to
     the ${HOME}/.xmame/ directory. (For xmess do this for xmessrc)

  17.
     If desired copy xmamerc.dist to the global xmamerc location as
     "xmamerc" (For mess copy xmamerc.dist to xmessrc). The global
     xmamerc location is defined in the Makefile.

  18.
     Edit ${HOME}/.xmame/xmamerc to match your preferences.  (For xmess
     edit ${HOME}/.xmess/xmessrc)

  19.
     Be sure that DISPLAY and PATH enviromment variables are  set
     correctly.

  20.
     Make sure your ROM images are installed.

  21.
     Start X-Windows. (Unless you compiled for a different display
     method in which case you skip this step.)

  22.
     Start xmame/xmess. For example:

     /usr/games/xmame.x11 dkong




  2.3.  If you have problems compiling, installing and starting
  xmame/xmess...


  o  Read  ``Xmame frequently asked questions''

  o  Read (the recent parts of) ``Changelogs'', they might contain some
     hints about recent changes which aren't fully documented yet.

  o  Check ``Compile Notes for Specific Operating Systems'' for
     operating system specific notes. You may need to do something
     special for your operating system.

  o  Check ``Display subsystem specific comments and notes'' for display
     subsystem specific notes. You may need to do something special for
     your operating system.

  o  If you get an error about gz_open and a bunch of other functions
     not found during linking read: ``FAQ: Why do I get gz_open symbol
     not while compiling?'' and ``FAQ: Why do I get zlib.h not found?''

  o  Be sure that the rompath in your xmamerc/xmessrc is correct, see
     ``FAQ: Where do roms.images.etc go?''


  o  Check xmamerc/xmessrc: is it configured correctly?

  o  Are you getting messages that you are missing files? Maybe you are
     missing PROMs, see ``FAQ: Why doesn't a game work?'' and ``FAQ:
     What are PROMs?''

  o  Is the program in your PATH?

  o  The svgalib/xf86_dga build of xmame/xmess requires setuid root. Are
     your permissions correct?

  o  Try asking the friendly folks at the newsgroup alt.game.mame to see
     if anyone else has experienced the same problem as you.

  o  Try mailing to the xmame mailinglist, see ``Mail'' for more
     information.

  If all else fails, send email to the current maintainer of the
  xmame/xmess project. See ``Mail'' for contact information.

  2.4.  Compile Notes for Specific Operating Systems

  2.4.1.  Linux i386

  Linux i386 is the platform I (Hans) use, so xmame should compile
  without any hassles on Linux i386.

  Some bugs have been found and worked around when using gcc27x, please
  use egcs if available. If more gcc bugs popup egcs will be  made
  mandatory, but I hope that won't be nescesarry.

  It has been reported that some SoundBlaster AWE32 cards do not
  correctly manage get_freespace(). If so you'll get some audio_ioctl()
  calls failed messages in console, and if everything goes right a
  message that xmame/xmess is falling back to timer based audio. If
  this doesn't happen and sound isn't right try forcing timer based
  audio by starting xmame/xmess with -timer.

  Sb64/128pci cards (ensoniq 137x based cards) also do not correctly
  manage get_freespace(), unfortunatly this doesn't result in failed
  ioctl's instead they just ignore the calls. Xmame tries to autodetect
  this and to fall back to timer based audio. If this doesn't happen and
  sound isn't right try forcing timer based audio by starting
  xmame/xmess with -timer.

  Also, I've tested sound using the PC-Speaker driver module. It
  works!!  But needs -timer, again it should do this  automagicly, but
  you know what todo if it doesn't.

  Distribution Specific Comments:


  o  S.u.S.E. Linux: Besides the gcc compiler and libc  libraries, which
     are both from the "d" series, other packages  need to be installed
     or the build will fail. If compiling for svgalib, the svgalib
     package from series "d" installed. If compiling for X-Windows, you
     must have xdevel package from series "x" installed. These packages
     can be installed using the "yast" utility included in the S.u.S.E.
     distribution.

  o  Red Hat Linux is the operating system used by the author.
     xmame/xmess should build correctly under Red Hat Linux. :-)




  2.4.2.  Linux powerpc

  Linux powerpc should work from now on, here's an email from: Andreas
  Varga sid@skater.htu.tuwien.ac.at
  <mailto:sid@skater.htu.tuwien.ac.at>, the linux/powerpc maintainer
  describing the nescesarry steps:

  Required changes to compile xmame 0.34b3.1 on Linux/PowerPC with
  SVGALIB

  Makefile:


  o  enable CFLAGS for linux/ppc

  o  enable DISPLAY_METHOD = svgalib

  o  enable ARCH = linux

  o  remove -lvgagl from LIBS.svgalib in src/unix/unix.mak(only -lvga is
     required)

  Required changes to compile xmame 0.34b3.1 on Linux/PowerPC with X11

  Makefile:


  o  enable CFLAGS for linux/ppc

  o  enable DISPLAY_METHOD = x11

  o  enable ARCH = linux

  Another thing... sound is not working, because sound drivers support
  is currently under development in Linux/PPC kernels...there is an old
  driver that is a hacked Soundblaster driver, and newer 2.1.1xx kernels
  have a sound drivers based on Amiga DMA sound drivers... Once this
  issues are settled there should be a full OSS-compatible driver...
  sound should work then...

  I can't speak about Joystick support...

  The original Linux/PPC target changes in the Makefile were done by me,
  but there are some other changes required to get it to compile...
  Starting from October I will have some more time to work on this, and
  I'll keep you updated...

  Cheers, Andreas

  2.4.3.  IRIX

  Use the generic unix arch for those machines that have no  sound
  support installed. ( xmame/xmess uses the dmedia package or the newer
  AL package on IRIX systems )

  Silicon Graphics provides several native compilers. xmame/xmess has
  been compiled and tested with the normal cc. There were some problems
  with this when using -n32 for new style 32bit code. It does work when
  using -o32 for oldstyle 32 bit code. It should now also work with -n32
  wich is much faster.

  The use of DCC is not recommended (anymore) since it's a c++  compiler
  and thus won't even compile xmame/xmess out of the box due to uncasted
  malloc's.  Changing all these malloc's would be crazy, esp since they
  are not only in the osd part, but also in the core which is not under
  our control. Besides that mame is normal c, so please compile it with
  a normal c compiler.

  Some problems have been reported using GNU linker. It's recommended
  that you use native one.

  2.4.4.  HPUX

  Use the generic unix arch. In HP-UX gcc and gnu-make is MANDATORY.

  2.4.5.  ULTRIX

  Use the generic unix arch.

  Notes received from Danny dboxhoor@iso.vilspa.esa.es
  <mailto:dboxhoor@iso.vilspa.esa.es>

  VERY IMPORTANT!!!

  The xmame/xmess CPU emulators access memory through pointers which are
  sometimes cast to illegal addresses - as far as the MIPS CPU is
  concerned.  The Ultrix operating system is aware of that and fixes
  this "unaligned data access".

  Depending on your system setup, lots of warnings are generated for
  certain games. Fortunately these messages can be disabled by
  executing the command "uac p 0" in the same shell where xmame/xmess
  will be running.

  UPDATE: The new -DALIGN_INTS switch in the makefile fixes these
  unaligned accesses in the source which is probably a lot faster than
  hot fixing them in the kernel segfault handler.

  Use gnu make.

  Compile with the `c89' compiler. Though `gcc' has no problems  with
  compiling and optimizing xmame/xmess, the resulting `c89'  executable
  is faster on an empty machine (read: xmame can use all  cpu & memory
  without competing with other high priority  processes), so you can set
  `frameskip' to 1.

  When compiling with `c89 -O2' don't forget to also use `-Olimit
  1000'.  If 1000 is not enough, the compiler will tell you to  increase
  it.

  2.4.6.  SunOS & Solaris

  There are 2 relevant architecture options available in the makefile:


      ARCH = generic : use this for old SunOs running on Sparcs,
                       but a Sparc running Solaris will usually
                       handle this option too.
      ARCH = solaris : this is the one you should use for Sparcs
                       running Solaris.



  Currently sound is not supported under sunos. The solaris arch does
  support audio.

  If you are using Sun's OpenWindows implementation of X11, then make
  sure that the X11INC and X11LIB variables in the X11 Options section
  of the makefile are set properly. (There are already entries for the
  standard OpenWin directory there that you can uncomment).


  Of course, if you are compiling for X11 then you need to set these
  variables properly, no matter what implementation of X11 you are
  using!  :)

  If you are using Sun's SunPro cc compiler, then the following
  optimisation flags have been reported to be good:


      OPTFLAGS    = -fast -xO4 -native



  Finally, there has been a case of the xmame compilation processes
  breaking over the "ar" program. Most Solaris installations will
  include a set of utilities that conform to the XPG4 standard, usually
  in the "/usr/xpg4/bin" directory. The XPG4 version of "ar" should be
  avoided like the plague.  Ensure that the "/usr/ccs/bin" appears in
  your path before the "/usr/xpg4/bin" directory and everything should
  go smoothly.

  PLEASE NOTE : there is currently not much support for SunOS/Solaris.
  If you have any trouble, try to fix it yourself. If you succeed, send
  a message to the mailing list detailing what you did. If you don't
  succeed, send a message anyway and someone _may_ be able to help you.
  Either way, this is the only way that problems with xmame on
  SunOS/Solaris will get fixed.

  2.4.7.  Openstep

  You must use the OpenStep gnumake, not make. You must also use the
  NeXT/Apple cc rather than gcc. Also use only the optimisation options
  as recommended for OpenStep in the makefile, others will cause the
  resulting executable to crash.  The OpenStep assembler on i386
  architectures is incompatible with the mame assembler cpu cores and
  thus you must use the C versions (Use i386-noasm instead of i386 when
  compiling for i386).

  The supplied complier is based on gcc 2.7.2.1 which will not compile
  src/profiler.c without crashing. To get around this you must turn off
  + optimisation when this crash occurs, re-make to compile this file
  only, then stop the make, re-enable optimisation and continue.

  On an OpenStep keyboard the functions keys do not all operate as
  expected.  Using the command key in conjuction with a number key
  generates the equivalent function key within xmame, with 0, - and = +
  representing F10, F11 and F12 resepectively. Also note that the ALT +
  keys cannot be mapped. As most games tend to use this as the default
  fire button it is exteremly useful to remap this globally the first
  time you run xmame.

  3.  Xmame frequently asked questions

  3.1.  What is mame?

  Mame is a arcade machine emulator. Started in 1997, by Nicola
  Salmoria, mame started out as a series of emulators for  individual
  games. This series of emulators was combined into a  multiple game
  emulator format. This is the current form of mame, no longer a one man
  show, there are over 100 contributors to the project.

  Mame was created by Nicola Salmoria.

  Also see the official mame readme file (readme.mame) <readme.mame>



  3.2.  What is mess?

  Mess is just like mame a virtual machine emulator, only it doesn't
  emulate arcade machines but other computers and consoles.

  Also see the official mess readme file (readme.mess) <readme.mess>

  3.3.  What is xmame/xmess?

  Xmame/xmess are the Unix/X11 ports of the mame and mess projects. It
  makes mame/mess available on *ix machines using the X11R6 X-Window
  system (and SVGAlib/ggi/XF86-DGA too).

  Mame was orginally ported by Allard Van Der Bas, Dick the Ridder and
  Juan Antonio Marmnez.

  Xmame/xmess is currently maintained by Hans de Goede.

  3.4.  What are the differences between mame/mess and xmame/xmess?

  None significant.

  Xmame/xmess is based on the mame/mess source code. Due to technical
  reasons beyond the scope of this document, the mame/mess source may
  not compile under Unix. That why the xmame/xmess project exists. Each
  time mame/mess is updated, the code is tested  (and patched if needed)
  under Unix. This way xmame/xmess releases are always the same as their
  mame counterparts.

  There are no plans for the independent development of xmame/xmess.

  3.5.  What hardware and operating systems are supported?

  Xmame runs on both little endian and big endian CPU's, using aligned
  integer access if needed and is compatible with 64 bit CPU's. The
  current list of supported CPU's in the makefile is:


  o  i386 + gnu-asm

  o  i386 no asm

  o  alpha

  o  ia64 (merced)

  o  m68k

  o  generic risc (powerpc, sparc, hppa, ibm)

  o  generic risc, lsb-first (RISC (ultrix machines))

  o  mips (generic risc + SGI compiler bug workarounds)

  Adding support for another cpu (if nescesarry) should be trivial.

  The following Unix platform's are specificly supported:


  o  Linux

  o  FreeBSD

  o  NetBSD


  o  Solaris (SunOS)

  o  OpenStep (noasm only on i386)

  o  IRIX with sound using the dmedia package or the new al package
     (sound currently broken)

  o  AIX (sound currently broken)

  o  generic unix, no sound

  The generic unix entry should work for any reasonable standard Unix
  variant, but lacks sound since there is no single Unix sound standard.

  On all platforms zlib is now needed since the core uses it, if you
  don't have zlib use the included one by uncommenting the appropriate
  line in Makefile.

  The following display methods are supported, X11 is the only one which
  works on all platforms, except for OpenStep which only work with
  Openstep bitmaps:


  o  X11 (X-windows)

  o  svgalib

  o  GGI (Generic Graphics Interface)

  o  OpenGL using X11 for input

  o  glide using X11 for input (3DFX)

  o  glide using svgalib for input (3DFX)

  o  OpenStep bitmaps

  o  SDL (Simple Direct Medialayer)

  The following is a list of arch/os/display combinations, with
  maintainers, for arch/os/display combinations which are activly
  supported. Please mail the maintainer of the arch/os/display
  combination for compilation and other arch/os/display specific
  problems. Mail Hans hans@highrise.nl <mailto:hans@highrise.nl> for
  generic (e.g. x11) problems.


  o  i386/linux/x11 (+DGA) -> Hans <hans@highrise.nl>
     <mailto:hans@highrise.nl>

  o  i386/linux/svgalib -> Hans <hans@highrise.nl>
     <mailto:hans@highrise.nl>

  o  i386/linux/xgl -> Hans <hans@highrise.nl> <mailto:hans@highrise.nl>

  o  i386/linux/xfx -> Hans <hans@highrise.nl> <mailto:hans@highrise.nl>

  o  i386/linux/svgafx -> Hans <hans@highrise.nl>
     <mailto:hans@highrise.nl>

  o  i386/linux/ggi -> Christian <cpg@aladdin.de>
     <mailto:cpg@aladdin.de>

  o  alpha/linux/x11 -> Christian <cpg@aladdin.de>
     <mailto:cpg@aladdin.de>

  o  alpha/digital unix/x11 * -> Leandro <ldardini@usl4.toscana.it>
     <mailto:ldardini@usl4.toscana.it>

  o  powerpc/linux/x11 -> Andreas <sid@skater.htu.tuwien.ac.at>
     <mailto:sid@skater.htu.tuwien.ac.at>

  o  powerpc/linux/svgalib -> Andreas <sid@skater.htu.tuwien.ac.at>
     <mailto:sid@skater.htu.tuwien.ac.at>

  o  i386/freebsd/x11 -> Jacob A. Hart
     <c9710216@studentmail.newcastle.edu.au>
     <mailto:c9710216@studentmail.newcastle.edu.au>

  o  i386/netbsd/x11 -> Dave <dave@dtsp.co.nz> <mailto:dave@dtsp.co.nz>

  o  alpha/netbsd/x11 -> Christian <cpg@aladdin.de>
     <mailto:cpg@aladdin.de>

  o  Sparc/Solaris/x11 -> Mathis <rosenhau@mailserv.sm.go.dlr.de>
     <mailto:rosenhau@mailserv.sm.go.dlr.de>

  o  i386/Unixware7/x11 * -> Richard <xmame@frogface.ddns.org>
     <mailto:xmame@frogface.ddns.org>

  o  i386/openstep -> Pete French <pete@toybox.twisted.org.uk>
     <mailto:pete@toybox.twisted.org.uk>

  o  Sparc/SunOs -> Saga <jolletx@cybercable.fr>
     <mailto:jolletx@cybercable.fr>

  o  mips/irix/x11 -> Dingus Family <ddingus@usewest.net>
     <mailto:ddingus@usewest.net>

  * These are supported using the generic unix entry of the makefile,
  and thus lack sound.

  We are always looking for people willing to test and answer questions
  about xmame on a new arch/os/display. This takes very little work and
  could help other people tremendously. If you're interested mail Hans
  hans@highrise.nl <mailto:hans@highrise.nl>.

  3.6.  My system is supported but xmame/xmess give me errors and fails.
  Why?

  Xmame/xmess should run on 8bpp Pseudo Color displays and on 16, 24 and
  32bpp True Color displays. If your X-Server does not support any  of
  these display types, xmame/xmess will not run.

  You can verify your X-Server support by starting your X-Server  and
  running the xdpyinfo program. See the xdpyinfo manual page  for more
  information.

  3.7.  What is the role of the xmamerc/xmessrc file?

  A normal xmame/xmess invocation looks like:


      xmame pacman -sound -nojoy -frameskip 2 -heightscale 3 \
          -widthscale 2



  Most of the time, you will want to use the same configuration for
  each game. Xmame/xmess will read this file for default values for the
  parameters that you can set. This way the only parameters you  need to
  express on the command line are the ones you want to  override.
  Another reason for xmamerc/xmessrc is keyboard remapping. Some Unix
  keyboards are very different than their PC counterparts. To
  compensate for the changes, xmame/xmess allows you to remap keys that
  are not available on Unix keyboards to keys that are available.

  3.8.  What is the syntax of the xmamerc/xmessrc file.

  The syntax is quite simple:


     "keyword value"



  See xmamerc.dist <xmamerc.dist> for most keywords. Allmost all
  commandline options can be used as keywords (without the -), use value
  0 or 1 for commandline options which have a negating (-no[option])
  counterpart. As usual lines begining with "#" are comments.

  You can also generate a configfile with all the current settings to
  use as a template by typing:


     xmame -showconfig > ~/.xmame/xmamerc



  3.9.  Where do roms, images, samples, highscores, configfiles, etc go?

  3.9.1.  Roms/Samples

  Xmame/xmess uses a ":" seperated rompath to find out which dirs to
  search for roms/samples.

  The default rompath is XMAMEROOT as defined in Makefile during
  compile.

  This is overwritten by any rompath in xmamerc/xmessrc. Which can be
  overwritten again with the -rompath commandline option.

  Xmame/xmess searches every dir in this path for roms/samples in the
  following way:


      <dir>/gamename.zip             (containing filename.ext)
      <dir>/gamename/filename.ext
      <dir>/gamename/filename.ext.gz (containing filename.ext)
      <dir>/gamename/filename.zip    (containing filename.ext)



  So lets say that we are searching for rom0001.1 which is part of
  pacman then xmame/xmess would search every dir in your rompath for:


      <dir>/pacman.zip               (containing rom0001.1)
      <dir>/pacman/rom0001.1
      <dir>/pacman/rom0001.1.gz      (containing rom0001.1)
      <dir>/pacman/rom0001.zip       (containing rom0001.1)



  Note: If your neogeo games can't find neogeo.rom put it in a dir
  called neogeo somewhere in your rompath, or put it in neogeo.zip
  somewhere in your rompath.

  3.9.2.  Read/write Diskette Images

  This section only applies to xmess emulations which support read/write
  diskette images and thus try to open the image read/write.

  Xmess first searches for read/write images with the name specified on
  the commandline:


      <path>/image.ext



  Where path is the path specified with the image on the commandline,
  this way absoulte and relative filenames can be used directly on the
  commandline for an image which is not in the rompath.

  Then xmess searches every dir in the rompath for roms/samples in the
  following way:


      <dir>/image.ext



  Note that (g)zipped images are not supported for r/w images.

  3.9.3.  Rom Cartridges/Read Only Diskette Images

  Xmess begins by searching for cartdriges/disks from the current dir in
  the following way:


      <path>/image.ext
      <path>/image.ext.gz            (containing image.ext)
      <path>/image.zip               (containing image.ext)



  Where path is the path specified with the image on the commandline,
  this way absoulte and relative filenames can be used directly on the
  commandline for an image which is not in the rompath.

  Then xmess searches every dir in the rompath for carts/images in the
  following way:


      <dir>/image.ext
      <dir>/image.ext.gz             (containing image.ext)
      <dir>/image.zip                (containing image.ext)



  Finally xmess searches the rompath as desribed above using the
  systemtype for gamename.

  So letts say we want to play mario.nes on the nes emulation of xmess.
  We would then type: "xmess nes mario.nes". Xmess then begins by
  searching the current dir for:


      mario.nes
      mario.nes.gz                   (containing mario.nes)
      mario.zip                      (containing mario.nes)


  After that xmess searches each dir in your rompath for:


      <dir>/mario.nes
      <dir>/mario.nes.gz             (containing mario.nes)
      <dir>/mario.zip                (containing mario.nes)



  And finally xmess searches each dir in your rompath for:


      <dir>/nes.zip                  (containing mario.nes)
      <dir>/nes/mario.nes
      <dir>/nes/mario.nes.gz         (containing mario.nes)
      <dir>/nes/mario.zip            (containing mario.nes)



  Since xmess first searches for cartridges/disks from the current dir
  you can also specify cartridges/disks not in your rompath for example:


      "xmess nes ../mario.nes"



  Xmess then searches for:


      ../mario.nes
      ../mario.nes.gz                (containing mario.nes)
      ../mario.zip                   (containing mario.nes)



  And will also search the rompath as described above with ../mario.nes
  as image name but this is not that usefull.

  3.9.4.  Artwork

  Xmame/xmess searches every dir in the rompath for artwork in the
  following way:


      <dir>/artwork.png
      <dir>/artwork.png.gz           (containing artwork.png)
      <dir>/artwork.zip              (containing artwork.png)



  Then xmame/xmess searches the rompath as in roms/samples.

  So lets say we want to play foo which uses bar.png. Xmame/xmess then
  begins searching each dir in your rompath for:


      <dir>/bar.png
      <dir>/bar.png.gz               (containing bar.png)
      <dir>/bar.zip                  (containing bar.png)



  And then xmame/xmess searches each dir in your rompath for:


      <dir>/foo.zip                  (containing bar.png)
      <dir>/foo/bar.png
      <dir>/foo/bar.png.gz           (containing bar.png)
      <dir>/foo/bar.zip              (containing bar.png)



  3.9.5.  Xmame configuration

  Xmame looks for the following configuration files and parses each one
  found, later parsed files can overwrite options in previously parsed
  files:


      XMAMEROOT/xmamerc
      XMAMEROOT/xmame-DISPLAY_METHODrc
      ${HOME}/.xmame/xmamerc
      ${HOME}/.xmame/xmame-DISPLAY_METHODrc
      ${HOME}/.xmame/rc/<gamename>rc



  XMAMEROOT is defined during compile time, see Makefile.

  DISPLAY_METHOD is the DISPLAY_METHOD for which xmame was compiled,
  this can be one of: x11, svgalib, ggi, xgl, xfx, svgafx, openstep,
  SDL.

  For xmess of course replace xmame by xmess ;)

  3.9.6.  Game configuration

  Game configuration files are kept on a per user base in:


      ${HOME}/.xmame/cfg/<game>.cfg resp
      ${HOME}/.xmess/cfg/<game>.cfg



  3.9.7.  Game state

  Game state files are kept on a per user base in:


      ${HOME}/.xmame/sta/<game>.sta resp
      ${HOME}/.xmess/sta/<game>.sta



  3.9.8.  NVram

  NVram files are kept on a per user base in:


      ${HOME}/.xmame/nvram/<game>.nv resp
      ${HOME}/.xmess/nvram/<game>.nv



  3.9.9.  Mem cards

  Mem cards files are kept on a per user base in:



      ${HOME}/.xmame/mem/<filename>.mem resp
      ${HOME}/.xmess/mem/<filename>.mem



  Where <filename> is given by the game-driver.

  3.9.10.  Screenshots

  Screenshots which can be made pry pressing F12 are saved as png files
  in the directory from where xmame is started (cwd).

  This can be overidden by the screenshotdir entry in xmamerc/xmessrc.
  Which can again be overidden by the -screenshotdir cmdline-option.

  They are saved as:


      <screenshotdir>/<game>xxxx.png
      Where xxxx is a number.



  3.9.11.  Highscore's

  Hi-scores are stored in XMAMEROOT as defined in Makefile when
  building.  This can be overidden by the spooldir entry in
  xmamerc/xmessrc. Which can again be overidden by the -spooldir
  cmdline-option.

  So only give a


      drwxrwsr-x root games <spooldir>



  permission and setgid xmame/xmess to "games" to get it to work.  Note
  this doesn't work with suid root versions (svgalib & XF86-DGA),
  suggestions welcome.

  For know use ${HOME}/.xmame or $ {HOME}/.xmess as spooldir in
  xmamerc/xmessrc for  suid root versions.

  Note for highscores to work, xmame must also be able to find
  hiscore.dat

  3.9.12.  hiscore.dat

  If you want to use highscores mame needs to load hiscore.dat to get
  highscore info.

  The default is XMAMEROOThiscore.dat/. XMAMEROOT is set during compile-
  time, see the Makefile. This can be overriden by the hiscorefile entry
  in xmamerc if present, which can again be overiden by the cmdline-
  option -hiscorefile.

  hiscore.dat is available from the mame webpage: http://www.mame.net
  <http://www.mame.net>

  3.9.13.  cheat.dat

  If you want to use cheats mame needs to load cheat.dat to get cheat
  info.


  The default is XMAMEROOT/cheat.dat . XMAMEROOT is set during compile-
  time, see Makefile. This can be overriden by the cheatfile entry in
  xmamerc if present, which can again be overiden by the cmdline-option
  -cheatfile.

  cheat.dat is available from the mame webpage: http://www.mame.net
  <http://www.mame.net>

  3.9.14.  history.dat

  If you want to display some nice background info on games mame needs
  to load history.dat.

  The default is XMAMEROOT/history.dat . XMAMEROOT is set during
  compile-time, see Makefile. This can be overriden by the historyfile
  entry in xmamerc if present, which can again be overiden by the
  cmdline-option -historyfile.

  history.dat is available from the mame webpage: http://www.mame.net
  <http://www.mame.net>

  3.9.15.  Input logs

  Input logs are saved / read under the name specified after the -record
  / -playback option, this name is relative to the current path.

  3.9.16.  Xmame/xmess still can't find file's / store highscore's

  Type "xmame/xmess -showconfig | more" and check that the rompath and
  spooldir showed are correct and readable/writable. Otherwise recheck
  xmamerc/xmessrc.  Remember that xmess also searches the current dir.

  3.10.  How do I start xmess/xmame ?

  To start xmame type:


      xmame [options] <gamename> [more options]



  For xmess type:


      xmess [options] <systemname> [more options] \
      <disk/romimage(s)> [more options]



  All options are optional ;)

  Xmame/xmess supports most dos commandline-options (see readme.mame /
  readme.mess) as well as a few of its own, type xmame -help |  more for
  a  complete list.

  With xmess some systems don't require a disk/romimage, but most do.

  3.11.  What are the command line parameters for xmame/xmess?

  To see a list of available parameters, type:


      /usr/games/xmame -help | more



  Xmame/xmess supports most of the command line parameters as the DOS
  version as well a some of its own.

  See the file readme.mame / readme.mess for more information about the
  command line parameters.

  3.12.  What keys does xmame/xmess use?

  Xmame/xmess uses the same key-bindings as the DOS version of mame: The
  following keys work in all emulators:


      `  or ~      Enter On screen display to change volume, brightness etc.
      Tab          Enter configuration menu. Press Tab or Esc to get back to
                   the emulation.
      P            Pause
      F3           Reset
      F4           Show the game graphics. Use cursor keys to change set/color,
                   F4 or Esc to return to the emulation.
      F8           Reduce frame skip
      F9           Increase frameskip
      F10          Toggle speed throttling
      F10 + shift  Toggle idle sleeping
      F11          Toggle speed display
      F11 + shift  Toggle profiler display
      F12          Save a screen snapshot.
      ESC          Exit emulator



  Xmame has 2 different auto frameskipping algorithms, these can be
  selected with the -frameskipper option. And with key combis:


      Key combi:             Gives you the:
      left-ctrl + insert     standard dos frameskipper
      left-ctrl + home       William Barath's frameskipper



  Xmames display scaling can be controlled on the fly with the following
  key combis:


      Key combi:             Result:
      left-shift + insert    Increase widthscale
      left-shift + delete    Decrease widthscale
      left-shift + home      Increase heightscale
      left-shift + end       Decrease heightscale
      left-shift + pageup    Increase scale
      left-shift + pagedown  Decrease scale



  Under X11 xmame can switch to and from different modes runtime:


      Key combi:             Warps you to:
      left-alt + insert      Normal window
      left-alt + home        DGA fullscreen mode



  Under X11 in a window you can also grab the mouse to be able to play
  with the mouse, press left-alt + page-down to grab the mouse, press it
  again to release it.
  3.13.  Why doesn't a game have sound?


  o  First check that sound is working in other applications.

  o  Check that sound is supported for the game that has no sound,  not
     all games have sound:

  o  For xmame take a look at gamelist.mame, is the sound for the game
     emulated?

  o  For xmess take a look at readme.mess is the sound for the system
     emulated?

  o  Check the operating system support chart in the earlier part of
     this file, does xmame/xmess support sound on your system?

  3.14.  My sound seems lagged? / My sound Clicks? / What does -bufsize
  do?

  With the -bufsize commandline option / the bufsize configfile keyword
  you can specify the number of frames of audio to buffer. The default
  is 2 frames.

  This value should be ok for everyone, but if you still have problems
  read on.

  If the buffersize is to small, this causes the buffer to get empty
  between frames which in turn causes clicks/pauses in the sound. If
  this is the case highering the -bufsize value to for example 2.5
  should help.

  If however you make the buffersize to large, then so much audio
  becomes buffered, that the sound could become lagged. E.g. you would
  here the coin drop sound 0.5 seconds after pressing the insert coin
  key. In this case lower the bufsize to for example 1.5 .

  Please lett me know if you need to change this setting, since I'm
  planning on removing it in a future release.

  3.15.  Why doesn't a game work?


  o  Do you have the right roms or did you get checksum failures?

  o  Xmame version 0.34 and higher require PROM files that were not
     included in ROM images released before version 0.34. See the
     question on PROMs  below for more information.

  o  For xmame check the file gamelist.mame to see if the game is
     playable, just because a game is included doesn't mean it is
     working yet.

  o  For xmess take a look at readme.mess maybe the system isn't
     emulated all that good yet.

  o  Some games require sound support. If you don't have sound  support
     under your Unix or sound isn't supported by xmame/xmess under  your
     Unix, try the -fakesound command line parameter.

  3.16.  What are PROMs?

  PROMs contain game specific information that used to be built in  to
  mame in versions prior to 0.34. This information has been  extracted
  and is now included with new versions of ROM files for  games that
  require this information.
  If you want to use your current ROM files, you can obtain just the
  PROM images in one large file at:

  http://mame.retrogames.com/ <http://mame.retrogames.com/>

  3.17.  Why is xmame/xmess slow?

  xmame/xmess is a compiled C program that is emulating hardware.
  Software emulation of hardware always pays a speed penalty. Here  are
  some things you can do:


  o  Try using the -frameskip command line parameter.

  o  Try pressing F8 while running xmame/xmess to alter the frame rate.

  o  Try disabling the throttle with the -nothrottle command line
     parameter or by pressing F10 while running xmame/xmess.

  o  While running xmame/xmess, press F11 to check the speed of
     xmame/xmess.  If you never get a display of 100%, you need a faster
     computer.

  You can also try recompiling xmame/xmess with more optimal settings,
  the following suggestions may not work or may not be appropriate on
  some machines and in some installations.  However, in cases where they
  do work, there can be a noticeable increase in overall performance of
  xmame/xmess.

  These "enhancements" simply require editing the Makefile that is
  distributed with xMame, and then recompiling the source.  If you are
  compiling the source for the second time you will need to do:


      make clean
      make
      make install



  after editing the Makefile to set your new settings.

  3.17.1.  SPEEDUP # 1 - Inline compiling

  Try enabling inline compiling by commenting and uncommenting the
  following lines:


      # IL    = '-DINLINE=static inline'
      IL     = -DINLINE=static



  3.17.2.  SPEEDUP # 2 - Direct Graphics Access

  For a big boost try enabling DGA by uncommenting the following line:


      DGA = 1



  Then start xmame as root, and press left-alt + home to switch to dga
  mode, that should be a lot faster, and doesn't need / use xsync ;)


  To get back to a window without exiting press left-alt + insert.

  The benefit of DGA is that it is Direct Graphics Access and as such
  writes directly to the framebuffer (Think directx versus GDI under
  windows). So it should be a tad faster, unless you've got a really
  really well accelerated X-server, which could be just as fast. Try
  pressing F11 to see the actual framerate, although it might be hardly
  noticable (visually atleast), it should give you some speed increase.

  Besides that it automaticly switches to the right mode and removes any
  window manager stuff, but that can be done without DGA too (I might at
  such a feature later, sine it allows easy fullscreen without running
  as root).

  And adding a 320x240 mode will most definatly get you a very nice
  fullscreen display at scale = 1 ;)

  Don't forget that you need still need to set up the Modes line of the
  "Display" subsection of the "Screen" section of your X config file if
  you want the games to fill the screen in DGA mode. Xmame will pick the
  best mode it can find, so if you have a line like:


      Modes  "1024x768" "800x600" "640x480" "320x240" "256x224"



  then any game which fits into a 320x240 screen can be displayed in
  that resolution, and so on. Don't forget you X11 config file might
  have a number of different "Screen" sections in it, and you will need
  to add Modes to the one that is actually active with your Xserver is
  running. And of course it's not always that easy, since you also need
  to tell X what monitor settings are required for these resolution
  modes. This is done through Modeline entries in the "Monitor" section
  of your X config file.

  You can check out the /contrib/tools/modelines file for a set of crazy
  modes made especially for xmame in DGA mode, they should work on any
  reasonable multisync, but don't use them on an old fixed-frequency
  (well if you can't resist trying I won't pay for a new one)

  3.17.3.  SPEEDUP # 3 - NASM

  You can also try installing nasm and compiling the asm core, that
  helps a bit too.

  3.18.  of this?  I've got a dual processor machine. What can I do to
  take full advantage

  Not much. Xmame is a single-threaded port of a single-threaded DOS
  app.  Some degree of speedup will hopefully be found on an SMP since
  xmame is more likely to get to hog its one CPU for longer. But of
  course the same applies to any CPU-intensive program. And all the
  things one would normally do to any application to give it more CPU
  time (higher priority, kill or renice unecessary process, etc.) will
  work with xmame.

  Now you may at this point be thinking "Surely you could have one
  thread doing emulation and another thead doing graphics to get a
  speedup." Yes, but there are some serious issues to consider. The
  first is synchronisation between the threads, which needs to be pretty
  tight. If not done smoothly the overhead will blow most of the benefit
  away. Also it needs to be implemented with a portable threads
  interface ... which basically means POSIX threads.  In a nutshell its
  a lot of effort and probably not much gain. But of course if you are
  feeling particulary energetic and in the mood to code then patches can
  always be submitted to the xmame devel mailing list ... :)

  3.19.  x86 system?  Why doesn't my joystick handle diagonal movement
  correctly on my Intel

  Xmame/xmess uses autocalibrating but you could try to use specific
  programs to calibrate it ( jscal that comes with joystick  module
  works fine.... )

  3.20.  How do I enable XinputExtensions X11 based joystick in Xfree86?

  You need to edit XF86Config to enable the XInput section. See the
  manual page for XF86Config.

  3.21.  How do I read a manual page?

  Easy. If you want to read the manual page for XF86Config, type: man
  XF86Config

  3.22.  Why do I get gz_open symbol not found while compiling?

  Xmame/xmess versions newer then 0.35 use zlib for some compression
  routines.  Unfortunatly a lott of Linux distributions have an old
  version of zlib installed as /usr/X11R6/lib/libz.a And the new version
  installed as /usr/lib/libz.a.  If this is the case its harmless to
  remove /usr/X11R6/lib/libz.a. If your not sure wether this is the case
  just move /usr/X11R6/lib/libz.a to another location.

  Removing or just moving /usr/X11R6/lib/libz.a should fix this problem.

  Also see: ``FAQ: Why do I get zlib.h not found?''

  3.23.  Why do I get zlib.h not found?

  Xmame/xmess versions newer then 0.35 use zlib for some compression
  routines.

  Zlib is standard on most Unix versions, for those who don't ship with
  zlib or ship with a too old version xmame/xmess now comes with a
  stripped down version of zlib. Uncomment the appropriate line in the
  Makefile to use this.

  3.24.  Where can I get the latest version of xmame/xmess?

  The xmame/xmess Home Page always has the most up to date version. The
  address is:

  http://x.mame.net/ <http://x.mame.net/>

  3.25.  Where can I send fixes, bug reports, suggestions, or money?
  :-)

  See ``Mail'' of this document.

  3.26.  What if my question is still not answered?

  Please check the offical mame and mess readme files to see if that
  answers your question:


  o  The official mame readme file (readme.mame) <readme.mame>

  o  The official mess readme file (readme.mess) <readme.mess>

  If that doesn't help then ask your question on the mailinglist or send
  it to the xmame/xmess maintainer, see  ``Mail'' for contact
  information.

  4.  Display subsystem specific comments & notes

  4.1.  FX-Mame a glide driver for xmame

  The latest version of this driver can be obtained at:
  http://glmame.linuxgames.com <http://glmame.linuxgames.com>

  4.1.1.  Requirements

  To run FXmame you must have:


  o  A 3Dfx card

  o  Glide 2x o the xmame distribution

  4.1.2.  Compiling and Installing

  FXmame comes in two flavours -- xfx and svgafx. The xfx version is
  designed to run under X11. It uses an X window for input. The svgafx
  version runs from the console, and uses svgalib for input. Both use
  the 3Dfx hardware for rendering.

  To install FXmame, follow the general instructions for installing
  xmame.  To specify the glide driver, do the following the Makefile:


  o  Select either "xfx" or "svgafx" as your display method

  o  Configure the glide variables to correspond to your glide setup

  The FXmame executables are called "xmame.xfx" and "xmame.svgafx"

  4.1.3.  Running

  FXmame runs with the same parameters and uses the same keyboard
  commands that xmame.x11 does.

  A few extra keyboard commands have been added in the glide driver:


  o  RIGHTCTRL-A -- toggle antialiasing in vector games

  o  RIGHTCTRL-B -- toggle bilinear filtering

  The glide driver also adds several command-line options:


      -fxgama <value> 3Dfx gamma correction value



  Note that in order to display the game options or the fps display in
  vector games, I have to overlay the game bitmap over the vector
  display. This is because I circumvent the bitmap entirely in vector
  games. Drawing the bitmap is a big cpu hog, so you'll notice that the
  game slows down when you turn on the fps display (I know, not ideal
  when you want to find out the frame rate...)

  4.1.4.  Common Questions (FAQ)

  Q: When I run FXmame, it just dumps core.


  A: Make sure you are running FXmame as root. Root priviledges are
  required to access the 3Dfx hardware

  Q: When I run xmame.xfx, it just hangs at the initial game screen

  A: Are you running KDE? For some reason, I can't get keyboard input
  under KDE. If you have this problem, switch window managers or use
  xmame.svgafx instead.

  4.1.5.  Present Limitations/Bugs


  o  antialiasing isn't working quite as well as it should o input
     problems under KDE

  4.1.6.  Future Work


  o  Optimize the drawing code to update only the changed portions of
     the game bitmap.

  4.1.7.  License

  The FXmame code is Copyright 1998 by Mike Oliphant. It may be used and
  distributed under the terms of the MAME license.

  4.1.8.  Version History

  v0.5 -- December 11th, 1998 ---------------------------


  o  implemented long copies in screen update

  o  added dirty handling. this greatly increases the speed of games
     that support the dirty update strategy (although most of them are
     older games that already ran at full speed on modern hardware)

  o  merged source with xmame b8.1

  v0.4 -- October 30th, 1998 --------------------------


  o  improved alpha handling in vector games - now bitmapped overlays do
     not dim the screen o added svgalib support (xmame.svgafx) o fixed a
     tiling bug that gave artifacts on texture tile boundaries

  v0.3 -- October 29th, 1998 --------------------------


  o  got rid of extra lines in vector games o added bitmap overlay in
     vector games to show options/fps o added antialiasing in vector
     games

  v0.2 -- October 28th, 1998 --------------------------


  o  added screenshots o added 3Dfx gamma adjustment o added direct
     acceleration of vector games (still buggy)

  v0.1 -- October 27th, 1998 --------------------------


  o  first public release



  4.1.9.  Author

  Mike Oliphant (oliphant@ling.ed.ac.uk) <mailto:oliphant@ling.ed.ac.uk>
  http://glmame.linuxgames.com <http://glmame.linuxgames.com>

  4.2.  GL-Mame a OPENGL driver for xmame

  The latest version of this driver can be obtained at:
  http://glmame.linuxgames.com <http://glmame.linuxgames.com>

  4.2.1.  Requirements

  To run GLmame you must have:


  o  An OpenGL implementation

  o  libjpeg

  o  hardware 3D acceleration (if you want any kind of framerate) o the
     xmame distribution

  4.2.2.  Compiling and Installing

  Follow the general instructions for installing xmame. To specify the
  OpenGL driver, do the following in the Makefile:


  o  Select "xgl" as your display method

  o  Configure the OpenGL variables to correspond to your OpenGL
     implementation

  o  Configure the CABDIR variable

  The GLmame executable is called "xmame.xgl"

  4.2.3.  Running

  xmame.xgl runs with the same parameters and uses the same keyboard
  commands that xmame.x11 does.

  The program starts up in cabinet mode. While this is pretty, and cool,
  you'll probably want to actually play in fullscreen mode.

  A few extra keyboard commands have been added in the OpenGL driver:


  o  RIGHTCTRL-B -- toggle bilinear filtering

  o  RIGHTCTRL-C -- toggle cabinet/fullscreen display

  o  RIGHTCTRL-T -- toggle phosphor trails --use at your own risk! -- it
     works best if double buffering is disabled (see below)

  The OpenGL driver also adds several command-line options:


      -[no]dblbuffer          Disable/enable double buffering
      -cabview                Start in cabinet view mode
      -nocabview              Start in fullscreen view mode
      -cabinet <cabname>      Use the cabinet model <cabname>
      -fxgama <value>         3Dfx gamma correction value



  Two cabinet models are provided. The default, "glmame", is designed to
  look like a standard arcade cabinet. The other, "trans", is a box with
  a transparent games screen that you can see through.

  Note that in order to display the game options or the fps display in
  vector games, I have to overlay the game bitmap over the vector
  display. This is because I circumvent the bitmap entirely in vector
  games. Drawing the bitmap is a big cpu hog, so you'll notice that the
  game slows down when you turn on the fps display (I know, not ideal
  when you want to find out the frame rate...) This overlaying seems to
  have some glitches in cabinet mode. I don't know what causes them.

  *** IMPORTANT! ***

  If you have trouble with GLmame, or it is slow, read the "Common
  Questions" section. Most of the questions people email me are answered
  here.

  4.2.4.  Cabinet Models

  Cabinet model information is stored in the "cab" subdirectory of the
  directory you specified with the ROMPATH variable in the Makefile.
  Path information specified in xmamerc or with the 'rompath' shell
  environment variable is currently not used. Each cabinet model has
  it's own subdirectory. GLmame will first try to load either the user-
  specified cabinet model (using the -cabinet command-line option), or a
  model corresponding to the current game name. Failing that, it will
  use the generic "glmame" model.

  A cabinet model directory must contain a geometry file
  <modelname>.cab, and any .jpg files used for textures on the model.
  The format of the .cab file will be familiar if you have ever
  programmed using OpenGL -- it looks much like an OpenGL display list.
  The format is as follows:


      cabv1.0



  This header must be the first 7 characters of the file.


      #<text>



  Comment lines begin with '#'


      begin <type>



  Begins a geometry object, where type is one of (polygon, quads,
  quad_strip, screen). Each "begin" must be paired with an "end"
  statement.  A "polygon" is specified using one vertex per, well...
  vertex. "quads" are four-sided polygons, each specified by four
  vertices in order around the polygon. A "quad_strip" is a series of
  four-sided polygons, each of which shares an edge with the polygons
  before and after it in the strip.  A "screen" is a quad that defines
  the actual area in 3D space where the game will be displayed. only one
  of these should be defined. For more info, look at any description of
  OpenGL geometry.


      end



  Ends the geometry object begun with "begin".


      color4 <r> <g> <b>



  Changes the current color to the corresponding rgb value (specified as
  floating point numbers between 0 and 1).


      color4 <r> <g> <b> <a>



  Changes the current color to the corresponding rgba value (specified
  as floating point numbers between 0 and 1).


      shading <type>



  Sets the shading type. available types are "smooth" (which blends
  colors from one vertex to the next) or "flat" (which doesn't).


      vertex <x> <y> <z>



  Specifies a vertex for the current geometry object as a point in
  3-space.


      numtex <num>



  Specifies the number of different textures to be loaded. This
  declaration must precede any "loadtex" call.


      loadtex <num> <width> <height> <filename>



  Loads texture number <num> from .jpg file <filename>. The .jpg file
  *must* be <width> by <height> pixels, and both <width> and <height>
  must be powers of two (and must conform to the hardware requirements
  of any 3D card you want the cabinet to work with -- 256x256 for 3Dfx).


      texcoord <xcoord> <ycoord>



  Sets the texture coordinate of the next vertex. This specifies where
  in 2D texture space the vertex lies.



      enable texture



  Enables texture mapping (using the currently-selected texture).


      disable texture



  Turns off texture mapping.


      settex <num>



  Select texture <num> for doing texturing. The texture must previously
  have been loaded using "loadtex".


      camerapan <num>



  Starts the camera pan definition that will be followed by <num> camera
  transistions. After the last transision definition, the pan sequence
  must be ended with an "end" statement.


      goto <lx> <ly> <lz> <px> <py> <pz> <nx> <ny> <nz>



  Relocates and reorients the camera. The arguments are the same as are
  used by the OpenGL command "gluLookAt()". The camera is positioned at
  point <lx,ly,lz>, pointing along vector <px,py,pz>, with "up" normal
  (the direction that is "up" for the camera) <nx,ny,nz>.


      moveto <lx> <ly> <lz> <px> <py> <pz> <nx> <ny> <nz> <frames>



  Moves the camera to a new location (specified as in "goto").  The
  transition occurs over <frames> frames.

  All commands must be on separate lines. Use the (somewhat) commented
  glmame cabinet as an example to work from.

  4.2.5.  Common Questions (FAQ)

  Q: I am only getting a few frames-per-second. This sucks! What gives?

  A1: You're probably running Mesa in software mode. You should read the
  "README.3Dfx" file in the Mesa distro. Specifically, you need to
  "setenv MESA_GLX_FX fullscreen"

  A2: You don't have a 3D graphics card. Go buy one!

  Q: When I run xmame.xgl, it just dumps core. That's not as much fun as
  3D Pacman, now is it?

  A1: If you are using a 3Dfx card, make sure you are running xmame.xgl
  as root. Root priviledges are required to access the 3Dfx hardware
  A2: If you're using Mesa and haven't upgraded to v3.0, do so.

  Q: When I run xmame.xgl, it just hangs at the initial game screen

  A: Are you running KDE? For some reason, I can't get keyboard input
  under KDE. If you have this problem, switch window managers

  4.2.6.  Present Limitations/Bugs


  o  No clipping of vector games (most noticeable in cabinet mode) o No
     preservation of game aspect ratio in cabinet mode o The phosphor
     trail stuff is *very* experimental at this point :-) o There's some
     weirdness when overlaying the configuration screen or fps display
     in cabinet mode for vector games

  4.2.7.  Future Work


  o  Fixing existing bugs

  o  Optimize the drawing code to update only the changed portions of
     the game bitmap.

  4.2.8.  License

  The GLmame code is Copyright 1998 by Mike Oliphant. It may be used and
  distributed under the terms of the MAME license.

  4.2.9.  Version History

  v0.6 -- December 14th, 1998 ---------------------------


  o  added support for systems that do not support paletted textures
     (SGI and solaris OpenGL implementations, for example)

  o  merged source with xmame b8.1

  v0.5 -- October 30th, 1998 --------------------------


  o  fixed a bug with texturing being left on in bad places o added 3Dfx
     gamma adjustment

  v0.4 -- October 21st, 1998 --------------------------


  o  updated to work with xmame v0.34b5.2

  v0.3 -- October 12th, 1998 --------------------------


  o  fixed verticle screen centering in fullscreen mode o moved cabinet
     and camera panning information into a user-editable configuration
     file o added command line options

  v0.2 -- October 6th, 1998 -------------------------


  o  adding missing 'cab' directory

  v0.1 -- October 5th, 1998 -------------------------



  o  first public release

  4.2.10.  Author

  Mike Oliphant (oliphant@ling.ed.ac.uk) <mailto:oliphant@ling.ed.ac.uk>
  http://glmame.linuxgames.com <http://glmame.linuxgames.com>

  5.  contact information and credits

  5.1.  Mail

  There is an official xmame/xmess mail List. All operations related to
  this list are performed via email to xmame-
  request@acm.csres.utexas.edu <mailto:xmame-
  request@acm.csres.utexas.edu> with a proper keyword in the body.

  Currently recognized commands are:


      subscribe      - subscribe to the list
      unsubscribe    - unsubscribe from the list



  X-Mame Mail List ideario


  o  The X-Mame mail list is intended to be a technical forum for XMame
     developers that is:

  o  To exchange ideas about getting a better X-Mame

  o  To share patches and notify bugs

  o  Study new design strategies

  o  To expose problems and learn know-how

  o  The X-Mame mail list is not a forum about playing games (but
     everyone in xmame-list plays...), so please:

  o  Dont use the list to ask about ROM's

  o  Dont ask about non-UNIX ports of Mame, just about MAME and X-Mame

  o  Dont ask for implementing a game. Just search doc and contribute
     yourself (you'll enjoy twice: programming and playing...)

  o  Dont show your last high score in xxx game (we are interested in
     programming, and then playing, in this order)

  o  Copyright notice: NEVER, I repeat NEVER send ROM images to the
     list. (but you can tell where to retrieve it... ;-) )

  o  At this moment X-Mame List is unmoderated, that is: every one
     subscribed will received everything sent to the list. Expected not
     need to change this policy...

  If you want to send a personal mail to the xmame/xmess coordinator,
  send to the address below. Everyone that contributes to xmame/xmess
  should subscribe to the xmame/xmess mail list.


  o  mailinglist: xmame-request@acm.csres.utexas.edu <mailto:xmame-
     request@acm.csres.utexas.edu>

  o  xmame/xmess coordinator: hans@highrise.nl <mailto:hans@highrise.nl>

  That's all. Enjoy X-Mame !

  5.2.  credits

  Lots and lots and lots of thank to everyone for there great help on
  the xmame project. I would like to thank the following people and of
  course anyone I've forgotten.

  Thank you all,

  Hans


  1. Fathers of the mame-creature (main version)

  o  Nicola Salmoria

  o  Allard van der Bas

  o  Mirko (Mix) Buffoni (General Mantainer)

  2. Fathers of mess

  o  Brad Oliver

  o  Richard Bannister

  o  Ben Bruscella (current coordinator)

  3. Original UNIX/X11 port

  o  Allard van der Bas

  o  Dick the Ridder

  o  Juan Antonio Marmnez

  4. Unix maintainer

  o  Hans de Goede

  5. Alpha specific issues

  o  Christian Groessler

  6. Sun specific issues

  o  Keith Hargrove

  o  Mathis Rosenhau

  7. Irix specific issues

  o  Tristram Scott

  8. GGI maintainance

  o  Gabriele Boccone (original port)

  o  Christian Groessler (current maintainer)

  9. OpenGL code & maintainance


  o  Mike Oliphant

  10.
     Network code

  o  Eric Totel

  11.
     Perl scripts for automation of some porting issues

  o  Bill Adams

  12.
     Xmame rpms

  o  Jeremy Hansen

  13.
     Mailing list maintainer

  o  Chris McCraw

  14.
     Bits and pieces

  o  Christian Groessler

  o  Torsten Paul

  o  Jack Patton

  o  David Black

  15.
     AIX Sound code

  o  Chris Sharpp

  16.
     IRIX Sound code

  o  entropy@zippy.bernstein.com <mailto:entropy@zippy.bernstein.com>

  17.
     German readme

  o  Robert Hamberger

  18.
     Documentation (SGML, HTML, MAN)

  o  Rene Herrmann

  6.  Legal issues and copyrights concerning mame/mess


  o  Please read the MAME/MESS readme-files first!

  o  xmame/xmess should be distributed under terms of the license in
     readme.mame <readme.mame>

  o  and if you are intessested in mess take a look in readme.mess
     <readme.mess>

  o  The main issue involves ROM images. ROM images are protected under
     the copyrights of their authors, and CANNOT be distributed in the
     same package as xmame/xmess. Download any ROM images at your own
     risk and responsibility.

  o  XInputExtensions based Joystick support. Source code is entirely
     pure hack work. No sample code, no info at all was found (only
     library  reference manual) and is copyrighted by me (Juan Antonio
     Marmnez). Use it under terms of GNU General Public License.

  7.  ChangeLogs

  7.1.  The mame/mess ChangeLogs

  This are the changelogs of the offical mame and mess release, the core
  of xmame / xmess.


  o  The mame changelog (changes.mame) <changes.mame>

  o  The mess changelog (changes.mame) <changes.mess>

  7.2.  The Unix ChangeLog

  And now here is the HISTORY of the xmame-project (of course thats why
  you are here :;-)) ... Ren


  o  The Unix port changelog (changes.unix) <changes.unix>







































