PSEmu Plugin ReadMe
===================

Plugin Type:   GPU
Plugin Name:   Lewpy's 3Dfx Glide3 Renderer
Plugin Ver:    1.0.15 BETA 11
Date:          27/12/98
Author:        Lewpy (based on Tratax's Glide plugin)

Only contact me about things to do with this plugin.
General enquiries about PSEmu Pro will be ignored. Read the FAQ.

Email: psemu@arisen.demon.co.uk

Send me details of the problems you encounter with the following info:-

1) Version of PSEmu
2) Version of my plugin
3) Game that has problem
4) Description of problem
5) Does the software renderer have this problem as well? [if so, then it
is more than likely not my problem, but a problem with the main emulator!]

*** READ THE VERSION NOTES FOR THE LATEST INFO ***

Disclaimer
----------
This plugin is a part of PSEmu and cannot be used in any other software.
This program is freeware and cannot be sold. Also this program cannot be
distributed without written permission. This program cannot be used for
any commercial purposes.
Authors are not responsible for any damages that this program may cause,
and are also not responsible for anything this plugin will be used for.

Description
-----------
This is Hardware based driver for 3Dfx graphics accelerators.
It *requires* Glide3 runtime libraries to be installed for you 3Dfx card.
Download them either from your card manufacturers web site, or grab the
3Dfx reference drivers from their web site http://www.3dfx.com/

Note: this driver is optimised for the latest range of 3Dfx cards. That is,
it offers better visual quality on Voodoo2 cards and probably on Banshee
cards (un-tested ... I hope it works!). Voodoo1 cards and Voodoo Rush cards
should work with the driver, but they will suffer some transparency problems
compared to the newer cards.

Installation
------------
Copy this plugin to to "plugin" directory that resides in PSEmu directory.
Use Configuration in PSEmu to choose this plugin, and select the resolution
you want it to run in.

Keys
----

    Del - Enable/Disable Bilinear filtering                    Default: Off
       Looks nice some of the time, but not all of the time.
       Now you can choose when and where.

    End - Enable/Disable OnScreen display                      Default: Off
       Mainly for debugging, not too useful.
       I can't say whether the stats are 100% accurate.
       There are now 2 different displays: simple & complex.
       Most people would want simple (just fps): complex is
       mainly for my benefit in debugging.

    Ins - Enable/Disable texture alpha blending                Default: On
       This setting is for the older 3Dfx cards: use this
       to disable alpha blending if you think some textures
       are being made transparent when they should be visible.
       Unfortunately, it will make textures that should be
       transparent visible. Sorry, it's one or the other :(
       For newer 3Dfx cards, this key does nothing as it would
       gain you nothing (except an incorrect image).

    Home - Enable/Disable extended palette
       This is for all you Banshee owners!!
       Until 3Dfx fix their Banshee Glide3 driver, leave this key
       alone. Once the drivers are fixed, press this key to gain
       extra transparency effects. 
       I'll remove this key on the next build after the drivers are fixed.

    Page Down - Toggle Display Modes                           Default: Mode 1
       Toggles between 3 Display Modes :-
       1) Bright, but high colour values clamped, fast
       2) Dim, high colour values okay, fast
       3) Bright, high colour values okay, but slow

    Page Up - Toggle FrameBuffer Writes                        Default: On
       Toggles 16bit framebuffer writes on and off. Maybe useful when a game
       slows down unexpectedly.

    CTRL - Show VRAM
       This is really for my benefit :)
       It's not perfect, as it can't handle double buffer too well.
       BGR is also displayed as RGB :( Seems to be a Glide bug. Oh well.

    SHIFT - Toggle Frame-Rate Limiter                          Default: 60fps
       Toggles between a 60fps and 30fps frame-rate limiter.

Problems
--------
Don't try and use this driver if you do not have a 3Dfx graphics card!!!
Also, make sure you have Glide3 installed: this will install a file called
GLIDE3X.DLL in your Windows/System directory. If this driver is not present,
expect it not to appear in the list of plugins at all!

Really old 3Dfx cards (mainly sent to developers early on) will not be able
to run with this plugin. This is due to the plugin needing a texture palette,
and the early 3Dfx cards did not have this capability (Revision0 TMU's).
I believe all production cards had later revision TMU's, so this should not
affect 99.99% of people.

Old Notes from the Author
-------------------------
Phew, what a hectic couple of weeks I've had! :)
It was just under 2 weeks ago that I got hold of the source code for Tratax's
Glide driver, and I started at work to improve things (I had a few ideas at
the time). Well, it's been _many_ late nights over the last week trying to
iron out all the niggly bugs with different games (I only have access to a
few games), so I expect there to be problems.
I've tried to improve the visual quality, and stream-line the rendering.
I intend to carry on work, mainly looking at the following, in some kind
of order:-

1) MDEC support
2) Correct screen centering and scaling
3) Improve performance

