USAGE:

within prog-unit 

    #import "vortex"

Contents:

Overview -- introduction to the object hierarchy Class Universe -- defines a vortex universe Class Scene -- loads a scene into a universe Class SolidRef -- references to named solids in a scene Class Box, etc. -- create new solids in a scene Class Joint -- references to named joints in a scene _

Overview:

There exist three classes of objects: universes, scenes and objects. At the top level one (or more) named universes can be defined, which are refered by one (or more) named scenes, which hold in turn several named objects (solids and joints). That is, objects in an universe are always defined within a scene which in turn refers to a specific universe. This allows for combining a complex universe using different scenes. Scenes are normally described in a file using a xml-style-syntax. But it is also possible to <:add solids directly:#solidself> within neo .

Universe class -- define a vortex universe:

constructor universe (char *pcName, int nBodies=100, int nConstraints=100, int nModels=100, int nModelPairs=1200):
Returns an instance of a universe with given name. The other parameters define the maximal number of used bodies, constraints (joints and contacts), collision models and collision pairs. If you get into trouble because of too small "pool size", try to increase these values.
reset ():
Resets, i.e. reloads all scenes connected with this universe. All objects created directly within neo get destroyed and NOT recreated.
step (float fStepSize=.05):
Does an iteration step with given time step.
draw ():
Draws the whole universe using OpenGL-commands. Use this command within an operand of a view3d unit
.

Scene class -- add a scene to universe:

constructor Scene (char *pcName, char *pcUniverse, char *pcFileName, float *pfBaseTransform=NULL):
Add a scene named pcName to the named universe pcUniverse. All objects defined within the xml-file are loaded into the universe applying the homogenous transform (4x4 matrix) pfBaseTransform (or identity) first.
reset ():
Resets this scene, i.e. reloads all objects in pcFileName and destroy all objects created directly in neo
.

SolidRef class -- reference named solids:

constructor SolidRef (har *pcScene, char *pcName):
Creates an instance of a reference to the solid pcName in scene pcScene.
int Remove ():
removes the solid from scene
The following vortex functions are wrapped for use in neo. Most of them should be self-explaining, see vortex documentation for more details. 

   void Enable (int bEnable)
   int IsEnabled ()
All positioning functions should be used with care. Generally they are called once at initialization time of a scene. All other movements should be achieved using forces and torques. 

   void SetPosition (float Pos[3])
   void GetPosition (float Pos[3])
   void SetQuaternion (float Quat[4])
   void GetQuaternion (float Quat[4])
   void SetTransform (float TM[16])

   void SetMass (float fMass)
   float GetMass ()

   void ResetForces ()
void GetForce (float Force[3]):
returns the sum of forces accumulated through calls of AddForce and AddForceAtPosition 

   void AddForce (float Force[3])
   void AddForceAtPosition (float Force[3], float Pos[3])
   void AddImpulse (float Impulse[3])
   void AddImpulseAtPosition (float Impulse[3], float Pos[3])
   void AddTorque (float Torque[3])

   void SetLinearVelocity (float LinVel[3])
   void GetLinearVelocity (float LinVel[3])
   void GetLinearAcceleration (float LinAcc[3])
   void SetAngularVelocity (float AngVel[3])
   void GetAngularVelocity (float AngVel[3])
void GetForces ((*CallBack)(int iType, float Force[3], float Torque[3]), int iFilter=-1):
Calls the CallBack function for every constraint (joint or contact) applying to this solid. For each constraint the constraint type, applied force and torque are supplied as arguments to the callback function. iFilter can be set to a value >= 0 in order to restrict the constraint search to a given type.
The following types are available:

   tBSJOINT, tHINGE, tPRISMATIC, tCARWHEEL, tCONTACT, tFIXEDPATH, tFPFOJOINT,
   tRPROJOINT, tUNIVERSAL, tLINEAR1, tLINEAR2, tANGULAR3, tSPRING, tCONELIMIT,
   tUSER
