Sunflow Global Illumination Rendering System 
v0.02.2

Contact: Christopher Kulla
         fpsunflower@users.sourceforge.net
         http://sunflow.sourceforge.net/

----------------------------------------------------------------

Sunflow is a rendering system for photo-realistic image synthesis. It is
written in Java and built around a flexible ray tracing core and an
extensible object-oriented design.

Please consult the LICENSE file for license information.

----------------------------------------------------------------

Build instructions:

Start by downloading the latest JDSK (1.4.2 at the time of this writing) from
Sun, http://java.sun.com/

Create a new directory and unzip the contents of the source
package into it, preserving sub-directories. Create the classes subdirectory
if your unzip program did not.

You may now compile the software by entering:
  javac -sourcepath src -d classes -g:none -O src\SunflowGUI.java
once the compiling is complete, run the code with:
  java -Xmx256M -cp classes SunflowGUI <filename.sc>

You will need to have some sample scenes to be able to render any pictures.

----------------------------------------------------------------

Scene file format:

Here is a brief description of the current scene format. Please note that everything
here is temporary, the final scene format will be more likely to be connected to some
scripting language to allow procedural scene creation. Very little error checking
is done, so don't be surprised if you see exceptions getting thrown on invalid
scenefiles.

* Image block ****************

image {
  aa min max threshold   % min/max number of samples to take for anti-aliasing
                         % threshold is the variance threshold used to determine
                         % if more samples are needed
  show-aa true/false     % if this is true, you will get an additional output file
                         % prefixed with "AA-samples" showing a greyscale of how many
                         % samples were taken at each pixel
  output filename.{png|hdr} % output filename either PNG or HDR, if the extension is left out
                            % the default is .hdr I recommend HDRShop to view these files.
}

* Light server block ****************

lightserver {
  shadows true/false   % enables/disables shadows in the direct illumination computation
  direct-samples n     % n is the number of samples to take for the direct illumination
                       % calculation note that this number is _per ray_ so the actual
                       % number of samples/pixels depends on the anti-aliasing parameters
                       % as well. 8 is a good start for scenes with area lights, 1 is
                       % sufficient if the scene only has a single point or directional source
  max-depth depth      % maximum raytracing recursion depth, 9 is a good default
  gi true/false numphotons numgather irrthreshold irrspacing irrsamples
                       % enables/disables the indirect-diffuse calculation
                       % numphotons is the maximum number of photons used for the global
                       % and caustic photon map
                       % numgather is the number of photons to gather for both the global
                       % and caustic photon map
                       % irrthreshold is the threshold to use for irradiance caching.
                       % 0.2 is a good default
                       % irrspacing is the minimum spacing between samples. Lower this value
                       % to get rid of artifacts around edges
                       % irrsamples is the number of samples to take. the actual number will
                       % be adjusted to get M*N samples where N=Pi*M
  caustics true/false ratio % enables/disables caustics. the ratio parameter is used to increase the relative
                            % size of the caustic photon map without increasing the size of the global photon map
                            % this should be a value between 0 and 1. It is only used when tracing both
                            % global and caustic photons.
}

* Camera block ****************

camera {
  type pinhole      % the pinhole camera is the only currently available type
  eye x y z         % x y z coordinates of the viewer
  target x y z      % x y z coordinates of the point the viewer is looking at
  up x y z          % x y z coordinates of the upwards direction
  fov angle         % field of view in degrees
  resolution width height % width and height of the image plane in pixels, this is used to set
                          % the size of the output image
}

* Shader blocks ****************

shader {
  name string    % name to bind to the shader
  type diffuse   % diffuse shader type
  diff r g b     % r g b value of the diffuse reflectance (all should be between 0 and 1)
}

shader {
  name string    % name to bind to the shader
  type diffuse   % diffuse shader type
  texture filename % file to use as a texture. jpg, png and gif are supported
}

shader {
  name string    % name to bind to the shader
  type mirror    % mirror shader type
  refl r g b     % r g b value of the reflectance (all should be between 0 and 1)
}

shader {
  name string    % name to bind to the shader
  type glass     % glass shader type
  ior ior        % ior is the relative index of refraction (n_in / n_out)
                 % this is about 1.5-1.7 for glass or 1.333 for water
  color r g b    % r g b value of the reflectance (all should be between 0 and 1)
}

* Light source blocks ****************

light {
  type point     % point light source
  power r g b    % RGB power of the point light source, this is typically quite large because
                 % of the square falloff
  p x y z        % location of the point source
}

light {
  type directional % directional spotlight
  source x y z     % center of the spotlight
  target x y z     % point in the direction of which light is emitted, note that light doesn't
                   % stop at the target
  radius 16        % defines the illumination cylinder around the source - target axis
  emit r g b       % emitted radiance, the total power of the light is a function of the radius
}

light {
  type mesh        % mesh light source (several triangle lights)
  name meshname    % name of the mesh (unused)
  emit 15 15 15    % emitted radiance, total power depends on the area of the surface
  nverts ntris     % number of vertices and triangles
  v x y z nx ny nz u v % (x, y, z) point, (nx, ny, nz) normal vector (ignored), (u, v) texture mapping (ignored)
  . ...                % this format is used for consistency with the object block
  . ...                % making it easy to switch an object between a reflector and a light
  . ...  
  t v0 v1 v2       % v0, v1, v2 are the vertex indices that define the triangle
  . ...
  . ...
}

* Object blocks ****************

object {
  shader name    % shader to bind to this surface (must appear before in the scenefile)
  type sphere    % sphere object type
  c x y z        % center coordinates
  r radius       % radius of the sphere
}

object {
  shader name      % shader to bind to this surface (must appear before in the scenefile)
  type mesh/flat-mesh    % smooth/flat triangle mesh (the flat-mesh type ignores vertex normals)
  name meshname    % name of the mesh (unused)
  nverts ntris     % number of vertices and triangles
  v x y z nx ny nz u v % (x, y, z) point, (nx, ny, nz) normal vector, (u, v) texture mapping
  . ...
  . ...
  . ...
  t v0 v1 v2       % v0, v1, v2 are the vertex indices that define the triangle
  . ...
  . ...
}

object {
  shader name     % shader to bind to this surface (must appear before in the scenefile)
  type plane      % infinite plane
  v x y z         % coordinates of a point on the plane
  n x y z         % normal vector to the plane
}

----------------------------------------------------------------
