WinGlide v0.99 - 1/25/1999
Enhancements Copr. 1998, 1999 Chris Dohnal
cwdohnal@ucdavis.edu

Based on
WinGlide v0.5 - 1/4/1998
Copr. 1998 Justin Frankel/Nullsoft, Inc.
justin@nullsoft.com

Thanks to
Justin Frankel for WinGlide v0.5
Andy Murdoch for the MMX detection code
Everyone else who has helped with WinGlide

What is WinGlide?
WinGlide allows 3Dfx Voodoo Graphics boards to output to a window.
The included glide2x.dll works by intercepting a few calls to the 3Dfx card and copying each
completed frame from the 3Dfx card to your 2D card.

The included glide2x.dll needs the glide2x.dll from 3Dfx to work properly.  You should leave the
3Dfx glide2x.dll in your Windows\System directory and put the included glide2x.dll in the same
directory as the application you want to use it with.

DO NOT COPY THE INCLUDED GLIDE2X.DLL INTO YOUR WINDOWS OR SYSTEM DIRECTORIES.


WinGlide mode settings
--------------------------------------------------------------------------------
WinGlide v0.99 supports four modes of operation:
- B2 WinGlide
- StretchBlt WinGlide
- Overlay WinGlide
- Off-screen Surface WinGlide

The [Mode] section of wg.ini is used to tell WinGlide what mode it should use.
Each available WinGlide mode will have a key in the [Mode] section of wg.ini.
Only one of these keys should be set equal to 1 at any one time.
- To use B2 WinGlide, set the B2WinGlide key equal to 1 and set the all of the other
mode keys equal to 0, or comment them out by putting a ; in front of them, or do not
include them in the ini file at all.
- To use StretchBlt WinGlide, set the StretchBltWinGlide key equal to 1 and set all of
the other mode keys equal to 0, comment them out, or do not include them in the ini file.
- To use Overlay WinGlide, set the OverlayWinGlide key equal to 1 and set all of the
other mode keys equal to 0, comment them out, or do not include them in the ini file.
- To use Off-screen Surface WinGlide, set the OffScreenSurfaceWinGlide key equal to 1
and set all of the other mode keys equal to 0, comment them out, or do not include
them in the ini file.

To use B2 WinGlide:
-------------------
[Mode]
B2WinGlide=1
StretchBltWinGlide=0
OverlayWinGlide=0
OffScreenSurfaceWinGlide=0

	- or -

[Mode]
B2WinGlide=1

To use Overlay WinGlide:
------------------------
[Mode]
B2WinGlide=0
StretchBltWinGlide=0
OverlayWinGlide=1
OffScreenSurfaceWinGlide=0

	- or -

[Mode]
OverlayWinGlide=1

Make similar modifications to the mode section of the ini file to use other WinGlide modes.


B2 WinGlide v0.99
--------------------------------------------------------------------------------
* Designed to be used with 3Dfx OpenGL Beta 2 or 3Dfx OpenGL Beta 2.1 to support some programs
that use OpenGL to render to a single window.  Also works with the miniGL.
* Programs that use OpenGL to render to multiple windows are not supported.
* Handles window resizing.
* Has gamma correction support.
* Has MMX support.
* Will not work with scanline interleaved systems.
* Supports multi-threading for improved performance on multi-processor systems.

Notes:
* Framerate goes way down.
* Possibly incompatible with some applications.  Not all of glide2x.dll is passed through.
* Will not work with applications that do not supply a window handle.

B2 WinGlide features and ini file format:
-----------------------------------------
B2 WinGlide reads configuration information from the ini file wg.ini.  B2 WinGlide and this 
ini file should be placed in the same directory as the application that is using B2 WinGlide.

Here's a sample ini file:
--- Beginning of wg.ini ---
[WinGlide]
MMX=0
Multi-threading=0
320x240Fix=0
SystemMenuOptions=0

[Mode]
B2WinGlide=1

[GammaCorrection]
Enable=1
Red=1.7
Green=1.7
Blue=1.7
--- End of wg.ini ---

[WinGlide] section of wg.ini
----------------------------
This version of WinGlide has MMX detection.  If the MMX key is not present in the ini file or if it
is set to 2, WinGlide will automatically use MMX instructions if it detects a processor that
supports MMX.

