VR-Link Capabilities

This example illustrates a simple, listen-only VR-Link application. This application can be compiled for DIS or HLA, and contains no protocol-specific code.

With each iteration of the loop, the program prints an entity's updated, dead-reckoned position in topographic coordinates. In addition, if a fire PDU or interaction is detected on the network, the program prints a message showing the entity ID of the attacker.

1 // Define a callback to process fire interactions
2 void fireCb(DtFireInteraction* fire, void* usr)
3 {
4    std::cout << "Fire Interaction from " << fire->attackerId().string() << std::endl;
5 }
6
7 int main(int argc, char** argv)
8 {
9    // Create a connection to the exercise or federation execution
10   // based on initialization arguments passed as command-line arguments
11   // This causes the application to connect to the DIS network,
12   // HLA execution.
13
14   DtVrlApplicationInitializer appInit(argc, argv, "VR-Link Listen");
15
16   DtExerciseConn exConn(appInit);
17
18   // Register a callback to handle fire interactions
19   DtFireInteraction::addCallback(&exConn, fireCb, NULL);
20
21   // Create an object to manage remote entities.
22   DtReflectedEntityList rel(&exConn);
23
24   while (1)
25   {
26     // Tell VR-Link the current value of simulation time
27     exConn.clock()->setSimTime(exConn.clock()->elapsedRealTime());
28     // Process any incoming messages
29     exConn.drainInput();
30
31     // Find the first entity in the reflected entity list
32     DtReflectedEntity *first = rel.first();
33
34     if (first)
35     {
36       // Grab its state repository, where we can inspect its data
37       DtEntityStateRepository *esr = first->entityStateRep();
38
39       // Print the position
40       std::cout << "Position: " << esr->location().string() << std::endl;
41     }
42
43     // Sleep till next iteration
44     DtSleep(0.1);
45   }
46 }

Connecting to an Exercise

In lines 14-16, the program creates a DtExerciseConnection. This connection serves as the program's interface to an exercise. Depending on whether the application is compiled for DIS, HLA 1.3, HLA 1516-2000, or IEEE 1516-2010, the DtExerciseConn constructor will ask the DtVrlApplicationInitializer for the appropriate initialization parameters, such as DIS port number or the HLA federation execution name. If you do not want to use VR-Link's command-line and configuration file-based initializer class, you can call alternate, protocol-specific constructors to create a DtExerciseConn.

Managing State and Interaction Information

Applications based on VR-Link typically use callbacks to handle incoming interactions such as fire, detonations, and collisions. For example, a callback named fireCb is registered with the DtFireInteraction class at line 19. This callback (defined at line 2) prints a message containing the attacker ID. It executes whenever the exercise connection receives a Fire interaction or PDU during a call to drain- Input().

Tracking Entities

We create a reflected entity list in line 22 to keep track of entities found on the network. The entity list tracks the arrival and departure of entities, performs dead reckoning, manages timeouts, and performs other entity-tracking tasks.

Listening to the Network

At the start of each iteration, the program sets VR-Link simulation time (line 27) to provide a common time value for use by time-related operations that occur within an iteration of the loop (such as the dead-reckoning of multiple entities). The drainInput() call (line 29) reads and processes any messages arriving through the exercise connection. This call triggers the execution, if needed, of any callbacks you have registered for that exercise connection. In HLA, this is where the RTI gets ticked. In line 32, the program finds the first entity in the entity list, then in line 37, retrieves the pointer to the entity's entity state repository, where VR-Link stores the values describing the remote entity's state. Line 40 obtains and prints the dead-reckoned entity location.

This example illustrates a simple send-only application that simulates the flight of an F18 aircraft. The program begins by sending an HLA fire interaction or a DIS fire PDU. Thereafter, the F18 flies north for 10 seconds, updating its position by sending HLA attribute updates or DIS entity state PDUs.

