DI-Guy API Version 12.5.1

This file was automatically generated from diguy_module_dis.h. Do not edit this file directly; the changes will be lost.

Contents:

• Functions

Link against: libdiguy_module_dis

Deprecated as of DI-Guy 9.0.0; please move to the interfaces in diguy_module_net.h.

Prototype:

int diguy_dis_set_cfg_file(const char* cfg_file);

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

Arguments:

cfg_file

filename of desired configuration file

Returns:

0 on success, -1 on failure

Callable From:

• C++

Prototype:

int diguy_dis_initialize();

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.

Returns:

0 on success, -1 on failure

Example:

diguy_dis_initialize();

Callable From:

• C++

Prototype:

int diguy_dis_deinitialize();

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.

Returns:

0 on success, -1 on failure

Example:

diguy_dis_deinitialize();

Callable From:

• C++

Prototype:

int diguy_dis_go_online(diguyScenario* scenario, void* exconn = NULL);

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.

Arguments:

scenario	pointer to the diguyScenario which will be connected to the network
exconn	optional pointer to an existing VR-Link exercise connection to use

Returns:

0 on success, -1 on failure

Example:

diguy_dis_go_online(the_scenario_app);

Callable From:

• C++
• Script

Prototype:

int diguy_dis_update();

Description:

This function tells DI-Guy that it should read PDUs from the network and process them. Call this function periodically.

Returns:

0 on success, -1 on failure

Callable From:

• C++
• Script

Prototype:

int diguy_dis_get_use_user_defined_coords();

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.

Returns:

0 if graphics file coordinates are used; 1 if user-defined coordinates are used

Callable From:

• C++
• Script

Prototype:

int diguy_dis_go_offline();

Description:

This function tells DI-Guy that it should stop networking with VR-Link.

Returns:

0 on success, -1 on failure

Callable From:

• C++
• Script

Prototype:

int diguy_dis_get_online();

Description:

This function queries whether DI-Guy is talking over VR-Link.

Returns:

1 if yes, 0 if no

Callable From:

• C++
• Script

Prototype:

int diguy_dis_get_exercise();

Returns:

the exercise id being used by DI-Guy Networking

Callable From:

• C++
• Script

Prototype:

int diguy_dis_get_host();

Returns:

the host id being used by DI-Guy Networking

Callable From:

• C++
• Script

Prototype:

int diguy_dis_get_site();

Returns:

the site id being used by DI-Guy Networking

Callable From:

• C++
• Script

Prototype:

int diguy_dis_get_port();

Description:

the port number being used for DI-Guy Networking

Callable From:

• C++
• Script

Prototype:

int diguy_dis_get_lat_lon(double* lat, double* lon);

Description:

Gets the latitude and longitude currently being used by DI-Guy networking for the placement of the database origin.

Arguments:

lat	latitude of origin, returned; see below
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).

Returns:

0 on success, -1 on failure

Callable From:

• C++
• Script

Prototype:

int diguy_dis_get_utm(int* zone,
    int* southzone,
    double* easting,
    double* northing);

Description:

Gets, in UTM coordinates, the location currently being used by DI-Guy Networking for the placement of the database origin.

Arguments:

zone	the UTM zone, returned
southzone	return value; 1 if the origin is in the southern hemisphere, else 0
easting	return value; normalized (positive only) easting of the database origin within the zone
northing	return value; normalized (positive only) northing of the database origin within the zone, returned

Returns:

0 on success, -1 on failure

Callable From:

• C++
• Script

Prototype:

int diguy_dis_set_utm(int zone,
    int southzone,
    double easting,
    double northing);

Description:

Sets, in UTM coordinates, the location currently being used by DI-Guy Networking for the placement of the database origin.

Arguments:

zone	the UTM zone
southzone	1 if the origin is in the southern hemisphere, else 0
easting	the normalized (positive only) easting of the database origin within the zone
northing	the normalized (positive only) northing of the database origin within the zone

Returns:

0 on success, -1 on failure