Overriding the MMX detection:
Setting the MMX key to 1 will enable WinGlide's MMX support and setting it to 0 will tell
WinGlide not to use MMX instructions.  Since WinGlide does not verify that it is running on
an MMX capable processor when overriding MMX detection, if the MMX key is set to 1 and
WinGlide is run on a processor that does not support MMX instructions, an invalid instruction
exception will be generated.

Setting the 320x240Fix key equal to 1 will enabled a fix in WinGlide that allows 320x240 windowed
to work when used with 3Dfx MiniGL v1.46.  If you cannot use 320x240 windowed but other windowed
resolutions work, see if enabling this fix makes 320x240 windowed work.

WinGlide's multi-threading support can improve performance on multi-processor systems.
This version of WinGlide has multi-processor detection and can automatically enable multi-threading
if it detects that there are multiple processors.  If the Multi-threading key is not present in the
ini file or if it is set to 2, WinGlide will automatically enable multi-threading if it detects
that it is running on a multi-processor system.

Overriding the multi-processor detection:
Setting the Multi-threading key to 1 will enable WinGlide's multi-threading support and setting the
Multi-threading key to 0 will disable WinGlide's multi-threading support.

[GammaCorrection] section of wg.ini
-----------------------------------
Set the Enable key to 1 to enable gamma correction or 0 to disable gamma correction.

The Red, Green, and Blue keys control the level of red, green, and blue gamma correction.  WinGlide
will accept values ranging from 0.0 to 10.0.  Values below 1.0 will make things darker and values
above 1.0 will make things brighter.  1.7 is the default.


StretchBlt WinGlide v0.99
--------------------------------------------------------------------------------
* Has gamma correction support.
* Has MMX support.
* Will not work with scanline interleaved systems.
* Supports multi-threading for improved performance on multi-processor systems.
* The output window can be stretched.
* Only use this WinGlide mode with a program that displays its output in a fixed sized window.

Notes:
* Framerate goes way down.
* Possibly incompatible with some applications.  Not all of glide2x.dll is passed through.
* Will not work with applications that do not supply a window handle.

StretchBlt WinGlide features and ini file format:
-------------------------------------------------
StretchBlt WinGlide reads configuration information from the ini file wg.ini.  This file should
be placed in the same directory as the application that is using StretchBlt WinGlide.  If you are
using StretchBlt WinGlide with Quake 2, put both the StretchBlt WinGlide glide2x.dll and wg.ini in
your Quake 2 directory.

Here's a sample ini file:
--- Beginning of wg.ini ---
[WinGlide]
MMX=0
Multi-threading=0
320x240Fix=0
SystemMenuOptions=0

[Mode]
StretchBltWinGlide=1

[GammaCorrection]
Enable=1
Red=1.7
Green=1.7
Blue=1.7
--- End of wg.ini ---

[WinGlide] section of wg.ini
----------------------------
This version of WinGlide has MMX detection.  If the MMX key is not present in the ini file or
if it is set to 2, WinGlide will automatically use MMX instructions if it detects a processor
that supports MMX.

Overriding the MMX detection:
Setting the MMX key to 1 will enable WinGlide's MMX support and setting it to 0 will tell
WinGlide not to use MMX instructions.  Since WinGlide does not verify that it is running on
an MMX capable processor when overriding MMX detection, if the MMX key is set to 1 and
WinGlide is run on a processor that does not support MMX instructions, an invalid instruction
exception will be generated.

Setting the 320x240Fix key equal to 1 will enabled a fix in WinGlide that allows 320x240 windowed
to work when used with 3Dfx MiniGL v1.46.  If you cannot use 320x240 windowed but other windowed
resolutions work, see if enabling this fix makes 320x240 windowed work.

WinGlide's multi-threading support can improve performance on multi-processor systems.
This version of WinGlide has multi-processor detection and can automatically enable multi-threading
if it detects that there are multiple processors.  If the Multi-threading key is not present in the
ini file or if it is set to 2, WinGlide will automatically enable multi-threading if it detects
that it is running on a multi-processor system.

Overriding the multi-processor detection:
Setting the Multi-threading key to 1 will enable WinGlide's multi-threading support and setting the
Multi-threading key to 0 will disable WinGlide's multi-threading support.

