==========================Updated:
SVGAlib wrapper for LibGGI990401
==========================

Introduction
============

The LibGGI SVGAlib wrapper is a library which is source and binary compatible
with SVGAlib, but instead of hitting VGA hardware directly it uses LibGGI to
access the underlying graphics system. This means that you can run even
binary-only (like Quake I/II) SVGAlib applications on any of the large number
of targets supported by LibGGI.

The SVGAlib wrapper can also be used to compile and run SVGAlib applications
on non-VGA/Intel/Linux machines.


Requirements
============

* LibGGI 2.0beta2 or later.
* Most likely GNU Make.


Installation
============

First type `./configure' to build the makefiles, then simply type
`make ; make install' to build and install the SVGAlib wrapper.
The wrapper need to link against LibGGI. If LibGGI is not installed where
your compiler usually looks for includes and libraries you need to specify
the location with the --with-ggi flag to "configure".

The SVGAlib wrapper will not overwrite any existing SVGAlib installation,
it will just disable it by installing libs with higher version numbers than
any current SVGAlib distribution. If you wish to remove the SVGAlib wrapper
you can just cd into the directory where the libraries was installed and type:
`rm libvga*.ggi'

Note that any SVGAlib includes will be overwritten with those shipped with the
wrapper. These are the original includes from SVGAlib 1.3.1, and should be
100% backward compatible with older includes, so this should not cause any
trouble.


Recognized environment variables
================================

GSW_ASYNC -
Makes the SVGAlib wrapper run LibGGI in ASYNC mode. This is generally
a good thing performance-wise, but ASYNC mode requires that ggiFlush()
is called once per frame. As SVGAlib doesn't have the notion of a 
"flush" operation we have to use some tricks here.
 
If GSW_ASYNC is set to "mouse" ggiFlush() will be called from the
SVGAlib function mouse_update, and if it is set to anything else it
will be called from keyboard_update().

Whether this option does any good obviously depends on how the
particular application works - see the application-specific section
below for some hints.

GSW_BUT2KEY -
If this is set the SVGAlib wrapper will translate mouse-button 4 to the
'i' key, button 5 to the 'j' key and button 6 to the 'k' key. 
This feature is useful if you want to use more than three mouse-buttons
in applications that doesn't support this. With the X-based targets
this can also be used to support a wheel-mouse that maps the
mouse wheel to buttons.

Setting this with a mouse with less than four buttons doesn't do
anything at all.

GSW_PAGEEMU -
Emulates paged SVGAlib modes on LibGGI targets that has a linear
framebuffer. This feature was introduced because Quake uses banked
modes with 64k pages even if SVGAlib reports that it can use linear
addressing. If an application looks good in 320x200x8 but looks
weird in higher resolutions you probably need this feature.

GSW_DB -
Enables double buffering when using the GSW_PAGEEMU feature on targets
that support it, else does nothing. If you experience visual "tearing"
artifacts when using GSW_PAGEEMU you should enable this.

GSW_MODEEMU - 
Tries to emulate modes which are not available. This is recommended
as most SVGAlib applications makes quite a lot of assumptions when it
comes to mode setting.

GSW_WIDTH -

IMPORTANT NOTE: GSW_WIDTH is in most cases not needed anymore if you
use the GSW_PAGEEMU and GSW_MODEEMU flags.

Force the stride to be the number of bytes GSW_WIDTH is set to.
This is needed on some targets because LibGGI doesn't tell what the
stride is until you actually set a mode, while SVGAlib can do that.
On most targets this causes no problems because the SVGAlib wrapper
simply assumes that the stride is equal to the horizontal resolution
multiplied by the pixel size.

But on some targets (specificly the DGA target) you have a fixed stride
and in that case you have to set GSW_WIDTH to the appropriate value.
To found out what this value should be for the DGA target you need to
know the maximum configured horizontal resolution of your X-server.
Multiply this with the pixel size in bytes and you have the value to
which you should set GSW_WIDTH.
Example:
Maximum horizontal resolution is 768 pixels and your X-server is
runningin 16bpp. The pixel size is 16/8==2 bytes, thus you should
set GSW_WIDTH to 1536.


Application-specific hints
==========================

Quake I/II/World -
Always set GSW_ASYNC (to anything but "mouse"), GSW_PAGEEMU,
GSW_MODEEMU and GSW_DB.
Setting GSW_BUT2KEY does not hurt even if your mouse has less than 
four buttons.
GSW_WIDTH shold _NOT_ be used when GSW_PAGEEMU and GSW_MODEEMU is set.

Also note that LibGGI'sX-target has builtin mouse grabbing. This means
that you can use the mouse even when running Quake in an X-window!
(The native X-version of Quake II supports this too, but for obvious
reasons you can't use that version with the SVGAlib wrapper ;)

To toggle this feature on and off, just press CTRL-ALT-m in the
GGI-on-X window. (When running on the DGA-target this feature is not
needed as you're in full-screen mode and the mouse always works fine)

Quake I has some visual artifacts in resolutions higher than 320x200
that I haven't tracked down yet, but they are not very serious.
Quake II works flawlessly.

Executor - 
Not tested yet, but be sure I will do that.


CREDITS
=======

Jason McMullan -
Originally laid out the framework and proved the concept with GGI 0.0.8

Todd T. Fries -
Was the maintainer until sometime around the winter 97/98

Marcus Sundberg -
Current maintainer.
Support for linear access via DirectBuffer and both absolute and
relative mouse events.
All the GSW_* features.
Mode emulation.


//Marcus Sundberg [marcus@ggi-project.org]