Callable From:

• C++
• Script

Prototype:

int diguy_dis_set_utm_zone(int zone, int southzone);

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.

Arguments:

zone	the utm zone
southzone	1 if the origin is in the southern hemisphere, else 0

Returns:

0 if successful

Callable From:

• C++
• Script

Prototype:

double diguy_parse_dms_to_radians(const char* dmsstring);

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

Arguments:

dmsstring

a string of the format described above

Returns:

a double precision floating point value in radians

Callable From:

• C++
• Script

Prototype:

void diguy_format_lat_or_lon(char* outbuf,
    double value,
    bool is_lat,
    bool is_decimal,
    bool value_is_degrees);

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.

Arguments:

outbuf	a buffer into which to copy the resulting string
value	the lat or lon value to be converted into a string
is_lat	boolean indicating latitude (North/South) rather than longitude (East/West)
is_decimal	boolean indicating that decimal degrees are desired, rather than degrees, minutes, and seconds
value_is_degrees	boolean indicating whether the input value is in degrees (as opposed to radians)

Callable From:

• C++
• Script

Prototype:

int diguy_dis_get_ipaddr(char** ipaddr);

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.

Arguments:

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.

Returns:

0 if successful

Callable From:

• C++
• Script

Prototype:

int diguy_dis_get_publish_local_chars();

Description:

Returns whether DI-Guy Networking will publish local characters when online.

C++, Script

Arguments:

none

Returns:

1 if enabled, 0 if not

Prototype:

int diguy_dis_get_display_remote_chars();

Description:

Returns whether DI-Guy Networking will display remote characters when online.

C++, Script

Arguments:

none

Returns:

1 if enabled, 0 if not

Prototype:

int diguy_dis_set_exercise(int exercise);

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

C++, Script

Arguments:

exercise

the exercise id to use

Returns:

0 on success, -1 on failure

Prototype:

int diguy_dis_set_host(int host);

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

C++, Script

Arguments:

host	the host id to use; the host id identifies the local machine

Returns:

0 on success, -1 on failure

Prototype:

int diguy_dis_set_site(int site);

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

C++, Script

Arguments:

site	the site id to use; the site id identifies where the local machine is

Returns:

0 on success, -1 on failure

Prototype:

int diguy_dis_set_port(int port);

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

C++, Script

Arguments:

port	the port number to use

Returns:

0 on success, -1 on failure

Prototype:

int diguy_dis_set_lat_lon(double lat, double lon);

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

C++, Script

Arguments:

lat	the latitude in radians, positive north
lon	the longitude in radians, positive east

Returns:

0 on success, -1 on failure

Prototype:

int diguy_dis_set_ipaddr(const char* ipaddr);

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

C++, Script

Arguments:

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.

Returns:

0 on success, -1 on failure

Prototype:

int diguy_dis_set_display_remote_chars(int display);

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

C++, Script

Arguments:

display

pass 1 if DI-Guy Networking should display remote characters, 0 if not

Returns:

0 on success, -1 on failure

Prototype:

int diguy_dis_set_publish_local_chars(int publish);

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

C++, Script

Arguments:

publish

pass 1 if DI-Guy Networking should publish local characters to the network, 0 if not

Returns:

0 on success, -1 on failure

Prototype:

int diguy_dis_get_position_offset(float* z, float* yaw, float* roll, float* pitch);

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.

Arguments:

z	z offset in meters
yaw	orientation offset in degrees
roll	orientation offset in degrees
pitch	orientation offset in degrees

Returns:

0 on success, -1 on failure

Prototype:

int diguy_dis_set_position_offset(float z, float yaw, float roll, float pitch);

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.

THIS FUNCTION DOES NOTHING if called while VR-Link is online.

Arguments:

z	z offset in meters
yaw	orientation offset in degrees
roll	orientation offset in degrees
pitch	orientation offset in degrees

Returns:

0 on success, -1 on failure

Prototype:

int diguy_dis_get_sync_mode_enabled();

