=============================================================================
=============================================================================
CPSC 533b Algorithmic Animation, Final Project

README.txt for the flowanim demo

Author: Andrew Nealen, Dept. of Computer Science, UBC Vancouver
Date: 04/22/02
=============================================================================
=============================================================================


COMPILIING AND RUNNING
----------------------

This zipfile contains all the FFTW (fastest Fourier transform in the west)
files needed to compile the source in the 'fftw' subdirectory, both for
linux (make) and windows (visual c++). More information on the FFTW is 
available at

http://www.fftw.org

You will need the glut headers and libraries to compile. These can be 
retrieved from

http://www.opengl.org/developers/documentation/glut.html

For convenience, I have provided a glut32.dll for windows in this zipfile.
To compile under linux, simply type 'make' on the command line. The provided
makefile expects FFTW to be in the 'fftw' subdirectory. The visual c++ 
workspace contains four configurations, both release and debug versions with
static and dynamic linkage of the FFTW libraries (the FFTW dll's are 
included in the 'fftw' subdirectory). I have added precompiled binaries for 
linux (flowanim) and windows (flowanim.exe).



USAGE
-----

For a more technical description, see the accompanying project report and
the references listed therein, available at http://www.nealen.com/projects

To start the demo, type

flowanim [gridsize]

Gridsize defaults to 64, but can me manually overridden on the command line.
Note, that on my machine (Pentium III 1GHz /w GeForce2 GTS) anything over
gridsize 256 is VERY slow. Dragging the mouse in the main window and holding 
the left mouse button down adds smoke and force to the field. by pressing 'p' 
the simulation can be paused/unpaused. When paused, it is possible to set up 
an initial situation, which can also be saved by pressing 'n' (the saved 
state can be restored by pressing 'shift-n').

All tweakable parameters of the simulation are accessible to the user via 
keypresses. Note, that tweaking these values is extremely machine dependent, 
as the demo does not monitor its own performance. Most of the keys listed 
above are also accessible via the glut menu when right clicking the 
main window.

Keys in the demo ('Z' stands for 'shift-z'):

z     Set velocities to zero
a     Set smoke densities to zero
c     Switch between smoke and vorticity display in main window
C     Enable/disable vorticity confinement forces
u     Toggle display of velocity field in main window
w     Draw scalar fields as wireframes
t     Decrease timestep by 0.01
T     Increase timestep by 0.01
v     Decrease viscosity by a factor of 10
V     Increase viscosity by a factor of 10
d     Decrease dissipation factor by 0.001
D     Increase dissipation factor by 0.001
s     Decrease injected matter at mouse location by 1.0
S     Increase injected matter at mouse location by 1.0
o     Decrease vorticiticy confinement force factor by 0.01
O     Increase vorticiticy confinement force factor by 0.01
q     Exit the simulation
p     Pause the simulation
r     Reset the simulation
f     Hide/show velocity field decompostion and FFT
F     Hide/show vorticity confinement computation
n     Save the current simulation state in memory
N     Restore a saved state from memory


ACKNOWLEDGEMENTS
----------------

The codebase I used to create flowanim was originally invented and written by 
Jos Stam. The extension to convecting densities and rendering them using 
OpenGL's GL_TRIANGLE_STRIP's and glut was written by Gustav Taxen 
(http://www.nada.kth.se/~gustavt/fluids/).


Have fun with the demo! And please mail any feedback to andy@nealen.com


Andrew Nealen, 
April 22nd 2002

____________________________________________________
nealen@cs.ubc.ca
andy@nealen.com
http://www.nealen.com
