Dynamic Terrain Network Interface

Table of Contents

• Receiving Dynamic Terrain Updates
  • Overview
  • Supported Dynamic Terrain Changes
  • HLA Object
  • DIS PDU
  • Description of Attributes and Fields
    • ObjectIdentifier
    • PDU Version (DIS only)
    • FinalUpdate (DIS only)
    • GeometryAndData
    • CommonData
    • CommonDataEventNumber
• Changing the Dynamic Terrain
  • DtAddDynamicTerrainChangesCommand
  • DtResetDynamicTerrainChangesCommand
  • DtRemoveDynamicTerrainDamageCommand
  • DtSwitchDynamicTerrainAtPointCommand
• Requesting Dynamic Terrain Information

The VR-Forces back-end can function as a dynamic terrain server.

It processes events and commands that can cause changes to the terrain, and publishes these changes to the network as persistent objects via a custom DIS PDU or HLA object class. Normally a single back-end will manage and publish all dynamic terrain changes for the entire simulation, but it is possible to configure different back-ends to control the dynamic terrain for different regions of the terrain.

User applications can also process these dynamic terrain changes for their own purposes, or send control messages to the VR-Forces back-end to request changes to the terrain.

Receiving Dynamic Terrain Updates

There are two ways of receiving dynamic terrain updates from the VR-Forces back-end. The easier method requires the use of the VR-Forces Remote Control toolkit. The toolkit includes a DtReflectedDynamicTerrainList which functions like other VR-Link reflected list classes. It handles subscribing to network updates and decoding data into a local state repository for easier access. For specific details on this class, please consult the VR-Forces Class Documentation as well as the VR-Link documentation for a general understanding of the VR-Link API.

If your application cannot use the VR-Link API, you can write your own code to read and process the VR-Forces custom HLA object class or DIS PDU. The following sections outline the contents of these updates and explain the meanings of each of the attributes and fields. An understanding of the either the HLA or DIS standard is required to receive and process these updates.

Overview

Each published dynamic terrain object includes one or multiple terrain geometries that define the areas of the terrain that are being changed. For each terrain geometry, a list of key/value pairs are specified. These key/value pairs are ASCII strings that define the type of change and the new state. This could, for example, identify a new state for switch nodes in that area of the terrain, or tell VR-Forces how to programmatically change the terrain. The exact values keys and values used will depend on the terrain and how VR-Forces is configured.

Supported Dynamic Terrain Changes

The types and values of dynamic terrain changes that VR-Forces will publish depends on the terrain being used and the configuration of VR-Forces. Different terrains will support different types of dynamic changes. The table below lists the types of dynamic terrain changes supported by VR-Forces in its default configuration, but new types of changes can be added through configuration or use of new terrains.

Here is the list of dynamic terrain changes VRF supports with default configuration in MAK terrains

Dynamic Terrain Changes

Type	Allowable Values	Description	Notes
damage	none, slight, moderate, destroyed	General terrain damage.
damage_structure	none, slight, moderate, destroyed	Damage specific to buildings and structures.
door	open, closed	The state of a door.
window	open, closed	The state of a window.

HLA Object

VR-Forces includes FOM versions that include a new object class and datatypes to support dynamic terrain changes. If you are using RPR FOM 2.0, the following FOMs should be used:

• For HLA 1516-2010, use RPR_FOM_v2.0_1516-2010.xml and the FOM module MAK-DynamicTerrain-1_evolved.xml.
• For HLA 1.3, use MAK-RPR2-1-2.fed.
• For HLA 1516-2000, use MAK-RPR2-1-2.xml.

No matter what HLA version you are using, you will need to subscribe to the DynamicTerrain class. The table below lists each attribute of the object and describes its format. For details on the meaning of each attribute and field, see the section below titled Description of Attributes and Fields. Padding is not explicitly indicated, but it is expected that all attributes and datatypes will follow standard HLA encoding padding rules. The value in brackets ([ ]) indicates the total size of the attribute or subfield in bits.

Attribute	Subfields				Format
ObjectIdentifier [48]	Site Number [16]				16 bit unsigned int
	Application Number [16]				16 bit unsigned int
	Entity Number [16]				16 bit unsigned int
