 |
VR-Forces Developer's Guide
|
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
|
VR-Forces Developer's Guide
|
State properties can be either be used for internal storage, or they can also be published to the network.
They can be published using either HLA or DIS. How the data is published and updated depends on how you define it in your SMS.
Let's walk through an example of how state properties are defined and how different settings affect what is sent on the network.
We start with a simple state property that is used to store some internal data. It's an integer with a default value of 0.
Now we want to send this data over the network to share with other simulators. In order to publish a state property it must:
If we move our internal state property to external-state-data and add the keyword "publish" to our definition, default publish settings will be used.
How this data is published depends on your protocol and, in HLA, your FOM. More information on this can be found in the sections below.
After publishing this data, however, we find that it is updating too frequently. We decide we want scale back how frequently the data updates. If the change is very small, we don't need to immediately send another update to the network. This can be done by configuring thresholding.
Now an update for this property will be sent only when it changes by 15% from the previously sent value. For instance, if the last value we sent was 200, we will not send another update unless the value changes to something below 180 or above 220. VR-Forces actually defaults to using percentage thresholding with a value of 2% for all numeric state properties.
Perhaps, however, we don't want to use percentage as a basis. We can also set the threshold based on the difference in value.
Now an update will be sent whenever the value changes by more than 5.
If you wish to completely disable thresholding, you can also specify a threshold-algorithm of "none".
If your state property changes value but never exceeds the threshold for an update, eventually an update will still be sent. By default, an update is sent once per minute regardless of change. This value can also be changed.
With this change, now our property is updated at a minimum of once every 30 seconds.
There is one final setting related to thresholding. Perhaps we find that our property sometimes changes by just a small amount and then stays there. We don't want to wait another 30 seconds for this change to be reflected, but perhaps we just want to target this specific case when a value stabilizes after a small change. For this, we can also set the max-unchanged-interval. Now if the property has not met the threshold but has stabilized at a new value, we will send an update when this new interval elapses.
While state properties can be published to both DIS and HLA, the details on how the data is sent differ. The following sections discuss the details of how data is transmitted in each protocol. Each section references the following state property definitions as an example.
In DIS, state properties are specified in attribute records within an Attribute PDU associated with the entity, aggregate, or environmental process. Please refer to the IEEE 1278.1-2012 standard for more details on how attribute records are used.
The attribute record is encoded based on how it was defined in the OPE or sysdef file. Using the state properties defined above as an example, VR-Forces would encode this data in the following ways.
StatePropA is not specified with the publish flag and will not be published to the network.
StatePropB and StatePropC are both specified with the publish flag. As a result, these properties are both encoded within an attribute record for this object. The record types used by the VR-Forces custom attribute record type start with a type ID value of 252200. Each subsequent attribute record type ID will increase by 1. Therefore the encoding of the attribute for StatePropB will look like this. (Refer to Supported Data Types for State and Parameter Properties to see how different data types will be encoded.)
| Encoding StatePropB | ||
|---|---|---|
| Value | Field Name | Size |
| 252200 | Record Type | 32 bits |
| 24 | Record Length (in bytes) | 16 bits |
| 10 | Name Length (in bytes) | 16 bits |
| 4 | Data Length (in bytes) | 16 bits |
| "StatePropB" | Property Name | 10 bytes (length of string) |
| 10 | Property Value | 32 bits (size of DtRwInt) |
| 0 | Padding | 0 bits (align to 64 bits - no padding needed in this case) |
StatePropD is specified with the publish flag but, in addition, a record type is also specified. When a record type is specified, VR-Forces associates this record type with the named property. This means that whenever an attribute with that record type is received, the associated property is updated. As a result, the name of the property does not need to be included in the record. This also allows you define properties in your OPE that match the formats of well-defined DIS attribute records and have them published in a way that any DIS standard application that supports those record types can understand. The encoding of the attribute for StatePropD will look like this.
| Encoding StatePropD | ||
|---|---|---|
| Value | Field Name | Size |
| 100610 | Record Type | 32 bits |
| 16 | Record Length (in bytes) | 16 bits |
| 30 | Property Value | 32 bits (size of DtRwInt) |
| 0 | Padding | 0 bits (align to 64 bits) |
StatePropE is defined in the internal-state-data section and will not be published to the network.
In HLA, state properties are published in object attributes. There are a few ways this can happen, depending on whether and how an attribute is defined in the FOM. If possible, VR-Forces will attempt to publish state properties directly within FOM attributes with matching names. This allows you to extend your FOM with new attributes, add new state properties to the OPE file, and VR-Forces will automatically match these up and publish your new attributes. If your attributes are added directly within existing RPR FOM classes, for example by adding a new attribute directly to the Platform class, then VR-Forces will discover and use these attributes. If your attributes are added to a subclass of an existing RPR FOM class, for example by adding MyAircraft as a subclass of the Aircraft class, then you must tell VR-Forces to publish this class in the OPE using the hla-fom-class parameter.
When this is not possible, VR-Forces uses a custom FOM class added as an extension to the RPR FOM to encode any remaining properties. This is the VrfExtendedAttributes class. It can be associated with PhysicalEntity, AggregateEntity, and EnvironmentProcess objects by using its AssociatedObjectIdentifier attribute to reference one of these objects.
As an example, we define the above state properties in our OPE file and indicate that we should be publishing the MyAircraft object class using the hla-fom-class parameter. We then define the following attributes in our FOM.
StatePropB is added to the MyAircraft class. StatePropC is added to the VrfExtendedAttributes class.
VR-Forces would then publish these properties as described below.
StatePropA is not specified with the publish flag and will not be published to the network. This is true even when an attribute named StatePropA can be found in the FOM.
StatePropB is specified with the publish flag. Since we are publishing a MyAircraft object, VR-Forces will look for any new attributes defined in MyAircraft or its parent classes. It will find a matching attribute called StatePropB in the MyAircraft class. StatePropeB will be published in this attribute and encoded as an HLAinteger32BE. (Refer to Supported Data Types for State and Parameter Properties to see how different data types will be encoded.)
StatePropC is specified with the publish flag. VR-Forces looks for any new attributes defined in MyAircraft or its parent classes that match this property name, but it is unable to find any. It then decides to publish this attribute as part of a VrfExtendedAttributes object. A new VrfExtendedAttributes object is then created and associated with the MyAircraft object. VR-Forces then checks the VrfExtendedAttributes class definition and finds that there is an attribute named StatePropC defined in this class. StatePropC will be published in this attribute and encoded as an HLAinteger32BE.
StatePropD is specified with the publish flag. VR-Forces tries to find matching attributes in MyAircraft and its parent classes and then in VrfExtendedAttributes, but it fails to find any. Since a VrfExtendedAttributes object has already been associated with MyAircraft, StatePropD is added to the list of properties published in the ExtendedAttributes attribute of this object. This attribute is simply a list of properties by name.
StatePropE is defined in the internal-state-data section and will not be published to the network. This is true even when an attribute named StatePropE can be found in the FOM.