 |
VR-Link API Documentation for HLA Evolved
|
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
|
VR-Link API Documentation for HLA Evolved
|
The included example is the complete source code for a plug-in that adds support for Laser Designators in DIS and HLA.
It uses the C++ VR-Link toolkit and the VR-Link C# library.
The project files for the example are broken down into five projects. One project for the protocol independent message representations to be loaded into the message factory, then 4 protocol project to create plug-ins that load a protocol specific strategy into the strategy factory and registers it with the initialization strategy so that it gets created on connection. Since VR-Link is protocol independent and uses compiler flags to determine which protocol to support, most of the source code for the example is shared between the 4 protocol specific projects. Changes to files in project will show up as changes in other projects.
Since the project files are configured to use environment variables to find the C++ VR-Link SDK, it is recommended to edit the included setupEnvironment.bat file to match your system and use it to launch Visual Studio.
Laser designators are stateful objects within DIS and HLA and change their state when painting a target. This means that we will need a discovery, state update, and removed message to inform VR-Link C# about laser designators.
These three messages are defined in laser.lua. Two things to note: entity ID’s are transferred to VR-Link C# as strings and all positions are vectors in VR-Link C#.
The Laser Designator plug-in loads the laser designator messages into the message factory in its initManagedInterfaceModule() function:
The protocol specific laser designator plug-ins load their specific strategy into the strategy factory and register with the initialization strategy to be loaded during connection.
When the laser designator strategy is created, it registers interest in laser object messages with ManagedInterface. It does this by wrapping its handler member functions with a delegate and passing this delegate to ManagedInterface:
It is important to remember to remove these delegates from ManagedInterface during shutdown so that they do not get called after the strategy is destroyed.
The initialization function of the laser designator strategy finds the exercise connection shared resource, creates a reflected laser designator list, and installs some callbacks on it to listen for laser designators coming from the DIS/HLA network. It also creates a laser designator publisher list to hold publishers that it creates to mirror laser designators being controlled in VR-Link C#.
Since this initialization function will be run more than once, it protects itself against being initialized more than once. In the event it cannot get the shared resource exercise connection, it may return false, causing it to be run again until is able to get the shared resource and fully initialize.
During the tick function, which is called every frame, the Laser Designator strategy updates any laser designator publishers that it created to mirror laser designators from VR-Link C# to the DIS/HLA network.
The strategy contains several callbacks for registering with VR-Link as well as with the ManagedInterface message handlers to handle discovery, removal and state update of laser designators from both the DIS/HLA network and within VR-Link C#. These callbacks marshal the data to and from the laser designator messages and VR-Link data structures ensuring to convert entity names and terrain coordinates using the conversion routines in the initialization strategy and terrain strategy respectively.
There are a few things that need to be defined in C# to now receive and send laser designators. The first step is to define a .lua file that will output a state message, a discovery message, and a removed message. This was covered in the message definition section. Here is an example of such:
Of course, as we have learned from the message definition section, this will output C# files defining the messages we supplied. Next, we must define a state repository class for laser designators. The state repository contains the items that make up the object being reflected, in our case, a laser designator.
To define a laserStateRepository, we derive from the VR-Link C# library class StateRepository. The StateRepository class contains a map of class members to their name. They are stored as C# "object" classes with a string as the key. This allows the StateRepository to remain very flexible in its use. To define and set new variables in our laserDesignator, we use the setAttribute function in the constructor with some initial value to signify the type.
We use the getAttribute function to get an attribute from the repository, casting the return value to the type we used in setAttribute.
Lastly, we need to provide functions that update from a state message, and output a state message from current values. These will be very simple functions that assign the state repository values to their corresponding state message values, and vice versa.
Next, we will create the reflected object that will be populated when a remote laser designator is discovered. The reflected object class will contain the state repository we just defined, as well as a constructor as well as a few wrappers around some of the state repository functions.
Now that we have a reflected object, we can define our reflected object list. The reflected object lists are where the callbacks for discovery, update, and removed are registered and handled. In other words, to receive incoming laser designators, you would construct the ReflectedLaserDesignatorList. The reflected list needs an exercise connection to be constructed, and will also create two maps of strings to reflected objects (entityIds to ReflectedLaserDesignators). These two maps handle undiscovered lasers and discovered lasers.
In the constructor, we will set the exercise connection to what was given, and register our callbacks with that exercise connection.
We then define some delegates to handle anything specific we want to happen when our callbacks are reached.
Lastly, we define the callback functions that we registered with the exercise connection. Here are a few examples.
As you can see, there are some helper functions to do some of the work required after a callback. This is typically how callbacks are handled, but once you have entered your callback, you can handle the information any way you would like. At this point we have all that we need to receive a laser designator from VR-Link, but we have not handled publishing our VR-Link C# laser designators to VR-Link. To achieve this, we define a publisher class – laserDesignatorPublisher.
This class will contain an exercise connection to publish on and a laser state repository that has the information we want to publish.
The actual publishing is handled in the tick function. The tick function is typically called on every simulation "tick" or update. Inside our publisher tick function, we will create a state message from the current information in our state repository and then use our exercise connection to send that message.
Lastly, we will add a dispose method that will be used once the entity is destroyed or deleted. To do so we will create a new LaserDesignatorRemovedMessage, assign the entityId value of the message to our state repository entityId, and send the message with the exercise connection.
Now if we define a publisher that uses an existing state repository and call its tick function in our simulation tick, we are able to send a laserDesignator that VR-Link can understand. Since we have already defined our strategy for laser designators, the published information will be formatted into what VR-Link will understand.
[<< Code Generator] [Home] [Top of Page]