\input texinfo   @c -*-texinfo-*-
@comment $Revision$
@setfilename libwheeled.info
@settitle LibWheeled 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{Libwheeled}
@sp 2
@center LibWheeled Programmer's Reference Manual
@sp 2
@center Wendy T Taylor
@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 libwheeled functionality
* Examples::                    Using libwheeled from an application
* Functions::                   Descriptions of public functions

@end menu

@node     Overview,  Examples, Top,       Top    
@comment  node-name, next,  previous,  up
@chapter 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:

@example
(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>)
 )
@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.

Applications interface to the wheeled 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.  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:
@enumerate

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

@item
Recompile ModSAF.
@end enumerate

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

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

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

@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 wheeled 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 libwheeled source file that contains the code to manage the
libwheeled class information (whl_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 libwheeled,
including the format and meaning of its arguments, and the meaning of
its return values (if any).  

@menu
* wheeled_init::                Initializes libwheeled
* wheeled_statsOn::             Turn on statistics collection
* wheeled_statsOff::            Turn off statistics collection
* wheeled_statsReset::          Zero out statistics
* wheeled_statsPrint::          Print statistics
* wheeled_statsStatus::         Print whether statistics are being collected
* wheeled_statsQuit::           Deallocate statistics memory
@end menu

@node wheeled_init, wheeled_statsOn, , Functions
@section wheeled_init

@example
void wheeled_init(cant, data_path)
    int32 cant;
    char *data_path;
@end example

@table @samp
@item cant
Specifies whether to cant the vehicle when it is m-killed.
@item data_path
Specifies where the data files are located.
@end table

@code{wheeled_init} initializes libwheeled.  Call this before calling
any other libwheeled functions.


@comment ********************************************************
@node wheeled_statsOn, wheeled_statsOff, wheeled_init, Functions
@section wheeled_statsOn
@example
void wheeled_statsOn()
@end example

This function turns on statistics collection for wheeled hulls

@comment ********************************************************
@node wheeled_statsOff, wheeled_statsReset, wheeled_statsOn, Functions
@section wheeled_statsOff
@example
void wheeled_statsOff()
@end example

This function turns off statictics collection for wheeled hulls

@comment ********************************************************
@node wheeled_statsReset, wheeled_statsPrint, wheeled_statsOff, Functions
@section wheeled_statsReset
@example
void wheeled_statsReset()
@end example

This function zeros out the statistics collected for wheeled hulls

@comment ********************************************************
@node wheeled_statsPrint, wheeled_statsStatus, wheeled_statsReset, Functions
@section wheeled_statsPrint
@example
void wheeled_statsPrint()
@end example

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

@comment ********************************************************
@node wheeled_statsStatus, wheeled_statsQuit, wheeled_statsPrint, Functions
@section wheeled_statsStatus
@example
void wheeled_statsStatus()
@end example

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

@comment ********************************************************
@node wheeled_statsQuit, , wheeled_statsStatus, Functions
@section wheeled_statsQuit
@example
void wheeled_statsQuit()
@end example

This function deallocates memory for collecting wheeled statistics

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

@contents
@bye