So, expect updates :)

Bug Reporting
-------------
Yes, I do want to hear about bugs.
No, I don't want to be bombarded with mail!!

So, a compromise please :)

*Before* you think about reporting a bug, please check if there is an update
for this driver. Try the PSEmu homepage at http://www.psemu.com/ or, if you
are an IRC user, join #PSEmu on EFNet. Check the FAQ.

If you do send me an email, please try to describe the fault as simply as you
can: tell me the game, and the format (language, NTSC/PAL, etc.)

*DO NOT* include any screenshots!!!! If I need one, I *may* ask for one :)
My mailbox does not need filling!!

Mail me at : psemu@arisen.demon.co.uk

I _really_ hope you enjoy this driver: it's taken a lot of my time in the last
couple of weeks, and I am sure it will take more of my time in the coming weeks/
months/years ;)

Lewpy, 11pm 21/10/98.

Greets to :-
IRC: mappy, moopy, stubbette, Ravian, Adept, Vastator, Gaffer, Frenzy, Statix
IRCNet #coders, EFNet #3Dfx & #PSEmu!
RealLife(tm): Paul, Damian, Sarah (and all at Bizarre Creations), Matt, Sue, Dunx, Tabs,
Paula, Giles "Hoohah", Simon "Delbert", Harry The Bastard, Jim, Rik, Pete,

Changes:

