ioq3/code/unix/README.Linux

+----------------------------------------+
| Q3Test                                 |
| The Official Quake 3: Arena TEST       |
| Linux version                          |
| Revision 1.08                          |
| Released Aug 3, 1999                   |
| Copyright (C) 1999 id Software, inc.   |
+----------------------------------------+
| Documentation: Paul Jaquays            |
|                Dave Kirsch             |
+----------------------------------------+

Outline:

1.  Introduction
2.  Bug Reporting
3.  Installing Q3Test
4.  Running Q3Test.  Operating Instructions
5.  Known Issues

==================
== Section 1.   ==
== INTRODUCTION ==
==================

This is the Linux version of the test.

Before proceeding onward, please read the README.EULA file. This is
the End User License Agreement. It's the agreement between you and id
regarding this test.  Read it. Understand that the acts of loading or
running the software, or placing it on your computer hard drive, RAM,
or other storage, you are agreeing to be bound by the terms of the End
User License Agreement. So it's best to know what you are agreeing to.

The operating instructions for the test are included in the 
separate "README.Q3Test" file.  For the most part, the game functions
are the same across all platforms.  Differences will be noted when necessary.

+----------------+
| THIS IS A TEST |
+----------------+

We want to set the record straight from the outset. This is neither a
demo nor an ALPHA version of the final game and should not be expected
to behave as such. Q3Test is a test of Quake3: Arena's network technology
and graphics compatibility. While many of the game features that you will
see in this test are in a highly polished state, do not confuse this with
being anything other than what it is intended to be: a test. By running
this test openly on the Internet and on a multitude of local networks,
we hope to expose problems that could not otherwise be discovered on the
limited number of in-house systems and computer. That's why we need your
assistance for this test.

Furthermore, it is anticipated that there may be revisions and additions
made to the test that will make it incompatible with earlier versions.

+---------------------+
| SYSTEM REQUIREMENTS |
+---------------------+

There is no software-only version of the game. If your computer is not
hardware accelerated with a game compatible graphics card, you will NOT be
able to run Q3Test. Currently, 3DFX based cards are the only
tested compatible cards. If your computer does not meet the 
minimum requirements, you are unlikely to be able to run a satisfactory 
game experience.

A glibc compatible Linux installation is required.  An easy to determine
if you have glibc support is to type this:

	ls -l /lib/libc*

If you get a report of libc6 (you may also have libc5), you have a
glibc based system.

The Linux version requires a supported hardware 3D acceleration card. The
following are currently supported:

        o 3Dfx Voodoo Graphics based cards
        o 3Dfx Voodoo2 based cards

Other cards of similar make and model may work, but are not supported.

Other X11 OpenGL libraries may work with a supported hardware
accelerator, but have not been extensively tested.  Performance on
untested OpenGL configurations may not produce acceptable game
speed.

For 3Dfx based products, Linux Q3Test is distributed with a version of Mesa
3-D specifically compiled for Voodoo support. You must have 3Dfx Linux Glide
drivers installed however. These drivers are available from:

		http://glide.xxedgexx.com/3DfxRPMS.html

Make sure that you download and install the glibc versions of the drivers
(found at the bottom of the page).

Mirrors for this site are can be found at:

		http://glide.mirrors.sonic.net 
		http://glide.samiam.org 

Please follow the installation instructions presented there for adding the
correct drivers for your 3D-acceleration card. Note that there are two ways
to install the 3DFX drivers-one with support for a /dev/3dfx device that
does not require root permissions in order to use the card. If you choose to
not use the /dev/3dfx method, you will have to run Q3Test as the root user.

NOTE:  Linux Q3Test will try to load "libGL.so" before using 3Dfx drivers.
This can cause problems if you have a software or third party OpenGL driver
installed.  You can specifically target the included 3Dfx based Mesa driver
by using the following command line:

	./linuxquake3 +set r_glDriver libMesaVoodooGL.so.3.1

For 3DFX users, you may disable the vertical sync refresh.  This can improve
proformance at the cost of some visual tearing of the image.  Entering the
following command into your shell before running Q3Test will turn off
the vertical sync:

	export FX_GLIDE_SWAPINTERVAL=0