1 int main(int argc, char** argv)
2 {
3    // Create a connection to the exercise or federation execution
4    // based on initialization arguments passed as command-line arguments
5    // This causes the application to connect to the DIS network or
6    // HLA execution.
7
8    DtVrlApplicationInitializer appInit(argc, argv, "VR-Link Listen");
9
10   DtExerciseConn exConn(appInit);
11
12   DtEntityType f18Type(DtPlatform, DtPlatformDomainAir,
13   DtUnitedStates, DtFighter, DtF18, 0, 0);
14
15   // Create an entity publisher for the entity we are simulating
16   DtEntityPublisher f18EntityPub(f18Type, &exConn, DtDrDrmRvw, DtForceFriendly);
17
18   // Hold on to its state repository, where we can set data
19   DtEntityStateRepository *esr = f18EntityPub.entityStateRep();
20
21   // Create a topographic view on the state repository, so we
22   // can set position information in topographic coordinates
23   double refLatitude = DtDeg2Rad( 35.699760);
24   double refLongitude = DtDeg2Rad(-121.326577);
25   DtTopoView f18TopoView(esr, refLatitude, refLongitude);
26
27   // We can use the ESR to set state
28   esr->setMarkingText("VR-Link");
29
30   DtVector position(0, 0, -100);
31   DtVector velocity(20, 0, 0);
32
33   // Send a Fire Interaction
34   DtFireInteraction fire;
35   fire.setAttackerId(f18EntityPub.globalId());
36   exConn.sendStamped(fire);
37
38   // Main loop
39   DtTime timestep = 0.05;
40   DtTime simTime = 0;
41   while (simTime <= 10.0)
42   {
43      // Tell VR-Link the current value of simulation time
44      exConn.clock()->setSimTime(simTime);
45
46      // Process any incoming messages
47      exConn.drainInput();
48
49     // Set the current position information
50     f18TopoView.setLocation(position);
51     f18TopoView.setVelocity(velocity);
52
53     // Call tick, which insures that any data that needs to be
54     // updated is sent.
55     f18EntityPub.tick();
56
57     // Set up for next iteration
58     position[0] += velocity[0] * timestep;
59     simTime += timestep;
60
61     // Wait till real time equals simulation time of next step
62     DtSleep(simTime - exConn.clock()->elapsedRealTime());
63   }
64 }

Connecting to an Exercise

Like the listen-only example, this program creates a DtExerciseConnection to provide an interface to the RTI or DIS network (lines 8 through 10).

Managing Entities

Line 12 defines the entity type the F18 will use. To be visible to other applications in the exercise, each locally-simulated entity requires a DtEntityPublisher, created in line 16. The entity publisher manages the generation of messages for this particular entity. It provides an entity state repository where you can set state values, and a tick() function, which causes state information to be sent to the network if necessary.

Line 19 sets up a pointer to the entity state repository, then line 25 creates a topographic view on that repository. This lets us set the entity's positional data using topographic coordinates, rather than the default geocentric coordinates. (Lines 23 and 24 hard code the coordinates for this example.) Line 28 shows an example of storing a non-positional state value in the repository.

Sending Interactions

An example of sending an interaction appears in lines 34-36. You can send the interaction using the exercise connection's sendStamped() function. You can use sendStamped() to send state updates as well, but it is preferable to let the entity publisher send state updates for you, using data in the entity state repository.

Sending State Messages

The main loop executes twenty times per second for ten seconds. As in the listen-only example, this program sets simulation time at the start of each iteration (line 44). While this program's main purpose is to demonstrate the sending of data to the network, it is not a true send-only application. Incoming data is also processed with the drainInput() call on line 47. This call is required for HLA because this is where we tick the RTI. The program updates the F18's positional data in its entity state repository in lines 50 and 51, and ticks the entity publisher in line 55 to send the updated data onto the network. Thereafter, the only remaining tasks are to increment the F18's position, increment the simulation time, and sleep until it's time to begin the next iteration.

Most applications need to maintain a database containing current information about the state of all remotely simulated entities (or other types of objects). For example, if you have a 3D-graphics-based application, you might want to query this entity database each frame to determine where to draw each entity. The RTI does not maintain this database for you. In fact, it doesn't "remember" the state of any objects at all. The RTI just passes update messages among federates.

