/*************************************************************************/
/*                                                                       */
/* Licensed Materials - Property of IBM                                  */
/*                                                                       */
/*                                                                       */
/* (C) Copyright IBM Corp. 2009                                          */
/* All Rights Reserved                                                   */
/*                                                                       */
/* US Government Users Restricted Rights - Use, duplication or           */
/* disclosure restricted by GSA ADP Schedule Contract with IBM Corp.     */
/*                                                                       */
/*************************************************************************/

================================================================================
OVERVIEW
================================================================================

   Name: Physical Based Fluid Simulation Sample
   
   This sample was inspired by the Physical based fluid simulation work from 
   Caltech, http://www.multires.caltech.edu/teaching/demos/java/stablefluids.htm
   This sample implements a fluid solver based on the semi-Lagrangian method 
   first introduced by Jos Stam in Stable Fuilds. 
   
   This implementation uses a sparse linear solver that can function
   under arbitrary boundary conditions. 
   
   The sample illustrates how to port a vectorized workload 
   to OpenCL. The sample shows how a program with many specialized
   compute kernels can work effectively in OpenCL, even when these 
   compute kernels need to be serialized. 
           
   Three different versions of the Fluid simulation sample are built for
   for both 32-bit addressing and 64-bit addressing. They are:

   fluid         Fluid simulation sample that computes frames without
                 display. Useful for measuring OpenCL device 
                 computational performance.

   fluid_gl      Fluid simulation sample that displays frames using 
                 the "GL Viewer". The GL Viewer (common/gl_viewer.c)
                 depends on OpenGL and the OpenGL Utility Toolkit 
                 (called GLUT). The display device can be either
                 HW accelerated or software enabled, and either local
                 or remote depending on the system enviroment and X11
                 DISPLAY environment variable setting.

                 If the rasterization is performed by MesaGL on a
                 big endian processor, there is a chance that MesaGL
                 will inadvertantly byte swap the image data. If you
                 find that images are incorrectly colored (initial
                 window is red), then a byte swap correction is required
                 by exporting the "GL_VIEWER_BYTE_SWAP" environment 
                 variable.

   fluid_remote  Fluid simulation sample that displays frames using 
                 the "Remote Viewer" client. The remote viewer is a 
                 separate application that displays image data
                 computed by the server application (fluid_remote).
                 Communications between the client and server is
                 over TCP sockets. More details on the remote 
                 viewer are found in the Remote Viewer's readme
                 (remote_viewer/readme.remote_viewer.txt).

   IBM's CL Utilities (CLU) API is used to simplify the task
   of initializing OpenCL code on the host. 

================================================================================
PREREQUISITES
================================================================================

   IBM OpenCL Dev Kit version 0.3 or later is required to run this sample

================================================================================
HOW TO BUILD 
================================================================================

   To build 32-bit binary, 
   change to the ppc directory in the sample and type "make".

   To build 64-bit binary, 
   change to the ppc64 directory in the sample and type "make".

================================================================================
HOW TO RUN   
================================================================================

   The binary is "fluid" and it will be in the directory where you typed "make".

   To run on the accelerator (Cell SPU):
      ./fluid --accel

   To run on the CPU:
      ./fluid --cpu

   To run with the GL Viewer using the default OpenCL device with verbose output:
      ./fluid_gl -V

   To run with the Remote Viewer with a image size of 768 x 768:
      ./fluid_remote -s 768

   The fluid simulation sample  will terminate after generating the specified 
   "iteration" frames.

   The viewer enabled samples, fluid_gl and fluid_remote, will run indefinitely
   and require user input, via the mouse and keyboard to produce interesting visual
   effects. The input options are:

   Left Mouse Button  - pressing the left mouse button and moving the mouse 
                        results in the insertion of density into the fluid.
   Right Mouse Button - pressing the right mouse button and moving the mouse 
                        results in the insertion of velocity forces into the 
                        fluid.
   "r" key            - resets the simulation and clears the buffers.
   "esc" key          - terminates the program.
      

================================================================================
COMMAND LINE SYNTAX
================================================================================

  Usage: fluid [options...]
  
  Examples:
     fluid --accel -V      # Run simulation on accelerator device with verbose output

   Device Types Options:
     -a, --accel              Use SPU Accelerator device for compute
     -c, --cpu                Use CPU device for compute
     -g, --gpu                Use GPU device for compute

    If a device type is unspecified, then the platform's CL_DEVICE_TYPE_DEFAULT 
    is used.

   Run Options:
     -m, --awgc               Run the version of the kernel that uses async 
                              work-group copy (default: no)
     -s, --size N             Specifies the window size (width and height) of the 
                              simulation (default: 512)
     -n, --numframes N        Number of frames to simulate (default: 100). 
     -p, --profiling          Enable CLU kernel profiling (default: off).
     -v, --verify             Verify the results with computations on the host 
                              (default: off). Forces the  number of frames to 2.
     -V, --verbose            Enable verbose output.

   The numframes, profiling, and verify options are only available in the "fluid"
   version.

================================================================================
END OF TEXT
================================================================================