Setting the SystemMenuOptions key to 1 will allow WinGlide to add menu items to the system menu.
Setting this key to 0 will leave the system menu unchanged.  If you are using WinGlide with an
application that adds its own menu items to the system menu, this option should be disabled because
it could cause WinGlide to interfere with the processing of those menu items.

[GammaCorrection] section of wg.ini
-----------------------------------
Set the Enable key to 1 to enable gamma correction or 0 to disable gamma correction.

The Red, Green, and Blue keys control the level of red, green, and blue gamma correction.
Overlay WinGlide will accept values ranging from 0.0 to 10.0.  Values below 1.0 will make things
darker and values above 1.0 will make things brighter.  1.7 is the default.


Overlay WinGlide v0.99
--------------------------------------------------------------------------------
* Uses hardware overlays to boost performance and add additional features to WinGlide.
* Requires DirectDraw and a video card that supports RGB 565 hardware overlays.
* Has gamma correction support.
* Has MMX optimizations.
* Will not work with scanline interleaved systems.
* The output window can be stretched to any size supported by your video hardware.  Many video
cards will support stretching an overlay with interpolation at no performance cost.  With this
feature, you can run GLQuake at a low resolution like 320x240 or 400x300 to get a good framerate
and then stretch the output window so it covers more of the screen.  Stretching with
interpolation should also provide better image quality than pixel doubling.
* Has the option to use a double buffered or triple buffered overlay.
* Only use this WinGlide mode with a program that displays its output in a fixed sized window.

Notes:
* Framerate goes way down.
* Possibly incompatible with some applications.  Not all of glide2x.dll is passed through.
* Will not work with applications that do not supply a window handle.

Overlay WinGlide features and ini file format:
----------------------------------------------
Overlay WinGlide reads configuration information from the ini file wg.ini.  This file should
be placed in the same directory as the application that is using Overlay WinGlide.  If you are
using Overlay WinGlide with Quake 2, put both the Overlay WinGlide glide2x.dll and wg.ini in your
Quake 2 directory.

Here's a sample ini file:
--- Beginning of wg.ini ---
[WinGlide]
MMX=0
320x240Fix=0
SystemMenuOptions=0

[Mode]
OverlayWinGlide=1

[GammaCorrection]
Enable=1
Red=1.7
Green=1.7
Blue=1.7

[Overlay]
BackBufferCount=0
Clipping=1
AlphaBlending=0
Red=112
Green=112
Blue=112
--- End of wg.ini ---

[WinGlide] section of wg.ini
----------------------------
This version of WinGlide has MMX detection.  If the MMX key is not present in the ini file or if it
is set to 2, WinGlide will automatically use MMX instructions if it detects a processor that
supports MMX.

Overriding the MMX detection:
Setting the MMX key to 1 will enable WinGlide's MMX support and setting it to 0 will tell
WinGlide not to use MMX instructions.  Since WinGlide does not verify that it is running on
an MMX capable processor when overriding MMX detection, if the MMX key is set to 1 and
WinGlide is run on a processor that does not support MMX instructions, an invalid instruction
exception will be generated.

Setting the 320x240Fix key equal to 1 will enabled a fix in WinGlide that allows 320x240 windowed
to work when used with 3Dfx MiniGL v1.46.  If you cannot use 320x240 windowed but other windowed
resolutions work, see if enabling this fix makes 320x240 windowed work.

Setting the SystemMenuOptions key to 1 will allow WinGlide to add menu items to the system menu.
Setting this key to 0 will leave the system menu unchanged.  If you are using WinGlide with an
application that adds its own menu items to the system menu, this option should be disabled because
it could cause WinGlide to interfere with the processing of those menu items.

[GammaCorrection] section of wg.ini
-----------------------------------
Set the Enable key to 1 to enable gamma correction or 0 to disable gamma correction.

The Red, Green, and Blue keys control the level of red, green, and blue gamma correction.
Overlay WinGlide will accept values ranging from 0.0 to 10.0.  Values below 1.0 will make things
darker and values above 1.0 will make things brighter.  1.7 is the default.

[Overlay] section of wg.ini
---------------------------
Set the BackBufferCount key to 0 to use a single buffered overlay, 1 to use a double buffered
overlay, or 2 to use a triple buffered overlay.  A double buffered overlay can prevent tearing
and it will require twice as much video memory as a single buffered overlay.  A triple buffered
overlay can prevent tearing like a double buffered overlay and it may provide better performance
compared to a double buffered overlay.  A triple buffered overlay will require three times as
much video memory as a single buffered overlay.