* ver. 1.0.15 Beta 11 - 27.12.1998
 - Optimised off-screen clearing
     This should speed games up a bit. Amount will vary from game to game.

 - Fixed connected lines bug
     Connected lines was messed up in Beta 10, doing all kinds of weird stuff (didn't
     crash though).

 - Implemented more basic off-screen rendering support, using Duddie's GPU code in the end :)
     In Beta 9/10, I added non-textured triangles. Now I've added Sprites. Although none
     are blended correctly yet, it's better to have something than nothing :)
     This means the skeletal menu in MediEvil is now visible: a personal crusade to get that
     going! :)
     None of the offscreen drawing (except clearing and copying) is optimised yet.
     This shouldn't affect too many things, since off-screen drawing is not all that common.

 - Fixed potential lockups selecting BiLinear filtering, or doing a screenshot
     These were "interrupts" coming in and executing out-of-synch with the rest of the Glide
     rendering. Thay are now synched to the main flow of execution.

 - New Banshee code
     Hopefully, this should improve matters for the Banshee owners. With the Banshee drivers
     being as painful as they have been, there is always a chance things actually get worse :(
     Since I don't have a Banshee, I can't check ... so please give feedback over this.

* ver. 1.0.15 Beta 10 - 25.12.1998 - Christmas Release Part II
 - Beta9 had a nasty bug which crept in at the last minute, which caused lots of crashes

 - This is a bug-fix for Beta9

 - Fix for DevKit problems

 - Extra "work-around" for Banshee

 - Implemented basic off-screen rendering support, using Duddie's GPU code in the end :)

 - Fixed a crashing bug that prevented Crash Bandicoot 3 from running.

* ver. 1.0.15 Beta 9 - 24.12.1998 - Christmas Release
 - Happy Christmas everyone :)

 - lots of things, and no time to write this :(

 - See if you can notice the differences


* ver. 1.0.15 Beta 8 - 14.12.1998
 - fixed a bug due to Tekken3 "fix"
     Fixed a bug whereby only some of the scene was being drawn in some games, such as GT.
     The whole scene is now drawn properly.

 - Added a Frame-Rate Limiter
     Games are now capped at 60fps(-ish), PAL and NTSC. You can slow it down to 30fps by
     using the SHIFT key.

 - Added multiple Display Modes
     Still playing around with the colour balance!! There are now 3 options. The latest
     option (Option 3) is the best, but it does slow down the update rate (depending on
     the game). Option 1 & 2 are the two options that have been available before:
     one bright, one dim.
     Select the one you prefer, which will probably vary from game to game.

 - Small palette optimisation
     I added a small optimisation to the palette code. Not sure if this will really be
     noticable.

 - Compiled under Visual C v6
     SP1 seemed to stabalise Visual Studio 6, so took the update step. Seems pretty cool.
     Dunno if it's affected the speed of the code, but it has made the plugin bigger!
     You will need the latest Visual C runtime libraries (MSVCRT.DLL and MFC42.DLL), which
     are available from the PSEmu beta page.

* ver. 1.0.15 Beta 7 - 07.12.1998
 - fixed the Tekken3 hang, we hope!
     Implemented a "fix" for the Tekken3 problem, thanks to the guys on IRC.
     Best bet is to advance to the next round by using the START button to skip over the
     end Replay and the "victory" animation of your character. I have noticed repeatable
     loops if the "victory" animation ends.

 - fixed display modes some more
     Something that I overlooked in Kaz's code. Thanks to Kaz for putting me straight!
     I hope this helps GT NTSC display frames properly .... we shall see.

 - fixed problem with DevMode
     Returned initialisation code back to how it was in v1.14, unless you have a Banshee
     in which case a little work-around is required until the Banshee Glide3 drivers are
     sorted!

 - altered colour balance
     I'm messing with the colour balance again! Display has dimmed down again: this will
     allow the menus in Spyro to display the selected item properly (it didn't flash in
     previous beta's, due to colour clamping). This may result in another toggle key, to
     provide a nice, bright display most of the time, but if something isn't displaying
     right you can switch down to the more-compatible dimmer display while needed.


* ver. 1.0.15 Beta 6 - 29.11.1998
[2 Beta's in one day :)]
 - fixed another crashing bug
     Yep, yet another one squashed! This one was in some old code, that pre-dates my
     work :) Anyway, this lets the demo of MediEvil play, so I'm sure it will help
     other games as well.

 - Messed up menu graphics in GT
     Corrected this. Probably helps other games as well.

 - Messed up dialogue text in MediEvil
     No-one would have seen this yet :) Corrected this. Probably helps other games as well.

 - Fixed Screen Scaling
     At last!! My screen resolutions are the same as Kaz's. No more dead area at the
     bottom of the screen!! Thanks to Kaz for his latest code for this.

Known Issues
 - Messed up graphics
     Skeletal menu at the start of MediEvil demo is not displaying right. This may affect
     other games too.

 - Incorrect MDEC display
     I have heard reports of MDEC playing back in white, or really slowly. I am investigating
     this.

* ver. 1.0.15 Beta 5 - 29.11.1998
 - fixed frame buffer writes
     Basically re-wrote the way frame buffer writes were handled, plus fixed 24bit
     MDEC support (re-wrote that really!). GT MDEC now displays properly (no flashing),
     but it does have rubbish in the "dead" area of the screen.
     This should also fix some crashes, since the previous code was trying to draw some
     "illegal" triangles that would have caused Glide3 to lock-up [see previous entries,
     it's all related!!]. Just to be safe, even the screen-writes are now clipped!! :)

Known Issues
 - Messed up menu graphics in GT
     Some menu graphics messed-up (illegible), such as the manufacturer select menu. This probably
     affects other games too.

 - Messed up graphics in the "dead" areas of the screen
     Normally these are CLUTs being uploaded to the screen. Once I sort out correct
     screen scaling, these will all magically go away. At the moment, just take this
     to mean that my framebuffer writing code is working properly!

* ver. 1.0.15 Beta 4 - 26.11.1998
 - fixed another crashing bug
     Another update, another crashing bug fixed! :) Hopefully, no more added!
     For those that want to know, it was a problem with Tiles that weren't being
     clipped. Now _everything_ is being clipped, and all seems to be more stable.
     I am sure there are still crashing bugs, so don't be surprised if it crashes :(
     This clears the lock-up in Glide3: I guess it was my fault, and I caused Glide3
     to get it's knickers in a twist!

Known Issues
 - Flashing Displays
     Yup, some framewrites are not working quite right

 - Messed up graphics in the "dead" areas of the screen
     Normally these are CLUTs being uploaded to the screen. Once I sort out correct
     screen scaling, these will all magically go away. At the moment, just take this
     to mean that my framebuffer writing code is working properly!

* ver. 1.0.15 Beta 3 - 24.11.1998
 - fixed some more things to do with frame write uploads
     This clears up a corruption/crashing problem that I located

 - removed some debug code
     This was forcing some default values (like fps counter), plus it prevented
     the frame delay "feature" from working. In fact, it would make some games run
     way too fast. Ooops.

Known Issues
 - I am trying to track down a lock-up within a Glide3 call. This is totally weird,
and none of the debugging tools I have is helping :( Basically, this is crashing
some games and I don't have a clue why!! This coding lark isn't fun sometimes :(

* ver. 1.0.15 Beta 2 - 19.11.1998
 - fixed some things with frame write uploads
     This should clear up some splash screens. It also now means that some stuff
     gets uploaded (ie. drawn) off the bottom of the screen in the "dead" area.
     Really, that "dead" area shouldn't be there!! It will go once I get the
     display setting stiff working 100% right.

 - removed the display clearing hack
     This was a nice idea, just not fully thought out!! This is what comes of
     coding late into the night!! :)
     I'll resolve the stray drawing another way, for now it just has to stay.

* ver. 1.0.15 Beta 1 - 17.11.1998
 - fixed problems with 2D clipping
     There were a couple of issues here. Firstly, I forgot to clip lines :(
     This resulted in repeatative lockups within games. FIXED. Secondly,
     textures were "swimming" on the edge of the screen, where polys were getting
     cropped. That is to say, they were swimming _more_ than normal for a PSX!! :)
     Problem is related to the fact that the PSX doesn't do perspective-correct
     texture mapping. FIXED.

 - got Banshee working!!!
     I've worked around bugs in the current 3Dfx Banshee Glide3 driver, so hopefully
     all you Banshee owners will be pleased! :) There are still issues, but this
     will be resolved once 3Dfx update the Banshee Glide3 driver, and it actually
     supports what it says it supports!!

 - MDEC support!!!
     Full 16bit and 24bit MDEC support!! It may be slow in some cases :( But I'll
     work on that :)
     This also means that those splash screens and backdrops that were missing should
     now be working!

 - Re-arranged keys
     This was to avoid clashes with other parts of the emulator (mainly the function
     keys), and also to match my Show VRAM to Kaz's :)

 - Altered palette stuff
     Reduced the complexity of my palette caching routines, which hopefully should
     resolve some palette bugs. It may result in slightly slower overall speed, but
     I'll work on that in a different way in the future.

 Things ToDo

 - Find more Speed!!
     Of course! Where I can, I will.
 - Better support for Bilinear filtering
     Maybe. There is a few things I could try. If 3Dfx actually put full support for
     their hardware in their drivers, the black edges that appear on alot of textures
     may well vanish (this is a ChromaKey/Bilinear clash that occurs in 3Dfx hardware).

 Known Issues

 - I've got a hack in place to tidy up the bottom of the screen. This may possibly
result in some weirdness in games I haven't been able to test with (something like a
large black square covering part of the screen). It does effect the Tekken3 menu
screen near the bottom, but that is easily outweighed by the reduction in rogue
flashing bits on the screen in other games!!