GeometryAndData [variable]	Length [32]				32 bit int
	GeometryAnd Data Entry 1 [variable]	Geometry [288]	TerrainAreaType [32]		32 bit int
			Location [192]	X [16]	64 bit float
				Y [16]	64 bit float
				Z [16]	64 bit float
			Radius [64]		64 bit float
		GeometryData [variable]	Length [32]		32 bit int
			GeometryData Entry 1 [variable]	Key [variable]	32 bit int (size) followed by ASCII string
				Value [variable]	32 bit int (size) followed by ASCII string
			...
			GeometryData Entry N [variable]		Same structure as GeometryData Entry 1
		EventNumber [32]			32 bit unsigned int
		Priority [32]			32 bit unsigned int
	...
	GeometryAnd Data Entry N [variable]				Same structure as GeometryAnd Data Entry 1
CommonData [variable]	Length [32]				32 bit int
	CommonData Entry 1 [variable]	Key [variable]			32 bit int (size) followed by ASCII string
		Value [variable]			32 bit int (size) followed by ASCII string
	...
	CommonData Entry N [variable]				Same structure as CommonData Entry 1
CommonDataEventNumber [32]					32 bit unsigned int

DIS PDU

VR-Forces sends a custom PDU that supports dynamic terrain changes. It uses PDU kind 160. All updates are heartbeated periodically using normal DIS hearbeating rules. The table below lists each field in the PDU and describes its format. For details on the meaning of each field, see the section below titled Description of Attributes and Fields. All padding fields are explicitly identified, though some are variable length depending on the data preceding them. This is to ensure proper buffer alignment. For example, if a padding field says "padding to 64 bit boundary" and the preceding data ends on a 32 bit boundary, the padding field should be 32 bits. The value in brackets ([ ]) indicates the total size of the field in bits.

Primary Field	Subfields				Format
Standard DIS PDU Header [96]					See DIS standard for details
ObjectIdentifier [48]	Site Number [16]				16 bit unsigned int
	Application Number [16]				16 bit unsigned int
	Entity Number [16]				16 bit unsigned int
PDU Version [16]					16 bit unsigned int
CommonDataEventNumber [32]					32 bit unsigned int
FinalUpdate [8]					8 bit boolean
Padding [56]					56 bits unused
GeometryAndData [variable]	Length [32]				32 bit int
	GeometryAnd Data Entry 1 [variable]	Geometry [288]	TerrainAreaType [32]		32 bit int
			Padding [32]		32 bits unused
			Location [192]	X [16]	64 bit float
				Y [16]	64 bit float
				Z [16]	64 bit float
			Radius [64]		64 bit float
		GeometryData [variable]	Length [32]		32 bit int
			GeometryData Entry 1 [variable]	Key [variable]	32 bit int (size) followed by ASCII string
				Value [variable]	32 bit int (size) followed by ASCII string
			...
			GeometryData Entry N [variable]		Same structure as GeometryData Entry 1
		EventNumber [32]			32 bit unsigned int
		Priority [32]			32 bit unsigned int
		Padding [variable]			Unused bits, padding to 64 bit boundary
	...
	GeometryAnd Data Entry N [variable]				Same structure as GeometryAnd Data Entry 1
CommonData [variable]	Length [32]				32 bit int
	CommonData Entry 1 [variable]	Key [variable]			32 bit int (size) followed by ASCII string
		Value [variable]			32 bit int (size) followed by ASCII string
	...
	CommonData Entry N [variable]				Same structure as CommonData Entry 1

Description of Attributes and Fields

ObjectIdentifier

This is the standard DIS object identifier including the site number, application number, and entity number.

PDU Version (DIS only)

This field indicates the version of the PDU. When VR-Forces makes changes to the PDU between releases, this number will be increased so that applications may understand how to properly decode the data contained in the PDU. This document describes the format of PDU version 1.

FinalUpdate (DIS only)

This is a boolean value that indicates if this is the final update for this dynamic terrain object. This is an indication that the dynamic terrain changes defined by this object should be immediately removed. In HLA, this processing should happen when the object is deleted.

GeometryAndData

This is a list of geometry records and associated terrain changes. This describes where the terrain is being changed and how it is being changed. This list can contain a single terrain change, or multiple.

The first subfield in the GeometryAndData is a 32 bit integer specifying the number of entries in the list. Following this is each GeometryAndData entry in order.

GeometryAndData Entry

A GeometryAndData entry defines a single terrain geometry and some associated terrain changes. It consists of several subfields described below. Once a GeometryAndData entry has been added, it will never be removed as it can be uniquely identified by its index in the GeometryAndData list. When a GeometryAndData entry should be removed, the GeometryData will be cleared.

Geometry

Defines the terrain geometry of a change. The first field, TerrainAreaType, is a 32 bit integer enumeration that specifies how the geometry is defined, for instance a circle, a polygonal area, or line with width. Currently only circular geometries are supported, which is a value of 1.

