===============================================================================
dgVoodoo 2.52:   Glide related stuffs

===============================================================================


Table of contents
-----------------

1. Tested on
2. Glide setup options
3. Gamma correction
4. Some technical info
5. Napalm build
6. 3Dfx emulation tips and known issues


===============================================================================

1. Tested on (by me)
--------------------


Operating system

- Windows 7


Graphic cards:

- Intel HD 2000:          Seemed to work OK but with low framerates, not
                          recommended.

- GeForce 8600 GT:        I used a special build for this one since it
                          does not support feature level 10.1. It worked
                          OK as well (apart from lack of mipmapping) but
                          with low framerates too.

- Geforce GT 610:         It's a cheap low end card.
                          Works OK and usable with low resolutions.

- AMD HD 6450:            Works OK and the same as GT610.

- GeForce GTS 450:        Works OK and usable. Larger resolutions like
                          1280x1024 or larger can cause performance drop
                          in specific applications. (I'm hearing the howl:
                          is 1280x1024 large resolution?? Haha.. But do not
                          forget, it uses a lot power for exact emulation.)

- GeForce GTX Ti560:	  Works like a charm.

- AMD HD7850:             Works like a charm, AMD bug is workarounded.


There are no "supported" and "unsupported" applications. If something shows
graphical glitches or defects then that must be because of a programming bug and
not a limitation of the underlying implementations.
But of course, there are tested and untested applications, hehe. :)

I also have to mention that dynamic compiling available from 2.5 can
significantly improve the performance. Results listed above show performances
without dynamic compiling.


2. Glide setup options
----------------------

I did not wanted to have a lot of setup options like in the old version.
It is confusing and now needless, I missed all that crap.

I explain it below what ones I kept after all and why other useful
ones disappeared and what the new ones are:


- 3Dfx card:            Don't think of anything serious here. It only limits your
                        choice possibilities in respect of 'Onboard RAM',
                        'Texture memory' and 'Number of TMUs' according to the
                        card type. Some applications (like the miniGL driver)
                        may check for those values and won't work if one of them
                        is too high. So it is more handy to select a card type
                        to limit those values alltogether than configuring
                        one-by-one by heart.

                        *New in 2.1: Selected card type affects some exposed
                         capabilites. See techical info for more. List of different
                         card caps/behaviors may be extended in the future,
                         according to 3dfx specs.


- Onboard RAM:          Videomemory without texture memory. Some application
                        compute by this value that what resolutions are supported.


- Resolution/MSAA:      Since forcing them proved to be a good thing in practice,
                        I kept the possibility in this version too. Antialiasing
                        is new of course. Note that you can set your own custom
                        resolution: if you want, say 128x128, then just type this
                        string here and it gets saved when you OK the dialog.

                        Note that a custom refresh rate can also be defined. If
                        enumerating refresh rates is enabled, just type the desired
                        refresh rate in the following form: "width x height, n Hz".
                        So that, for example: "800x600, 59Hz".
                        If refresh rate is not defined then it means "app default".
                        What is more, if you want to override the refresh rate only
                        but not the resolution, use "0" for resolution values, e.g.
                        "0x0, 59Hz".

                        'Auto' option for MSAA has meaning only for Napalm build,
                        meaning 'application controlled'. For non-Napalm builds
                        it is equivalent to 'Off'.


- Number of TMUs:       This version can emulate more than one Texture
                        Management Units.


- Texture mem size:     Onboard RAM and texture memory are unified video memory on
                        UMA 3Dfx cards (see table in technical info). Future
                        versions of the setup may not allow to config them
                        separately.


- Force bilinear filter: Not much to say.


- Disable mipmapping:   I liked it in some games that looked nicer without
                        mipmapping. :)


- Enable Glide-gamma ramp:
                        See section "Gamma Correction".

- Force VSync:		Forces at least one vertical retrace before buffer swapping.
                        Use this option if something gets too fast.

- Force Emulating True PCI Access:
                        see section 'Some techincal info'

- 16 bit depth buffer:  see section 'Tips'

- 3Dfx Watermark:       Enables displaying the 3Dfx logo during the app animation.
                        You need the 3Dfx splash dlls for this. If they are
                        missing, no logo will be displayed.

- 3Dfx Splash screen:   Enables splash screen at game/app startup.
                        You need the 3Dfx splash dlls for this. If they are
                        missing, no splash screen will be rendered.

- Pointcast Palette Driver Build:
                        see section 'Some techincal info'



Missing but (present in old dgVoodoo and maybe) useful options:

- Screenshots:          Did not have time&mood to code it, but you can capture
                        the screen easily in other ways, I think. :)