Description:

Gets whether sync mode is enabled when online.

C++, Script

Arguments:

none

Returns:

1 if sync mode is enabled when online, 0 if not

Prototype:

int diguy_dis_get_sync_mode_master();

Description:

Gets whether this machine will serve as sync master when online and in sync mode.

C++, Script

Arguments:

none

Returns:

1 if this machine will serve as sync master when online and in sync mode, 0 if not

Prototype:

int diguy_dis_get_sync_mode_slave_cam();

Description:

Gets whether this machine's camera will be slaved to a remote master when online and in sync mode and not sync master.

C++, Script

Arguments:

none

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

Prototype:

int diguy_dis_set_use_database_coords(int use_database_coords);

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.

C++, Script

Arguments:

use_database_coords

1 if database coordinates should be used, else 0

Returns:

0 if successful, -1 on failure

Prototype:

int diguy_dis_set_use_user_defined_coords(int x);

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.

C++, Script

Arguments:

x	pass 1 if user-defined coordinates should be used, else 0

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

Prototype:

int diguy_dis_set_sync_mode_enabled(int enabled);

Description:

Sets whether sync mode is enabled when online.

The function will fail if DI-Guy is on-line (is participating in an exercise).

C++, Script

Arguments:

enabled

pass 1 if sync mode should be enabled when online, 0 if not

Returns:

0 on success, -1 on failure

Prototype:

int diguy_dis_set_sync_mode_master(int master);

Description:

Sets whether this machine will serve as sync master when online and in sync mode.

C++, Script

Arguments:

master

pass 1 if this machine will serve as sync master when online and in sync mode, 0 if not

Returns:

0 on success, -1 on failure

Prototype:

int diguy_dis_set_sync_mode_slave_cam(int sl_cam);

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

C++, Script

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

Returns:

0 on success, -1 on failure

Prototype:

int diguy_dis_set_sync_mode_camera_offset(float offset_r, float offset_y, float offset_p);

Description:

This function sets the camera orientation offset to be used in sync_mode (when VR-Link is online).

Arguments:

offset_r	orientation offset
offset_y	orientation offset
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

Returns:

0 on success, -1 on failure (VR-Link is online).

Prototype:

int diguy_dis_get_sync_mode_camera_offset(float* offset_r, float* offset_y, float* offset_p);

Description:

This function gets the camera orientation offset to be used in sync_mode (when VR-Link is online).

Arguments:

offset_r	orientation offset
offset_y	orientation offset
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.

Returns:

0 on success, -1 on failure

Prototype:

int diguy_dis_set_sync_mode_camera_slaved(int slaved);

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.

Arguments:

slaved

whether the camera will be slaved when VR-Link is

online, in sync mode, and not sync master.

Returns:

0 on success, -1 on failure

Prototype:

int diguy_dis_get_sync_mode_camera_slaved();

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

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.

Prototype:

void* diguy_dis_get_next_participant_name(char* buf, void* handle);

Description:

This function allows iteration through the list of names remote VR-Link hosts that DI-Guy knows about.

Arguments:

buf	destination buffer for host name (64 bytes is plenty)
handle	return value from last call to the function; pass NULL to get the first host name; pass previous return value to get the next host name

Returns:

void* to be passed as handle argument on the next call. NULL when end of list is reached.

Prototype:

int diguy_dis_set_camera_details_out_of_date();

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.

Returns:

0 on success, -1 on failure

Prototype:

int diguy_dis_get_model_from_septet(const char** chartype, const char** appearance, const int septet[7]);

Description:

Fetches what character type and what appearance should be used for a given DIS entity type septet.

Arguments:

chartype	address of char*, for returning a string which names the DI-Guy character type
appearance	address of char*, for returning a string which names the DI-Guy character appearance
septet	array of seven integers specifying the kind, domain, country, category, subCategory, specific, and extra of the entity in question

Returns:

0 on success, -1 on failure

Prototype:

int diguy_dis_get_septet_from_model(int septet[7], const char* chartype, const char* appearance);

