 |
VR-Link API Documentation for DIS
|
|
VR-Link API Documentation for DIS
|
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 hExerciseConn.h. The DIS version is defined in dExerciseConn.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 (exConnInit.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. For example, if the federation execution name is VR-Link, we assume the FED file is VR-Link.fed.
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 VR-Link.fed. It is in ./bin. If you are using the FOM described by this file, you must copy VR-Link.fed 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:
If you are using the Pitch RTI, make sure that you turn off asynchronous tick.
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 (exConnInit.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 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 Default HLA Command Line Options and Default DIS Command Line Options.
| Default HLA Command Line Options | |||
|---|---|---|---|
| Parameter | Syntax | MTL Parameter | Default |
| Execution name | (-x | –execName) exec_name | execName | VR-Link |
| Federate name | (-N | –federateName) federate_name | federateName | VR-Link |
| FED file name | (-F | –fedFileName) fedfile_name | fedFileName | VR-Link.fed |
| FOM Mapper library name | (-f | –fomMapperLib) libname | fomMapperLib | |
| FOM Mapper initialization data | –fomMapperInitData data | fomMapperInitData | |
| Notification level | (-n | –notifyLevel) level | DtNotifyLevel | 2 |
| RPR FOM revision | –rprFomRevision | rprFomRevision | 1 |
| RPR FOM version. (0.5, 0.7, 0.8, 1.0, 2.0006, 2.0014, or 2.0017) | –rprFomVersion version_number | RprFomVersion | 1.0 |
| Default DIS Command Line Options | |||
|---|---|---|---|
| Parameter | Syntax | MTL Parameter | Default |
| DIS port | (-P | –disPort) port | disPort | 3000 |
| Exercise ID | (-x | –exerciseId) ID | exerciseId | 1 |
| Application number | (-a | –appNumber) number | appNumber | 2 |
| Site ID | –siteId ID | siteId | 1 |
| Destination address | (-A | –destAddrString) address | destAddrString | "" |
| Device address | –deviceAddress address | deviceAddress | |
| Send buffer size | –sendBufferSize size | sendBufferSize | -1 (use sys-tem default) |
| Receive buffer size | –recvBufferSize size | recvBufferSize | -1 (use sys-tem default) |
| Multicast TTL | –mcastTtl ttl | mcastTtl | -1 (use sys-tem default) |
| Multicast address | (-S | –mcastAddresses) addresses | ||
| Notify level | (-n | –notifyLevel) level | DtNotifyLevel | 2 |
| Suppress self-reflection | –suppressSelfReflect | suppressSelfReflect | false |
| Use IPv6 | –useIpv6 | useIpv6 | false |
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 dExerciseConn.h and hExerciseConn.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 >>]