\input texinfo   @c -*-texinfo-*-
@comment $Revision$
@setfilename libtracked.info
@settitle LibTracked Programmer's Reference Manual
@iftex
@finalout
@end iftex

@setchapternewpage odd

@ifinfo
Copyright @copyright{} 1995 Loral Advanced Distributed Simulation, Inc.
@end ifinfo

@titlepage
@center NAWCTSD, Contract Number: N61339-91-D-0001
@center Data Item Number: A007, ModSAF Programmer's Reference Manual
@sp 4
@center @titlefont{LibTracked}
@sp 2
@center LibTracked Programmer's Reference Manual
@sp 2
@center Joshua E. Smith
@sp 2
@center $Revision$

@vskip 0pt plus 1filll
Copyright @copyright{} 1995 Loral Advanced Distributed Simulation, Inc.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1995 Loral Advanced Distributed Simulation, Inc.
@end titlepage

@node Top, Overview, (./modsafprm), (./modsafprm)

@menu
@ifinfo
This is the top level menu of an info file.  To go to a section in
this menu, you should type ``m'' followed by the first few characters
of the section you are interested.  If you put the text cursor next to
the section you are interested (use ``C-n''), ``m'' will default to
that section (you can then hit RETURN to go to the section).
@end ifinfo

* Overview::                    Overview of libtracked functionality
* Examples::                    Using libtracked from an application
* Functions::                   Descriptions of public functions

@end menu

@node     Overview,  Examples, Top,       Top    
@comment  node-name, next,  previous,  up
@chapter Overview

Libtracked implements an instance of the hull class of components.  It
provides a low-fidelity model of tracked vehicle dynamics.  Capabilities
are modeled only to the second order (maximum velocity, maximum
acceleration), and they depend upon the soil type.  Unlike previous
models, the parameters for each soil type are specified in a data file,
so the software does not need to be modified to accommodate new types of
terrain.

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

@example
(tracked (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>)
                                     (plow_speeds
                                           (<plow_type1> Ss Sd Ps Pd)
                                           (<plow_type2> Ss Sd Ps Pd)
                                           ...
                                           (<plow_typeN> Ss Sd Ps Pd)))
                (<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>)
                                      (plow_speeds
                                           (<plow_type1> Ss Sd Ps Pd)
                                           (<plow_type2> Ss Sd Ps Pd)
                                           ...
                                           (<plow_typeN> Ss Sd Ps Pd)))
                 ...)
         (fuel_usage (<float speed1> <float speed2> ...)
	             (<float rate1>  <float rate2> ...))
 )
@end example