Using the RTI API alone, you would need to explicitly subscribe to each object class you are interested in, then subclass RTI::FederateAmbassador and implement callbacks (by overriding virtual functions) for the discoverObjectInstance, removeObjectInstance, and reflectAttributeValues services. You would need to implement an object list, and add objects to it as a result of discoverObjectInstance calls, and remove objects from it as a result of removeObjectInstance calls. In addition, you'd probably want to call RTI::RTIambassador's requestObjectAttributeUpdate after you discover an object, to make sure you get updates for all needed attributes. (If you don't do this, and attribute values haven't changed since the last time they were sent, they will not be sent to you). When you receive a reflectAttribute- Values call, you would need to find the appropriate object in your list, decode the update message, and place the updated values into the structure you are using to store the current state. (Decoding an update message means converting attribute values from opaque streams of bytes to more useful structures or C++ classes. For example, you may need to deal with byte-alignment issues, littleendian/ big-endian conversions, doing byte arithmetic to iterate through variable length fields in complex attributes, etc.)

Using VR-Link, you just create an instance of the DtReflectedEntityList class. It subscribes to object classes, requests attribute updates, and does all the bookkeeping above. It automatically creates and deletes instances of DtReflectedEntity based on discover and remove service calls. It automatically receives and decodes update messages into the appropriate DtReflectedEntity's DtEntityStateRepository. It also performs dead-reckoning and (optionally) smoothing. It means that you never even have to worry about when individual attribute update messages are received from the RTI. You can just ask the DtReflectedEntityList for the current dead-reckoned position of a particular entity (identified by handle or by name), and it will give it to you. The complete VR-Link-based application below prints the entire current state of the first discovered entity each frame, including dead-reckoned position and orientation. Of course, it also handles the mechanics of properly creating (if necessary), joining, resigning and destroying (if necessary) the federation execution as well.

  int main(){DtExerciseConn exConn("VR-Link", "MyFederate");DtReflectedEntityList rel(&exConn);while(1){exConn.clock()->setSimTime(exConn.clock()->absRealTime());exConn.drainInput();if (rel.first()){rel.first()->entityStateRep()->printData();}}}

On the sending side, VR-Link will save you just as much bookkeeping as on the receiving side, perhaps more. Using the RTI's API alone, you would need to query the RTI for the object class handle you want to use, and for the attribute handles of any attributes you want to publish. You would then need to publish the object class. You would subclass RTI::FederateAmbassador, and write callbacks for start/StopRegistrationForObjectClass and turnOn/OffUpdatesForObjectInstance services in order to be notified about whether any remote federates are interested in the classes and attributes you are publishing. You would register your object instance. You would need to maintain a data structure containing the current state of the object you are simulating, and a similar data structure containing the attribute values you have last sent through the RTI. Each frame, you would need to determine whether any values have changed (perhaps by enough to exceed a threshold) since the last time it was sent. Once you've determined which attributes need to be sent this frame, you would need to create an RTI::AttributeHandleValuePairSet, encode values into it for the relevant attributes (all the same issues apply as in decoding), and send the update using updateAttributeValues. In addition, you'd need to write a federateAmbassador callback for provideAttributeUpdate. You need to maintain a list for each object you are simulating of the attributes that have been requested since the last time they were sent. You need to add attributes to this list when you get a provideAttributeUpdate callback, and remove attributes from the list when you send updates.

Using VR-Link, you just create an instance of the DtEntityPublisher class, set current values for attributes each frame, and call tick(). DtEntityPublisher publishes the class, keeps a record of the values that have been sent through the RTI, performs the comparisons to determine which attributes need to be sent because they have changed, keeps track of which attributes are actually needed by remote federates, processes provideAttributeUpdate callbacks and ensures that attributes that have been requested in this way are sent even if their values have not changed, encodes updates when necessary and sends them. Application code looks like this:

VR-Link's top-level API is FOM-independent, in that it allows you to set and inspect the state of local and remote objects, and the data contained in locally generated or received interactions, without regard to how the data is actually represented in a FOM. This top-level API includes the object publishers, reflected objects, reflected object lists, state repositories, and interaction classes. The implementations of these classes consult a VR-Link object called a FOM Mapper for help in encoding and decoding data as dictated by your current exercise's FOM. A FOM Mapper for a particular FOM is built by writing encoding and decoding functions and registering them with a DtFomMapper object. When we say that VR-Link comes with built-in support for the RPR FOM, what we mean is that we have implemented a FOM Mapper for the RPR FOM, and that this FOM Mapper is distributed with VR-Link. This means that you have out-of-the-box interoperability with RPR-FOM-based federations without having to implement a FOM Mapper yourself. However, the techniques that we used for implementing the RPR FOM Mapper are no different than the ones a customer would use to create a FOM Mapper for their new FOM. In other words, user-defined FOM Mappers are treated no differently than the built-in RPR FOM Mapper.

