+----------------------------------------+
| The Official Quake Deathmatch TEST     |
| Released Saturday, February 24th, 1996 |
| Copyright (C) 1996 id Software, inc.   |
+----------------------------------------+
| Video Subsystem Documentation          |
| by Michael Abrash                      |
+----------------------------------------+

Quick start
-----------

To see the video modes available, bring up the console (either
start Quake without loading a level, or press Esc while in a level).
Type vid_describemodes<enter> to see all available modes.  Type
vid_mode <mode #> to set a mode, where <mode #> is the mode number
listed for the desired mode by vid_describemodes.

See "Bug Reporting," below, for information on how to report any
problems you encounter.


More detail
-----------

This version of Quake supports software drawing in a variety of
video modes.  It does not support any hardware accelerators.  Video
modes that are always supported are:

320x200, 360x200, 320x240, 360x240, 320x350, 360x350, 320x400,
360x400, 320x480, 360x480

In addition, all VESA 2.0 256-color linear framebuffer modes
supported by the video adapter are supported.  Further information
about VESA 2.0 is provided below.


Video mode reporting and selection
----------------------------------

Quake assigns each available video mode a mode number, which can
then be used to query information about the mode or to select the
mode.  The first 11 mode numbers are always as follows:

0:  320x200
1:  320x200
2:  360x200
3:  320x240
4:  360x240
5:  320x350
6:  360x350
7:  320x400
8:  360x400
9:  320x480
10: 360x480

You will notice that modes 0 and 1 are both 320x200; mode 1 is a
Mode X-style version, which will someday allow support of page
flipping for cleaner graphics, but right now it's just slower with
no advantages, so use mode 0 for 320x200 resolution.  Modes 2-10
are all higher resolution than mode 0, and look very nice, but are
also all slower than mode 0.  Mode 0 is the fastest of the 11
built-in modes.

In addition to the built-in modes, Quake checks for the presence
of a VESA version 2.0 driver.  If such a driver is detected, the
driver is queried for all 8-bit-per-pixel linear framebuffer (LFB)
modes that are supported.  All such modes are added to the mode
list starting at mode 11.  The available modes will vary depending
on adapter, graphics chipset, amount of memory, and VESA 2.0 driver.
The higher the resolution, the lower the performance, and the
higher-resolution modes will often be too slow for good gameplay
on most machines.  The screen can be sized down to improve performance
in higher-resolution modes, but then of course the effective
resolution of Quake is reduced.

In its current form, Quake supports only page-flipped VESA modes.
This means that on adapters, such as the Diamond Viper, that don't
support VESA-compatible page-flipping, Quake will not report any
available VESA modes.  Modes 0-10 will still be supported on those
adapters, however.  Similarly, modes that use more than half the
total video memory for the screen, and thus can't provide two pages
for page-flipping, are not available under Quake.  Thus, on a 1 Mb
adapter, a 1024x768 mode, which uses 0.75 Mb, will not be reported
as available.

Quake always starts up in mode 0, and modes 0-10 are always available.


How to get VESA 2.0 support
---------------------------

Some video adapters have VESA 2.0 support in ROM.  Other video
adapters come with loadable VESA 2.0 TSRs.  In the absence of either
of these, UniVBE, from SciTech, provides VESA 2.0 support for most
video adapters.  The latest version of UniVBE can be obtained from
the following locations:

www: http://www.scitechsoft.com
ftp: ftp.scitechsoft.com
Compuserve: GO VESA
AOL: Keyword VESA

SciTech can be contacted at:

email: sales@scitechsoft.com

SciTech Software
5 Governors Lane, Suite D
Chico, CA
95926-1989

The currently most recent version is UniVBE 5.1a.  UniVBE 5.2,
which should be released soon, will support more adapters and add
many low- and medium-resolution modes, such as 512x384.


Video-related commands
----------------------

vid_describecurrentmode: lists the description for the current
video mode.

vid_describemode <mode #>: lists the description for the specified
video mode, where <mode #> is as reported by vid_describemodes.

vid_describemodes: lists descriptions for all available video modes.

vid_mode <mode #>: sets the display to the specified mode, where
<mode #> is as reported by vid_describemodes.

vid_nummodes: reports the total number of modes available.

vid_testmode <mode #>:  tries to switch Quake to the specified
mode, then returns to the current mode after 5 seconds.  This allows
you to try an untested mode without ending up with a black screen
if, for example, the monitor can't display the mode properly.
There may still be instances in which, due to VESA driver or hardware
bugs, the machine will hang in certain modes; vid_testmode can't
recover from these situations, but it can recover from a blank or
scrambled screen.

vid_wait <wait type>: sets the type of waiting that the video
adapter should do, as follows:

0: no waiting
1: wait for vertical sync active
2: wait for display enable active

The default state of vid_wait depends on the video mode selected.
In built-in modes 0-10, the default is always 0, no waiting.  You
can set vid_wait to 1 (wait for vertical sync) to eliminate shear
and tearing in these modes (so partially-completed frames are never
drawn, resulting in a rock-solid image).  However, waiting for
vertical sync can result in substantial performance loss.

