Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


                                      Titan Terrorfish Tank
                                          David Sansome

A fishtank containing three Titan Terrorfish from Stingray.

 * HDR overbrightening
 * Stencil shadow volumes
 * Underwater wobble effect
 * Underwater lighting caustics
 * Planar reflections
 * Water surface normal perturbations

= Keyboard controls        =

Standard keyboard controls:
Q or Esc          Quit
P                 Moves to the castle
T                 Starts the tour
E                 Exits tour or FishCam modes
Left, Right       Turn
Up, Down          Change speed
Space             Stops motion
R                 Resets animation

Extra keyboard controls:
Page Up/Down      Raise/Lower the camera's elevation
F                 FishCam (press again to cycle through fish and exit)
U                 Toggles scene post-processing (affects performance at high resolutions)
I                 Toggles wireframe mode
V                 Toggles shadow volume drawing
[, ]              Decreases/increases the amount of blur used in post-processing.

Alternate controls:
W, S, A, D        Move
O, K              Look up/down

= Files                    =

Note: - Associated C++ or Objective-C implementation files are not listed
      - Some of these files are copied or renamed to create the release .zip

Filename                             Description
---------------------------------    ------------------------------------------------------------
./bezier.h                           Class to calculate Bezier curves
./castle.h                           Render object for the castle in the fish tank
./engine.h                           Main class containing rendering and control logic
./fish.h                             Render object for fish
./main.cpp                           Entry point
./model.h                            Class for loading .mdl files generated by
./outside.h                          Render object for the wooden table
./sdlglwindow.h                      Abstract base class for using GL with SDL.  Reused from CW1
./SDLMain.h                          Objective-C required for compilation in Xcode on Mac OS X
./seaweed.h                          Render object for the seaweed
./shader.h                           Class for loading and binding shaders
./solidobject.h                      Abstract interface for collision detection
./starfish.h                         Render object for the starfish
./tankwalls.h                        Render object for the tank's glass walls
./terrain.h                          Render object for the terrain
./texture.h                          Class for loading and binding textures
./timedependentvariable.h            Class that moves a variable slowly towards a target value
                                     over time.  Used for camera movement.
./utilities.h                        General utility functions
./waterstuff.h                       Render object for the floating muck in the water.
./watersurface.h                     Render object for the water's surface.
./models/castle.blend                Blender source for the castle
./models/castle.mdl                  Exported castle model
./models/          Python script to export models from blender to a custom
                                     binary format suitable for loading by the Model class
./models/seaweed.blend               Blender source for the seaweed
./models/seaweed.mdl                 Exported seaweed model
./models/starfish.blend              Blender source for the starfish
./models/starfish.mdl                Exported starfish model
./models/terrorfish.blend            Blender source for the terrorfish
./models/terrorfish.mdl              Exported terrorfish model
./shaders/castle_*.glsl              Textures and lights castle
./shaders/fish_*.glsl                Animates and lights the fish.  Makes fish more blue as they
                                     move further from the viewer.
./shaders/pp_*.glsl                  Applies post-processing effects - including the underwater
                                     wobble and HDR lighting.
./shaders/seaweed_*.glsl             Textures the seaweed
./shaders/shadowvol_*.glsl           Extrudes shadow volumes from degenerate edge quads
./shaders/starfish_*.glsl            Animates and textures the starfish
./shaders/table_*.glsl               Lights the table
./shaders/tank_*.glsl                Colors the walls of the fishtank.  Walls get more blue the
                                     further they are from the viewer.
./shaders/terrain_*.glsl             Textures and lights the terrain.  Applies caustic lighting
./shaders/terrainr_*.glsl            Textures the terrain as reflected in the glass.
./shaders/waterstuff_*.glsl          Animates the little blobs of light floating in the water.
./shaders/watersurface_*.glsl        Lights the water's surface.
./textures/brick.jpg                 Red brick texture used on the roof of the castle
./textures/caust*.jpg                Caustic lighting used on the terrain
./textures/darkstone.jpg             Dark stone texture used on the castle
./textures/glow.jpg                  White light circle used by the floating stuff in the water
./textures/help.jpg                  Help screen that is displayed when pressing 'h'
./textures/lightstone.jpg            Light stone texture used on the castle
./textures/moss.jpg                  Green terrain texture
./textures/noise.jpg                 Multichannel noise used by post-processing shader
./textures/sand.jpg                  Yellow terrain texture
./textures/seaweed.jpg               Seaweed texture
./textures/starfish.jpg              Starfish texture
./textures/wood.jpg                  Texture for the wooden table

= Build instructions       =

Required libraries:
 * OpenGL
 * SDL
 * SDL_image
 * SVL

CMake is the preferred way to build the application on all platforms:
   cd bin
   cmake ..

Otherwise, g++ can be used to compile and link the .cpp files individually.

Visual C++ has an unusual interpretation of standard C++ and does not compile this
source - use MSYS and MinGW on Windows instead.
Compiling SDLMain.m is only required on Mac OS X.

= How it works             =

The terrain is generated randomly at the beginning of the program - restart to get a new terrain.
Fish's tails are animated with a sin(t) * x^2 function (see fish_vert.glsl).
Fish follow cubic bezier curves.  This used to be computed in the vertex program, but it turned out to
be more efficient to calculate on the CPU per frame instead of on the GPU per vertex.
The tour also follows cubic bezier curves.
The terrain is reflected in the glass by drawing the edges of the terrain again, mirrored about the
glass plane.  The stencil buffer is used to clip each reflection to its glass pane.
Caustic lighting effects are applied to the seabed in some places by cycling through a set of 32 textures
and blending them with the moss/sand color in the fragment program.
Shadows work by extruding shadow volumes from the fish and darkening any pixels inside these volumes.

Rendering is multi-pass:
 1) The scene is drawn as normal
    Color buffer is copied to a texture and used later in 2c
 2) Post-processing passes are run on textured screen-aligned quads covering the entire viewport.
     2a) A glow texture is created by raising color values to a power.  This makes dark pixels darker
         and bright pixels brighter.
     2b) The glow texture is blurred a number of times.
     2c) The glow texture is added to the original color resulting in an overbright HDR-like effect
         in bright portions of the scene.  The texture coordinates are also wobbled slightly using a
         noise texture and sin functions.

= Performance              =

The GPU used for testing was an NVIDIA Quadro FX 570M with 512MB Memory.
With the FPS limiter disabled (comment lines 112 and 113 of sdlglwindow.cpp), 177 FPS was acheived
at the default resolution of 800x600.

The program is fill-rate limited, largely due to the post-processing shader.  Switching off
post-processing increases the framerate to 430 FPS.

= Acknowledgements         =

* Some ideas and code has been reused from Baarbarity, one of my previous graphics projects.
  Baarbarity is GPL and its SVN repository is hosted at:

* Blender was used to generate all the models

* Moss, sand, stone, brick and wood textures came from OddOneDude.  Terms of use state
  "You are free to use OneOddDude images and textures in your personal, non-commercial

* Caustic lighting textures were taken from Mark Kilgard's tutorial:

* Starfish texture was licensed from iStockPhotos:

* Terrain generation tutorial:

* "The Theory of Stencil Shadow Volumes":

* Ideas for some of the rendering techniques came from the following books:
   - The Cg Tutorial - NVIDIA
   - GPU Gems 2 - NVIDIA
   - GPU Gems 3 - NVIDIA

* Thanks to John Maguire (jbm305) for letting me test on his Macbook