LINE-SWEEP AMBIENT OBSCURANCE:  REFERENCE IMPLEMENTATION
--------------------------------------------------------

Ville Timonen, 2013, BSD license throughout
http://wili.cc/research/lsao/





CONTENTS:
1)  How to run the example
2)  How to configure the algorithm
3)  Deploying the algorithm in a graphics engine





1  HOW TO RUN THE EXAMPLE

You need a Linux distribution with X, OpenGL, libpng, and OpenCL or CUDA.
You also need a Wavefront object (I suggest you download the Sibenik Cathedral http://graphics.cs.williams.edu/data/meshes/sibenik.zip and link "model.obj" in the program directory against the .obj file found within the zip)

1.1  Go to the source dir: cd lsao-0.2

1.2  Get the model: wget -O/tmp/sibenik.zip http://graphics.cs.williams.edu/data/meshes/sibenik.zip && unzip /tmp/sibenik.zip sibenik.obj && ln -s sibenik.obj model.obj && rm /tmp/sibenik.zip

1.3  Compilation: ./configure && make
The configuration script will search for OpenCL or CUDA, either one should be sufficient.

1.4  Run: ./demo [-kA] [-fB] [-OpenCL] [-gCxD] [-bE] [F]
Where all the parameters are optional:
  A: the number of azimuthal directions used, K (default 24),
  B: the falloff decay rate, r, in the falloff function: p(d) = r/(r + d^2).  (Default 4.0)
  -OpenCL: can be used to enforce OpenCL when also CUDA is supported (default use CUDA, fallback to OpenCL if not supported)
  C, D: width and the height of the framebuffer without guard bands (default C 1280, D 720)
  E: the guard band size relative to the framebuffer size (default 0.1 (10%))
  F: which model file to load (default "model.obj")
Example:
  ./demo -k24 -f8.0 -OpenCL -g1920x1080 -b0.2 sibenik.obj




2  HOW TO CONFIGURE THE ALGORITHM

There's a whole bunch of configuration parameters in SSEOController::genConfig() in sseo.cpp if you want to tweak around.
Not every combination is possible, so be careful.





3  DEPLOYING THE ALGORITHM IN A GRAPHICS ENGINE

There are three ways to make use of the implementation provided here:

3.1  You can use the code as it is (it's BSD licensed) by including it in your engine and using it as shown in demo.cpp.  You pass the OpenGL depth buffer handle and the algorithm gives you the resulting ambient light map.

3.2  You can use this implementation to output kernel code which you then incorporate into your engine.  Just run the program and kernels are written as "sweep.*" and "accumulate.*".  Please note that as code is generated on-the-fly, some configuration parameters are hard-coded:  resolution, guard band sizes, K, falloff function, and thread block sizes to name a few.  See SSEO::init(), SSEOController::SSEOController(), and SSEOController::execute() about how to initialize the kernels and buffers, and how to execute them.

3.3  You can write your own kernels based on the example provided by the automatically generated kernels.  Pretty much same notes apply as in option 3.2.  In case you're not running Linux or are not able to compile or execute the program for some reason, example generated kernels are provided in the "example_kernels" directory.  Also check out the pseudocode algorithms in the paper (http://wili.cc/research/lsao/lsao.pdf).




If you're trying to use this algorithm in a graphics engine I would be happy to hear about it.  And to help, too.
So drop an email:  wili@wili.cc  :-)