- Force trilinear mipmapping:
- Autogenerate mipmaps:
                        Since no real texturing takes place in the emulation,
                        there is no way to generate mipmaps for a particular
                        texture. It would have to be done on-the-fly which is
                        impossible. Also, trilinear filtering would end up in
                        more complex shader code which is complex enough right
                        now.


- Texmem scaling to 4MB: It was specific to Red Baron 3D to be able to cache
                        more textures than with 4MB (to avoid texture corruption).
                        However uploading textures to the Voodoo TMUs are very
                        quick and virtually free now so I do not see the point
                        of scaling. No texture caching.


- Triple buffering:     Did not work well with some games. Also, it would not
                        fit well into the current implementation. Glide has
                        3 buffers of which one may be an auxiliary buffer.



3. Gamma correction
-------------------

A gamma correction curve can be set through the Glide interface. Since Glide
uses a linear curve by default it might not match the default or one's taste
and can look ugly (at least in the old days, I remember it looked ugly on CRTs).
For the standard see sRGB on google.

That's why the setup has the 'Enable Glide gammaramp' option: you can disable
the curve coming from Glide and let your monitor use the default.


*As taking a closer look into this, I realized that a linear curve is used by
the nowadays adapters by default but they probably post-calibrate it according
to the sRGB standard. So Glide's linear curve won't change anything to wrong.
I'm little confused about this. Back in the old days my real problem could be
that either brightness of my CRT was too high by default or sRGB was not
followed by the adapters therefore some gamma-adjusting game had really bad (pale
and really bright) look. I do not know it by now but won't remove the possibility
of disabling Glide gamma ramp. Test it on your monitor.


Color adjustments are supported in both fullscreen and windowed mode however
brightness is always calculated into the gamma ramp curve in fullscreen so
it has effect only if your adapter supports setting up gamma curves.


4. Some technical info
----------------------

Unfortunately Glide cannot be implemented in practice as a standalone API which
is completely independent on the underlying hardware. If someone looks through
the Glide SDK then it is clear that this API is suited for the 3Dfx Voodoo
hardware and its registers. However there are rules even in Glide (as in other
APIs too) that must be observed in respect of driving the API. An application
should never assume anything about the hardware being driven even if it knows
what hardware it is driving. The application should get all the info from the
API and keep the driving rules.
However in practice there are some application violating those rules very hard.
Since Glide provides free direct access to the frame buffer it is typical to
utilize the properties of a real 3Dfx hardware connected to the PCI bus. For
example, writing to the frame buffer while it was requested to lock for reading,
swapping buffers while one/some of the buffers are locked and assuming that the
mapped pointers of buffers remains unchanged, using 2048 bytes as frame buffer
stride, or drawing simultaneously by the 3D hardware and LFB writes through the
PCI bus even when a buffer was locked with idle 3D hardware mode.
Most of them can be workarounded easily but there is one case which can cause
performance drop if emulated perfectly. This case is the mentioned simultaneous
writing. dgVoodoo can emulate this usecase but you must enable it explicitly so
I reluctantly inserted an option into the setup, named
'Force emulating true PCI access'. This is the only technical option related to
the quality of the implementation. There are only a few games it should be used
for (see 'Tips') so it would be a pity to have it pointlessly enabled for the
rest.

There is another strange option in the setup, namely 'Pointcast Palette driver
build'. Well, early 3Dfx hardware allowed separate texture palettes/ncc tables
for each TMU so this possibility was reflected in Glide 2.11 and 2.43. However,
latter 3Dfx hardware used a unified memory model meaning that only one global
palette/ncc could be set for all the TMUs. Glide3 don't even allow to set them
in any other way. The funny thing is that original Glide2 drivers internally
also forced the global palette/ncc thing despite the API allowed separate ones.
It was because of pushing the programmers towards the future hardware. But, maybe
there were drivers built for custom vendors with the capability of separate
tables. So if this option is enabled in the setup then such a driver build is
emulated but it has effect only on non-UMA cards. I don't think that any Glide
application in the world requests such a driver build so always keep this option
disabled. It just makes the appearance wrong if more than one TMU are used.
This option is only for the sake of fullness.

dgVoodoo exposes the following Glide capabilities according to the selected card
type:

............................................................................................
Card type                   FBI revision    TMU revision     Glide3 extensions         UMA

? (unexposable via dgVoodoo)     1               0                  -                  no

Voodoo Graphics (SST-1)          2               1               GETGAMMA              no

Voodoo Rush (SST-96)             2               1        GETGAMMA, CHROMARANGE        no

Voodoo 2                         2               1        GETGAMMA, CHROMARANGE,       no
                                                          TEXMIRROR, PALETTE6666

Voodoo Banshee                   2               1        GETGAMMA, CHROMARANGE,       yes
                                                          TEXMIRROR, PALETTE6666,
                                                          TEXUMA, TEXTUREBUFFER

