[fluxus] more docs, depth of field effect

[dave]

Hi all,

Some more commits:

* Added (override-frame-callback) which allows you to take control of
the underlying render loop in normal fluxus scripts. See below for an
example of a multipass depth of field effect using this - screenshot
with 50 passes: http://www.pawfal.org/fluxus/images/dof3.jpg

* Doxygen docs for libfluxus - this should help people wanting to hack
fluxus, and also for using libfluxus for applications other than than
via PLT Scheme (eg Haskell bindings)
http://www.pawfal.org/fluxus/docs/libfluxus-0.13/

* Added accumulation buffer interface (see online docs for accum and
clear-accum) but I couldn't test this due to the fact it doesn't seem to
be working with my driver... :(

--->8---
; use multipass rendering to accumulate a depth of field effect.
; I can't get my accumulation buffer to work, so I'm just using a 
; global opacity and rendering into the back buffer directly, 
; which is slow, and a bit artifacty

(define focal-distance -5) ; sets the focal depth
(define num-passes 5) ; number of passes
(define strength 5) ; degrees of rotation

(define (dof-render-callback)
  (define (render-pass n factor)
    ; position the camera for this pass
    (set-camera (mmul 
                 (mmul
                  (mmul
                   (mtranslate (vector 0 0 focal-distance))
                   (mrotate (vmul (vsub 
                                   (vector (flxrnd) 0 0) ; rotate in the
x axis
                                   (vector 0.5 0.5 0.5)) strength)))
                  (mtranslate (vector 0 0 (- focal-distance))))
                 (get-camera-transform)))
    
    (render) ; render the scene 
    (clear-frame 0) ; turn clearing off 
    (if (zero? n)
        0
        (render-pass (- n 1) factor)))
  
  (clear-frame 1) ; clear buffer before the first render
  (flxseed 0) ; seed the rnd gen to use the same rotations each time
  (render-pass (- num-passes 1) (/ 1 num-passes)) ; render passes
  (tick-physics)  ; update everything else
  (update-audio))      

; build some cubes
(define (loop x y)
  (define (line x)
    (push)
    (translate (vector 0 (* 0.6 (sin 
           (* 1.5 (vmag (vsub (vector x y 0) (vector 5 5 0)))))) 0))
    (scale (vector 1 1 1))
    (rotate (vector 0 90 0))
    (build-cube)
    (scale (vector (flxrnd) 1.5 (flxrnd)))
    (build-cube)
    (pop)
    (translate (vector 1 0 0))
    (if (zero? x)
        0
        (line (- x 1))))
  (translate (vector 0 0 1))
  (push)
  (line x)
  (pop)
  (if (zero? y)
      0
      (loop x (- y 1))))

; set up the scene
(clear)
(opacity (/ 1 num-passes))
;(hint-depth-sort)
(clear-colour (vector 0 0 0))
(light-diffuse 0 (vector 0.2 0.2 0.2))
(light-specular 0 (vector 0.4 0.4 0.4))
(define l (make-light "point" "free"))
(light-diffuse l (vector 1 1 1))
(light-specular l (vector 1 1 1))
(light-position l (vector -50 60 50))
(shadow-light l)
(hint-cast-shadow)

(push)
(translate (vector -8 0.5 -9))
(loop 15 15)
(pop)

; use our own frame callback function
(override-frame-callback dof-render-callback)