In VESA modes, if the adapter is VGA compatible and there's enough
memory for three video pages, then triple-buffering is enabled and
vid_wait is set to 2, wait for display enable.  There is little
performance loss to this sort of waiting.  If the adapter is not
VGA compatible, or if there's only enough memory for double-buffering,
then vid_wait is set to 1 (wait for vertical sync).  This can cause
significant loss of performance, but some sort of wait is generally
necessary to avoid occasional glitching of the screen when
page-flipping; we always choose the lowest-cost wait option that
we're sure is safe to use.

The default setting for vid_wait can be changed from the console
at any time.  If you are in a VESA mode that waits for vertical
sync and want to turn it off to get a speed-up, you can do so.
However, changing a vid_wait 1 default in a VESA mode may result
in problems.  If vid_wait defaults to 1 (wait for vertical sync)
in a mode, and you force it to 2 (wait for display enable), the
machine may hang, because some VGA-incompatible adapters, such as
some ATI Mach64s, don't support the display enable status.  If you
force vid_wait to 0 (no wait), then the screen may glitch periodically
if the page flips at a time that results in a bad flip address,
although some adapters work fine with no wait at all.

If you force a new setting for vid_wait and encounter problems, DO
NOT send us a bug report!


Setting the video mode automatically
------------------------------------

If you want to default to a mode other than mode 0, place the line:

vid_mode <mode #>

in your .cfg file; the mode will be selected when you exec the .cfg
file, either from the console or with +exec <filename>.cfg on the
command line when you start Quake.  Note that if you use the .cfg
file on another machine, it may cause problems if the other machine
doesn't support the specified mode; the mode set should merely
fail, but bugs in the VESA driver or the hardware can possibly
cause the machine to hang.  You can always get the machine to
function properly by removing the vid_mode line from the .cfg file,
or not execing the .cfg file.


Known video problems and workarounds
------------------------------------

There are currently no known video bugs in Quake, which of course
doesn't mean there are no video bugs.  If you think you've encountered
a bug, see "Bug Reporting," below.  As a general rule, go back to
mode 0 if you have problems; mode 0 should work properly in all
cases.

On some ATI Mach64 adapters, the palette is sometimes too dark in
320x200 and 320x240 VESA modes.  The workaround is to use different
modes, such as 360x200, 360x240, or mode 0.

In modes 0-10, shear and tearing can occur as partially finished
frames are displayed.  Workaround:  set vid_wait to 1 (wait for
vertical sync); this can result in a substantial performance loss,
however.  An alternative is to use a VESA mode.

In VESA modes, occasional glitched frames may occur with some VESA
driver-hardware combinations.  Workaround:  set vid_wait to 1 (wait
for vertical sync), or use a different mode.

A very fast machine displaying simple scenes could possibly run
faster than the video frame rate, resulting in flicker.  Workaround:
set vid_wait to 1 (wait for vertical sync).  An alternative is to
use a higher-resolution mode.


Performance
-----------

Quake's graphics are not yet fully optimized, but should be adequately
fast on all Pentium-class machines.  486-based machines will be
sluggish.  You will see a turtle icon appear in the upper left
corner of the screen if the frame rate drops below 10 frame/second;
if you are getting the turtle, you are probably not getting great
gameplay.  Performance can be improved in several ways:

* size down the screen with the minus key

* select a lower-resolution mode, if possible

* use a VESA mode

* if you're using a VESA mode and vid_wait is set to 1 (wait for
vertical sync) by default (you can check by typing vid_wait<enter>
in the console), you can try setting vid_wait to 0 or 2, as detailed
in the discussion of the vid_wait command above.  Be aware that
risks of screen glitching or hung machines are associated with
overriding a default vid_wait 1 setting in VESA modes.


Bug Reporting
-------------

If you encounter a video-related bug, please fill out the following
form and e-mail it to qtest1@idsoftware.com.  There are several
problems that are not bugs, and shouldn't be reported, including:

* unavailability of some VESA modes; as noted above, VESA modes
are only supported by Quake if they have enough memory and the
hardware capability to support VESA-style page-flipping

* problems that occur when you change vid_wait from a default value
of 1 (wait for vertical sync) in VESA modes

* sluggish performance, especially on 486s

* the known palette problem in 320x200 and 320x240 VESA modes on
some Mach64s.

Apart from these, we would very much like to hear about any video
problems you encounter.


-------------------------------cut here-------------------------------------

		    Quake Deathmatch TEST #1 Bug Report


E-mail to: qtest1@idsoftware.com


Date:


Name:

Company:

Street address:

City, state, ZIP:

Phone:

Fax:

E-mail:



Manufacturer/model of graphics adapter (company, model, chipset if
known; if you are using UniVBE, please run uvconfig and list the
chipset, RAMDAC, and clock chipinformation that's reported):





Is the problem associated with a VESA mode?



If so, what is the VESA driver and version?  (eg., UniVBE 5.1a,
built into board BIOS, or manufacturer provided TSR)



What operating system are you running?  (eg., DOS 6.0 or Windows
95):




Please describe the problem you are encountering, including a
procedure for reproducing the problem:




Please list any error messages, crash dump, or other information
that you think might be relevant:




-------------------------------cut here-------------------------------------