Description:

Fetches what DIS entity type septet should be used for a given character type and appearance.

Arguments:

chartype	a string which names the DI-Guy character type
appearance	a string which names the DI-Guy character appearance
septet	array of seven integers, returned, indicating the kind, domain, country, category, subCategory, specific, and extra of the entity in question

Returns:

0 on success, -1 on failure

Prototype:

int diguy_dis_get_earth_coord(char* outbuf, const float x, const float y, const float z);

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.

Arguments:

outbuf	buffer into which to put the output string
x, y, z	3 floats specifying location

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.

Prototype:

void diguy_dis_toggle_earth_coord_format();

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.

Arguments:

none

Returns:

void

Prototype:

diguyCharacter* diguy_dis_get_character_from_id(char const* id);

Description:

returns the diguyCharacter associated with the entity id specified.

Arguments:

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.

Prototype:

void diguy_dis_enter_vpnet_mode();

Description:

Turns the 'never create' character bit on.

Prototype:

char* diguy_dis_get_name_from_entity(void* reflected_entity);

Description:

This function returns the name corresponding to the passed entity.

The user must not delete the returned string.

Arguments:

reflected_entity

entity to be named

Returns:

entity name

Prototype:

void diguy_dis_establish_new_offsets(int deprecated = 0);

Prototype:

void diguy_dis_set_send_custom_pdus(int val);

Prototype:

int diguy_dis_get_send_custom_pdus();

Prototype:

void diguy_dis_set_client_mode();

Prototype:

void diguy_dis_set_server_mode();

Alphabetical Index

• diguy_dis_deinitialize
• diguy_dis_enter_vpnet_mode
• diguy_dis_establish_new_offsets
• diguy_dis_get_character_from_id
• diguy_dis_get_display_remote_chars
• diguy_dis_get_earth_coord
• diguy_dis_get_exercise
• diguy_dis_get_host
• diguy_dis_get_ipaddr
• diguy_dis_get_lat_lon
• diguy_dis_get_model_from_septet
• diguy_dis_get_name_from_entity
• diguy_dis_get_next_participant_name
• diguy_dis_get_online
• diguy_dis_get_port
• diguy_dis_get_position_offset
• diguy_dis_get_publish_local_chars
• diguy_dis_get_send_custom_pdus
• diguy_dis_get_septet_from_model
• diguy_dis_get_site
• diguy_dis_get_sync_mode_camera_offset
• diguy_dis_get_sync_mode_camera_slaved
• diguy_dis_get_sync_mode_enabled
• diguy_dis_get_sync_mode_master
• diguy_dis_get_sync_mode_slave_cam
• diguy_dis_get_use_user_defined_coords
• diguy_dis_get_utm
• diguy_dis_go_offline
• diguy_dis_go_online
• diguy_dis_initialize
• diguy_dis_set_camera_details_out_of_date
• diguy_dis_set_cfg_file
• diguy_dis_set_client_mode
• diguy_dis_set_display_remote_chars
• diguy_dis_set_exercise
• diguy_dis_set_host
• diguy_dis_set_ipaddr
• diguy_dis_set_lat_lon
• diguy_dis_set_port
• diguy_dis_set_position_offset
• diguy_dis_set_publish_local_chars
• diguy_dis_set_send_custom_pdus
• diguy_dis_set_server_mode
• diguy_dis_set_site
• diguy_dis_set_sync_mode_camera_offset
• diguy_dis_set_sync_mode_camera_slaved
• diguy_dis_set_sync_mode_enabled
• diguy_dis_set_sync_mode_master
• diguy_dis_set_sync_mode_slave_cam
• diguy_dis_set_use_database_coords
• diguy_dis_set_use_user_defined_coords
• diguy_dis_set_utm
• diguy_dis_set_utm_zone
• diguy_dis_toggle_earth_coord_format
• diguy_dis_update
• diguy_format_lat_or_lon
• diguy_parse_dms_to_radians