diguy_module_dis.h

Go to the documentation of this file.

/*
 *  Copyright (C) 1992-2013 Boston Dynamics
 *  ALL RIGHTS RESERVED.
 *
 *  These coded instructions, statements, and computer programs
 *  contain unpublished proprietary information of Boston Dynamics
 *  and are protected by Copyright Laws of the United States.
 *  They may not be used, duplicated, or disclosed in any form, in
 *  whole or in part, without the prior written consent from Boston
 *  Dynamics.
 *
 *  RESTRICTED RIGHTS LEGEND
 *  Use, duplication, or disclosure by the government is subject
 *  to restrictions as set forth in FAR 52.227.19(c)(2) or
 *  subparagraph (c)(1)(ii) of the Rights in Technical Data and
 *  Computer Software clause at DFARS 252.227-7013 and/or in
 *  similar or successor clauses in the FAR, or the DOD or NASA
 *  FAR Supplement, or to subparagraphs (c)(1) and (c)(2) of the
 *  Commercial Computer Software--Restricted Rights at 48 CFR
 *  52.227-19, as applicable.  Unpublished-rights reserved under
 *  the Copyright Laws of the United States.
 *  Contractor/Manufacturer is:
 *  Boston Dynamics/78 Fourth Avenue/Waltham MA 02451.
 */


/*********************************************************************
 **
 *t  DI-Guy API, VR-Link DIS Module
 **
 *b    Link against: libdiguy_module_dis
 **
 *b    Deprecated as of DI-Guy 9.0.0; please move to the interfaces in diguy_module_net.h.
 */

#pragma message("WARNING: diguy_module_dis.h is deprecated as of DI-Guy 9.0, please move to the interfaces in diguy_module_net.h")


#ifndef __diguy_module_dis_H
#define __diguy_module_dis_H

#include <declspec_diguy.h>
#include <stdlib.h> // for NULL

class diguyScenario;
class diguyCharacter;

