Copyright © 1995 Loral Advanced Distributed Simulation, Inc.

Overview
********

LibWheeled implements an instance of wheeled vehicle dynamics, along with some initialization routines and collision and damage functions. Also included is a "Mini Driver" which decides on desired acceleration and steering wheel angle.  The dynamics are multi-resolutional.  That is, there are levels of dynamics, each with varying levels of complexity.  The levels are switched using a switching function, which can be based on many things, such as tick time, vehicle interractions, etc.  It is currently based only on tick time.  Each tick of the dynamics is referred from a resolution level, where the dynamics are calculated accordingly.

The parameters of a wheeled vehicle are specified in its configuration file as follows:

     (wheeled (soils (<integer soil type> (max_speeds <float forward KPH>
                                                      <float reverse KPH>)
                                          (max_accel <float mps2>)
                                          (max_decel <float mps2>)
                                          (max_turn  <float dps>)
                                          (max_climb <float degrees>)
                                          (dust_speeds <float smallKPH>
                                                       <float mediumKPH>
                                                       <float largeKPH>))
                     (<integer soil type> (max_speeds <float KPH>
                                                      <float reverse KPH>)
                                          (max_accel <float mps2>)
                                          (max_decel <float mps2>)
                                          (max_turn  <float dps>)
                                          (max_climb <float degrees>)
                                          (dust_speeds <float smallKPH>
                                                       <float mediumKPH>
                                                       <float largeKPH>))
                      ...)
              (fuel_usage <float kpl>)
      )

The parameters specified for soil type 0 (or the first soil type, if no 0 type is provided) are used as a default when on a soil type not in the list.

To indicate that the vehicle should not kick up any dust on a kind of soil, specify a speed which is higher than the maximum the vehicle can travel across that soil.

Applications interface to the wheeled model primarily through the libhulls interface.  The most efficient interface for controlling vehicle motion is HULLS_SET_DIRECTION_SPEED.  All interfaces use only two dimensions of the provided parameters.  Also, when a direction vector is given it is not necessary to make that vector a unit vector.  Libwheeled will do the normalization only if it is necessary (for example, if the vehicle is already pointing the right way, no normalization is needed).

Libwheeled supports only one instantiation per vehicle (i.e., a vehicle may not have more than one wheeled hull).

The libhulls library defines a common set of functions (and the semantics of those functions) which are invoked on instances of the hulls class (such as those instantiated by libwheeled or libfwa). It is possible to modify the wheeled model by changing an exisiting hulls interface function or by adding a completely new function.

To modify an existing libwheeled interface function would require the following actions:

 1. If the change occurs only in the function body, only change the function code in the libwheeled library.  If the change occurs to the function's argument list, change the function code in both the libwheeled library and the hulls interface structure definition found in libhulls.h.  Also to maintain the common hulls interface, change the code for the modified function in any other hull specific component libraries (such as libfwa or libmissile).

 2. Recompile ModSAF.

To add an additional libwheeled function to the current model would require the following actions:

 1. Write the function as part of the libwheeled library.  The function is written in the code which manages the libwheeled class information attached to each vehicle (whl_class.c).

 2. Add the function and its declaration to any of the other hull specific component libraries.  This maintains the common hulls interface.

 3. In the libwheeled source code that handles libhull initialization processing, include a
      "function_number, function" entry identifying the new function for the
      "cmpnt_define_instance" function and every other hull instance library (libfwa, libmissile, etc.).

 4. In libhulls.h, add an entry to identify the new macro and associate it with a function code number.  This new addition means that the number of hulls functions must be incremented by one.  The hulls interface structure definition that appears in libhulls.h must include a structure to define the new function's argument list.

 5. Recompile ModSAF.

To replace this wheeled model with a completely different one would require the following actions:

 1. Decide on the get functions and set functions that would be required in the new model.  Try to map these needed functions to the existing hulls interface.  A function can map if its argument list can remain the same.  Functions that can not map must be added to the hulls interface.

 2. For those functions that can map to the existing hulls interface but whose code body you want to change, edit the code for the function in the libwheeled source file that contains the code to manage the libwheeled class information (whl_class.c).

 3. For those functions that can't map to the existing hulls interface, add an additional function to the hulls interface.  The addition procedure was described above.

 4. Recompile ModSAF.

Examples
********

To get the component number of my hull:

     extern int32 my_hull;

     if ((my_hull = cmpnt_locate(vehicle_id, reader_get_symbol("hull"))) ==
         CMPNT_NOT_FOUND)
       printf("Vehicle %d does not seem to have a hull\n", vehicle_id);

To then give a command to that hull:

     if (my_hull != CMPNT_NOT_FOUND)
       HULLS_SET_DIRECTION_SPEED(vehicle_id, hull, dirvec, speed, 0.0, 0.0);

Functions
*********

The following sections describe each function provided by libwheeled, including the format and meaning of its arguments, and the meaning of its return values (if any).

wheeled_init
============

     void wheeled_init(cant, data_path)
         int32 cant;
         char *data_path;

cant
     Specifies whether to cant the vehicle when it is m-killed.

data_path
     Specifies where the data files are located.

wheeled_init initializes libwheeled.  Call this before calling any other libwheeled functions.

wheeled_statsOn
===============

     void wheeled_statsOn()

This function turns on statistics collection for wheeled hulls

wheeled_statsOff
================

     void wheeled_statsOff()

This function turns off statictics collection for wheeled hulls

wheeled_statsReset
==================

     void wheeled_statsReset()

This function zeros out the statistics collected for wheeled hulls

wheeled_statsPrint
==================

     void wheeled_statsPrint()

This functions prints out the statistics for wheeled hulls. Uses hulls_statsPrint.

wheeled_statsStatus
===================

     void wheeled_statsStatus()

This function prints whether wheeled hulls data collection is on or off

wheeled_statsQuit
=================

     void wheeled_statsQuit()

This function deallocates memory for collecting wheeled statistics