# Real-Time Smoke Simulation and Visualization

1. Introduction

This directory contains the code for the Real-Time Smoke Simulation and Visualization assignment. The code contains a real-time simulation of matter which flows under the influence of a user-controlled force field. The simulation follows the Navier-Stokes equations for fluid flow. This document describes briefly how to compile the code and the structure of the main program. This is not intended as an in-depth description of how to write or compile programs in C or another programming language, OpenGL, event-based programming, or how to build a real-time fluid simulation engine. However, starting here, you should be able to compile the code and add visualization features to the provided skeleton application.

2. Structure of the code:

The provided software consists of three main parts:

· a mathematical library, called FFTW (standing for Fastest Fourier Transform in the West), is used to provide the numerical engine that simulates a fluid flow in two dimensions.

· the GLUT library (GL Utility Toolkit), used to provide simple OpenGL graphics, mouse, and keyboard support to the application.

· a very simple application skeleton which shows how to call the FFTW simulation code, steer it interactively using the mouse, and do some basic visualization and graphics, using GLUT.

All the code is written in the C programming language. Although it helps if you understand C, you should be able to rewrite the application skeleton to use the FFTW library from the programming language of your choice (e.g. Java, Python)

The provided code is structured in the following main components (files and folders):

· fftw-2.1.3: Contains the sources of the FFTW library

· fluids.c: The application skeleton which calls the FFTW library

· GLUT: Contains the GLUT (GL Utility Toolkit) library

There are some other less important files and folders. These will be described in the building instructions below.

3. Building the code

Let us first assume you have a C compiler installed (e.g. Microsoft Visual C++ Express Edition, or GNU gcc, both which are freely available). To build the application, you have to compile all C files in fftw-2.1.3/fftw, fftw-2.1.3/rfftw, and fluids.c in a single executable, and link with the GLUT/glut32.lib.

If you have the Microsoft Visual C++ compiler, you can compile by simply opening the Smoke.sln solution file and building it – either in debug or release mode.

The following directories contain Visual C++ project-related files:

· FFTW: Contains the project for building the FFTW library

· Smoke: Contains the project for building the complete application

· library: Contains the FFTW static library FFTW.lib that the application is linked against.

The final application, Smoke.exe, is created in the top-level directory. Note that, to run it, you must have the GLUT library glut32.dll in the same location as the executable. This library is provided with the code.

Of course, you can build the code using different C compilers.

4. Running the code

Just run the smoke.exe application. You will get a text window showing some help messages and a graphic window. Select the graphic window. To control the simulation, click and drag the mouse. To change the visualization and/or simulation options, press use the indicated keys in the graphical window. After a bit of experimenting, you should be able to create some images like the ones shown below:

5. The application

The main application is a single file, fluids.c. The structure of this file is described briefly below. See also the comments embedded in the source code. The purpose of these explanations is to help you understanding how you can start modifying the code, to add new visual functionality to it, or how you can start porting the code, if you want to write your assignment in a different programming language than C or C++.

As a general note: Do not worry too much if you do not understand the numerical code. This is not the purpose of the assignment. You can use that code as a simulation ‘black-box’. The purpose is to focus on building new visualization methods atop of that simulation code.

A list of the most important data structures and functions in the program follows. The functions are divided into three groups: simulation, visualization, and interaction. They are listed in inverse order of importance to the program’s functionality.

Global data structures:

· plan_rc, plan_cr: The 2D uniform n*n grid on which the simulation takes place. The actual data type for these structures comes from the FFTW library – you do not have to use these directly.

· fx, fy: The components of the 2D force vectors that drive (steer) the simulation. These are directly controlled by the user via the mouse.

· rho,rho0: The density of the matter which flows in. As the flow direction and speed changes, so does the density. See below.

· vx,vy,vx0,vy0: The components of the 2D velocity field which is simulated. The simulation computes v,rho (velocity and density) out of v0,rho0 (their previous values one time-step ago) and f (the forces).
In a functional notation:

(vx, vy, rho) = do_one_simulation_step(vx0, vy0, rho0, fx, fy)

or in a more mathematical notation (bold denote vectors):

(v (t+Dt), rho(t+Dt)) = do_one_simulation_step(v(t), rho(t), f(t+Dt))

Simulation functions:

· do_one_simulation_step: Does one single step of the fluid flow simulation. This involves passing the mouse-controlled forces to the FFTW library, executing one simulation step to compute the new velocity and density values, and visualizing all these.

This function is called repeatedly to keep on the simulation running forever. This is the first of the two functions calling the FFTW library.

· solve, diffuse_matter: These functions contain the actual numerical simulation code which computes vx, vy, rho out of vx0, vy0, rho0, and fx, fy.

· init_simulation: Initialize the various global data structures as function of the grid size. This is the second of the two functions calling the FFTW library.

Visualization functions:

· visualize: Contains all the visualization code which draws the velocities vx,vy, and the density rho. This is the main visualization function.

· rainbow: Maps a floating-point value to a RGB color using a blue-to-red (rainbow) colormap.

· direction_to_color: Maps a vector’s direction to a RGB color using a directional hue-based colormap.

Interaction functions:

· main: The main program. Prints some help messages and sets up GLUT to perform the display and interaction.

· drag: Called when the user clicks-and-drags the mouse in the visualization window. This sets up the force (fx,fy) and density (rho) at the mouse location, effectively steering the simulation.

· keyboard: Changes the simulation and visualization parameters based on keyboard input.

· display: Draws a new visualization frame, whenever the simulation is ready with producing a new step.

6. Further reading

If you are interested to study the above topics in more depth, there is additional documentation in the fftw-2.1.3 directory on the FFTW library implementation. The overall simulation algorithm is described in the paper “A Simple Fluid Solver based on the FFT” by Jos Stam (Journal of Graphics Tools, volume 6, number 2, 2001, pages 43-52). You can find the paper online e.g. at http://www.dgp.utoronto.ca/people/stam/reality/Research/pub.html or other sites (Google for it).