The parameters specified for soil type @code{0} (or the first soil type,
if no @code{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.

The fuel_usage table consists of a list of speeds in kilometers per hour,
with a list of corresponding consumption rates in liters per hour.
If an older vehicle parameter file is used, with a scalar fuel_usage
figure, it will ignore it and use the internal default corresponding to
8 kilometers per liter.  The minimum table size is one speed/rate pair.

The plow speeds are used to control the maximum speed for the vehicle
when it has certain plows attached to it.  The <plow_type> fields are
character strings that represent the name of the plow (FWMP, TWMP,
moldboard, etc.).  If this vehicle can have such a plow attached (it
has the plow component), then each soil type specified in the Tracked
params should have an associated plow_speeds array.  Each plow that
the vehicle can have attached must have an entry in each soil type.

The format of the plow data is (plow_name Ss Sd) such that the
name is a character string (FWMP, TWMP, etc); Ss is the speed at which
this vehicle can travel in this soil type with the plow attached but
in its stowed position; Sd is the speed at which it can travel ...
in its deployed position;

Be careful about setting the speeds for the plows in relation to the
"max_speeds" entry.  The algorithm used it to set the current speed
equal to the max speed and then check to see if that speed to greater
than the speeds allowed if there is a plow attached (either stowed or
deployed).  Therefore, the max_speed should be greater than or equal
to at least one of the speeds Ss or Sd.  Otherwise, the plow speed 
data will essentially be ignored.

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

Libtracked supports only one instantiation per vehicle (i.e., a vehicle
may not have more than one tracked 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 libtracked or libfwa).
It is possible to modify the tracked model by changing an exisiting
hulls interface function or by adding a completely new function.  

To modify an existing libtracked interface function would require the
following actions:
@enumerate

@item 
If the change occurs only in the function body, only change the function
code in the libtracked library.  If the change occurs to the function's
argument list, change the function code in both the libtracked 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).

@item
Recompile ModSAF.
@end enumerate

To add an additional libtracked function to the current model would
require the following actions:
@enumerate

@item 
Write the function as part of the libtracked library.  The function is
written in the code which manages the libtracked class information
attached to each vehicle (trk_class.c).  

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

@item 
In the libtracked source code that handles libhull initialization
processing, include a @code{function_number, function} entry identifying
the new function for the @code{cmpnt_define_instance} function and every
other hull instance library (libfwa, libmissile, etc.).@refill

@item
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.  

@item
Recompile ModSAF.
@end enumerate

To replace this tracked model with a completely different one would
require the following actions:
@enumerate

@item 
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.

@item 
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 libtracked source file that contains the code to manage the
libtracked class information (trk_class.c). 

@item 
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.  

@item
Recompile ModSAF.
@end enumerate

@node     Examples, Functions,  Overview, Top    
@comment  node-name, next,  previous, up
@chapter Examples

To get the component number of my hull:

@example
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);
@end example

To then give a command to that hull:

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

@node     Functions,      , Examples,    Top    
@comment  node-name, next, previous, up
@chapter Functions

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

@menu
* tracked_init::                Initializes libtracked
* tracked_statsOn::             Turn on statistics collection
* tracked_statsOff::            Turn off statistics collection
* tracked_statsReset::          Zero out statistics
* tracked_statsPrint::          Print statistics
* tracked_statsStatus::         Print whether statistics are being collected
* tracked_statsQuit::           Deallocate statistics memory
@end menu

@node tracked_init, tracked_statsOn, , Functions
@section tracked_init

@example
void tracked_init(cant, data_path, constant_env, mobility_sw)
    int32 cant;
    char *data_path;
    int32 constant_env;
    int32 mobility_sw;
@end example

@table @samp
@item cant
Specifies whether to cant the vehicle when it is m-killed.
@item data_path
Specified where the data files are located.
@item constant_env
Specifies whether constant environmental models are in use (suppresses
wave interaction for amphibious vehicles).
@item mobility_sw
Enable CCTT soil types
@end table

@code{tracked_init} initializes libtracked.  Call this before calling
any other libtracked functions.

@comment ********************************************************
@node tracked_statsOn, tracked_statsOff, tracked_init, Functions
@section tracked_statsOn

@example
void tracked_statsOn()
@end example

@code{tracked_statsOn} turns on statistics collection for tracked hulls

@comment ********************************************************
@node tracked_statsOff, tracked_statsReset, tracked_statsOn, Functions
@section tracked_statsOff
@example
void tracked_statsOff()
@end example

This function turns off statictics collection for tracked hulls

@comment ********************************************************
@node tracked_statsReset, tracked_statsPrint, tracked_statsOff, Functions
@section tracked_statsReset
@example
void tracked_statsReset()
@end example

This function zeros out the statistics collected for tracked hulls

@comment ********************************************************
@node tracked_statsPrint, tracked_statsStatus, tracked_statsReset, Functions
@section tracked_statsPrint
@example
void tracked_statsPrint()
@end example

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

@comment ********************************************************
@node tracked_statsStatus, tracked_statsQuit, tracked_statsPrint, Functions
@section tracked_statsStatus
@example
void tracked_statsStatus()
@end example

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

@comment ********************************************************
@node tracked_statsQuit, , tracked_statsStatus, Functions
@section tracked_statsQuit
@example
void tracked_statsQuit()
@end example

This function deallocates memory for collecting tracked statistics

@comment *********************************************************


@contents
@bye