Setting the Clipping key to 1 will enable clipping and setting it to 0 will disable clipping.
Clipping requires a 2D card that supports destination color keying.  Without clipping, the
overlay surface will cover other windows even when they should be displayed over the window
displaying the overlay.

Setting the AlphaBlending key to 1 will enable alpha blending and setting it to 0 will disable
alpha blending.  Overlay WinGlide's alpha blending feature requires a video card that supports
destination alpha blending using a constant alpha value for the destination.  By blending the
overlay with background color of the window, the brightness and color of the image can be
adjusted.

Some video cards may support both clipping and alpha blending but may not support using clipping
and alpha blending at the same time.

The Red, Green, and Blue keys are used to set the background color of the window.  This color is
used for both clipping and alpha blending.  Valid values for each of these three keys are in the
range 0 to 255.

Overlay WinGlide uses destination color keying to allow the overlay to only be displayed over
the background color of the window displaying the overlay.  This prevents the overlay from being
drawn over other windows that cover the window displaying the overlay because the overlay is only
drawn over pixels with the same color as the background of the window displaying the overlay.
For this reason, you should not choose a background color that is commonly used in your other
applications.  When using alpha blending, Overlay WinGlide will display the overlay over the
background color of the window using partial transparency.

If Overlay WinGlide can't find wg.ini, it will default to using no clipping, no alpha blending
and a background color with red, green and blue values of 112.

If the overlay is covering up your other windows because you don't have clipping enabled or have
alpha blending enabled but have clipping disabled, you can make the overlay go away by minimizing
the window displaying the overlay.  Restoring the window will bring the overlay back.

Getting Overlay WinGlide to restore the overlay surface in video memory if it is lost
-------------------------------------------------------------------------------------
If the overlay surface in video memory used by Overlay WinGlide is lost, Overlay WinGlide will
attempt to restore the surface if the window is resized.  Overlay WinGlide may lose its surface
in video memory when the video mode is changed or when a program that uses a DirectDraw
fullscreen video mode is switched to.

Overlay WinGlide error messages
-------------------------------
Overlay WinGlide will display error messages when it cannot get the overlay to be displayed.
Some of these error messages can be confusing because they do not directly describe the error
that occurred.
Here are some examples:
1. If you run Overlay WinGlide, switch to a higher resolution video mode that does not leave
enough video memory for the overlay surface and then resize the window so that Overlay WinGlide
tries to restore the surface, it will say "Invalid object" rather than "Out of memory".
2. Many of the error messages are based on the error codes returned by DirectDraw which do not
always give a good description of what went wrong.  Overlay WinGlide will usually say "Invalid
window size" when I choose a size that does not work because of the minimum overlay stretch
factor but if I change the window size to certain size ranges, it will say "No stretch hardware".

Tips for getting Overlay WinGlide to work on your computer
----------------------------------------------------------
If you do not see anything in the window after the game has finished initializing, your card
may have a minimum overlay stretch factor that is greater than 1.  Make the window bigger or
maximize it to see if overlays will start working.  Also, start the game at a low resolution such
as 320x240 at first so that you have room to make the window bigger.

Sometimes Quake 2 will capture the mouse, preventing you from moving or resizing the window.
To move or resize the window, make another window active and then click on the title bar or
resizing border of the inactive Quake 2 window.

If you are running Quake 2 at 512x384 or 640x480 and cannot get overlays to work (possibly
because of a minimum overlay stretch factor that is too large), you can just hit Alt-Enter to
tell Quake 2 to switch back to fullscreen.

If you still do not see anything after running GLQuake or Quake 2 at 320x240 and maximizing the
output window, overlays may not be working properly on your system.  Future version of Overlay
WinGlide will have better error reporting to give a more detailed description of what went
wrong.

If you have the DirectX 5 control panel for Windows 95, you can see what your minimum and
maximum overlay stretch factors are by looking at the overlay capabilities on the DirectDraw
tab.  If your card does not support overlays, this can also be determined by looking at the
information reported on the DirectDraw tab.

Running Quake or Quake 2 at 320x240 and stretching the overlay to whatever size you want the
output window to be should give you a very playable framerate.