extern "C" {

/*****************************************************************************/
#ifdef CPLUSPLUS_ONLY

/*l
 *b  Description:
 **
 **    This function sets the filename of the VR-Link configuration file that
 **    will be read by the DI-Guy software.  The default is "network.cfg".
 **    This function must be called before diguy_dis_initialize().
 **
 *b  Arguments:
 **
 *a    cfg_file - filename of desired configuration file
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 **
 *b  Callable From:
 **
 *-    - C++
 */
BDI_DECLSPEC_diguy
int diguy_dis_set_cfg_file(const char* cfg_file);

/*l
 *b  Description:
 **
 **    This function allows VR-Link to install some callbacks so that .dss
 **    file load and save will include VR-Link-specific info.
 **
 **    It should be called BEFORE the scenario object is constructed.
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 **
 *b  Example:
 **
 *e    diguy_dis_initialize();
 **
 *b  Callable From:
 **
 *-    - C++
 */
BDI_DECLSPEC_diguy
int diguy_dis_initialize();

/*l
 *b  Description:
 **
 **    This function allows DI-Guy networking to clean up.
 **
 **    It should be called once, on application shutdown, after the scenario
 **    object has been destroyed.
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 **
 *b  Example:
 **
 *e    diguy_dis_deinitialize();
 **
 *b  Callable From:
 **
 *-    - C++
 */
BDI_DECLSPEC_diguy
int diguy_dis_deinitialize();


#endif // CPLUSPLUS_ONLY


/*l
 *b  Description:
 **
 **    This function tells DI-Guy that it should
 **    start talking over VR-Link.
 **
 **    It should be called when DI-Guy should join an exercise.
 **
 *b  Arguments:
 **
 *a    scenario  - pointer to the diguyScenario which will be connected to
 *a                the network
 *a    exconn    - optional pointer to an existing VR-Link exercise connection
 *a                to use
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 **
 *b  Example:
 **
 *e    diguy_dis_go_online(the_scenario_app);
 **
 *b  Callable From:
 **
 *-    - C++
 *-    - Script
 */
BDI_DECLSPEC_diguy
int diguy_dis_go_online(diguyScenario* scenario, void* exconn = NULL);

/*l
 *b  Description:
 **
 **    This function tells DI-Guy that it should read PDUs from the
 **    network and process them.  Call this function periodically.
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 **
 *b  Callable From:
 **
 *-    - C++
 *-    - Script
 */
BDI_DECLSPEC_diguy
int diguy_dis_update();

/*l
 *b  Description:
 **
 **    This function returns whether DI-Guy is using user-defined
 **    latitude/longitude coordinates for the origin of the database,
 **    or the coordinates that come from graphics files for
 **    scenario scene objects.
 **
 *b  Returns:
 **
 **    0 if graphics file coordinates are used;
 **    1 if user-defined coordinates are used
 **
 *b  Callable From:
 **
 *-    - C++
 *-    - Script
 */
BDI_DECLSPEC_diguy
int diguy_dis_get_use_user_defined_coords();

/*l
 *b  Description:
 **
 **    This function tells DI-Guy that it should stop networking with VR-Link.
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 **
 *b  Callable From:
 **
 *-    - C++
 *-    - Script
 */
BDI_DECLSPEC_diguy
int diguy_dis_go_offline();

/*l
 *b  Description:
 **
 **    This function queries whether DI-Guy is talking over VR-Link.
 **
 *b  Returns:
 **
 **    1 if yes, 0 if no
 **
 *b  Callable From:
 **
 *-    - C++
 *-    - Script
 */
BDI_DECLSPEC_diguy
int diguy_dis_get_online();

/*l
 *b  Returns:
 **
 **    the exercise id being used by DI-Guy Networking
 **
 *b  Callable From:
 **
 *-    - C++
 *-    - Script
 */
BDI_DECLSPEC_diguy
int diguy_dis_get_exercise();

/*l
 *b  Returns:
 **
 **    the host id being used by DI-Guy Networking
 **
 *b  Callable From:
 **
 *-    - C++
 *-    - Script
 */
BDI_DECLSPEC_diguy
int diguy_dis_get_host();

/*l
 *b  Returns:
 **
 **    the site id being used by DI-Guy Networking
 **
 *b  Callable From:
 **
 *-    - C++
 *-    - Script
 */
BDI_DECLSPEC_diguy
int diguy_dis_get_site();

/*l
 *b  Description:
 **
 **    the port number being used for DI-Guy Networking
 **
 *b  Callable From:
 **
 *-    - C++
 *-    - Script
 */
BDI_DECLSPEC_diguy
int diguy_dis_get_port();

/*l
 *b  Description:
 **
 **    Gets the latitude and longitude currently being used by DI-Guy
 **    networking for the placement of the database origin.
 **
 *b  Arguments:
 **
 *a    lat - latitude of origin, returned; see below
 *a    lon - longitude of origin, returned; see below
 **
 **    lat and lon are char**'s, into which char*'s will be
 **    placed.  These char*'s point to static data owned by DI-Guy.  Do not
 **    store these pointers, and do not modify what they point to.  Copy the
 **    strings needed out of the static buffers.  (Assignment of a char* to
 **    a Microsoft CString will work very nicely, for example.)
 **
 **    lat and lon are expressed as strings of the form:
 **
 **       [-]d [N|W|S|E]     or
 **       [-]d m [N|W|S|E]   or
 **       [-]d m s [N|W|S|E]
 **
 **    N and E are taken as positive.  S and W will negate the value otherwise
 **    computed. d m and s are positive, floating point values, taken as
 **    degrees, minutes, and seconds, respectively.  A leading minus sign will
 **    negate the entire value otherwise computed (so, e.g., a '-' and a 'S' will
 **    result in a double-negation).
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 **
 *b  Callable From:
 **
 *-    - C++
 *-    - Script
 */
BDI_DECLSPEC_diguy
int diguy_dis_get_lat_lon(double* lat, double* lon);

/*l
 *b  Description:
 **
 **    Gets, in UTM coordinates, the location currently being used by
 **    DI-Guy Networking for the placement of the database origin.
 **
 *b  Arguments:
 **
 *a    zone      - the UTM zone, returned
 *a    southzone - return value; 1 if the origin is in the southern
 *a                hemisphere, else 0
 *a    easting   - return value; normalized (positive only) easting of the
 *a                database origin within the zone
 *a    northing  - return value; normalized (positive only) northing of the
 *a                database origin within the zone, returned
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 **
 *b  Callable From:
 **
 *-    - C++
 *-    - Script
 */
BDI_DECLSPEC_diguy
int diguy_dis_get_utm(int* zone,
        int* southzone,
        double* easting,
        double* northing);

/*l
 *b  Description:
 **
 **    Sets, in UTM coordinates, the location currently being used by
 **    DI-Guy Networking for the placement of the database origin.
 **
 *b  Arguments:
 **
 *a    zone      - the UTM zone
 *a    southzone - 1 if the origin is in the southern hemisphere, else 0
 *a    easting   - the normalized (positive only) easting of the database
 *a                origin within the zone
 *a    northing  - the normalized (positive only) northing of the
 *a                database origin within the zone
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 **
 *b  Callable From:
 **
 *-    - C++
 *-    - Script
 */
BDI_DECLSPEC_diguy
int diguy_dis_set_utm(int zone,
        int southzone,
        double easting,
        double northing);

/*l
 *b  Description:
 **
 **    Sets the UTM zone of the location currently being used by DI-Guy
 **    Networking for the placement of the database origin.  The easting and
 **    northing are assumed not to change.
 **
 *b  Arguments:
 **
 *a    zone      - the utm zone
 *a    southzone - 1 if the origin is in the southern hemisphere, else 0
 **
 *b  Returns:
 **
 **    0 if successful
 **
 *b  Callable From:
 **
 *-    - C++
 *-    - Script
 */
BDI_DECLSPEC_diguy
int diguy_dis_set_utm_zone(int zone, int southzone);

/*l
 *b  Description:
 **
 **    Parses a string of the form
 **
 **       [-]d [N|W|S|E]     or
 **       [-]d m [N|W|S|E]   or
 **       [-]d m s [N|W|S|E]
 **
 **    N and E are taken as positive.  S and W will negate the value otherwise
 **    computed. d m and s are positive, floating point values, taken as
 **    degrees, minutes, and seconds, respectively.  A leading minus sign will
 **    negate the entire value otherwise computed (so, e.g., a '-' and a 'S' will
 **    result in a double-negation).
 **
 *b  Arguments:
 **
 *a    dmsstring - a string of the format described above
 **
 *b  Returns:
 **
 **    a double precision floating point value in radians
 **
 *b  Callable From:
 **
 *-    - C++
 *-    - Script
 */
BDI_DECLSPEC_diguy
double diguy_parse_dms_to_radians(const char* dmsstring);

/*l
 *b  Description:
 **
 **    Returns a string of the form
 **
 **       d [N|W|S|E]     or
 **       d m s [N|W|S|E]
 **
 **    N and E are used for positive angles.  S and W are used for
 **    negative angles.  In the d m s format, d and m are integers
 **    (degrees and minutes) and s (seconds) is a floating point value.  In
 **    the d format, d (degrees) is a floating point value.
 **
 *b  Arguments:
 **
 *a    outbuf           - a buffer into which to copy the resulting string
 *a    value            - the lat or lon value to be converted into a string
 *a    is_lat           - boolean indicating latitude (North/South) rather
 *a                       than longitude (East/West)
 *a    is_decimal       - boolean indicating that decimal degrees are
 *a                       desired, rather than degrees, minutes, and seconds
 *a    value_is_degrees - boolean indicating whether the input value is
 *a                       in degrees (as opposed to radians)
 **
 *b  Callable From:
 **
 *-    - C++
 *-    - Script
 */
BDI_DECLSPEC_diguy
void diguy_format_lat_or_lon(char* outbuf,
        double value,
        bool is_lat,
        bool is_decimal,
        bool value_is_degrees);

/*l
 *b  Description:
 **
 **    Gets the IP address currently being used by DI-Guy
 **    networking.  This address is the address to which messages are sent.
 **    Normally, it is some kind of broadcast or multicast address.
 **
 *b  Arguments:
 **
 *a    ipaddr - IP address, returned; see below
 **
 **    ipaddr is a char**, into which a char* will be placed.  This
 **    char* points to static data owned by DI-Guy.  Do not store this
 **    pointer, and do not modify what it points to.  Copy the strings you
 **    need out of the static buffer.  (Assignment of a char* to a
 **    Microsoft CString will work very nicely, for example.)
 **
 **    ipaddr is a string containing 4 integers separated by periods.
 **
 *b  Returns:
 **
 **    0 if successful
 **
 *b  Callable From:
 **
 *-    - C++
 *-    - Script
 */
BDI_DECLSPEC_diguy
int diguy_dis_get_ipaddr(char** ipaddr);

/*l
 *b  Description:
 **
 **    Returns whether DI-Guy Networking will publish local characters
 **    when online.
 **
 *i  C++, Script
 **
 *b  Arguments:
 **
 **    none
 **
 *b  Returns:
 **
 **    1 if enabled, 0 if not
 */
BDI_DECLSPEC_diguy
int diguy_dis_get_publish_local_chars();

/*l
 *b  Description:
 **
 **    Returns whether DI-Guy Networking will display remote characters
 **    when online.
 **
 *i  C++, Script
 **
 *b  Arguments:
 **
 **    none
 **
 *b  Returns:
 **
 **    1 if enabled, 0 if not
 */
BDI_DECLSPEC_diguy
int diguy_dis_get_display_remote_chars();

/*l
 *b  Description:
 **
 **    Sets the exercise id to be used by DI-Guy Networking.
 **
 **    The function will fail if DI-Guy is on-line (is participating
 **    in an exercise).
 **
 *i  C++, Script
 **
 *b  Arguments:
 **
 *a    exercise - the exercise id to use
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 */
BDI_DECLSPEC_diguy
int diguy_dis_set_exercise(int exercise);

/*l
 *b  Description:
 **
 **    Sets the host id to be used by DI-Guy Networking.
 **
 **    The function will fail if DI-Guy is on-line (is participating in
 **    an exercise).
 **
 *i  C++, Script
 **
 *b  Arguments:
 **
 *a    host - the host id to use; the host id identifies the local machine
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 */
BDI_DECLSPEC_diguy
int diguy_dis_set_host(int host);

/*l
 *b  Description:
 **
 **    Sets the site id to be used by DI-Guy Networking.
 **
 **    The function will fail if DI-Guy is on-line (is participating in
 **    an exercise).
 **
 *i  C++, Script
 **
 *b  Arguments:
 **
 *a    site - the site id to use; the site id identifies where the local
 *a           machine is
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 */
BDI_DECLSPEC_diguy
int diguy_dis_set_site(int site);

/*l
 *b  Description:
 **
 **    Sets the network port number to be used by DI-Guy Networking.
 **
 **    The function will fail if DI-Guy is on-line (is participating in
 **    an exercise).
 **
 *i  C++, Script
 **
 *b  Arguments:
 **
 *a    port - the port number to use
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 */
BDI_DECLSPEC_diguy
int diguy_dis_set_port(int port);

/*l
 *b  Description:
 **
 **    Sets the latitude and longitude to be used by DI-Guy Networking.
 **    The latitude and longitude are taken as the location, on Earth, of
 **    the origin of the database.
 **
 **    The function will fail if DI-Guy is on-line (is participating in
 **    an exercise).
 **
 *i  C++, Script
 **
 *b  Arguments:
 **
 *a    lat - the latitude in radians, positive north
 *a    lon - the longitude in radians, positive east
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 */
BDI_DECLSPEC_diguy
int diguy_dis_set_lat_lon(double lat, double lon);

/*l
 *b  Description:
 **
 **    Sets the IP address to be used by DI-Guy Networking.  This address
 **    is the address to which messages are sent.  Normally, it is a
 **    broadcast or multicast address.
 **
 **    The function will fail if DI-Guy is on-line (is participating in
 **    an exercise).
 **
 *i  C++, Script
 **
 *b  Arguments:
 **
 *a    ipaddr - the IP address
 **
 **    ipaddr is a string containing 4 integers separated by periods, or
 **    the null string, which means "let DI-Guy choose the address".  An
 **    address of "0" or "0.0.0.0" means broadcast.
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 */
BDI_DECLSPEC_diguy
int diguy_dis_set_ipaddr(const char* ipaddr);

/*l
 *b  Description:
 **
 **    Sets whether DI-Guy Networking will display remote characters.
 **
 **    The function will fail if DI-Guy is on-line (is participating in
 **    an exercise).
 **
 *i  C++, Script
 **
 *b  Arguments:
 **
 *a    display - pass 1 if DI-Guy Networking should display remote characters,
 *a              0 if not
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 */
BDI_DECLSPEC_diguy
int diguy_dis_set_display_remote_chars(int display);

/*l
 *b  Description:
 **
 **    Sets whether DI-Guy Networking will publish local characters to the
 **    network.
 **
 **    This function WILL succeed even if DI-Guy is on-line (is
 **    participating in an exercise).
 **
 *i  C++, Script
 **
 *b  Arguments:
 **
 *a    publish - pass 1 if DI-Guy Networking should publish local characters
 *a              to the network, 0 if not
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 */
BDI_DECLSPEC_diguy
int diguy_dis_set_publish_local_chars(int publish);

/*l
 *b  Description:
 **
 **    This function gets the position offset which is currently added to each character
 **    when it is published, and subtracted from each character when it is
 **    reflected.  The offset is useful to compensate for inter-application
 **    database location and orientation error.
 **
 *b  Arguments:
 **
 *a    z     -  z offset in meters
 *a    yaw   -  orientation offset in degrees
 *a    roll  -  orientation offset in degrees
 *a    pitch -  orientation offset in degrees
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 */
BDI_DECLSPEC_diguy
int diguy_dis_get_position_offset(float* z, float* yaw, float* roll, float* pitch);

/*l
 *b  Description:
 **
 **    This function sets the position offset which is currently added to each character
 **    when it is published, and subtracted from each character when it is
 **    reflected.  This is useful to compensate for inter-application location
 **    error.
 **
 *i    THIS FUNCTION DOES NOTHING if called while VR-Link is online.
 **
 *b  Arguments:
 **
 *a    z     - z offset in meters
 *a    yaw   - orientation offset in degrees
 *a    roll  - orientation offset in degrees
 *a    pitch - orientation offset in degrees
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 */
BDI_DECLSPEC_diguy
int diguy_dis_set_position_offset(float z, float yaw, float roll, float pitch);

/*l
 *b  Description:
 **
 **    Gets whether sync mode is enabled when online.
 **
 *i  C++, Script
 **
 *b  Arguments:
 **
 **    none
 **
 *b  Returns:
 **
 **    1 if sync mode is enabled when online, 0 if not
 */
BDI_DECLSPEC_diguy
int diguy_dis_get_sync_mode_enabled();

/*l
 *b  Description:
 **
 **    Gets whether this machine will serve as sync master when online
 **    and in sync mode.
 **
 *i  C++, Script
 **
 *b  Arguments:
 **
 **    none
 **
 *b  Returns:
 **
 **    1 if this machine will serve as sync master when online
 **    and in sync mode, 0 if not
 **
 */
BDI_DECLSPEC_diguy
int diguy_dis_get_sync_mode_master();


/*l
 *b  Description:
 **
 **    Gets whether this machine's camera will be slaved to a remote
 **    master when online and in sync mode and not sync master.
 **
 *i  C++, Script
 **
 *b  Arguments:
 **
 **    none
 **
 *b  Returns:
 **
 **    1 if this machine's camera will be slaved to a remote
 **    master when online and in sync mode and not sync master,
 **    0 if not
 */
BDI_DECLSPEC_diguy
int diguy_dis_get_sync_mode_slave_cam();
/*l
 *b  Description:
 **
 **    Sets whether networking should use database coordinates or
 **    not.  If database coordinates are used, the database
 **    origin is placed at the center of the earth.  This makes
 **    coordinate conversion to and from UTM unnecessary.  Using
 **    database coordinates renders ineffective any UTM-related
 **    settings which would position the database.
 **
 *i  C++, Script
 **
 *b  Arguments:
 **
 *a    use_database_coords - 1 if database coordinates should be used, else 0
 **
 *b  Returns:
 **
 **    0 if successful, -1 on failure
 **
 */
BDI_DECLSPEC_diguy
int diguy_dis_set_use_database_coords(int use_database_coords);
/*l
 *b  Description:
 **
 **    Sets whether networking should use user-defined coordinates or
 **    not.  If user-defined coordinates are not used, the database
 **    origin is placed at the earth location specified in the graphics
 **    files for the database.
 **
 *i  C++, Script
 **
 *b  Arguments:
 **
 *a    x - pass 1 if user-defined coordinates should be used, else 0
 **
 *b  Returns:
 **
 **    1 if this machine's camera will be slaved to a remote master when
 **    online and in sync mode and not sync master; 0 if not
 */
BDI_DECLSPEC_diguy
int diguy_dis_set_use_user_defined_coords(int x);

/*l
 *b  Description:
 **
 **    Sets whether sync mode is enabled when online.
 **
 **    The function will fail if DI-Guy is on-line (is participating in an
 **    exercise).
 **
 *i  C++, Script
 **
 *b  Arguments:
 **
 *a    enabled - pass 1 if sync mode should be enabled when online, 0 if not
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 */
BDI_DECLSPEC_diguy
int diguy_dis_set_sync_mode_enabled(int enabled);

/*l
 *b  Description:
 **
 **    Sets whether this machine will serve as sync master when online
 **    and in sync mode.
 **
 *i  C++, Script
 **
 *b  Arguments:
 **
 *a    master - pass 1 if this machine will serve as sync master when online
 *a             and in sync mode, 0 if not
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 */
BDI_DECLSPEC_diguy
int diguy_dis_set_sync_mode_master(int master);

/*l
 *b  Description:
 **
 **    Sets whether this machine's camera will be slaved to a remote
 **    master when online and in sync mode and not sync master.
 **
 **    The function will fail if DI-Guy is on-line (is participating in
 **    an exercise).
 **
 *i  C++, Script
 **
 *b  Arguments:
 **
 **    sl_cam - pass 1 if this machine's camera will be slaved to a remote
 **             master when online and in sync mode and not sync master,
 **             0 if not
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 */
BDI_DECLSPEC_diguy
int diguy_dis_set_sync_mode_slave_cam(int sl_cam);

/*l
 *b  Description:
 **
 **    This function sets the camera orientation offset to be used in
 **    sync_mode (when VR-Link is online).
 **
 *b  Arguments:
 **
 *a    offset_r - orientation offset
 *a    offset_y - orientation offset
 *a    offset_p - orientation offset
 **
 **    yaw and pitch represent PERCENTAGES of the camera's
 **    horizontal and vertical field of view, respectively.  The
 **    ROLL (which is in degrees) is applied first, then the yaw,
 **    then the pitch.
 **
 **    A typical two screen arrangement would use yaws of 50 and -50 for the
 **    left screen, and right screen, respectively.  For three screens, the
 **    yaws would be -100, 0, and 100.
 **
 **    Using percentages this way makes the screens contiguous even if the
 **    camera's field of view changes.
 **
 **    THIS FUNCTION DOES NOTHING (and returns -1) if called while VR-Link is
 **    online
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure (VR-Link is online).
 */
BDI_DECLSPEC_diguy
int diguy_dis_set_sync_mode_camera_offset(float offset_r, float offset_y, float offset_p);

/*l
 *b  Description:
 **
 **    This function gets the camera orientation offset to be used in
 **    sync_mode (when VR-Link is online).
 **
 *b  Arguments:
 **
 *a    offset_r - orientation offset
 *a    offset_y - orientation offset
 *a    offset_p - orientation offset
 **
 **    yaw and pitch represent PERCENTAGES of the camera's
 **    horizontal and vertical field of view, respectively.  The
 **    ROLL (which is in degrees) is applied first, then the yaw,
 **    then the pitch.
 **
 **    In the orientation offset the yaw and pitch
 **    represent PERCENTAGES of the camera's horizontal and vertical field
 **    of view, respectively.  The ROLL (which is in degrees) is applied
 **    first, then the yaw, then the pitch.
 **
 **    A typical two screen arrangement would use yaws of 50 and -50 for the
 **    left screen, and right screen, respectively.  For three screens, the
 **    yaws would be 100, 0, and -100 going from left to right.
 **
 **    Using percentages this way makes the screens contiguous even if the
 **    camera's field of view changes.
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 **
 */
BDI_DECLSPEC_diguy
int diguy_dis_get_sync_mode_camera_offset(float* offset_r, float* offset_y, float* offset_p);

/*l
 *b  Description:
 **
 **    This function sets whether the camera will be slaved when VR-Link is
 **    online, in sync mode, and not sync master.
 **
 **    It can be set even when VR-Link is online.
 **
 *b  Arguments:
 **
 *a    slaved   - whether the camera will be slaved when VR-Link is
 **               online, in sync mode, and not sync master.
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 */
BDI_DECLSPEC_diguy
int diguy_dis_set_sync_mode_camera_slaved(int slaved);

/*l
 *b  Description:
 **
 **    This function gets whether the camera is currently slaved.  It does NOT
 **    simply return what was passed to
 **    diguy_dis_set_sync_mode_camera_slaved().
 **
 *b  Returns:
 **
 **    Whether the camera is currently slaved.  This will be 1 only if
 **    VR-link is online, is in sync mode, and is not the sync master, and if
 **    sync_mode_camera_slaved has been set to 1.
 **
 */
BDI_DECLSPEC_diguy
int diguy_dis_get_sync_mode_camera_slaved();

/*l
 *b  Description:
 **
 **    This function allows iteration through the list of names remote
 **    VR-Link hosts that DI-Guy knows about.
 **
 *b  Arguments:
 **
 *a    buf     - destination buffer for host name (64 bytes is plenty)
 *a    handle  - return value from last call to the function; pass NULL to
 *a              get the first host name; pass previous return value to get
 *a              the next host name
 **
 *b  Returns:
 **
 **    void* to be passed as handle argument on the next call.  NULL when end
 **    of list is reached.
 */
BDI_DECLSPEC_diguy
void* diguy_dis_get_next_participant_name(char* buf, void* handle);

/*l
 *b  Description:
 **
 **    Lets VR-Link know that the user has moved the camera, so that if it
 **    is in sync mode, and is the sync master, it can let other hosts
 **    know the new camera position so they can move their cameras.
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 */
BDI_DECLSPEC_diguy
int diguy_dis_set_camera_details_out_of_date();

/*l
 *b  Description:
 **
 **    Fetches what character type and what appearance should be used for a
 **    given DIS entity type septet.
 **
 *b  Arguments:
 **
 *a    chartype     - address of char*, for returning a string which names
 *a                   the DI-Guy character type
 *a    appearance   - address of char*, for returning a string which names
 *a                   the DI-Guy character appearance
 *a    septet       - array of seven integers specifying the kind, domain, country,
 *a                   category, subCategory, specific, and extra of the entity
 *a                   in question
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 */
BDI_DECLSPEC_diguy
int diguy_dis_get_model_from_septet(const char** chartype, const char** appearance, const int septet[7]);

/*l
 *b  Description:
 **
 **   Fetches what DIS entity type septet should be used for a given character
 **   type and appearance.
 **
 *b  Arguments:
 **
 *a    chartype     - a string which names the DI-Guy character type
 *a    appearance   - a string which names the DI-Guy character appearance
 *a    septet       - array of seven integers, returned, indicating the kind,
 *a                   domain, country, category, subCategory, specific, and
 *a                   extra of the entity in question
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 */
BDI_DECLSPEC_diguy
int diguy_dis_get_septet_from_model(int septet[7], const char* chartype, const char* appearance);

/*l
 *b  Description:
 **
 **    Converts a 3d database-origin-relative location into a string
 **    describing it in earth coordinates.  This string could be in a number
 **    of different formats including decimal lat/lon, dms lat/lon, and UTM.
 **
 *b  Arguments:
 **
 *a    outbuf  - buffer into which to put the output string
 *a    x, y, z - 3 floats specifying location
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure.  Fails if DI-Guy Scenario is not currently
 **    on the network, meaning that a database-to-earth coordinate conversion
 **    cannot be performed.
 */
BDI_DECLSPEC_diguy
int diguy_dis_get_earth_coord(char* outbuf, const float x, const float y, const float z);

/*l
 *b  Description:
 **
 **    Changes the format of the output of diguy_dis_get_earth_coord.  Toggles
 **    between UTM, dms lat/lon, decimal lat/lon, and "punting", meaning that
 **    the caller of diguy_dis_get_earth_coord should fend for itself.  This
 **    generally means that the caller will use database-origin-relative
 **    coordinates.
 **
 *b  Arguments:
 **
 **    none
 **
 *b  Returns:
 **
 **    void
 */
BDI_DECLSPEC_diguy
void diguy_dis_toggle_earth_coord_format();

/*l
 *b  Description:
 **
 **    returns the diguyCharacter associated with the entity id specified.
 **
 *b  Arguments:
 **
 *a    id - entity id
 **
 **    Under HLA, two formats are permitted: the HLA object name, or
 **    the DIS entity identifier ("site:application:entity", where each
 **    is an integer).
 **
 **    Under DIS, only the DIS Entity Identifier is permitted.
 */
BDI_DECLSPEC_diguy
diguyCharacter* diguy_dis_get_character_from_id(char const* id);

/*l
 *b  Description:
 **
 **    Turns the 'never create' character bit on.
 */
BDI_DECLSPEC_diguy
void diguy_dis_enter_vpnet_mode();

/*l
 *b  Description:
 **
 **    This function returns the name corresponding to the passed
 **    entity.
 **
 **    The user must not delete the returned string.
 **
 *b  Arguments:
 **
 *a    reflected_entity - entity to be named
 **
 *b  Returns:
 **
 **    entity name
 */
BDI_DECLSPEC_diguy
char* diguy_dis_get_name_from_entity(void* reflected_entity);

BDI_DECLSPEC_diguy
void diguy_dis_establish_new_offsets(int deprecated = 0);

BDI_DECLSPEC_diguy
void diguy_dis_set_send_custom_pdus(int val);

BDI_DECLSPEC_diguy
int diguy_dis_get_send_custom_pdus();

BDI_DECLSPEC_diguy
void diguy_dis_set_client_mode();

BDI_DECLSPEC_diguy
void diguy_dis_set_server_mode();

}  /* extern "C" */