When working with FOMs that have the same concepts as the VR-Link API, you can switch from FOM to FOM just by modifying the FOM Mapper, which you can do without affecting the top-level API. This means that application code written to the top-level API does not need to change when switching from FOM to FOM. When a FOM Mapper is implemented in a DLL, applications do not even need to be recompiled in order to switch to a new FOM.

For example, in one FOM (such as the RPR FOM), position data may be represented in geocentric coordinates in an attribute named " Position". In another, it might be represented in topographic coordinates in an attribute named " Location". In either case, position data is available to application code through VR-Link in the manner indicated by its FOM-independent API - as geocentric data obtainable using DtEntity-StateRepository's location() member function. FOM Mapping code takes care of converting from the various FOMs' representations to the representation chosen by VR-Link.

Because FOM-Mapping code can be dynamically loaded by VR-Link as a plug-in, applications do not even need to be recompiled when switching among such FOMs, as long as the target FOM includes the same concepts as VR-Link's API. When you build a FOM Mapper as a DLL, you can even use it with applications for which you don't have source code. For example, you can tell the MAK Data Logger, VR-Forces, or any application in the VR-Vantage product line if you want to use those tools in federations that do not use the default RPR FOM.

If you are using FOMs that contain concepts not found in the VR-Link API, you must extend the VR-Link API with new classes to represent your FOM's new objects and interactions. Specifically, you need to create new classes derived from our base state repository, publisher, reflected object, and reflected object list classes to handle your new FOM elements. Although you can do this by hand coding or cutting and pasting, we strongly recommend using the VR-Link Code Generator to do the work of extending VR-Link automatically.

The VR-Link Code Generator reads any HLA FOM and automatically generates VR-Link extensions for that FOM. The tool produces fully formed C++ source and header files, along with the Microsoft Visual C++ solution files and the UNIX® Makefiles required to compile them into a VR-Link extension library. It also supports the C# API.

The generated classes are ready to use for publishing and tracking new classes of HLA objects, and for sending and receiving custom interactions. The generated code has the same "look and feel" as built-in VR-Link classes. The VR-Link Code Generator works with HLA-1.3-style OMT files and IEEE-1516-style XML-based FOMs.

Extending the RPR FOM

VR-Link users often need to extend the RPR FOM. Although you could use the VR-Link Code Generator to generate state repositories, publishers, and so on, for your entire RPR-based FOM, it doesn't really make sense to do that, since VR-Link already has built-in support for the underlying RPR FOM. Instead, you can instruct the VR-Link Code Generator to generate VR-Link extensions just for the classes that are not covered by VR-Link already. The Code Generator's GUI allows you to select which classes to generate code for.

For cases where your FOM changes the name or data representation of some existing RPR FOM classes or attributes, you don't need to generate API extensions at all. Just start with the built-in RPR FOM Mapper, and register a few new mapping functions to handle the changes.

Most VR-Link customers can seamlessly transition their federates from HLA 1.3 to either IEEE 1516-2000 or IEEE 1516-2010 (also known as HLA Evolved) - without changing any code! The same top-level protocol-independent API that has always supported both DIS and HLA 1.3 supports both IEEE 1516-2000 and IEEE 1516-2010 as well. Customers write federate code once and choose a protocol version at compile time. If you use the MAK RTI, you will probably even be able to mix and match HLA 1.3 and IEEE 1516 federates in the same federation. (For most services, we were able to use the same on-the-wire message format for our HLA 1.3 version and IEEE 1516 versions).

HLA Evolved is the latest version of the IEEE HLA 1516 standard, which was finalized in August 2010. VR-Link 4.0 and later fully supports HLA Evolved.