Then run Linux Q3Test from the same command line normally.

+-----------+
| X11 Setup |
+-----------+

Linux Q3Test requires X11 to run. There is no console-based version as in
previous id products such as GLQuake and Quake2. XFree86 version 3.2 or
later is required.

There are two ways that mouse input is handled under XFree86:

        o By default, Q3Test will attempt to use DGA mouse handling. DGA
          support features direct reading of the mouse motion and provides
          more accurate control while playing the game. By default this
          support is enabled, but can be disabled by adding "+set
          in_dgamouse 0" to the command line at startup.
        o The non-DGA method of mouse input uses pointer grabbing and warps
          the pointer to the middle of the window on each mouse update. On
          systems with a slow frame rate and a lot of mouse user input, the
          motion can get "clipped" to the window boundaries. This method of
          input is more compatible however.

Q3Test uses the XFree86 VidModeExtension facilities if available to provide
fullscreen play. This does not apply to 3Dfx passthrough based cards, since
the passthrough cable takes over the video display upon activation anyway.

When configuring your X11 server, make sure that you include lower
resolution modes such as 640x480 and 800x600. Q3Test will auto-switch to
these modes using the VidModeExtension if you select fullscreen from the
graphics options menu. If the lower resolution modes are not listed in the
XFree86 configuration file, Q3Test will be unable to switch to the desired
resolution for fullscreen play.

+-------------------------+
| Sound Support and Setup |
+-------------------------+

Q3Test uses the /dev/dsp sound device for sound support under Linux. This is
the default device provided by the sound drivers included with the Linux
kernel. Please note that at the time of this writing, PCI based sound cards
such as the SoundBlaster Live and Diamond Monster MX series were not
supported. They may be supported in the future. Check
http://www.opensound.com/ for support in the future.

If you do not run Q3Test as root (recommended), you may need to make sure
the permissions for the /dev/dsp device are read and write by the user
running Q3Test. The cheap and easy way to make this happen is to do "chmod
o+rw /dev/dsp" as root. For the more security conscious, a special sound
group could be created and Q3Test could be made setgid to the sound group to
access the device.

Q3Test uses mmap() to map the sound buffers on /dev/dsp directly in order to
provide responsive sound needs. Sound cards must be able to support this
feature in order to work. SoundBlaster 16, AWE32 and AWE64 cards are known
to work.

+----------------------+
| WHAT'S IN THIS TEST? |
+----------------------+

We have included three maps with this test version of Quake3: Arena. They
are q3test1, q3test2,  and q3tourney.

q3test1    for 4-8 players    on Internet or LAN play   Best with 6 players
q3test2    for 3-8 players    Primarily for LAN play    Best with 3 players 
q3tourney is the tournament map

===================
== Section 2.    ==
== BUG REPORTING ==
===================

What we would like from our testers are emails with descriptions of
problems that are encountered, particularly those involving video or
network bugs. Do NOT send reports to individual id employees.  All bug
reports should go to the following e-mail address:

q3feedback@idsoftware.com

In your subject line, please describe the system the game is being played
on (Mac, Linux, Win32) and the type of problem you are reporting: video,
network, sound or game. Example Subject Line:  "Mac/video problem" or
"Linux/network connection problem."

In the body of your letter (no attached files please), briefly list and
describe the problems.  Detailed descriptions of problems are good, but
remember that brevity is best. Please do NOT send screen shots unless
they are the ONLY way to show a problem.

While we realize that you may have comments and suggestions regarding
specific game play features, please refrain from submitting such along
with bug reports. Comments on game play can be made on the official
Quake 3: Arena message board at:

http://www.quake3arena.com 

========================
== Section 3.         ==
== INSTALLING Q3TEST  ==
========================

After you have installed the needed hardware drivers for your 3D
acceleration and sound hardware, you need to install the Q3Test package.

Q3Test is available as a Red Hat RPM file or as a tar file. To install the
RPM file, enter the following when logged in as the root user:

rpm -Uvh q3test-1.00-glibc-1.i386.rpm

