caffeineviking / cnpf

Curl-Noise Particle Flow using OpenCL

Curl Noise Particle Flow

Based on the Curl-Noise for Procedural Fluid Flow by Bridson et al. from 2007, we designed an implemented an application which enables the simulation and visualization of particles in real-time by calculating each curl-noise iteration purely on the GPU by using OpenCL kernels. We did this by generating a 3-D Simplex noise, and converted it to a vector field by finding the gradient in each point in space. Afterwards, we apply the curl operator on the vector field, which provides a divergence-free vector field (and no particles will therefore get stuck together at any point in space). With this, we can in each step, for every particle, calculate the new position of the particle by assuming a point in the curl-field is the velocity (e.g. in a fluid) of a particle in that position. Since we apply these steps on the GPU by using OpenCL (for the simulation) and OpenGL (for the visualization), and share the buffer state by OpenCL-OpenGL buffer interoperability, we never leave GPU-space, and can therefore do this in real-time, even when rendering a huge number of particle billboards.

You can find our very short article describing this technique over here: Fluid Animation in Real-Time using 3-D Curl-Noise

Dependencies

For windows:

• Download and place premake5 in your path.
• Install MinGW with everything except ADA and Fortan under C:\MinGW (should be default location).
• Download GLM and place the glm folder with all includes into C:\MinGW\include.
• Fetch the latest OpenCL headers and find your runtimes (usually the drivers).
• Download the pre-compiled GLFW binaries.
  • Copy the include directory into C:\MinGW\include.
  • Copy the content of lib-mingw into C:\MinGW\lib except the glfw3.dllwhich you will place under the bin folder for this repo.
• Download the source for GLEW and copy the compile_glew.bat from the misc folder provided with this repo to the root of the glew source folder.
  • Run the bat and copy the libraries from lib into C:\MinGW\lib. Copy the glew32.dll into the C:\Windows folder.
• Download CUDA for Nvidia devices.
• Copy content of C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v8.0\lib\Win32 to C:\MinGW\lib.
• Copy C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v8.0\include\CL to to C:\MinGW\include.

If you encounter a run-time error about some basic_string funcitonallity, it's caused by the wrong libstdc++-6.dll is first in the path. The easiest solution is to copy it from C:\MinGW\bin to C:\Windows, or to the folder where the binaries are run from.

For linux or bsd (maybe macos):

• Using your favorite package manager, install:
  • GLFW with development packages.
  • GLEW with development packages.
  • Maybe OpenCL hardware runtimes.
  • Oh yea, the OpenCL headers too.
  • The standard MESA schenanigans.
  • AntTweakBar by building source.
  • The Premake5 build system.
• If it doesn't work, ask Erik!!

Building

1. Make sure library dependencies are in your path.
2. Place yourself in the root directory of this project.
3. Acquire the latest version of the premake5 build system (add it to your PATH in windows).
4. Thereafter, execute premake5 gmake if building on Make.
5. Finally, issue the command make -C build and wait.
6. When complete, either bin or lib are built.
7. Tests can be run with bin/*-tests program.
8. Shortcuts: make run and make test.

Contributing

1. See if there any updates upstream: git remote update
2. If you are already working on a feature branch, jump to step 4.
3. Create a new branch for your feature: git branch <feature>
4. Change to the feature branch by: git checkout <feature>
5. Start/continue building the feature. Jump to 7 if done.
6. Push your changes to your remote feature branch with:
   • git add -A (everything) or git add -u (updates).
   • git commit -m "Message describing the additions."
   • Publish remotely: git push origin <feature>
   • Go back to step 1 or 5 (if working quickly).
7. Your feature is done (single/many commits).
8. Fetch the changes from upstream first:
   • Go to master: git checkout -b master
   • Pull changes: git pull origin master
9. Rebase your changes on top of master:
   • Back to feature: git checkout <feature>
   • Thereafter, issue: git rebase master
   • Fix any conflicts that may happen...
   • Changes now on top of the Git tree.
10. Finally, go to GitHub and issue PR.
    • Listen in on other's feedback!
    • Make changes if necessary.
11. Back to the master: git checkout master
12. Pat yourself on the back, then goto 1 again.

Structure

• assets: contains all resources required at runtime (shaders, textures,...).
• bin: contains the built software and accompanying testing suite.
• build: stores intermediate object files and generated GNU Make files.
  • obj: has all of the generated object files given under compilation.
  • Makefile: automatically generated by executing premake5 gmake.
  • *.make: program specific make config for augmenting Makefile.
• docs: any generated documentation for this project is over here.
• include: both external and internal project headers are here.
  • foreign: any foreign headers which should be included.
  • project directories: internal headers for the project.
• lib: any generated libraries from the project reside here.
• license.md: please look through this very carefully.
• premake5.lua: configuration file for the build system.
• readme.md: this file, contains information on the project.
• share: any extra data that needs to be bundled should be here.
• src: all source code for the project should be located below here.
  • project directories: source code for specific project build.
  • foreign: any external source files which might be needed.
• tests: source code for the project's testing suite, using Catch syntax.
  • project directories: project specific testing suite for one build.

cnpf's Issues

Particles doesn't follow background field perfectly

When not mixing background field with noise the particles doesn't follow the field correctly. It still respects boundaries but seems to be slightly offset in relation to the direction of the background field. It is probably caused either by the curl implementation in the OpenCL kernel or by the camera implementation.

Preprocessing of vector fields

Since we aren't using hardware acceleration for the construction of the vector fields we probably have to fetch them from preprocessed images if we want live demo.

Curl-Noise "Black Hole" Behaviour

When attempting to apply velocities to the particles in respect to the generated curl-noise we get these "black holes", where all particles seem to converge to a singular point around them. Martin has fixed the issue with the "particle lines" that seemed to happened before, now only this issue remains.

We need to figure our what's the source of the problem. Rasmus has created a Processing demo of the particle simulation using curl-noise, and seems to be getting the correct behaviour. My suggestion is that we analyze both the curl-noise implementation and the particle system implementation of his demo and try to see if there are any discrepancies in the results we get (alternatively we can see what other people seem to be getting by applying curl to the simplex noise). In particular, I suggest we do the following: we generate the curl-noise in the Processing application, since we know that it produces a valid curl vector field, write it to an image, and load it in our C++ implementation. If the particles behave better, then we need to look into where our C++ curl-noise implementation differs from the Processing one and fix it, or, if the behaviour is still wrong in our C++ implementation, despite having the correct curl vector field, then in the particle system we must have missed something or made some erronous assumption about the field.

It would be nice if we could get some images of the problems here so we can discuss it better, I still have problems with my open-source drivers which I'll try to fix in the weekend (alternatively, I'll implement a software backend for the particle simulation). We should discuss this problem, and see if anyone can find a solution or motivation why we get these weird particle "black holes" (alt. motivate why they are correct).

Timer for particles

I think we need a timer for the particles. Probably implemented as a cl::Buffer with a float for each particle. Each frame we call a kernel which checks if the value for a given particle is below 0 and re-randomize the position of the particle.

Non-Accelerated Particle Simulation

For easier project building and better support/portability, we should also implement a software back-end for the particle simulation. Since the OpenCL kernel isn't especially complicated, it shouldn't be very hard to implement it (but might be hard to make they work alongside each other). I'll try to implement this in a weekend, by providing a build flag telling what back-end we should use (i.e. DISABLE_OPENCL) and also an extra flag telling (if OpenCL is enabled) which hardware accelerator should be used (i.e. CLDEVICE).