fishpye
-------

A non-recursive voxel-based real-time raytracer in Python, OpenCL and OpenGL,
with support for fish-eye/panoramic field-of-views.

Currently tested on a beefy NVIDIA GTX 570. Lesser cards may suffer.

Controls:
   * WASD to move around
   * Mouse to control camera
   * P to toggle physics
   * Space to jump / cling to ceiling immediately above you
   * N to go down (with physics off)
   * O to change field of view

Dependencies:
   * Definitely needed:
      * python
      * python-opengl
      * python-pyopencl
      * Your graphics card's OpenCL drivers (see vendor's website)
   * Currently tested with:
      * Ubuntu 11.04
      * python2.7
      * NVIDIA CUDA/OpenCL drivers

Command-Line Options:
   * --unlimited
      * Raises framerate limit from 50fps to 1000fps.

License:
   * BSD-3 (see LICENSE file)

Technical Notes:
   * Lighting:
      * Ambient lighting depends on the face of the block being viewed.
        Top surfaces get lit, bottom surfaces get darkened.
      * "Diffuse" lighting treats the camera as the light source. The
        amount lit/darkened by depends on the relative angle of the ray
        and the surface. It also falls away as 1/t instead of 1/t^2 to
        make it easier to discern the edge of a surface when it's in
        front of a parallel surface of the same color.
   * Portals
      * Each is defined by its own portal block types deployed in the map
        grid and a matrix that defines its scaling, rotating, reflecting,
        translating effects.
      * _Have volume_ (and so work differently from in Valve's Portal).
      * May be approached from any face, and all faces act as portals.
      * When crossing a portal face, the ray/physics object is first
        translated to the opposite face, and _then_ transformed by the
        portal's matrix. This has the effect of looking into a portal always
        looking out of the exit portal (in the case of two linked portals),
        and is necessary because portals are 3-dimensional.

TODO:
   * Gravity / physics
      * Possibly hit-detection with volumes instead of line-segments?
      * walking through portals
         * reflecting player character
   * Self-viewing / entity rendering
   * Make into a game

Handy links:
   * OpenCL 1.1 Reference
       http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/
   * PyOpenCL Documentation
       http://documen.tician.de/pyopencl/runtime.html
   * OpenGL 2.1 Reference Pages
       http://www.opengl.org/sdk/docs/man/
   * Voxel Traversal Algorithm - J Amanatides and A Woo
       http://www.cs.yorku.ca/~amana/research/grid.pdf

Youtube videos:
   * http://youtu.be/krL_vPRofAI
   * http://youtu.be/TBL7Y7_kCjA
   * http://youtu.be/accWhQRYBnA