                 ===) druid-'s Stonehenge v1.0 (===
     released 3/4/98 for Operation 3dFX's programming contest #2
                      (http://www.op3dfx.com) 
                 ===> by Scott Franke (druid-) <===
                        druid-'s GL Journal
               (http://www-scf.usc.edu/~sfranke/glj)

//===--
     ===) Short description:
Stargazing turns into a mystic event.

(what do you expect for <40 characters? sheesh)
//===--


//===--
     ===) About the author:
This demo was programmed in it's entirety from scratch by me, Scott Franke
(aka druid-) over the time period of about 2 1/2 months.  This doesn't mean
working straight for 2 1/2 months (I have school and all), just that all the
code in this version was written in that time period.  This is my first
complete large-scale project.  It was a learning experience to say the least.  

I'm 19 years old, and a freshman CS major at the University of Southern
California in Los Angeles.

There's more info about me and my history/experiences of programming on my
web page.
//===--


//===--
     ===) Long description:
  <official 5 line deal>
druid-'s Stonehenge begins (after the title) as a casual night gazing at the
stars.  But when some sort of comet appears, rocketing fiercely towards the
ground near you, the night changes dramatically.
  </official 5 line deal>

     ===) Extended information:
This demo is a compilation of many different effects.  Here's a brief list:
  * Dynamic lighting (parallel and positional) (colored of course :) )
  * Complex particle systems and physics
  * 3d model format with texture and normal data
  * Fractal based textured and lit landscape
  * Scripted control of position/rotation/color of 
	camera, objects, particle systems, lights, etc.

I also wrote two extra programs to aid in the development.  One to convert
objects from wavefront format to my own format.  And the second that creates
fractal landscapes (based on the Mandelbrot set) and exports them in wavefront
format.  The source for those is included.
//===--


//===--
     ===) Hardware / software requirements
The base hardware requirement for the competition is/was:
  P166MMX
  24 Megs of RAM
  4Mb 3dFX card

However, in theory, it should work on any fast 3d video card that has a
MiniGL driver for (GL)Quake(2).  Check below for which systems/cards I
have tested it on.

I developed the demo on (initially):
  K6 200
  32 Mb of RAM
  Diamond Monster 3d video card
and later added:
  64 Mb more RAM
  Diamond FireGL 1000 Pro (Permedia2 chipset)

Software requirements:
  Windows95 or WindowsNT 4.0
  Latest drivers for your video card

******] AN IMPORTANT NOTE ON THE OPENGL32.DLL INCLUDED
  The DLL that was included is for 3dFX Voodoo's only.  It is an old
DLL from GLQuake days, but it does everything I require flawlessly (as
does my FireGL), which I can't say for the later 3dFX miniGL DLLs.
If you are attempting to run the demo on a system without a 3dFX card,
delete this file.
  NOTE: I am not a troubleshooter for getting the demo to work on non-3dFX
cards.  Please do not send me email asking me how to get it working on xxx
chipset.

Tested systems and video cards:]
  K6/200 w/ 80Megs of RAM running WindowsNT (sp3)
	Windows NT standard OpenGL using a Permedia2 accelerator
		works fine
	* Monster3d, 3dFX alpha GLport (7-22-97) (from GLQuake)
		works fine
	Monster3d, 3dFX beta OpenGL dll (10-20-97)
		textures on console (fonts) don't work - Yes, I know 
		why, and I'll fix it for the next test release)
	Monster3d, 3dFX Quake2 test dll (9-26-97).  
		(funky blue transparent textures.  Not sure what's 
		up with this, but I'll have it fixed when I get the 
		chance).
	Monster3d, 3dfx Quake2 final dll (11-16-97). 
		same as the q2test dll
  Pentium 200 w/ 64Megs of RAM running Windows95
	Canopus Pure3d running the 3dFX DLL distributed in this zip
		works fine
  Dual Pentium Pro 200 w/ 128 Megs of RAM running WinNT sp3
	Monster 3d running the 3dFX DLL distributed in this zip
		works fine
  Pentium 133 running Windows95
	Intergraph Intense3d Voodoo Rush w/ same 3dFX DLL
		no texture-mapping (demo is unviewable)

* - this is the DLL that comes with the zip.
//===--


//===--
     ===) Instructions:
Simply run demo.exe.  If you want to quit half-way through, hit insert (might have
to hit it several times), and then type 'quit' at the console to terminate the
program.  (Or just hit alt-F4). There are also some other available commands at the
console, which I'll publish in the next week on my web site.
//===--


//===--
     ===) Bugs, issues, etc:
*) Very seldom I've seen the program just freeze when working on the first big
particle explosion.  It's still running and you can just hit alt-F4 to close it
and start it over.  I have no idea why it does this.

*) Another weird particle bug (maybe related) is that sometimes it just stops
animating a particular particle system.  I've seen this happen almost anywhere. It
does it pretty rarely however, and since there's a lot of randomness involved in
those systems, it's pretty hard to find the bug.  So if it looks like there are some
big particles there not doing anything, hit alt-f4 to close it and start it over.
It's probably just superstition, but it seems to work better when run from the
start->run menu rather than from explorer or the command prompt.

*) If the framerate seems to be pretty low at points, it probably is.  It's not
the fault of your computer.  It's a few things.  
 First, the amount of lighting calculations involved is very large (it recomputes
the lighting from every light source to every vertex whenever a light moves or
changes color or a model moves).  This turns out to be a processor bottleneck,
because that's a whole lot of floating point calculations for any given frame.
 Second, the particles are individually rendered from textures and blended into