* ver. 1.0.14 - 01.11.1998
 - implemented 2D clipping against the viewport
     This fixes a hack that I had to introduce, so visual quality is up a bit
     It also seems to help speed

 - tried to balance the lighting
     Display is a brighter now, with better balance between textured and
     non-textured surfaces. It's still not perfect, so I may implement a
     toggle-key in a future version

 - loads of behind-the-scenes stuff that you probably won't notice :)

 - maybe fixed problems with Banshee? Nope, it appears not :(
     Damn this is painful ... believe me, I am _trying_ to get my plugin
     to run on the Banshee.

 - PLEASE RE-RUN THE CONFIG SCREEN AND SELECT A RESOLUTION!!!
     Things have changed slighty, so some of the higher resolutions
     will not be on offer. These seemed to be bugged anyway.

 Things ToDo

 - MDEC support!!
     Full support for direct writes to the framebuffer
 - Find more Speed!!
     Of course! Where I can, I will.

* ver. 1.0.12 - 29.10.1998
 - added runtime keys as follows

    SHIFT - Show VRAM
       This is really for my benefit :)
       It's not perfect, as it can't handle double buffer too well

 - stream-lined colour support in primitives
 - added better palette caching
 - fixed screen resolutions: Tekken3 now scales correctly
 - cleaned-up init/shutdown code

 Known Issues

 - Doesn't work on Banshee :(
     I am investigating this ....
 - Funny display
     Try lowering the resolution. I believe this to be a Glide3 driver bug,
     so it may be fixed with improved drivers. If I can find a workaround
    (short of disabling problem resolutions), I will incorporate it.
 - Crashes in some games
     This is on the ToDo list, once I am happy the driver is pretty solid.

 Things ToDo

 - MDEC support!!
     Full support for direct writes to the framebuffer
 - Find more Speed!!
     Of course! Where I can, I will.

* ver. 1.0.11 - 22.10.1998
 - added runtime keys as follows

    F6 - Enable/Disable Bilinear filtering                    Default: Off
       Looks nice some of the time, but not all of the time.
       Now you can choose when and where.

    F7 - Enable/Disable OnScreen display                      Default: Off
       Mainly for debugging, not too useful.
       I can't say whether the stats are 100% accurate.

    F8 - Enable/Disable texture alpha blending                Default: On
       This setting is for the older 3Dfx cards: use this
       to disable alpha blending if you think some textures
       are being made transparent when they should be visible.
       Unfortunately, it will make textures that should be
       transparent visible. Sorry, it's one or the other :(
       For newer 3Dfx cards, this key does nothing as it would
       gain you nothing (except an incorrect image).

 - disabled the following configuration settings

    Enable bilinear filtering
    Disable VSync
    Enable OnScreen display

   They are now obsolete: use the runtime keys instead.

* ver. 1.0.10 - 21.10.1998
 - first public release