+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
++                         XAERO README       				 ++
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

REQUIREMENTS:
-------------

For compilations you need to have:

     X11-libraries (best: Release 5 or newer)
     Athena-Widget-Set:
          Command       -   Widget
          Form          
          AsciiText
          AsciiSink
          Dialog
          Repeater
          Scrollbar
          Paned
          Toggle
          Viewport
          MenuButton
          SimpleMenu
          SmeBSB
          SmeLine
          Box
          Label
     gcc (Version greater 2.3.3)
     ld or gld

To render the written raytracer files, POVRAY1.0 or newer should be
used. The included script files for automatic generation of readable
picture files out of the raytracer files need the "tgatoppm" command
out of the PBM+ distribution. A special text file called
README.raytracer explains how to use AERO's raytracing feature.



USING THE SIMULATOR WITHOUT THE GRAPHICS INTERFACE:
--------------------------------------------------- 

Due to the popular demand, here came some hints to use the simulator
without the X-Windows system to include them in own applications.

The simulator is designed as library. This simulator computes the
world from a single timepoint (state) to a following timepoint. The
german name is "FolgeSchrittBerechnung", so the library generated by
the Makefile is named "fsblib.a". In this library you find all
necessary routines. Sorry for the german identifiers, remarks and
filenames.

It follows now a table of all modules included in the FSB library and
their aim:

ausgabe.h			- simple output routines
beruehrung.h			- compute the forces of touching objects
bewegungsgleichungen.h		- equations of motion
fehler.h			- error handling 
folgeschrittberechnung.h	- main module with the simulator
gleichungsloeser.h		- lineare equation solver
integration.h			- integrator modul
io.h				- read/write state, configuration and materials
koerper.h			- body initalistation/definition 
kollision.h			- collision detection routines
kollisionsbehandlung.h		- collision response routines
konfig.h			- configuration of the simulator
kraft.h				- routines to add external forces to bodies
materialien.h			- material definitions
rev.c				- revision
stoss.h				- routines for solving the impact of bodies
vektor.h			- usefull macros and routines for vector operations

Look at the headerfiles(.h) for an spezification of the single
routines.

There is also two "simple" programs which use the FSB library. Look
into the file example1.c and example2.c for the usage of the main
routines of the library.

You can create and check the examples simply with:

    > make examples
    > examples1
    > examples2

These two examples do the same: They show the horizontal and vertical
position or a sphere which is falling to the ground plus drifting to the
right cause of a force. But Example 2 use the ReadZustand(..) function
to load the world from the file "bsp.state".

Now an prototype for the usage of the main simulation routines defined
in folgeschrittberechnung.h:
---------------------------------------------------------------------------
#include <folgeschrittberechnung.h>

simulate_your_world()
{
	TZustand mystate;

	/* generate a correct initialized state and material table!
         * see koerper.h, materials.h (or io.c as an example)!
         * Note: use KoeInitMech(body, materialtable) for initializing a body!
         */

	InitFBB(mystate);

        ErfrageFBB(myconfig);
	/* change configuration to your demands 
	 */
	KonfigFBB(mystate);

	/* State at starttime (0.0 normally)
	 */	
	FolgeBildBerechnung(mystate, 0.1);

	while (forever) {
	   /* state after 0.1 seconds.
	    * print/display/change the state at your own!
	    */
	
	    /* for speedup, 
	     * don`t use after an change of the state!
             */
	    UngeaendertFBB(mystate);	

	    /* compute next state
	     */		
	    FolgeBildBerechnung(mystate, 0.1);
	}

	EndFBB(mystate);
}	
---------------------------------------------------------------------------



SCRIPTS:
--------

This release include four script files in the "scripts" directory to
convert the rayracer output of XAero into a readably image-format
(PPM). To save space it compress the images with the unix "compress"
command. Most Image-Viewers (XV, ImageMagicks`s display,...) displays
this compressed pictures. It's also necessary to install the
POVraytracer and the pov-includefiles of this distribution. Also copy
the scripts into a directory within your path. PBM+ should also be
installed, the "tgatoppm" command is needed to convert the povray-output
into PPM.

Short description of the script-files:

raystart - Starts the transformation of all *.pov (raytracer source) files
	   in a specific directory into *.ppm.Z (compressed pictures).
           It possible to specify more than one computer at which the
           transformation process(the raymany script!) is invoked by a
	   remote shell call.
           
raymany  - Transforms on one machine all *.pov files via "povray" and 
 	   "tgatoppm" into *.ppm.Z pictures.
           (not necessary to invoke by hand!)

rayclear - clean up after an unsuccessful transformation process.
           (p.e.: some temporare tga-images (generated by povray) are not
                  transformed to ppm!)
           Also kills all scripts started on remote machines from the
           "raystart" command.

raystat  - shows statistic information of the progress of the transformation
           process.

All four scripts have an help-text, reachable via the -h option. Read them 
for further explanations.

Now an example session to transform the directory video/pendel which is
full of *.pov files(generated by XAero), into rendered image files.

To start the transformation process on four remote machine with the same
directory layout type the following in you shell:

    salvador:[~] raystart -name video/pendel -width 320 -height 160 -zippov \
	                  -computers salvador vincent escher rembrandt

Note: The -zippov option compress the pov-files after the rendering to save
disk space!

    salvador:[~] raystat -name video/pendel -time
	            
The above commands print out progress information and the rendering
times of finished images.

If the transformation is finished type the following to remove all obsolent
files used by "raystart":

    salvador:[~] rayclear -cleanup



								Good luck!
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

