GLmame -- an OpenGL driver for xmame
====================================


The latest version of this driver can be obtained at:

  http://www.ling.ed.ac.uk/~oliphant/glmame


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


Compiling and Installing
------------------------

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

 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"


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
  -fullview                   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.

*** IMPORTANT ***


Cabinet Models
==============

Cabinet model information is stored in the "cab" subdirectory of the
directory you specified with the ROMPATH variable in makefile.unix. 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.


Common Questions
----------------

 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


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


Future Work
-----------

In addition to fixing existing bugs, I plan on:

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


License
-------

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


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 'trans' cabinet model
 o added double buffer, view type, and cabinet selection command line
   options

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

 o adding missing 'cab' directory

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

 o first public release


--
Mike Oliphant (oliphant@ling.ed.ac.uk)
http://www.ling.ed.ac.uk/~oliphant/glmame