the scene with varying transparency.  This means that they all have to be sorted,
which takes some time.  It also is a vicious slaughterer of frame rates when a lot
of them pile up and get close to the camera.  The 3dFX is extremely good at this
sort of thing, but when you're talking about 50+ almost screensize texture-
modulated polygons on top of everything else, it will slow it down.
 Thirdly, I haven't apent anywhere near the time optimizing that I would like to.
This is primarily because I wanted to develop a large scale demo from near
nothingness in a somewhat short amount of time (plus school and all :[ ).
 But anyway, it's basically a floating point-devouring monster, and if it runs
reasonably on my K6 200, it should run as well or better on Intels.
//===--


//===--
     ===) Sourcecode notes
Blah, the sourcecode could be MUCH better.  I have spring break next week, so
I'll probably be spending some of the time then putting the source code and
better explanations of what's going on in it on my web page.  So don't email me
with questions until after that's up.

On the bright side, there is a LOT of stuff in there for you to check out.

Unzip it with winzip or the -d option under DOS.  That will create three
directories:
	demo_src\	- Source and project file for the actual demo
	frac_src\	- Source, project, and exe for fractal generator
				(outputs a wavefront .obj file that can be
				imported into most 3D packages)
	obj2hm_src\	- Source, project, and exe for Obj2HM converter.
				(HM is just some format I made up to use)

All the sourcecode is Copyright 1998 by Scott Franke.  However, you can use it
for anything you like as long as you give the appropriate credits and send me
an email telling me what you're up to.
//===--


//===--
     ===) Remarks about the present and future:
After many hard months getting this sucker written, scripted and out, what am I
going to do now?

Well, I'm probably going to relax a little bit, play some more Quake2 CTF, work
on my web page.

Then I'm going to spend a lot of time reading some of the source-code for games
that have been released (Doom, Descent) to see how my methods compare with
others' (from a design standpoint).

Then I'll be starting on another project.  What it's going to be isn't clear yet,
but I'll be spending a good while just developing some new technology.  I'd like
to work on another demo, this time with a team to make a more complete demo with
music and better models/textures.

But if the opportunity arose, I'd be more than happy working on a game or something
like that.
//===--

//===--
     ===) Contact information:
If you liked/loved/hated/despised/watched the demo, and have something to say to
me, email me.  This can just be encouragement, initiating a technical discussion,
interest in working on a future project, or just about anything.  I won't have
much to do for a week or so anyway :)
  sfranke@scf.usc.edu

And go check out my web page!  It's got lots of sample source code for helping
coders get started writing OpenGL programs for 3dFX or anything else that supports
it.  I'll be updating it more now that this is done with.
  http://www-scf.usc.edu/~sfranke/glj
//===--

//===--
     ===) FAQ (Frequently Anticipated Questions)

 * When I run the program, it says I need MSVCRTD.DLL.
This is a DLL that programs compiled with Microsoft Visual C++ 5 need.  Since you
don't have it, go check out ftpsearch.ntnu.no and search for it.  You should find
it.  If anyone knows how to build my program so it doesn't require this, please
email me.

 * When I run the program, it says I need GLU32.DLL.
This is a DLL that is part of OpenGL.  If you haven't installed OpenGL for Win95,
do that now.  Go to the OpenGL Repository http://imagine.iss.nus.sg:8888/~leo/oglrep
and download the Microsoft Windows95 OpenGL DLLs.  Unzip those and put the DLLs
in your /windows/system directory.  You can delete the .lib and .h files.

 * How when I run the program it's all black?
First of all, turn off the lights.  This is a dark demo, it takes place at night.
If that isn't enough, you can always crank up the gamma on your video card either
through the desktop settings or environment settings.

 * I tried that and it's still black!
If you're not using a 3dFX Voodoo card, the driver you have may not support one
of the GL functions necessary for texture mapping or something like that.  The
Voodoo Rush I tested it on did this.  If this is the case, there's not much you
can do until the hardware vendor releases a newer OpenGL driver.

 * The demo seems to run fine, but it's in a window!
Yeah, if you're running a non-3dFX card, it will appear in a window.  I have the
code in there to switch resolutions so it will be full screen (I'm not using
directDraw), but I have it commented out because it does some annoying things with
resizing windows and moving icons around.  Plus it was easier to debug with the
Permedia2 if it wasn't in a lower resolution.
If you want it to be fullscreen you can uncomment that section of code (it's in
demo.c near the bottom, and is marked) and rebuild the whole thing.  Or you can
email me, and I'll put the executable for that on my web page.  (Be sure to check my
page first to see if it's already there).

 * There seem to be a bunch of horizontal lines over the textures.
As far as I know, this is a limitation in the blending of the Voodoo chip.  I
understand it's much better in Voodoo2.

 * Why is there no sound/music?
Because it's a graphics competition, and I have no experience programming sound.  I
didn't have enough time to get any experience, otherwise it would be in there.  Don't
try to play an MP3, because it saps away from the processor.  If you must have 
music, just stick in a CD and set up a program to play it.

 * I want to play around with this scripter, where can I get the program you used?
Heh, you may change your mind.  I did it all in notepad.  Check the script.h and
demo.h files under demo_src\ for some constants you'll need.  The top of script.h
has some extra information about the parameters, etc.  Then just look at my scripts
(*.hs) I guess.  I would recommend against trying this however.  It's really not
worth it.  Take my word for it :).
//===--

until next time \
  druid-
