This tutorial is against version 0.5.2.

Contents

1.  How to use SimSimSim?
 1.1.  What header file to include?
 1.2.  What code to write?
  1.2.1.  The AbstractSimulation object
   1.2.2.1.  Required methods
   1.2.2.2.  Optional methods (missing)
  1.2.2.  Starting SimSimSim
 1.3.  Linking
 1.4.  Running
2. Complete Examples (missing)

1.  How to use SimSimSim?

To use the SimSimSim library, you have to:
 - write your simulation as a C++ object;
 - invoke simsimsim passing the simulation, and selecting
    an available user interface (UI).

1.1.  What header file to include?

The only header file you need is "simsimsim.h".  
So you start your program with:

  #include <simsimsim.h>

The location of this header file depends on where you (or
someone else) installed it.
simsimsim.h contains:
 - the definitions of the abstract simulation object;
 - the UI startup functions (sim3_run_*);
 - global settings;
 - other utility functions (sim3_*);
 - includes for other needed header files.

1.2.  What code to write?

For interfacing with SimSimSim, you have to write a C++
class representing the simulation.  You have to define
three methods that will make the simulation work:
start, step, and draw.  There are some other methods which you
can overwrite, but they are optional.
 
1.2.1.  The AbstractSimulation object

Your simulation object must be a descendant of AbstractSimulation
class.  This class is defined in simsimsim.h (you can have a look!).
It is indeed an abstract class, meaning that it has some undefined
methods, so objects of this class cannot be used, only descendants.
Your declaration might look like this:

  class MySimulation: public AbstractSimulation 
  ...

Naturally, you can define new data fields and methods specific to
your simulation.  
(Note: if you using a class that should inherit form another class
as well, you can use multiplte inheritence, or make the simulation
class a 'container' class, and contain another object as data)

1.2.2.1.  Required methods

There are three basic methods that *must* be overriten.
These are start, stop, and draw.

The start method
start() is invoked by SimSimSim when it wants to start (or restart)
the simulation.  This method should reset the simulation state to
its initial state -- initialize private data.
The declaration of the start method look like this (very simple):

  virtual void start(void);

The step method
This is the heart of the simulation.  This method is invoked repeatedly,
and it should perform a single step of the simulation.
There are no arguments involved:

  virtual void stop(void);

The draw method
draw() is invoked whenver the simulation is to be redrawn.  How
exaactly the graphical representation looks depends on the kind
of user interface used.  In order to work under *any* user interface,
draw should be general -- it should use only the drawing primitives
supplied by SimSimSim!  The library will then ensure that the correct
rendering is used.

  virtual void draw(void);

Drawing primitives exists for drawing points, lines, spheres, triangles,
etc.  They are declared in "simsimsim.h", and are prefixed by sim3_draw_.
Note: for more sophisticated, but only OpenGL rendering, you can use
drawGL.

1.2.2.2.  Optional methods

1.2.2.  Starting SimSimSim

You also have to write your main program, which will create an object 
of the simulation class you defined, and start up SimSimSim with
the simulation object as an argument.  Running the SimSimSim user interface
is accomplished by invoking a sim3_run_XXX function, with the simulation
object its a paramter.  A minimal main function could look like this:

  int main(void)
  {
    MySimulation Sim;        // create a simulation object

    sim3_run_GLUT(&Sim);     // run the simulation using the GLUT interface

    return 0;
  }

1.3.  Linking

For building your code, you have to link agains the sim3 library, which
contains the used functions.  You must ensure that the linker finds the
correct library.  Typical arguments to the linker look like this:
'-L~/mysim3dir -lsim3'

1.4.  Running

When running the executable, be sure that whatever shared library
are required for the user interface are available.  For example,
if you use X Windows UI, you should run it under X.


2. Complete Examples
For working examples, you can always have a look at the demos:
some are them are quite simple.