The rpm installs the game and data files in /usr/local/games/q3test.

[ Note: If you have not installed (or do not wish to install) the Linux
glide drivers, you may get an error message about not having libglide2x.so 
installed.  This can be ignored and installation can be forced by adding 
the --nodeps option to the rpm command line as follows: 
rpm --nodeps -Uvh q3test-1.00-glibc-1.i386.rpm ]

If you are going to install the tar version, make a directory for
installation, untar the file as follows:

tar xzvf q3test-1.00-glibc-i386.tar.gz

This will untar the files into a q3test subdirectory under the current
directory.

====================
== Section 4.     ==
== RUNNING Q3TEST ==
====================

It is recommended that you do not run Q3Test using the root account or with
root privileges. There are two exceptions to this:

        o If you are using a 3Dfx based accelerator card and do not install
          the /dev/3dfx configuration option. (You will have to run as root
          in order to access the card).
        o If you do not have access to the /dev/dsp device and do not wish
          to change the mode of the device so that non-root accounts can
          access it.

You will have to be running under X11 or have the DISPLAY variable pointed
to a OpenGL glX capable X Server.

By default, Q3Test tries to find the following OpenGL libraries in this
order:

        o libGL.so.1
        o libMesaVoodooGL.so.3.1

You can override the library name by entering, "+set r_glDriver <libname>"
on the command line. This may be needed if you are using a non-standard set
up and have a different name for the OpenGL shared library.

If everything proceeds successfully, you should have a Q3Test window on your
desktop with a menu displayed (3DFX owners will get a full screen view). If
you want to use full screen, go to the System Configuration, Graphics
Options, Fullscreen, change the value to Yes, and hit enter to apply it.

If you intend to connect to the Internet to play Q3Test, make certain
that your net connection is open and working first.

======================
== Section 5.       ==
== KNOWN ISSUES     ==
======================

Q. My mouse is erratic. My player is constantly looking up or down and
I can't seem to move him.

A. This happens with two issues. Some versions of XFree86 have a bug in
DGA mouse handling that confuses Q3Test. You can try turning off DGA mouse
support by entering "+set in_dgamouse 0" on the command line when you
start Q3Test. This problem can also occur after a restart of the video
system (such as after a graphic setting change). This is because some
sort of event occurred to jam up the mouse. Restarting the video system
another time and not moving the mouse during the restart should clear it.


Q. When I do a video restart (for example, selecting Apply in the Graphics
Options menu), Q3Test exits with a Sig11.

A. This is a driver related problem.  
On 3DFX hardware that is using the /dev/3dfx device and you are NOT running 
as root, it seems that the restart doesn't clear some sort of permission. 
Running Q3Test as root will fix this problem.  


Q. Performance is so slow I can't play! The frame rate looks like one
frame per second!

A. Most of the current drivers for Linux do not support hardware
acceleration at any bit depth other than 15 or 16 bit color. Make sure
that you specify 16 bit color when you run your X11 Server, such as:

	startx -- -bpp 16


Q. I have a Voodoo3.  When I start the game, I send up at a low resolution
version of my desktop.

A. The current Voodoo3 X11 Servers have problems with DGA Mouse support.
This is a known driver issue and will be fixed in newer revisions of the
Voodoo3 X11 Server.  Run the game with the following to disable it:
	./linuxquake3 +set in_dgamouse 0


Q. I'm running Gnome with Englightenment and sound doesn't work.

A. If you are using the Enlightenment Sound Daemon (esd), it will not release
the sound hardware for Quake3 Test's usage.  You can disable it before running
the test as follows:
		esdctl off  # turn it off
		start q3test the normal way
		esdctl on   # turn it back on


Q. I try to run Q3Test, but sound doesn't work.  The console says "Can't
open /dev/dsp.  /dev/dsp:  Can't allocate memory."

A. This can happen if the vmware kernel modules are loaded.  You can unload
them by typing when logged as root:
	/etc/rc.d/init.d/vmware stop
Assuming you are using a RedHat system.


Q. I was playing Q3Test and suddenly it quit and reported a signal error.

A. This is probably a bug. Please report it.