dgVoodoo v1.50 Beta2 by DEGE, 2007
==================================

Hi again! No, dgVoodoo hasn't resurrected, I've just done some cosmetic
intervention on it.
Unfortunately it's still a beta as there are known bugs to fix as well as
missing developments related to Windows Vista.

And now, the well-known fanfare I hate so much:

dgVoodoo is a Glide Wrapper that implements Glide 2.11 and Glide 2.43 API by
using DirectX.
dgVoodoo provides support to run Windows-based and DOS-based applications using
Glide, and it can also emulate VESA 2.0 for DOS applications.

-----------------------------------------------------------------------------

I. Requirements
II. Files of dgVoodoo 1.50
III. What's news in 1.50
IV. Working of, and using the wrapper
V. VESA emulation
VI. Installation
VII. Running DOS programs under Windows Vista (new!)
VIII. General tips for dgVoodoo (updated!)
IX. Differences between DirectX7 and DirectX9 renderers
X. Technical notes (you can skip this section)
XI. Resolution setting
XII. About screen shots
XIII. Using dgVoodooSetup (GUI)
XIV. Using dgVoodooSetup (Command line)

-----------------------------------------------------------------------------


I. Requirements
---------------

- Windows 95/98/Me/2000/XP for Windows applications
- Wndows 95/98/Me/XP for DOS applications
- DirectX 7.0 or greater
- what else important to write here? Idonnow

====================================================================================
This is a Beta2 only!! I didn't do extensive testings, so take it into account if/when
it refuses to work, or gives worse result compared to earlier versions!!
DX9 renderer is still tested only on: GeForce 5700 Ultra, Detonator 56.64
ATI X600, Catalyst 5.6
(The drivers I use are still not really up to date...)
====================================================================================

====================================================================================
IMPORTANT: dgVoodoo may not work with all ATI Catalyst versions, your PC may reboot
when launching the wrapper in VDD mode with DOS-Glide applications.
It should work in server mode however. I myself use it with Catalyst 5.6
without any problems, but there are reports about rebooting with the same
driver.
So, I must say that use this shit only at your own risk !!!
====================================================================================


II. Files of dgVoodoo 1.50
--------------------------

glide.dll - Glide 2.11 driver for windows-based applications
glide.ovl - Glide 2.11 driver for DOS-based apps
(see remarks on it!)
glide2x.dll - Glide 2.43 driver for windows-based applications
glide2x.ovl - Glide 2.43 driver for DOS-based apps
dgVoodoo.exe - Glide server process for DOS-based apps
dgVoodoo.vxd - Kernel module for DOS-based apps
dgVesa.com - VESA 2.0 driver for DOS
dgVoodooSetup.exe - Setup program
readme_eng.txt - dgVoodoo documentation, English version
readme_hun.txt - dgVoodoo documentation, Hungarian version


III. What's new in v1.50 Beta2
------------------------------

- Texture memory scalability to 4MB. Only for Red Baron 3D.
Idea and implementation technique is by GabiLaser!! Thanxxx GabiLaser!!!

And now that I'm writing this readme, it has come to my mind that I forgot
to include the promised "Ignore Palette Changes" function in the wrapper...
But it's late....

- Hardware accelerated regenerating of paletted textures when using the DirectX9 renderer,
if your videocard supports certain texture formats (mainstream cards support them...)

- Flashing desktop elements and other craps are eliminated. At least they should be.

- VESA-emu: the wrapper doesn't insist on the resolution and color depth coming from
a given VESA mode parameter. If a particular video mode isn't supported by the
videodriver, it looks up for the best matching available one, converts the color
format and scales the screen-image as needed (like in windowed mode).
What is more, it chooses the best matching refresh frequeny according to the one
given in the setup on VESA tab. It all needed because I had troubles with VESA emu
under Windows Vista.
Previous versions didn't supported it, and always used 60hz as monitor refresh freqency.
Only exceptions are 8 bit modes, they were wrapped to 32 bit because DirectX9 doesn't
support so legacy things.

- I think that's all, some other modifications were done as I recall, but they were so
long ago, I can't remember them exactly, and had some beers since then.


IV. Working of, and using the wrapper
-------------------------------------

Back in time, 3Dfx cards were driven via the API called Glide. Newer and newer version of
Glide came out as it evolved and it existed on several platforms. From viewpoint of
dgVoodoo, two important and supported platforms are DOS and Windows, and, two important
Glide versions are 2.11 and 2.43.
The driver itself was a library, that was attached either statically or dinamically to
the application using Glide.

- DOS, Glide 2.11, driver: lib linked statically
- DOS, Glide 2.43, driver: glide2x.ovl
- Windows, Glide 2.11, driver: glide.dll
- Windows, Glide 2.43, driver: glide2x.dll

So, it was enough to provide the proper file for the given Glide application (or others too,
if the driver itself also consisted of additional files) and the application run. All that Glide
wrappers, like dgVoodoo, do is replace the file(s) mentioned above with one(s) that still implement(s)
the Glide API, but all the Glide calls are converted (wrapped) into OpenGL or DirectX calls,
so no need for a real 3Dfx card to run those applications.

But, all this can't be done directly in DOS, since there is no and there have never been any
OpenGL or DirectX implementation under DOS. It means that DOS driver of dgVoodoo needs the
Windows driver. The point of the DOS driver is to be a bridge from DOS to Windows, it passes
all Glide calls from DOS to Windows.
dgVoodoo can realize the communication from DOS to Windows in two ways:

- VDD mode: This is the preferred mode, in all aspects (technical, comfort, etc.).
In this case the DOS driver automatically finds, starts and uses the
Windows driver. This mode is only available under WinXP.

- Server mode:
In this case, launching a server application (dgVoodoo.exe) is needed. The server
attaches the Windows driver to itself, and then, DOS driver communicates
with the server. WinXP itself supports communication from DOS to Windows,
while Win9x/Me doesn't, so, under Win9x/Me the wrapper has to realize it
itself (that's why file dgVoodoo.vxd appears here).

So, usage of the wrapper:

For Windows applications, after copying proper files and potential setup (dgVoodooSetup),
you can run them without doing anything else.

For DOS applications, after copying proper files and setting up the wrapper to work in VDD mode,
you can run them without doing anything else.

For DOS applications, after copying proper files and setting up the wrapper to work in server mode,
you have to launch the server (dgVoodoo.exe) first, and then you can run them.


You can also run DOS programs in the background, but be careful! In certain cases,
when cooperative level changes (e.g. when a DOS program is being run in full screen,
but you changes to an other application), some of the Glide-functions cannot be
called without fail. This means that a game may quit with an error message, etc.


V. VESA emulation
-----------------

dgVoodoo can emulate VESA 2.0 for DOS applications, with minor-major bugs.
Similarly to the Glide emu, VESA emulation can be used in either VDD or server mode.
What is more, it needs and uses file glide2x.dll, so that, VESA emu code is
integrated into the Glide 2.43 driver (except for Win9x/Me, because most of the
emu is done by the kernel module (dgVoodoo.vxd) there and only a few parts are called
in the dll, like video refresh via DirectDraw).

[I know that I should have placed the implementation into a dll like dgVesa.dll or
something like that, but according to the feedbacks I got and experienced, many people
think that dgVoodoo consists of too many files, and they get confused about their usage.
OK, I thought I won't bugger about with it then, integration made things go easier
as well, as for switching between VESA and Glide modes at runtime. Maybe I will resolve
it in about 2010, when the DOS part of this wrapper will be unusable not only in practice,
but theoretically too, as 64 bit Windows doesn't support 16 bit code.]

VESA emu of dgVoodoo supports all resolutions from 320 x 200 to 1280 x 1024 in
8, 16 and 32 bit color depths. 320 x 200 x 256color is a standard VGA mode, you can
enable it for emulation.

To use VESA emulation, you will need to run the DOS-driver, dgVesa. Under Win9x/Me,
when the server is running with VESA emu enabled, it installs DOS driver automatically
into each newly opened DOS-box, so in that case using dgVesa is needless.
(DOS driver of VESA emu is for maintaining the contact between DOS and Windows, like
the DOS driver of Glide.)


VI. Installation
----------------

Important: If you have any of the previous versions installed, overwrite each component
of dgVoodoo, don't mix them with older version files or with files with the
same names from other software!

Global installation: copy all the needed files to your Windows folder
Local installation: copy all the needed files to the folder of the application/game you
want to play


Installing dgVoodoo to run Windows apps
.......................................


Just copy the following files into the proper folder, depending on you do global or
local installation:

GLIDE2X.DLL
GLIDE.DLL (in the case you need Glide 2.11 support as well, but take
advice from me, and do local install for Glide2.11)
DGVOODOOSETUP.EXE

After doing this and setup, Windows applications should work.


Installing dgVoodoo to run DOS apps
...................................

Just copy the following files into the proper folder, depending on you do global or
local installation:

GLIDE2X.DLL
GLIDE2X.OVL
DGVOODOOSETUP.EXE
DGVOODOO.EXE
DGVOODOO.VXD (this file is required under Win9x/Me only, WinXP won't miss it)
DGVESA.COM (if you need VESA emulation)

After doing this and setup, DOS applications can be launched (VDD mode), or
you have to start the server first, and then DOS applications can be launched
(server mode).


VII. Running DOS programs under Windows Vista
---------------------------------------------

Unfortunately dgVoodoo isn't completely compatible with Vista, there are some inconvenience
I haven't mop up yet.

Theoretically dgVoodoo can be used with Vista, but only with 32 bit Vista (like it can be
used only with 32 bit XP), once I reported about it on Vogons:

Two main sucks compared to XP:
- Vista is disposed to load any VDD only from Windows\system32, I think this is
because of a security-crap or something like that. The point is that keep your
Glide2x.dll there if you want to run any DOS stuff. Actually, it's important
NOT to have any Glide2x.dll in the folder of DOS app because the DOS driver
notices it in this case and wants Vista to load that instance. And Vista's
respond is dismissive.
(This behavior should be avoided by some development as well as getting setup to
search for Glide2x.dll instances in Windows\system32.)
You have to do the same with VDMSound, just copy its vddloader.dll into System32,
and voila, it works like a charm.

- If the desktop composition (Aero look & feel) is enabled, so that Vista is driving
the video card through the new WDDM driver model, then no any kind of full screen
functionality is available (except via DirectX of course), as this driver model
doesn't support such functionality. So you can neither switch into full screen
text mode, nor into VGA mode, etc. Instead you get a kind message from Vista saying
"This system doesn't support full screen mode". And the usual choice, you can ignore
it, or close the renitent application. A common user closes it since he/she has no
any idea about it.
The point is that you are forced to use dgVesa with VGA emu enabled. dgVesa bypasses
this all via DirectX. There's no other way!

I can't say I did many testing around DOS stuffs under Vista, but accordingly to the facts
listed above, I was managed to run Tomb Raider 1.



VIII. General tips for dgVoodoo
-------------------------------

- Scaling of texture memory means that dgVoodoo reports 4MB total texture memory to the
application, but effectively it uses as much as it's configured for. It has no any use
by default, this option was designed expressly for Red Baron 3D because RB has a bug,
you get texture corruption if it uses more than 4MB memory.
DON'T use it for any other application!!!!
To get perfect working, the application is needed to entrust all texture size calculation
to the wrapper, because texture sizes are scaled too. If not that is the case, so that
the application does its own calculations, then texture sizes and scaled texture
memory addresses won't be chimed together, and causes texture corruptions. So, one more,
use this option only with Red Baron 3D, RB3D behaves well enough to make use of it.

- If hardware accelerated regenerating of paletted textures is enabled, dgVoodoo eats up
some extra video memory, exactly as much more as minimally needed. Hw acceleration
has use with applications that make the wrapper work hard by altering texture palettes
continuously. Such ones are e.g. Blood and Red Baron 3D. However, there's no point to
use it with Tomb Raider 1 as its textures are rather static, they don't change, so
the extra video memory is just wasted.
There's a stupid restriction: you cannot use hw acceleration if you use managed textures.
Don't ask why, the implementation would be relatively complicated.

- Don't force your videodriver in any of its settings dialog to apply FSAA if you're
going to use dgVoodoo, or create separate profiles for Glide applications with FSAA set to
application controlled!! If FSAA is applied, video memory buffers can't be locked and
modified directly which is required by many Glide applications. Of course this will
cause visual artifacts (missing screen items), or the application terminates at once
due to the failed lock. The point is all that looks as if it were the fault of the
wrapper. But it's not, hehehehehehahahhaa....

- There are no magic options to set, so that if dgVoodoo won't work at all with default
settings, probably won't work at all with others too. Only exception is maybe the
difference between VDD- and server-mode.

- DON'T USE the server (dgVoodoo.exe) in compatibility mode (WinXP)!!!!
It messes up the detection of version of the operating system, so the server may think
it's running under Win98.

- When your screen is flashing, try to use the wrapper with "closer to a real hardware"
option enabled. Flashing occures when a game unexpectedly behaviors and the wrapper
locks the LFB in a very optimalized way (most likely in 16 bit full screen).

- If you start a DOS game, and the glide-window appears, and then nothing happens, try
to run that program with unhided console window. It's possible the game exits with an
error message, but you cannot see anything because the console window is hided.

- If you want the smoothest animation try to set the refresh frequency to the closest one
to the desired freq (see setup)

- Automatically generated mipmap levels can cause serious artifacts, so it is not
recommended to use it in general. Missing levels are generated by resampling the
original texture and it means colorkey-pixels are going to be recoloured to
something different color around a given shape. Alpha values can also be modified
in a wrong way if an application uses alpha testing.
Furthermore, when an application refreshes certain textures continuously, speed
can be degraded due to calculating all the levels every time.

- Some applications were programmed in a way that it utilizes properties of a real
hardware when locks the LFB, so they weren't completely programmed according to
the Glide specification (such a program is e. g. Extreme Assault Demo). If you get "slided"
pixel rows or something similars, try to enable the "closer to a real hardware"
option of the wrapper. This option does not confuse other programs but eats up more
memory and provides slower buffercontent caching, so do not use it if not needed.
NOTE that this option is automatically enabled when using Glide 2.11 to
keep compatibility with Voodoo1.

- dgVoodoo generates additional timer interrupts when it works in DOS Glide mode,
so DOS games may seem to be faster than normal. This was brought in earlier, because
3D rendering could be too time-consuming, taking out much execution time of DOS, resulting in
losing timer interrupts, so that games slowed down to slowmotion.
Since then, I've improved cooperation of certain threads, so this problem may not take place
now (I hope, at least).
Previous versions (like 1.31) generated one timer interrupt after each 15ms, now this version do
that after each 80ms by default (from 1.40+, it's been changed to 80ms from 40ms of 1.40).
Time of period was a hidden option in all of the previous versions. Since games can be faster
than normal, if you want, now you can turn off timer boosting in the setup, or can set to the
aforementioned 80ms. (It's a limited choice, since it could be set to other values too, but
I'm far from happy to make this option public at all).

- I think all of Glide 2.11 DOS-applications have their Glide libraries statically
linked (according to the Glide 2.11 SDK). However file glide.ovl could only be usable by dynamic
linking. I myself don't know of any program using it in this way. That's why this file exists
but isn't included in this version.

- Focus problem (Win9x/Me):

If serverproc loses the focus, it suspends the served DOS box and wakes it up when it gets
back the focus. In some cases the serverproc gets the focus but Windows does not send
any message about it (or I coded it nastily) so you have to inactivate and reactivate the
window of the server manually. In full screen, you can do it by moving the invisible mouse
cursor to the edge of the screen and resize the window (when mouse focus is not set to
the DOS-box).

In certain cases it can be very annoying that mouse focus is set to the DOS box.
For example, when you run the program in windowed mode, you can't resize the window
severely. However, if Ctrl-Alt is pressed, mouse focus is released from the DOS box.
If you click on the window, it gets back the focus.


IX. Differences between DirectX7 and DirectX9 renderers
-------------------------------------------------------

One may think that DX9 can only be better. Generally speaking, maybe it's true but unfortunately
DX7 has some advantages been removed by MS in the later interfaces (e.g. killing DirectDraw
completely in DX8...)

Note that DirectX 9.0c or greater installed is required to use the DX9 renderer, the wrapper
won't access the API via earlier versions!!

Advantages of DirectX9:

- Pixel shaders. This renderer uses pixel shaders of version 1.4 in order to emulate the 3dfx
pipeline almost completely. With shaders, renderer can reach greater accuracy in its internal
calculations (so that it can avoid saturation between texture stages present in
fixed function shaders), and can emulate the 3dfx pipeline almost perfectly
(texture combine -> chroma keying -> alphaControlITRgbLingthing -> alpha/color combine).
FF shaders can only do it partially and with constraints. Pixel shaders of version 1.4
are needed because of chroma keying, it couldn't be solved with earlier version pixel shaders.
If your card doesn't support pixel shaders v1.4, DX9 renderer can still fall back to
FF shaders, but using the DX7 renderer instead is highly recommended in this case.
GeForce Fx Series and Radeon 8500 both have support for pixel shaders of v1.4.

- Alpha based colorkeying doesn't rely on alpha testing and blending at all, can't conflict
with any other effect, so it can be used under arbitrary circumstances. Native colorkeying
works in a well defined way, so the result doesn't depend on the video driver.

- Using vertex and index buffers more efficiently. Using hardware vertex buffers
(which also applies to index buffers in DX9 renderer) is stoutly recommended (as opposed to DX7
as you'd better not use it with that accordinging to the experiences), it seems to work much
nicer than in DX7 probably due to the buffer renaming techinque done internally in DX9.
In fact, buffer renaming is a double buffering techinque done transparently to the application
which is missing in DX7 and the wrapper itself doesn't implement it.

Disadvantages of DirectX9:

- When DX9 renderer falls back to FF shaders it cannot emulate native colorkeying. This also
affects lfb access with texture tiles, so DX9 with FF shaders can prove to be unusable in
most cases. Old cards with FF-only support should use the DX7 renderer. FF support in DX9
renderer is going to be removed in future versions.

- Generally, accessing the Lfb is mostly done by texture tiles with nondefault resolutions because
Direc3D9 supports only a simple buffer blitting.

- Front buffer is inaccessible. This doesn't matter at all for most of the applications, but
for the sake of possibility, DX9 renderer can be switched into a special working mode with its
own administration of the render buffers, always doing copying between them.
In this mode front buffer is accessible but slight performance penalty can take on, that's why
it is disabled by default. (It has an annoying side effect: when the front buffer is inaccessible,
you cannot take screenshots because they are saved as the content of the front buffer...)

- With full screen only, buffer switching interval can't be affected per switch, but only at init
(so that, bufferswitching with sync to vertical retrace or immediate bufferswitch).
Thus, DX9 renderer always syncs it to the vertical retrace, but it can be forced to immediate
bufferswaps if needed.

- Lack of paletted textures (in practice). GeForces up to FX series supports them by hardware but
their drivers seem not to expose this capability via the DX9 interfaces for some reasons (I have
some tips why not, but...), so I couldn't even test it in this renderer. Since I didn't want to
put dead and untested code in the wrapper, DX9 renderer always disables paletted texture support
independently on the driver capabilites.

- Full screen 8 bit VESA modes are always emulated by using 32 bit screen modes because D3D9 is all
about 3D. It cannot be driven through 8 bit modes.


Colorkeying with DirectX7:


- Native: General colorkeying method using the native colorkeying of cards

- Native for TNTs:
This method is a special alpha based colorkeying for TNT cards only
(TNTs implement their cking on an alpha based conception,
working under special circumstances only)

- Alpha based:
General colorkeying method using alpha testing and
mask textures as alpha channels

- Automatic:
It always forces alpha based colorkeying by default, but if it
won't work due to either lack of enough videomemory or constraints of
alpha based method, then it falls back to native colorkeying.

Alpha based colorkeying is the closest to the real Glide-colorkeying
and it should give the same results on every video card, that's why automatic
method always forces this by default.
Disadvantages: this method cannot provide colorkeying at all if alpha testing
is enabled in special modes and also, wrong results may be produced if special
alpha blending modes are used.


Colorkeying with DirectX9:

- Native: Can only be used with pixel shaders, and works according to the definitions
in 3dfx's documentations.

- Native for TNTs:
It makes no sense here, so it's equivalent to the plain native method.

- Alpha based:
It uses the alpha components of separate mask textures to decide what
pixels to reject like in DX7 but this functionality is moved to pixel
shaders from the alpha testing/blending level.

- Automatic:
It always prefers native method to alpha based by default. However, native
has one issue worth to deal with: if precision loss occures because of a
texture conversion (e.g. when 16 bit textures are forced then 8 bit paletted
3dfx textures are converted to 16 bit too, so 32 bit color values have to be
stumped), then not only pixels matching the colorkey will be rejected but
all ones in a certain, small interval around the colorkey in the colorspace.
Automatic method tries to avoid that case.
With FF shaders, automatic always uses alpha based method.


FF shaders has the same constraints as with DX7 renderer.


X. Technical notes (you can skip this section)
----------------------------------------------

Glide LFB locking
.................

- Option "closer to a real hardware" is automatically enabled when Glide 2.11 is used,
because of maintaining the Voodoo1-compatibility. It means that stride (AKA pitch or logical
line length) for LFB operations is always 2048 bytes, and read/write pointers to buffers
are "constant" (for particular formats).

- A hidden option, "No matching LFB formats" are also automatically enabled for
Glide 2.11 to avoid buffer pointer mismatch problem. In fact, this prevent dgVoodoo
from using directly any of its internal optimized buffers in order to read/write pointers of
a particular buffer always do point to a certain memory area (this is important in Glide 2.11).

- "No matching formats" is also enabled when you use the wrapper for DOS programs under WinXP
in server mode. This is because matching lfb formats means using directly one of the
internal buffers residing in the video memory. Thus, the DOS program and the locked buffer
would be in separate address spaces. Note that when "no matching formats" is enabled, there is
no extra conversion from the format to the same format, just a raw copy is done.


DOS Glide
.........

- In VDD mode, the wrapper file (glide2x.dll) is attached directly to the
NTVDM process running the DOS program as a VDD (Virtual Device Driver). You can
avoid running the serverprocess, the application and the wrapper share the same
process and address space like in case of Windows applications. Also, more than one
applications can use the wrapper simultaneously.


- Disadvantages of server mode under WinXP: Since the application and the wrapper run
as two separated processes in separate address spaces, dgVoodoo can't utilize matching
LFB formats (it considers them as if they were always different), server can serve only
one DOS program.
You should try this mode if you have troubles with VDD mode.


VESA Emu
........

- dgVoodoo reports VGA-compatibility altough its compatibility is restricted
to the palette registers and the vertical blank (3DA) register.
It means X mode cannot be emulated, etc.
(But, this project is not about developing VESA to the perfectness...)

- Linear/Flat Frame Buffer mode is not supported under Windows Xp.

- Under Windows 98/Me, Bank Switching is done by changing the actual memory mapping
in kernel mode. However it is beyond the possibilities under Windows XP, so copying
large 64K memory blocks is needed there. Thus, it is slower than W98/Me implementation.

- Win9x/Me only: If you use dgVoodoo for VESA in a DOS box, then you stop it
and use the original driver, you will probably see a messy screen. This is because
dgVoodoo overwrites the memory mapping for videomemory set up by VDD
(Virtual Display Driver) and cannot fully restore it. In this case close
that DOS box and use another.

- Win9x/Me only: VESA init can fail when starting the server.
The memory area used as videomemory is allocated when kernel module is loaded into
the kernel. (When it is unloaded, this memory area is released.) Normally the kernel
module behaves as a dynamic VXD. It means it is loaded and unloaded to/from
kernel by the serverproc. The main problem is the videomemory has to be
physically continuous but Windows cannot provide it if bulk of the
physical pages are messy-allocated for running applications.
If you want, you can insert the following line in SYSTEM.INI into the
[386Enh] section:
device = dgVoodoo.vxd
In this case kernel module is used as a static VXD, so it is loaded into
the kernel during Windows startup. It reserves 2MB as videomemory (because
it cannot read the current configuration) and releases it when Windows shuts down.


XI. Resolution setting
----------------------

If an application does not allow you to set the required resolution you can
do it by dgVoodoo. However keep in mind that this can not only cause graphical
artifacts, but the wrapper even has to work harder in the background in such a case,
mainly when the application is using direct Lfb-access, so it all can have a serious
overhead.

So, that's why do use nondefault resolution only when it cannot be set via the application
itself.

You can use all of the resolutions supported by your video card.


XII. Screen shots
-----------------

You can save the content of the screen into a file or to the clipboard.
You can do it by pressing the "Pause" button in case of Windows apps and DOS in XP,
and "Scroll Lock" for Win9x/Me DOS. I know it should be done by the same button for
all platforms but I cannot solve it (temporarily). Result of the saving
operation can be seen on a green label in the middle of the screen except when
you are in an 8 bit full screen mode (VESA) because the label cannot be drawn by the
3D hardware.
If the screen is saved into a file, the name of the saved file is the same as
the application's concatenated by an ordinal number. It is saved to the "Temp"
directory on the same drive where the application is. If the name of the
application is unknown (only in DOS) then filename is
C:\Temp\dgVoodoo_xyz_.bmp where _xyz_ is an ordinal number.
The saved file is 8 bit (full screen, VESA), 16 or 32 bit depending on what
the bit depth of the used videomode is. The saved file is always saved as
a BMP file and dgVoodoo is not intended to support any other format in the
future. Just save the screen then convert it to whatever you want.


XIII. Using dgVoodooSetup (GUI)
-------------------------------

dgVoodoo does not have a configuation file from which it reads the actual
settings. Settings are stored in GLIDE2X.DLL and GLIDE.DLL instead.
The setup program needs these file as well.

Setup program organizes setup options on three main tabpages and one hidden tabpage.

Page "Global": Options that affects both the Glide and VESA emulation
Page "Glide": Contains options for Glide
Page "VESA": Contains option for VESA
page "Renderer specific": Specific options for both renderers
(can be made unhidden from context menu)

Let's have a look at the setup-dialog:


Platform
Here you can select the Win or DOS platform to configure.

Language / Nyelv
You can select a language to setup in, and which the wrapper itself uses.

Instance of dgVoodoo
In this list you can see the names of wrapper files to be configured.
By default, setup searches for such files in the current directory, but
if none is found, it does it in Windows directory. You can add additional
wrapper files to the list by "Search" button.
"Win dir" and "./" button adds files from Windows and current directory
if any is found there.

Below this field, you can see the actual page. You can select between pages by the tabs.


Page "Global"
-------------

Renderer API
You can choose between DirectX7 and DirectX9 renderers.

Display device
You can select a screen adapter to use.

Display driver
You can select which rendering driver to use.
(dgVoodoo will probably work unproperly with software drivers, but I
think that's not a big pain. :) )


Screen mode
You can select between full screen and windowed mode.

Screen bit depth
You can set the bit depth of full screen mode.
In windowed mode bit depth is determined by the
actual settings of the desktop. These settings can be seen
above the tabs. If it is not compatible with
dgVoodoo (so that it is not a 16 or 32 bit mode), you will
be warned.
16 bit mode can be useful for fast LFB accesses.

Enable screen shots
You can enable the screen saving here.

Saving to file
You can enable saving to file here.

Saving to the clipboard
You can enable saving to the clipboard here.

Working in VDD mode
Only for DOS under WinXP: you can set VDD mode here.

Active in background
Only for DOS under WinXP: by enabling this option, DOS programs
runs in the background too.

Hide console
Only for DOS: Hides the console window of the application.

Set mouse focus to application
Only for DOS: If application is running, mouse focus is set
to the application. You can use the mouse by enabling this
option.

Enable Ctrl-Alt
If enabled, you can release the mouse focus from DOS box by this
key combination.

Always preserve window size
Only for DOS, in windowed mode: if you resize the window, further
mode switchings (e.g. between VESA and Glide) won't resize the
window to the default size when a new resolution is applied.

Preserve aspect ratio
Preserves aspect ratio of the window during sizing.


Page "Glide"
------------

DirectX textures bit depth
Bit depth of textures used in Direct3D. dgVoodoo can use the
following texture formats (arbitrary component order):
- 16 bit ARGB_4444
- 16 bit ARGB_1555
- 16 bit RGB_555
- 16 bit RGB_565
- 32 bit ARGB_8888
- 32 bit RGB_888
- 8 bit P8
At startup, it puts all the texture formats supported by your card
into a list. When dgVoodoo has to decide which format to use for a
particular 3Dfx format (best fit) it selects it from the list.
Options meaning:
- 16 bit: select from only 16 bit formats
- 32 bit: select from only 32 bit formats
- Optimal: select from any format including paletted
(8 bit) textures

Refresh rate
- Monitor freq is the closest supported freq:
Only with usage of full screen, it sets the effective refresh frequency
to one of the supported values by the monitor that is closest to the one
application requires. In practice they will probably be equal since most
of the Glide applications use 60Hz (or 70, 72), which must be supported
by even a crappy monitor.
Of course this option overrides the value set in "Monitor freq" option.
Recommended for perfect emulation and smoothest animation!!

[The other old option, with which application-given freq could be emulated
at arbitrary effective refresh freq, has been removed, I didn't have a
good mind to deal with it while reimplementing the base of DX7 renderer.
I don't think anybody used it at all, it's only use perhaps was keeping
one's eyes in its sockets by using a high refresh freq while it could be
virtually capped to a lower value. :)]

- Always wait for vertical sync:
Waits for at least one vertical retracing even if an application doesn't
demand it. It can be useful for applications not synchronizing themselves
to the refreshing ending in running too fast on modern computers,
or rendering artifacts such as horizontal refresh-lines.
Note that this options has no effect with DX9 renderer!!
Use the renderer specific option for it to control globally this behavior!

LFB access
- Disable LFB access (read, write)
Accessing the LFB can be a slow operation.
If you disable an access with a certain type in this combo box,
applications still have the sense they access the LFB but in fact
they access an unused buffer instead. Because of it the rendering
may not be complete (and can be bad if reading is disabled) but
the application can run at max speed.

- Use hardware cache buffers when possible
Keep this option enabled

- Use fastwrite for unmatching formats
Keep this option enabled

- Disable texture tiles
The wrapper decides if texture tiles are needed or not according to
the current circumstances, by default. If you find its decisions
not too optimal and/or texture tiling is just causes performance loss
or artifacts, disable it all by this options causing a fallback to
plain buffer blitting.

- Closer to a real hardware
LFB has such properties that are closer to the LFB properties
of a real Voodoo card

Note: if an application tries to read/write the aux buffer when it
is used as a depth or alpha buffer, then it will always manipulate
the unused buffer (locking depth and alpha buffers are not implemented
yet :-| ).

Resolution
You can override the the resolution of an application here.
This list contains all the supported resolutions.

Refresh rate
You can set the refresh freq of your monitor here.
You cannot do it if you use the wrapper in windowed mode or monitor freq
is set to the closest supported one.

Texture memory size
Size of the emulated texture memory.


Disable mipmapping
If you don't like mipmapping in a game, you can disable it, falling back
to using only the first mipmap of textures.

Force trilinear mipmapping
Interpolating between the levels of mipmaps

Autogenerate mipmaps
If a mipmap consists of only one level, missing levels are generated.
This option does not override multilevel mipmaps.

Force bilinear filtering
You can force textures to be always blurred.

Texmem scaled to 4MB
You can enable texture memory to be 4MB virtually.
For more info, see general tips.

Gamma correction
You can set the gamma correction between 0% and 400%.
This also works in windowed mode!

Colorkeying method
Colorkeying is the effect when pixels that matches the colorkey are not rendered.

You can select between four methods for colokeying:

- Native
- Native for TNTs
- Alpha based
- Automatic

See chapter describing differences between renderers for details.

Force triple buffering
You can force the wrapper to always use three buffers for animation. This can
speed up things, but also can produce wrong appearance if the application uses
the content of previous frames.

Fix TR's shadow-problem
You can avoid the no-shadow problem in Tomb Raider 1.
Don't use this option if it confuses other Dos-programs.

Enable using hardware vertex buffers
If this option enabled, dgVoodoo puts all the geometry data directly into the
hardware buffer of the video card, avoiding extra copies. However this also can cause
problems, so I let you disable it.

Force W-buffering
You can force true W-buffering if your video card supports it (old ATI cards,
and pre-GeForce 6xxx series).

Timer boosting
Turning on and off timer boosting, for more see section "General Tips".


Page "VESA"
----------

This page is used only for DOS.

Use built-in VESA support
You can enable the VESA emulation.

Refresh frequency
Refresh freq. You can get smooth animations at higher freqs, but be
careful: refreshing the screen is time-consuming so the higher the
freq the more time is spent on refreshing, the less time is left
for the program for running.
(This text is rather old, so it can be a problem only with ancient
hardware.)

Emulated video memory
Size of the video memory (see related problems).
Size of mem should not be smaller than a particular video mode requires.

Mode 13h support
You can enable emulating the standard 320x200 256 color VGA-mode.

Disable Flat/Linear Frame Buffer Modes (Win9x/Me)
Since implementation of the VESA emu is far from perfect, some programs
may not work in linear mode. So, disable it to force the program to
use good old bank switching VESA technique.


"Renderer specific"
-------------------

DirectX9

- Force swap chain copy (accessible front buffer)
It is only for making the front buffer accessible, doesn't worth to
keep it enabled all the time because it can decay performance.

- No vertical sync at bufferswap
Forces immediate bufferswap. Some applications require this behavior,
you can force it only with this option for DirectX9.

- Force fixed function shaders
Mostly for testing DX9 renderer without pixel shaders.

- Enable hw accelerated regenerating of paletted textures, if available
It speaks for itself, but can only be used with pixel shaders.

- Try Black&White rendering
It's a kind of Easter egg, renders in grayscale if your hw has enough
support. It can only be used with pixel shaders.


You can save your settings by pressing button "OK", while "Cancel" quits
without saving. Button "About" is the usual unusable one that makes a feeling of a
serious application.


XIV. Using dgVoodooSetup (Command Line, advanced)
-------------------------------------------------

If command line of dgVoodooSetup is not empty, GUI interface does not pop up,
information for setup operations are taken from the command line. No any feedback
on the console. (Damn, an application can't be both a GUI and Console application
under Windows, at least not in an easy way.)
This is useful for using the setup in command line scripts.

You can model the GUI workflow, which is usually the following:
- configuration is loaded from either the wrapper file (glide2x.dll, glide.dll),
or from an exported config file
- some config changes are applied if needed
- configuration is either saved in the wrapper file, or exported to external config
file, or both

Command line options:

dgVoodooSetup [wrapperfile] [/opt1] ... [/optn]

where wrapperfile can be:

File Specified file
$Win$[File]|[:0|1|2] $Win$ prefix is changed to Windows directory
if File is specified, appended to Win dir

$FirstFound$[:0|1|2] directory where wrapper file is first found

1 = glide.dll, 2 = glide2x.dll, 0 = any of them
default = 0

where options:

(E/D = Enable/Disable)
(Dec = decimal number)
(Hex = hexadecimal number prefixed by 'x' or '0x')
(Default of boolean operations (On|Off|Inv) = On)

options for operations

/?, /h, /help Help for command line options

/NoSave Does not save config in wrapper file
/Import:configfile Load config from configfile, mandatory parameter
/Export:configfile Save config in configfile, mandatory parameter
/ExportToText:textfile Export config into textfile, mandatory parameter

/Platform[:Win|Dos] Load appropriate platform config, default = Win
/Lang[:Eng|Hun] Language, default = Eng

options modifying config:

/Windowed[:On|Off|Inv] E/D windowed mode.
/BitDepth[:16|32] Color buffer bit depth in full scr mode.
Default: 16
/ScrShot[:On|Off|Inv] E/D screen shots.
/ScrShotToCb[:On|Off|Inv] E/D screen shots going to clipboard
/VDDMode[:On|Off|Inv] E/D VDD mode
/RunInBkgnd[:On|Off|Inv] E/D running in background
/CLIPOPF[:On|Off|Inv] Force handling CLI/POPF (XP)
/HideConsole[:On|Off|Inv] Hide/Show console window
/Mouse[:On|Off|Inv] E/D setting mouse focus to Dos
/MouseCtrlAlt[:On|Off|Inv] E/D Ctrl-Alt to release mouse focus
/PreWinSize[:On|Off|Inv] E/D Preserving window size
/PreWinAspRat[:On|Off|Inv] E/D Preserving window aspect ratio

/MonFreq[:Hex|Dec] Monitor freq, 0 = default freq, default = 0
/ClosestMonFreq[:On|Off|Inv] E/D Setting the closest supported monitor
freq to the one that app requires,
overrides MonFreq setting
/WaitOneRetrace[:On|Off|Inv] E/D waiting for at least one retrace

/TextureBitDepth[:0|16|32] Bit depth of D3D textures, 0 = optimal,
default = 0
/PerfectTexEmu[:On|Off|Inv] E/D perfect texture memory emu
/StoreTexCopies[:On|Off|Inv] E/D storing texture copies
/DisableMipMap[:On|Off|Inv] E/D mipmapping
/ForceTriMipMap[:On|Off|Inv] E/D forcing trilinear mipmapping
/AutoGenMipmap[:On|Off|Inv] E/D autogenerating mipmap levels
/ManagedTextures[:On|Off|Inv] E/D managed textures: textures are handled and
recovered by DirectX runtime if needed
/TexMemScaleTo4M[:On|Off|Inv] E/D scaling texture memory to 4MB


/LfbAccess[:Enable|Disable|DisableRead|DisableWrite]
Setting LFB acessibility, default = Enable
/HwCacheBuffs[:On|Off|Inv] E/D hardware cache buffers
/FastWriteUnmatch[:On|Off|Inv] E/D fastwriting for unmatching formats
/FastWriteMatch[:On|Off|Inv] E/D fastwriting for matching formats
/ColorFmtOnLfbFmt[:On|Off|Inv] E/D Lfb read/write format affected by color format
/RescaleChangesOnly[:On|Off|Inv]E/D rescaling only lfb changes at write
/FlushAtUnlock[:On|Off|Inv] E/D always flushing lfb changes when unlocking
/NoMatchingFmt[:On|Off|Inv] E/D no matching lfb formats
/TextureTiles[:Auto|Disabled|Forced]
Method for applying texture tiles
default = Auto

/LfbRealHw[:On|Off|Inv] E/D closer to a real hardware

/CKMethod[:Auto|Alpha|Native|NativeTNT]
Setting colorkeying method, default = Auto
/CKTntInFallback[:On|Off|Inv] E/D using native TNT method when fallback in auto
/AlphaRef[:Hex|Dec] Alpha reference value for auto ck mode,
range: 0-255, default = 0

/TexMemSize[:Hex|Dec] Texture memory size in kB, default = 8192

/XRes[:Hex|Dec] Overrided horizontal resolution
/YRes[:Hex|Dec] Overrided vertical resolution
(X=0 and Y=0 means resolution required by app)

/Gamma[:Hex|Dec] Gamma correction in percents,
range: 0-400, default = 100

/ForceTriBuff[:On|Off|Inv] E/D forcing triple buffering
/FixTR1[:On|Off|Inv] E/D fixing shadow bug in TR1
/ClipByD3D[:On|Off|Inv] E/D geometry clipping by Direct3D
/GlideGamma[:On|Off|Inv] E/D Glide gamma ramp
/HwVertexBuff[:On|Off|Inv] E/D hardware vertex buffers
/WBuffDetMethod[:ForceZ|ForceW|DriverFlag]
Setting W-buff emulation detection method,
def = DriverFlag
/DepthColorEq[:On|Off|Inv] E/D setting bit depth of depth buffer to the same
as color buffer
/ForceIndexed[:On|Off|Inv] E/D forcing indexed primitives
/PreferTMUW[:On|Off|Inv] E/D preferring W of TMU when needed
/TimerBoost[:Hex|Dec] Timer boost period time in ms for DOS
0 = boosting disabled, default = 80

/Vesa[:On|Off|Inv] E/D built-in VESA support
/VesaRefRate[:Hex|Dec] VESA refresh rate in Hz, range: 45-70,
default = 50
/VesaMem[:Hex|Dec] VESA videomemory in kB, default = 1024
/Supp13[:On|Off|Inv] E/D VGA mode 0x13 (320x200x8)
/DisableFlat[:On|Off|Inv] E/D Flat/Linear VESA modes

/MirrorVert[:On|Off|Inv] E/D mirroring the screen vertically

options only for DX9

/DX9LfbCopy[:On|Off|Inv] E/D copying in lfb chain, accessible front buffer
/DX9NoVRetrace[:On|Off|Inv] E/D immediate bufferswap
/DX9FFShaders[:On|Off|Inv] E/D forcing FF shaders
/Dx9HwPalTextures[:On|Off|Inv] E/D Hw accelerated regenerating of paletted textures
/DX9BlackWhite[:On|Off|Inv] E/D grayscale rendering


Configuration is loaded from the wrapper file, but /Import option overrides it if
specified. If neither wrapper file nor external config file is specified then
default config is used. Then, all config modifications are done, and config is
saved in wrapper file if /NoSave is not specified, and, it will be saved into an
external config file if /Export is used. Also, it will be exported into a text file
if /ExportToText is present.
If an option has a parameter, it is separated by a colon. If a parameter is not mandatory
and not specified, then default parameter is used.
In case of syntax error or unrecognized options, nothing is done.
Command line options are case insensitive.

Examples:

dgVoodooSetup $FirstFound$:2 /Platform:Dos /Windowed:On

Searches for the glide2x.dll file (current dir and Win dir), loads the DOS config,
sets windowed mode, then saves the config.

dgVoodooSetup $Win$Glide2x.dll /Platform:win /CKMethod /Export:MyConfig.cfg

Searches for the glide2x.dll file in Win dir, loads the Win config,
sets colorkeying method to automatic, then saves the config and also exports it
to MyConfig.cfg.

dgVoodooSetup /Platform:win /LfbAccess:DisableRead /ExportToText:MyConfig.txt

Takes the default config, disables lfb access for read, then exports it to
MyConfig.txt text file.

Remarks:

$Win$:1 is the same as $Win$glide.dll, and $Win$:2 is the same as $Win$glide2x.dll.

$Win$:0 (or just $Win$) searches for glide2x.dll in Windows dir, and, if it is not found
it searches for glide.dll

$FirstFound$:0 (or just $FirstFound$) searches for glide2x.dll or glide.dll in current dir and
Windows dir.
Search order is:

current_dir\glide2x.dll
current_dir\glide.dll
Win_dir\glide2x.dll
Win_dir\glide.dll

as done in GUI.

I hope it is really gruesome, enjoy! :)