fluxus documentation
copyleft (C) 2003 pawfal entertainment PLC

user guide
concepts
	renderstate
	immediate/retained mode
	scenegraph
fluxus script
	primitives
	renderstate operations
	audio
	lifeforms
	flx file streaming
	fluxface
	physics
	general

--------- user guide ---------

simply type, paste or load scripts into the green script editor window, select 
some or all of the script and press f5 to execute. the interpreter remains 
active throughout, so functions and variables can be manually changed by 
re-executing them during rendering.

--------- concepts ---------
renderstate

like opengl, fluxus is a state machine which has a renderstate you can modify to describe
objects created later. for example:

(colour (vector 1 0 0))
(draw_cube)
(colour (vector 0 1 0))
(draw_cube)

will draw a red cube, then a green cube
states can also be stacked, for example:

(colour (vector 1 0 0))
(push)
	(colour (vector 0 1 0))
	(draw_cube)
(pop)
(draw_cube)

will draw a green, then a red cube

immediate/retained mode

both examples so far have used what is known as immediate mode, you have one state stack, the 
top of which is the current context, and everything is drawn once per frame. fluxus contains 
a structure known as a scenegraph for storing objects and their render states.

scenegraph

time for another example:

(colour (vector 1 0 0))
(build_cube)
(colour (vector 0 1 0))
(build_cube)

the only difference between this and the first example is the use of (build_cube) instead of 
(draw_cube). the build functions create a primitive object, copy the current renderstate and 
add the information into the scenegraph in a container called a scenenode.

the (build_*) functions return object ID's (just numbers really) which enable you to do things
to the scene node after it's been created. you can now specify objects like this:

(define myob (build_cube))

the cube will now be persistant in the scene until destroyed with

(destroy myob)

if you want to modify a objects renderstate after it's been loaded into the scenegraph, you 
can use the grab function to temporarially set the current context to that of the object. use
ungrab to turn fluxus back into normal state stack mode. this allows you to animate objects 
stored in the scenegraph, for instance:

(colour (vector 1 1 1))
(define obj1 (build_cube))
(push)
	(translate (vector 2 0 0))
	(define obj2 (build_cube))
(pop)

--->8---

; in a function called per frame

(grab obj1)
(rotate (vector 0 1 0))
(ungrab)

(grab obj2)
(rotate (vector 0 0 1))
(ungrab)

if you call push or pop while an object is grabbed, it will still effect the state stack - 
it's probably a bad idea to do this.

the scenegraph also enables you to parent objects to one another, using the renderstate's 
parent setting. this is only effective before an object is loaded into the scenegraph, setting
it afterwards via a grabbed state will be ignored:

(colour (vector 1 1 1))
(define a (build_cube))

(push)
	(parent a)
	(translate (vector 0 2 0))
	(define b (build_cube))
(pop)

(push)
	(parent b)
	(translate (vector 0 2 0))
	(define c (build_cube))
(pop)

creates three cubes, all attached to each other in a chain. transforms for object a will be 
passed down to b and c, transforms on b will effect c blah.

destroying a object in such a heirachy will in turn destroy all child objects parented to it.

------- giving up control of objects --------

sometimes you will want to hand over control of an object to a procedural system within 
fluxus, (the physics and lifeforms are the only ones at the moment).
objects have to be in the scenegraph for this to be possible, and modifications to the objects
transform by grabbing it's state will not have any effect (I think). you may still change any 
the state other than the tranform though.

-------- fluxus script ---------------

this is an exhausive list of all the functionality within fluxus

-------- primitives --------

(build_cube)
(build_plane)
(build_cylinder)
(build_sphere)
creates a geometry in the current render context, adds it to the scenegraph and returns the 
object ID

(draw_cube)
(draw_plane)
(draw_cylinder)
(draw_sphere)
draws a cube in immediate mode to the current frame

(destroy object)
removes the object from the scenegraph

--------- renderstate operations ---------

(push)
(pop)
pushes and pops items off the state stack. push duplicates the current stack top

(grab object)
(ungrab)
grabs the object's state and puts it in the current context so that all state 
modification calls (translate, rotate, colour etc) effect the specified object 
rather than the state stack. ungrab turns the state modification back on.