void GetContacts ((*CallBack)(int iType, float Force[3], float Torque[3], float Position[3], float Normal[3], float Direction[3], float FrictionForce1, float FrictionForce2)):
Calls the CallBack function for every contact of this solid. The arguments of the callback function provide the following information about the contact: force and torque applied during last time step, the position and normal of this contact in world coordinates, the relative moving direction of the affected bodies, the maximal friction forces along the moving direction (1) and its perpendicular direction (2).
These are some auxiliary functions, which should be self explaining too. 

   PosToWorld (float PosLocal[3], float PosWorld[3])
   PosFromWorld (float PosWorld[3], float PosLocal[3])
   SetColor (char *pcName, float fAlpha=1)
   SetColor (float color[4])
.

Box classes -- create new solids:

All these object types are subclasses of SolidRef, and thus inherit all solid methods. Directly created solids are useful, if a whole bunch of similar objects has to be created. All constructor functions create the solids with default properties, i.e. located at the origin and oriented along the world coordinates. All constructor functions have an argument int bFrozen, which if set equal to 1, creates a frozen solid used only within collision detection, but with no dynamics connected to it.
Box (char *pcScene, float Size[3], int bFrozen=0):
Creates a box within scene pcScene with given Size
.

Joints -- reference named joints:

All joints have some common methods defined in the parent class Joint. All concrete joint types (hinge, prismatic) are derived from this class and may have some additional special methods. All methods are wrappers for appropriate vortex functions and are documented in detail within vortex documentation.
constructor Joint (char *pcScene, char *pcName):
Creates an instance of a reference to the joint pcName in scene pcScene. 

   void Enable (int bEnable)
   int IsEnabled ()
   void EnableBodies ()

   void SetPosition (float Pos[3])
   void GetPosition (float Pos[3])
   void SetAxis (float Axis[3])
   void GetAxis (float Axis[3])
   void GetForce (int iBodyIndex, float Force[3])
   void GetTorque (int iBodyIndex, float Torque[3])
Limit methods: Some joints have a limit connected with them. They share the following limit methods. 

   void EnableLimit (int bEnable)
   int IsLimitEnabled ()

   float GetStiffnessThreshold ()
   void SetStiffnessThreshold (float fStiff)

   void EnableMotor (int bEnable)
   int IsMotorEnabled ()
   float GetMaxForce ()
   void SetMaxForce (float fMaxForce)
   float GetDesiredVelocity ()
   void SetDesiredVelocity (float fVel)
   int GetMotor (float*)
   void SetMotor (float velocity, float maxforce)
   void Approach (float dest, float gap, float maxSpeed, float maxForce)

   void GetLowerLimit (float Params[4])
   void SetLowerLimit (float Params[4])
   void GetUpperLimit (float Params[4])
   void SetUpperLimit (float Params[4])
   float GetDamping (int which)
   void SetDamping (int which, float fDamp)
   float GetRestitution (int which)
   void SetRestitution (int which, float fRest)
   float GetStiffness (int which)
   void SetStiffness (int which, float fStiff)
   float GetStop (int which)
   void SetStop (int which, float fStop)

The lower and upper limits are defined by four parameters:

Damping, Restitution, Stiffness and Stop .

Hinge:

constructor Hinge (char *pcScene, char *pcRefName):
Returns a reference to the hinge joint pcName in scene pcScene. Hinges are limited, i.e. the limit methods apply. 

   void SetAngle (float)
   float GetAngle ()
   void SetAngularVelocity (float)
   float GetAngularVelocity ()
.

Prismatic:

Prismatic (char *pcScene, char *pcRefName):
Returns a reference to the prismatic joint pcName in scene pcScene. Prismatic joints are limited, i.e. the limit methods apply. 

   void SetDistance (float)
   float GetDistance ()
   void SetVelocity (float)
   float GetVelocity ()

FILE

nst_vortex.cc