#endif /* __diguy_module_dis_H */

/*
 *  Copyright (C) 1992-2013 Boston Dynamics
 *  ALL RIGHTS RESERVED.
 *
 *  These coded instructions, statements, and computer programs
 *  contain unpublished proprietary information of Boston Dynamics
 *  and are protected by Copyright Laws of the United States.
 *  They may not be used, duplicated, or disclosed in any form, in
 *  whole or in part, without the prior written consent from Boston
 *  Dynamics.
 *
 *  RESTRICTED RIGHTS LEGEND
 *  Use, duplication, or disclosure by the government is subject
 *  to restrictions as set forth in FAR 52.227.19(c)(2) or
 *  subparagraph (c)(1)(ii) of the Rights in Technical Data and
 *  Computer Software clause at DFARS 252.227-7013 and/or in
 *  similar or successor clauses in the FAR, or the DOD or NASA
 *  FAR Supplement, or to subparagraphs (c)(1) and (c)(2) of the
 *  Commercial Computer Software--Restricted Rights at 48 CFR
 *  52.227-19, as applicable.  Unpublished-rights reserved under
 *  the Copyright Laws of the United States.
 *  Contractor/Manufacturer is:
 *  Boston Dynamics/78 Fourth Avenue/Waltham MA 02451.
 */