(print_scene_graph)
dumps the scene graph to stderr, for debugging purposes

(apply object)
applies the tranformation stored in the object's scene graph node directly to the 
vertices of the geometry, and sets the transform to identity.

(translate transvec)
(scale scalevec)
(rotate rotvec)
(colour colvec)
(opacity a)
(specular colvec)
(ambient colvec)
(emissive colvec)
(shinyness pow)
(texture textureID)
modify the current state.

(hint_solid)
(hint_wire)
(hint_normal)
(hint_points)
(hint_anti_alias)
sets the render hint flags for the current state

(hint_none)
clears the render hint flags for the current state
	
(parent object)
sets the parent flag in the state stack, so all subsequent objects in this state 
are parented to object.	

-------- audio ----------
to see the fft levels window, use ctrl-f

(gain value)
sets the gain level for the fft sound, usually quite small - 0.025 by default.
	
(gh harmonic)
returns the contribution of the harmonic specified. the return value is normalised 
between 0 and 1.

------- lifeforms ------
lifeforms are an easy way to create flocking systems using classic alife algorithms

(make_lifeforms name)
makes a new lifeforms alife system

(lifeform_avoidance name value)
(lifeform_flockcentering name value)
(lifeform_scenecentering name value)
(lifeform_inertia name value)
(lifeform_scenecentre name value)
(lifeform_maxspeed name value)
sets global behaviour paramters for a lifeforms system

(add_lifeform name object)
gives control of the object to the named lifeforms system - uses the current transform in the 
objects state to place the lifeform. parented objects should be moved too.

------- flx functions ------
flx files are binary representations of the entire render state and scenegraph, they can be 
played back later by running fluxus with an flx filename argument.

(save_frame filename)
dump a single frame to a flx file

(start_flx filename)
start streaming continuous frames to an flx file

(end_flx)
stop streaming

------- fluxface functions ------
fluxface is a simple gui for executing bits of script on a keypress. use ctrl-i in the 
render window to show the fluxface window

(clear_fluxface)
removes all buttons

(fluxface executetext x y)
add a new button

---------- physics -------------
the physics system, based on the ode library

(active_box object)
(active_sphere object)
(active_cylinder object)
give the object to the physics system calculating and using a box/sphere/cylinder 
as the bounding volume. as an active object, it will now be transformed by ode.

(passive_box object)
(passive_sphere object)
(passive_cylinder object)
give the object to the physics system calculating and using a box/sphere/cylinder 
as the bounding volume. as a passive object, active objects will collide with it.

(ground_plane planevec planeoffset)
create an infinite passive plane for use as the ground

(build_hinge2joint object1 object2 anchorvec hinge1vec hinge2vec)
(build_balljoint object1 object2 anchorvec)
builds hinges between two objects

(joint_vel2 joint value)
(joint_fmax2 joint value)
(joint_fmax joint value)
(joint_histop joint value)
(joint_lostop joint value)
(joint_vel joint value)
(joint_fudge joint value)
sets the joint paramater for joint - see the ode docs for more information
	
(kick object kickvec)
applies translation force kickvec to the object

(twist object twistvec)
applies rotational force twistvec to the object
	
(set_max_physical num)
sets the maximum number of objects the physics system can deal with. when the max level
has been reached the oldest objects are destroyed.

-------- general functions ----------

(clear)
clears the scene graph of all objects and empties the state stack

(ortho)
(persp)
sets the projection type

(load filename)
loads a script into the editor, better than the fileselector - as it doesn't stop the renderer

(key_pressed keystr)
returns true if key has been pressed

(lock_camera object)
locks the camera to the object, not currently working...
	
(load_texture filename)
loads the texture and returns the ID

(engine_callback execute_text)
sets the engine callback script, this will be called once a frame in the engine loop. usually 
a function call, so you can easily change the function.

(show_axis bool)
turns the origin axis display on or off

(random)
returns a random float between 0 and 1

(frame)
returns the frame number

(reset_camera)
resets the camera matrix in case you get lost

(blur amount)
turns hackish motion blur on, just renders a transparent poly over the frame rather
than clearing. the transparency is set by amount, setting amount to 0 turns this 
feature off. 

(clear_colour colvec)
set the background clear colour

(clear_frame 0/1)
enables/disables clearing