 |
VR-Link C# API Documentation
|
All Classes Namespaces Files Functions Variables Enumerations Enumerator Properties Events Macros Pages
|
VR-Link C# API Documentation
|
In general, an HLA federation or DIS exercise can be defined as a collection of simulation applications communicating with each other through the exchange of data (HLA messages or DIS PDUs). A simulation application (called a federate in HLA) can, in turn, be defined as a participant in an exercise. Such an application may simulate one or more entities.
VR-Link's class DtExerciseConn is a simulation application's interface to an exercise. The application sends data to other applications, and receives data from other applications, through its DtExerciseConn. Virtually all applications based on VR-Link make use of a DtExerciseConn.
There are HLA and DIS versions of DtExerciseConn. For HLA, the DtExerciseConn exchanges data with other applications by making calls to the RTI. For DIS, data is usually exchanged through the sockets-related system calls sendTo() and recvFrom().
The HLA version of DtExerciseConn is defined in exerciseConnHLA.h. The DIS version is defined in exerciseConnDIS.h. If you are writing an application for use with both HLA and DIS, you do not have to include both header files. You can include exerciseConn.h, which includes the appropriate version depending on whether or not you have included the DtHLA=1 definition in your compile line.
Although the two versions of DtExerciseConn are defined separately, most public member function names and signatures are shared by the two versions, so that you can make most of these calls regardless of which protocol you are using. Much of this commonality is enforced because both versions are derived from DtBaseExerciseConn, an abstract class that defines much of the DtExerciseConn interface.
Creating a DtExerciseConn must be done differently for HLA and DIS because they require different initialization parameters.
To create a DtExerciseConn in HLA, you must provide a federation execution name and a federate name. You can specify this information in the DtExerciseConnInitializer (exerciseConnInitializer.h) and pass it in to the DtExerciseConn through the constructor or you can specify it in one of the other DtExerciseConn constructors. One of DtExerciseConn's constructors lets you specify the name of the FED file that you want to use. The FED file provides information about the FOM to the RTI and to VR-Link. If you do not provide the name of a FED file to the DtExerciseConn constructor, we assume that you are using a file with the same name as the federation execution, but with a .fed extension, or a .xml extension if using HLA 1516 or later. For example, if the federation execution name is VR-Link, we assume the FED file is VR-Link.fed or VR-Link.xml.
VR-Link looks for the FED file in the directory from which you run your application. Make sure that the FED file that you are using with your DtExerciseConn is in this directory.
The default FED file supported by VR-Link is RPR_FOM_v2.0_1516-2010.xml. It is in ./bin64. If you are using the FOM described by this file, you must copy the default FED file to the directory that you are running from.
All applications that want to interact in the same HLA world must use the same federation execution name, and the exact same FED file.
The federate name is a name you give to your application. It is used for RTI diagnostics. Federate names do not have to be unique in a federation.
The DtExerciseConn constructors:
To create an exercise connection for DIS, you need:
As with HLA, you can specify these values in the DtExerciseConnInitializer and pass them to the DtExerciseConn constructor, or specify them directly in the constructor. All applications that want to interact in a DIS exercise must use the same UDP port number and exercise ID number.
By default, DIS PDUs sent through the DtExerciseConn are sent to the broadcast address of the machine's primary network interface. The DtExerciseConn receives any unicast or broadcast packets destined for the machine on the specified port. Additional constructors and functions of the DIS version of DtExerciseConn allow greater flexibility in setting up your network connection, and are discussed in 8.3 - Configuring Your Connection to the DIS Network.
You can specify default initialization values in DtExerciseConnInitializer. You can enable parsing of command line input, or loading XML or MTL files to VR-Link-based applications if you use a DtVrlApplicationInitializer (exerciseConnInitializer.h). You can also save the state of the DtVrlApplicationInitializer class to an XML file. For an example of using an MTL file, please see f18.mtl.
When you use this constructor, all of the initialization values, which are protocol-dependent, are in the DtExerciseConnInitializer, the configuration file, or the command line. Therefore, the initialization code is completely protocol independent. The last parameter passed into the constructor is the application name. It is printed to the screen when the command line usage is printed out, and it also specifies the default federate name in HLA.
The DtVrlApplicationInitializer class plays a central role in the startup and configuration process of a VR-Link application. Upon initialization, it parses the command-line arguments to determine if a user-specified configuration file has been provided using the --exConnConfigFile argument. If such a file is specified, the initializer loads it using the exerciseConnectionConfig()->loadFile() method; otherwise, it defaults to loading the standard configuration file.
After the configuration file is loaded, the initializer proceeds to initialize all configuration variables and applies the relevant settings to the exercise connection, ensuring that the application is properly configured for the intended simulation environment. Additionally, DtVrlApplicationInitializer supports the loading of MTL files, which allows for advanced configuration and customization beyond the standard XML-based settings. This comprehensive approach ensures that both basic and advanced configuration needs are met during application startup.
The DtExerciseConnConfig class is responsible for managing all exercise connection settings in a protocol-independent manner, supporting both DIS and HLA parameters. It provides a unified interface for configuring connection details, allowing users to specify options such as port, exercise ID, site ID, application number, buffer sizes, multicast addresses, and other protocol-specific settings. Configuration can be loaded from XML and MTL files, enabling flexible and extensible setup for a wide range of simulation scenarios.
The class maintains a comprehensive set of configuration variables, which include options for file logging and advanced protocol features. Through its API, users can programmatically set and retrieve all relevant parameters, ensuring that the exercise connection is tailored to the needs of the application and simulation environment.
The exConnConfigFile is a command-line and configuration variable that allows users to specify external configuration files for exercise connection settings. This mechanism is protocol-independent and is managed by the DtExerciseConnConfig class. The user-specified configuration file can be provided via the command line using the --exConnConfigFile argument, or the MAKOne-2025-Config.xml file will be loaded by default. You can find a copy of the MAKOne-2025-Config.xml file in your VR-Link install's bin64 directory.
The MAKOne-2025-Config.xml file is the default configuration file provided with VR-Link. It contains essential connection parameters for both DIS and HLA exercises, including:
The file is structured in XML format, making it easy to edit and extend for custom requirements. Users can modify this file to match their simulation environment and exercise needs.
Default values:
Example excerpt:
myApp.exe --exConnConfigFile customConfig.xmlDtVrlApplicationInitializer parses the arguments and detects the custom config file.DtExerciseConnConfig::loadFile().DtExerciseConnConfig::loadFile(const DtString& fileName)DtVrlApplicationInitializer::parseCmdLine()DtVrlApplicationInitializer::loadFile(const DtString& fileName)The command parser can accept individual letter commands, prefaced by a dash (-), or multiple letter commands, prefaced by two dashes (--). The default commands and values specified in DtExerciseConnInitializer are listed in Protocol Independent Command Line Options Default HLA Command Line Options and Default DIS Command Line Options.
| Protocol Independent Command Line Options | |||
|---|---|---|---|
| Parameter | Syntax | MTL Parameter | Default |
| Displays usage information and exits. | (-h | --help) | ||
| Displays version information and exits. | (-v | --version) | ||
| Notification level | (-n | --notifyLevel) <level> | notifyLevel | 2 |
| Exercise Connection Configuration File | --exConnConfigFile <string> | ||
| Site ID | (-s | --siteId) <int> | siteId | 1 |
| Application number | (-a | --appNumber) <int> | appNumber | 1 |
| Output Interval | --outputInterval <double> | outputInterval | 5.0 |
| Log file to use | --logFileName <filename> | ||
| Notify level in log file to use. | --fileNotifyLevel <level> | 2 | |
| Ignores the rest of the labeled arguments following this flag. | (-- | --ignore_rest) | ||
| Default HLA Command Line Options | |||
|---|---|---|---|
| Parameter | Syntax | MTL Parameter | Default |
| Execution name | (-x | --execName) <string> | execName | VR-Link |
| Federate Type | (-p | --federateType) <string> | ||
| Federate name | (-N | --federateName) <string> | federateName | |
| FED file name | (-F | --fedFileName) <string> | fedFileName | RPR_FOM_v2.0_1516-2010.xml |
| Add FOM Modules (Accepted multiple times) (HLA Evolved) | --fomModules <string> | fomModules | |
| List of FOM Modules to use(HLA Evolved) | --setFomModuleList <string> | ||
| MIM Module (HLA Evolved) | --mimModule <string> | mimModule | "" |
| Local Settings Designator (HLA Evolved) | (-S | --localSettingsDesignator) <string> | ||
| FOM Mapper Library name | (-f | --fomMapperLib) <string> | fomMapperLib | |
| FOM Mapper Initialization Data | --fomMapperInitData <string> | fomMapperInitData | |
| RPR FOM Version (0.5, 0.7, 0.8, 1.0, 2.0006, 2.0014, 2.0017, or 2.0) | --rprFomVersion <double> | rprFomVersion | 1.0 |
| RPR FOM Revision | --rprFomRevision <int> | rprFomRevision | 1 |
| NETN FOM Version | --netnFomVersion <double> | netnFomVersion | 1.0 |
| NETN FOM Revision | --netnFomRevision <int> | netnFomRevision | 1 |
| Ignore Advisories | --ignoreAdvisories | useAdvisories | 1 |
| Disable RTI Compiler version check | --noRtiCompilerCheck | ||
| Default DIS Command Line Options | |||
|---|---|---|---|
| Parameter | Syntax | MTL Parameter | Default |
| DIS Port | (-P | --disPort) <int> | disPort | 3000 |
| Exercise ID | (-x | --exerciseId) <int> | exerciseId | 1 |
| Destination Address | (-A | --destAddrString) <string> | destAddrString | "" |
| Device Address | --deviceAddress <string> | deviceAddress | |
| Send Buffer Size | --sendBufferSize <int> | sendBufferSize | -1 |
| Receive Buffer Size | --recvBufferSize <int> | recvBufferSize | -1 |
| Multicast TTL | --mcastTtl <int> | mcastTtl | -1 |
| Multicast Address | (-S | --mcastAddresses) <string> | ||
| Suppress Self-Reflection | --suppressSelfReflect | suppressSelfReflect | false |
| Use IPv6 | --useIpv6 | useIpv6 | false |
| DIS Version | --disVersion <int> | disVersion | 6 |
| Use Asynchronous I/O | --useAsyncIO | useAsyncIO | 0 |
| Subnet Mask to use | --subnetMask <string> | ||
| Attribute PDU Strategy | --attributePduStrategy <int> | ||
The next table describes the most commonly used protocol-independent member functions for DtExerciseConn.
| DtExerciseConn Member Functions | |
|---|---|
| Function | Description |
| addPostDrainCallback() | Lets you register functions (with the DtExerciseConn) that you want to have called automatically each time drainInput() is called. |
| removePostDrainCallback() | Lets you unregister functions that you no longer want to have called each time drainInput() is called. |
| drainInput() | Causes to read and process input from the exercise. Most user callbacks are executed from within drainInput(). |
| nextEventID() | Generates consecutive event IDs for use in fire, detonate, or collision interactions.For DIS, the event ID is composed of the site ID, application ID, and event number based on the exercise connection’s site and host. For HLA, the event ID is composed of the object ID (from setObjectId()) and event number.You can choose your own event IDs in both DIS and HLA. Event IDs are not managed by the RTI as Object IDs are. Therefore it is up to the application to ensure that event IDs are unique. |
| send() sendStamped() | Sends interaction messages, object updates, and DIS PDUs to the exercise. sendStamped() includes a time stamp with outgoing messages. |
| setTimeStampType() | Lets you specify the type of time stamp being sent. The options are DtTimeStampAbsolute and DtTimeStampRelative. |
| timeStampType() | Returns the time stamp type. |
| vrlinkVersion() | This static function returns the version of VR-Link that you are running. |
The following sections contain more detailed information about these functions.
The send() and sendStamped() member functions are used to send interactions to the exercise. For more information, please see 4.3.1 Sending Interactions.
Sending of object state information is typically handled using higher-level object-management classes, such as DtEntityPublisher, rather than by sending individual update messages directly using DtExerciseConn. For more information, please see 4.5 - Working with Locally Simulated Entities.
The DtExerciseConn::drainInput() function receives and processes information from the RTI or the DIS network. From within DtExerciseConn::drainInput(), VR-Link executes any callbacks that you have registered on DtInteractions (for either HLA or DIS), DtPdus (for DIS), or various RTI services (for HLA).
Your application should call DtExerciseConn::drainInput() periodically, usually once per simulation loop. This is true for HLA even if your application does not care about remotely simulated objects or remotely generated interactions, because the RTI requires RTI::tick() to be called periodically.
drainInput() repeatedly calls RTI::tick() until it fails to return RTI::RTI_TRUE (meaning there is no more data waiting to be read).
The mintime argument lets you specify a minimum amount of time to spend before returning. This value is passed to RTI::tick().
drainInput() reads PDUs from the network directly.
The optional timeout argument to drainInput() lets you specify a time (in seconds) after which drainInput() should return even if there is more data left to be read. A value of -1 (the default) is to never return if there is still data to be read. A value of 0 means return immediately. The second argument to drainInput() specifies the number of packets to be read or the number of times to call RTI::tick() in between tests of whether the timeout has been exceeded.
Post-drain callbacks are callback functions that you can register with a DtExerciseConn, and have called automatically by DtExerciseConn::drainInput() immediately before it returns. Post-drain callbacks are called after all interaction, PDU, and RTI service callbacks have been made. For more information about callbacks in general, please see 2.7.3 Using Callbacks.
Post-drain callbacks have the following function signature:
They are registered with a DtExerciseConn using addPostDrainCallback(), and unregistered using removePostDrainCallback(). The value passed to your callback function as the usr pointer is the value that was passed as the usr argument to addPostDrainCallback().
The most common use of post-drain callbacks is to get around an HLA restriction. RTI services cannot be invoked from within user callbacks on other RTI services. For example, at the time that you are processing an incoming interaction within an interaction callback, you cannot send an interaction in response. But you can register a response-sending post-drain callback that is executed after all RTI service callbacks have been invoked, when it is safe to send interactions. For more information, please see 4.3.2.1 Making RTI Calls in Response to Interactions.
DtExerciseConn's setTimeStampType() function lets you set the time stamp type of your application to either DtTimeStampAbsolute or DtTimeStampRelative. Use DtTime-StampAbsolute if your local clock is synchronized to a global exercise clock, and you want to use the values of time stamps on messages from other synchronized hosts in dead-reckoning calculations. The default, DtTimeStampRelative, indicates that your local clock is not necessarily synchronized to anyone else's clock, and therefore time of receipt is used in dead-reckoning rather than incoming time stamp values. For more information, please see 2.7.6 Timestamps.
When using absolute timestamping, make sure to keep VR-Link simulation time in step with your system clock by passing the current time to setSimTime() each frame.
If VR-Link fails during initialization, the default behavior is to abort. DtExerciseConn's constructor has an optional argument (status) that you can use to store the result of initialization. When this argument is non-NULL, the exercise connection does not exit if a non-license management related problem occurs during startup. The cause of the failure is put into this variable to be inspected later. For more information, please see exerciseConnDIS.h and exerciseConnHLA.h.
To cleanly check for license management errors, two global functions enable you to check whether a VR-Link or RTI license is available from the license server before they try to create any VR-Link data structures. They are DtHaveVrLinkLicense() and DtHaveRtiLicense() (defined in checkLicense.h). These functions return a bool instead of calling DtFatalError and exiting.
[<< Introduction to the Protocol-Independent Interface] [Home] [Top of Page] [Working with Interactions >>]