4.11 - Embarkation

Table of Contents

• 4.11.1 How Embarkation Affects Entity Models
• 4.11.2 Attaching Environmental Objects to Entities

Embarkation is the ability to place an entity on or in another entity.

Embarkation includes the ability to attach objects, such as points or routes, to entities. Support for embarkation means that you cannot assume that an entity is attached to the terrain. This has implications for how you develop entity models. This section describes the major classes that implement embarkation.

The embarkation controller (DtEmbarkationController) (embarkationController.h) handles embarkation of an object onto a parent and the disembarkation from that parent. The DtEmbarkationController is a state machine that handles the embarkation of an object from its current location to an embarked location.

DtDisaggregatedEmbarkationController (disaggregatedEmbarkationController.h) passes tasks and set data requests to currently taskable subordinates (sets are passed down to all subordinates). The controller also adds the checkEmbarkationState() member function, which is called every tick regardless of whether or not the aggregate is tasked. The pseudo aggregate is considered embarked if all available taskable subordinates are embarked. The aggregate is then embarked on the same object as the current leader of the aggregate. If any subordinate disembarks, the aggregate also disembarks.

DtOccupancyDirectorController (occupancyDirectorController.h) allocates reserved embarkation slots and determines which (if any) objects can be embarked on an object. This controller responds to messages of type DtIfRequestEmbarkationInformation. When the request is received, the controller looks to see if there are any slots available, and, if so, reserves it (if requested) and then returns a DtIfEmbarkationInformation structure with the reservation information. This controller also provides disembarkation information and responds to disembarkation requests. If an entity cannot embark either because the object does not support the requesting object type or because the slots are full, an information return structure is sent with the DtEmbarkCannotEmbark result status.

4.11.1 How Embarkation Affects Entity Models

Because entities can be embarked on other entities and can be tasked to perform operations on those entities, if you model dynamics of an entity, you must consider how your models will take advantage of this behavior.

You cannot assume that an entity is solely attached to the terrain. An entity can be attached to any other model (except for environmental objects) in the simulation. When an entity is embarked, you need to know the following information about it:

• Terrain intersections
• Velocity relative to the host
• Acceleration relative to the host.

To support embarkation, your code must do the following:

• Terrain Intersections: In your models, when you need to query for information about the surface or structure your entity is currently positioned on, do so through the entity's attached terrain member (myEntity->terrainAttachedTo()). This returns a pointer to a DtAttachedTerrain object, which is an abstraction of the surface or structure an entity is currently attached to. The underlying structure represented by this object may be a terrain database or another entity. The DtAttachedTerrain object provides an interface for determining terrain height and chord intersections.
• Velocity relative to the host: To handle velocity relative to the host, use the member function calls, relativeVelocity() and setRelativeVelocity(). The return and set values are in local (database) coordinates, but if the entity is attached, the return value of relativeVelocity() is the velocity of the entity only. If you call localVelocity(), the return value is the sum of the velocity of the entity and any objects it might be attached to. You must also call setRelativeVelocity() to preserve the notion that this velocity is for the entity only. If the entity is not attached, these calls pass through to localKinematicState().velocity() and localKinematicState().setVelocity().
• Acceleration relative to the host is handled that same way as velocity relative to the host, except that the member functions are relativeAcceleration() and setRelativeAcceleration().

4.11.2 Attaching Environmental Objects to Entities

You can attach environmental objects (routes, waypoints, areas, and so on) to entities. For example, a route can be placed on an aircraft carrier for a DI to walk along or a plane to taxi along. To support this, the createOverlayObject() member function has an optional parameter (initially the empty string) that can contain the name of the object to attach to. The sendVrf-OverlayObjectModifyMsg() member function has the parameters attachTo and keepExistingAttachment. This is so the create function can assign the attachment and future modifications can keep any attachment that has been created (or, can change it).

[<< The Resource Manager] [Home] [Top of Page] [Entity Communication Page >>]