For circular geometries, this is followed by a location, expressed in geocentric coordinates, and a radius, expressed in meters.

GeometryData

Defines how the terrain at the specified geometry should be changed. This is a list of changes. The first field is a 32 bit integer specifying the number of changes. Following that is a list of key/value pairs, where each key and value is an ASCII string. The first 32 bits of each string is an integer that specifies the number of characters in the string. Following that are the characters of the string.

The specific keys and values to be used will depend on your terrain and what switches it expects. For example, a specific key/value pair may be "damage"/"3". This indicates that any dynamic terrain features within the specified geometry should have their "damage" state changed to "3".

EventNumber

This field starts with a value of 0 the first time the GeometryAndData Entry is updated. Each time it is updated thereafter this value will be incremented by 1. This allows an application to monitor a single field to determine if any update has been made to this particular dynamic terrain change. This saves the application the work of comparing its stored state with every field in the GeometryAndData Entry.

Priority

Specifies the priority of this terrain change relative to other terrain changes. If two different GeomentryAndData Entries conflict with one another, the one with the higher priority will take precedence.

CommonData

CommonData is similar to the GeometryData described above. It has the same format and contains a list of key/value pairs that define changes to the terrain. The difference is that CommonData applies to all GeometryAndData entries described in this object. This can be useful if the same changes are being described for multiple different terrain geometries.

CommonDataEventNumber

This field starts with a value of 0 the first time CommonData is updated. Each time it is updated thereafter this value will be incremented by 1. This allows an application to monitor a single field to determine if any update has been made to the CommonData of this object. This saves the application the work of comparing its stored state with each key/value pair in the CommonData list.

Changing the Dynamic Terrain

To change the dynamic terrain state, you must communicate the desired change to the VR-Forces back-end which is functioning as the dynamic terrain server. This can be done using a series of sim commands available in the VR-Forces Remote Control toolkit. To send a dynamic terrain change sim command you must create DtIfExecuteSimCommand interface content message and send this via the DtVrfRemoteController. Here is a small code example.

DtAddDynamicTerrainChangesCommand command;
// Fill in command with the specifics of the changes to add

DtIfExecuteSimCommand ifSimCommand;
content.setSimCommand(&command);

remoteController->vrfMessageInterface()->createAndDeliverMessage(DtSimSendToAll, ifSimCommand);

The dynamic terrain will also be affected by any detonations that are published to the network. The back-end will determine if the detonation causes any damage to the terrain and will publish dynamic terrain updates accordingly.

Below is a description of each of the dynamic terrain commands available. For specific details, please consult the VR-Forces Class Documentation.

DtAddDynamicTerrainChangesCommand

Commands VR-Forces to add new changes to the dynamic terrain in the specified area. A list of changes, represented as key/value pairs of strings, must be specified, indicating how the terrain is to be changed.

DtResetDynamicTerrainChangesCommand

Commands VR-Forces to reset dynamic terrain changes of specific types within the designated area back to their default states. Changes are specified as a list of strings that match the keys to the key/value pairs used in the DtAddDynamicTerrainChangesCommand.

DtRemoveDynamicTerrainDamageCommand

Commands VR-Forces to reset any dynamic terrain changes that are the result of damage due to munition detonations within the designated area. This can also be achieved using the DtResetDynamicTerrainChangesCommand with the proper keys representing terrain damage types, but this command is simpler to use and will automatically adapt if new types of terrain damage are configured.

DtSwitchDynamicTerrainAtPointCommand

Commands VR-Forces to switch the state of one or multiple dynamic terrain features along a specified chord. The command may specify a list of dynamic terrain change types that can be switched, or instead a list of dynamic terrain changes types that should not be switched. This can be useful for certain types of changes, for example opening a door immediately in front of an entity.

Requesting Dynamic Terrain Information

An application can learn about changes to the default terrain state by listening to the DynamicTerrain HLA object updates or DIS PDUs. Sometimes, however, it might be useful for an application to understand what types of changes are possible in a specified area. For instance, it may be useful to query the VR-Forces back-end to understand if there are any openable doors in a particular area. These kinds of requests can be performed using the interface content message DtIfRequestDynamicTerrainInformation. This is a simple request that will request information about all possible dynamic terrain changes available in a defined area of the terrain. VR-Forces will then respond with a DtIfDynamicTerrainInformationResponse message containing this information. For specific details on these classes, please consult the VR-Forces Class Documentation.