SimObject and LocalObject Facade Classes

This section describes the Facade system used in VRF Sim to interact with DtLocalObject and DtSimObject instances which represnet various types of simulation objects.

Object facades are convenience objects that allow a developer to check and see if a simulation object implements a specific API before usage and easily access the elements provided by the API.

Since DtSimObject and DtLocalObject are built up with various DtStateComponent instances through composition, there is not a direct API to all aspects of the state directly on the DtSimObject and DtLocalObject interface. These facade classes make it much easier to access the state contained in the objects.

A DtSimObjectFacade is used on a DtSimObject and provides read-only access to current frame state.

A DtLocalObjectFacade is used on a DtLocalObject and provides both read-only access to current frame state along with read/write access to next-frame state.

To use a facade, the desired facade class is constructed with the DtSimObject or DtLocalObject as a parameter to the custructure, and then the isUsable() method is called on the new facade. This returns true if the facade was able to find the specific DtStateComponent subclasses on which it depends as part of the passed in objects. If the isUsable() call returns false, then the facade is not valid, and will throw an exception if any methods are used to access state that is not available.

Available Facades:

• DtPlatformSimObjectFacade / DtPlatformLocalObjectFacade - Usable on any platform objects. Provides access to parameters for platform objcts.
• DtAggregateSimObjectFacade / DtAggregateLocalObjectFacade - Usable on any unit (aggregate) objects. Provides access to unit specific parameters such as suborniate list.
• DtTacticalGraphicSimObjectFacade / DtTacticalGraphicLocalObjectFacade - Usable for objects that are considered tactical graphics. Provides access to various graphic parameters.
• DtHumanSimObjectFacade / DtHumanLocalObjectFacade - Usable on any human object. Provides access to human specific parameters.
• DtMissileSimObjectFacade / DtMissileLocalObjectFacade - Usable on any missile objects. Provides access to missile specific parameters such as target.
• DtArticulatedPartsSimObjectFacade / DtArticulatedPartsLocalObjectFacade - Usable for any objects with articulated parts. Provides access to articulated part parameters.
• DtAppearanceSimObjectFacade / DtAppearanceLocalObjectFacade - Usable for any objects with appearance bitfields. Provides access to the appearance values.
• DtRangeItemSimObjectFacade / DtRangeItemLocalObjectFacade - Usable for any objects with range rings. Provides access to range rings parameters.
• DtNavigationLocalObjectFacade - Usable on DtLocalObject only for any objects using the navigation system. Provices access to DtVrfObjectNavinface.
• DtVrfSimulatedSimObjectFacade - Usable on DtSimObject only for objects that are VRF simulated.

Note that many facade classes are composed on other facades, since they share data elements. For example, both DtPlatformLocalObjectFacadeInterface "DtPlatformLocalObjectFacade" and DtAggregateLocalObjectFacadeInterface "DtAggregateLocalObjectFacade" contain a DtRangeItemLocalObjectFacade since they can both have range rings. Facade instances are low overhead to create and destroy, and have very small memory footprint, so it is acceptable to create them as needed. It is also safe to create them and hold onto them over mutiple frames, as long as the object they are created on continues to exist.

Example facade usage:

// Function returns true if the specified entity is a human in a detained or surrendered state, otherwise false.
bool isSurrenderedLifeform(const DtSimObject* entity) const
{
   DtHumanSimObjectFacade humanSimObjectFacade(entity);
   if (humanSimObjectFacade.isUsable()) // Returns true if entity is a human
   {
      // Only call facade functions if isUsable() returned true.
      int complianceState = humanSimObjectFacade.complianceState();
      return (complianceState == DtComplianceDetained ||
         complianceState == DtComplianceSurrender);      
   }
   return false;
}