PyroTechnics v1.4
-----------------

PyroTechnics is an OpenGL-based firework simulator that runs under Linux
(and other *nix platforms) and win32.

PyroTechnics Copyright (c) 1998-1999 by Mike Oliphant and Rob Clark. It may
be distributed freely under the terms of the GNU General Public License (see
the file LICENSE for details).


Features
--------

 o a bunch of nifty kinds of fireworks
 o the ability to choreograph firework displays
 o a texture-mapped water surface
 o reflections in the water
 o fogging
 o a moving camera
 o the ability to save screenshots


System Requirements
-------------------

PyroTechnics requires:

 o an OpenGL implementation
 o the GLUT library
 o the libjpeg library (compiled into PyroTechnics under win32)

3D Hardware acceleration (such as a 3Dfx card) is strongly recommended.


Running PyroTechnics
--------------------

Usage: pyro [-r] [-d <displayfile>] [-w <numworks>] [-p <workprob>]
            [-c <camdist>]

  -h                 Display usage
  -r                 Display random sequence (ignore display file)
  -d <displayfile>   Read display sequence from <displayfile>
  -w <numworks>      Maximum of <numworks> fireworks at a time
  -p <workprob>      New firework with probability <workprob> per second
  -c <camdist>       Rotate camera <camdist> units from center of display
                     (value should be less than 70.0)

Help is available in the demo by typing 'h'. Screenshots are saved in PPM
format.

*** IMPORTANT! ***

If you have trouble pyro, or it is slow, read the "Common Questions"
section. Most of the questions people email me are answered here.

*** IMPORTANT ***


Choreographed Displays
----------------------

Firework display information is read from the file "pyro.dsp". The format of
this file is:

 #<text>         -- comment

 <name> [ (<x>,<y>,<z>) [ (<dx>,<dy>,<dz>) ] ]
                 -- launch firework <name> from position (<x>,<y>,<z>)
                    with velocity relative to (<x>,<y>,<z>)

 wait <val>      -- wait <val> seconds

 repeat <val>
 ...             --  repeat the given commands <val> times
 done  

 loop            -- loop back to the beginning of the display

Currently the available firework names are:

 o white -- basic white firework
 o purple -- basic purple firework
 o cyan -- basic cyan firework
 o yellow -- basic yellow firework
 o rednwhite -- white and red particles
 o innout -- a center of green with a surround of yellow
 o spray -- a spray of purple particles
 o xzwobble -- an explosion of blue particles that turn white wiggle down
 o rg -- particles with full blue component, but varying red and green
 o rb -- particles with full green component, but varying red and blue
 o lilyel -- small yellow firework
 o ring -- red sphere with a cyan ring around it
 o yellgrn -- particles whose color turns from yellow to green
 o purpblue -- particles whose color turns from purple to blue
 o cross -- white sphere with a blue cross along x,y,z axes
 o whitespark, goldenspark, rgspark, rbspark -- sparkling streamers
 o vertring -- a cyan-colored vertical ring

OpenGL Notes
------------

You must have OpenGL and Glut installed on your system. On *nix machines,
you can either use a native OpenGL implementation, or use Mesa. On win32,
you can use Microsoft's software OpenGL implementation (slow!), 3Dfx OpenGL
(if you have a 3Dfx card) or Mesa (although I've had some problems with Mesa
under windows). Here are locations where you can find some of the OpenGL
implementations:

 - Mesa:  http://www.ssec.wisc.edu/~brianp/Mesa.html

 - 3Dfx OpenGL:  http://www.3dfx.com/docs/opengl_beta/opengl_beta.html

 - Microsoft OpenGL:  ftp://ftp.microsoft.com/softlib/mslfiles/opengl95.exe

 - GLUT for Windows:  http://reality.sgi.com/opengl/glut3/glutdlls.zip


Windows Notes
-------------

Pyro seems to be more jerky under windows than it is under Linux on the same
hardware. Perhaps the wait for video synch isn't enabled by default under
windows?

None of the windows OpenGL implementations seems to support fogging. It
just doesn't do anything under Microsoft OpenGL and 3Dfx OpenGL, and crashes
Mesa. Mesa also crashes if textures are used.

If you've got any ideas about how to solve the above problems, drop me a
line.


Compiling
---------

PyroTechnics was developed on a Linux system using Mesa v3.0 and a 3Dfx
Voodoo card. It should work with minimal modification on other OpenGL
implementations. If you successfully compile PyroTechnics on another
platform, please let us know.

To compile PyroTechnics using Mesa, first edit the Makefile to ensure that
MESADIR is set to point to the directory that contains your Mesa include
files. If you aren't using Mesa on a 3Dfx card, remove the "-DXMESA" from
CFLAGS. Then type 'make' and PyroTechnics should compile.

The parsing code requires a YACC compatible parser generator such as GNU
bison. "parser.c" (the output of running bison on "parser.y") is included,
in case you do not have a compatible parser generator.

Makefiles for Solaris, SGI machines (courtesy of Brian Paul), OS2 (courtesy
of Doug LaRue) and HP machines (courtesy of Matt Taggart) are included.


Customizing the code
--------------------

The implementation of fireworks is designed to be easily
extensible. Both firework types and the particles that they use can be
customized. Have a look at the code and play with it. If you come up with
any interesting firework types, send them to us.


Common Questions
----------------

 Q: I am only getting a few frames-per-second. This sucks! What gives?

 A1: You're probably running Mesa in software mode. You should read the
     "README.3Dfx" file in the Mesa distro. Specifically, you need to
      "setenv MESA_GLX_FX fullscreen"

 A2: You don't have a 3D graphics card. Go buy one!


 Q: When I run pyro, it just dumps core. That's not the kind of
    pyrotechnics I was looking for!

 A: If you are using a 3Dfx card, make sure you are running xmame.xgl as
    root. Root priviledges are required to access the 3Dfx hardware


TODO
----

Things we think would be cool to add to Pyrotechnics:

 o more kinds of fireworks
 o sound
 o better frame-rate independence
 o velocity modulation (to do things like pinwheels)
 o particle generation (fireworks that spark as they go, particles that
   shoot off other particles)


Acknowledgments
---------------

Thanks go to:

 o Brian Paul and all the others working on Mesa
 o Mark Kilgard for the GLUT library
 o David Bucciarelli, for the Mesa 3Dfx driver, and for 3Dfx example code
 o The Independent JPEG Group
 o Raul Alonso, for ssystem -- cool program, and useful as example code
 o Eric Plante for help on saving a screenshot


---
Mike Oliphant (oliphant@ling.ed.ac.uk)
Rob Clark (robert@cstr.ed.ac.u)

http://www.ling.ed.ac.uk/~oliphant/pyro