Overlays require extra video memory.  If you are running at a high resolution on a 2MB video
card, there may not be enough memory left to create the overlay.  The number of bytes required
by the overlay is equal to width * height * 2.  A 640x480 overlay requires 640 x 480 x 2 =
614.4K.  A 320x240 overlay only requires 153.6K.  The width and height used to calculate the
memory needed by the overlay is the width and height that the glide application is using, not
the width and height of the stretched output window.  Running GLQuake at 320x240 and stretching
the output window to 640x480 (or any other size supported by the hardware) would still only
require 153.6K of video memory.


Off-screen Surface WinGlide v0.99
--------------------------------------------------------------------------------
* Has gamma correction support.
* Has MMX support.
* Will not work with scanline interleaved systems.
* The output window can be stretched.
* Only use this WinGlide mode with a program that displays its output in a fixed sized window.
* This version only works with video cards that support off-screen YUY2 surfaces and functions
that can StretchBlt data from these surfaces to the primary surface.

Notes:
* Framerate goes way down.
* Possibly incompatible with some applications.  Not all of glide2x.dll is passed through.
* Will not work with applications that do not supply a window handle.

Off-screen Surface WinGlide features and ini file format:
---------------------------------------------------------
Off-screen Surface WinGlide reads configuration information from the ini file wg.ini.  This file
should be placed in the same directory as the application that is using Off-screen Surface WinGlide.
If you are using Off-screen Surface WinGlide with Quake 2, put both the Off-screen Surface WinGlide
glide2x.dll and wg.ini in your Quake 2 directory.

Here's a sample ini file:
--- Beginning of wg.ini ---
[WinGlide]
MMX=0
320x240Fix=0
SystemMenuOptions=0

[Mode]
OffScreenSurfaceWinGlide=1

[GammaCorrection]
Enable=1
Red=1.7
Green=1.7
Blue=1.7

[Overlay]
UseFourCCSurface=1
FourCC=YUY2
--- End of wg.ini ---

[WinGlide] section of wg.ini
----------------------------
This version of WinGlide has MMX detection.  If the MMX key is not present in the ini file or
if it is set to 2, WinGlide will automatically use MMX instructions if it detects a processor
that supports MMX.

Overriding the MMX detection:
Setting the MMX key to 1 will enable WinGlide's MMX support and setting it to 0 will tell
WinGlide not to use MMX instructions.  Since WinGlide does not verify that it is running on
an MMX capable processor when overriding MMX detection, if the MMX key is set to 1 and
WinGlide is run on a processor that does not support MMX instructions, an invalid instruction
exception will be generated.

Setting the 320x240Fix key equal to 1 will enabled a fix in WinGlide that allows 320x240 windowed
to work when used with 3Dfx MiniGL v1.46.  If you cannot use 320x240 windowed but other windowed
resolutions work, see if enabling this fix makes 320x240 windowed work.

Setting the SystemMenuOptions key to 1 will allow WinGlide to add menu items to the system menu.
Setting this key to 0 will leave the system menu unchanged.  If you are using WinGlide with an
application that adds its own menu items to the system menu, this option should be disabled because
it could cause WinGlide to interfere with the processing of those menu items.

[GammaCorrection] section of wg.ini
-----------------------------------
Set the Enable key to 1 to enable gamma correction or 0 to disable gamma correction.

The Red, Green, and Blue keys control the level of red, green, and blue gamma correction.
Overlay WinGlide will accept values ranging from 0.0 to 10.0.  Values below 1.0 will make things
darker and values above 1.0 will make things brighter.  1.7 is the default.

[Overlay] section of wg.ini
---------------------------
The UseFourCCSurface tells WinGlide to use a surface defined by a FourCC if it is set to 1.  WinGlide
will use an RGB surface if this key is set to 0.
- This version of Off-screen Surface WinGlide only works when the surface to use is defined by a FourCC
so this key must be set to 1.

The FourCC key tells WinGlide what kind of FourCC surface to use if the UseFourCCSurface key is set
to 1.
- This version of Off-screen Surface WinGlide only supports the FourCC YUY2 so this key should always
be set equal to YUY2.


--------------------------------------------------------------------------------
If you have any questions or comments about this version of WinGlide, I can be reached at
cwdohnal@ucdavis.edu

Chris Dohnal