Other (greater)                  3               2        GETGAMMA, CHROMARANGE        yes
                                                          TEXMIRROR, PALETTE6666,
                                                          TEXUMA, TEXTUREBUFFER,
                                                          FOGCOORD, TEXCHROMA,
                                                          *PIXEXT, *COMBINE, *TEXFMT,
                                                          *SURFACE, *GETREGISTRY
............................................................................................

* Available in Napalm build only


5. Napalm build
---------------

Why is a separate build needed for Napalm? Why not just use it as a plain Glide3
implementation in general? Well, the answer is about the performance, again.
Napalm has a bit more complicated shaders in order to handle Voodoo4 features
like extended combine modes, 32 bit rendering, 32 bit texture formats and big
textures. So, it would be wasting of GPU resources to use it with Glide3
applications not requiring these features (so that all apps, in practice :) ).

Note that there is no significant difference between Glide3 and Glide3 Napalm
as for performance if dynamic shader compiling is enabled. In both cases, much
more optimal shaders are compiled and used than the precompiled ones.

Some limitiations:

- Compressed textures (FXT1, DXT*) are not supported. :(
- Reading/writing stencil values via 32 bit aux lfb lock won't work.
- T-Buffer writemask can only be controlled by the application if antialiasing
  mode is set to 'Auto'.
- SURFACE and GETREGISTRY extension are only used by the 3Dfx OpenGL 1.1 driver
  which is an OpenGL -> (Glide3 Napalm and DirectDraw) wrapper. Since Glide3
  operates on surfaces created by DirectDraw (3Dfx implementation), SURFACE
  functionality cannot be implemented. It means that original 3Dfx OpenGL driver
  won't work with a standalone Glide3 wrapper (it would make no sense but would
  be nice).
  Since OpenGL does not work, GETREGISTRY functionality is also needless. So,
  those two extensions are only placeholders, bunch of empty functions.
  
Don't forget to set card type to 'Other (greater)' with 2 TMUs in the setup to
emulate a Voodoo4.



6. Tips and known issues
------------------------

-  Forced trilinear texture filtering is not available in this wrapper version
   but an application can implement it by 2 drawing passes if one TMU is used.
   If more than one TMU are enabled then it can be done by one pass. Since
   more TMUs are generally used for drawing the same as with one TMU but with
   less passes, enabling multiple TMUs can be useful even if the gpu is loaded
   with heavier shader code. It depends. Try out both cases.


-  Keep in mind that not all Glide application are usable in windowed mode. Some
   of them behave very well while others may not at all. Since they were
   designed for an environment with one monitor and exclusive fullscreen display,
   an application can get minimized or simply quits when its window loses the
   focus. Also, they may capture the mouse into a fix area and you cannot even
   move the game window. Or worse: if this fix area is hardcoded and (so) is on
   the primary monitor then you can play the game only on the primary monitor even
   in fullscreen mode. dgVoodoo tries to workaround these cases by hiding some
   events from the application but generally it is not enough.


-  DosBox: Unlike previous versions, this one works perfectly with Gulikoza's
   newest Glide patch. Keep in mind that Extreme Assault needs a 3Dfx card with
   non-UMA architecture (see table of exposed caps) and PCI emulation.

-  Emulating PCI access is optimized for applications locking and accessing the
   LFB very frequently (per frame). Altough it provides faster lfb data access than
   doing the normal way, I cannot recommend to use it in general for all apps.
   Due to nature of the technique used it can cause slowdown in applications
   that access the lfb "regularly", so that once or twice per frame.
   Carmageddon 1, Extreme Assault, Dreams To Reality and Pyl are the only cases
   where it has to be used, afaik.

-  A strange case: when I tried to run a Glide based scene-demo, TBC,
   it always crashed at a certain point due to stack overflow. I had to
   manually grow the reserved stack size of the exe file to get it to run.
   Probably a real 3Dfx driver required smaller stack than a Direct3D11
   based driver.
   (http://xona.com/tobecontinued/)

-  I ran into a problem with NFS 3 Hot Pursuit: ugly z-fighting which is most
   noticable with projected headlights. This game does not use depth bias
   but utilize the inaccuracy of the 16 bit voodoo depth buffer when rendering
   polygons onto each other (I'm not sure if it was intentional or just a bug).
   If an app uses z-buffering then using a 16 bit depth buffer in the emulation
   provides the correct and exact mapping of the z values, like on a real Voodoo.
   And so NFS3 HP also works well with a 16 bit depth buffer. I was thinking on
   how to workaround this problem or automate this mechanism but found no way.
   So, reluctantly again, I exposed this into an option in the setup...
   This is the second option related to the quality of the implementation,
   aaaarrghh.