VR-Forces 4.0.4 Class Documentation
Public Member Functions | Static Public Member Functions | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Private Member Functions
DtDisaggregatedFormationController Class Reference

Class DtAggregateFormationController is a controller that manages the formation state for an aggregate entity. More...

Inheritance diagram for DtDisaggregatedFormationController:
Inheritance graph
[legend]

List of all members.

Public Member Functions

 DtDisaggregatedFormationController (const DtString &name, DtVrfObject *owner, DtSimManager *simManager, DtComponentDescriptor *desc=0, DtReaderWriterRegistry *parentRegistry=0)
 (const DtString&,DtVrfObject*,DtSimManager*,
virtual ~DtDisaggregatedFormationController ()
virtual bool init ()
 Initializes myCommandRadio and myAggregateStateRepository members.
virtual void tick ()
 Calls formationUpdateIsNeeded().
virtual DtString type () const
 Returns a string identifies the class type of component.
virtual void setRadio (DtSimBaseRadio *radio)
 Overridden to register for following radio messages: DtSetFormationTypeRequestType DtSetFormationRequestType DtSetLocationRequestType DtSnapIntoFormationRequestType.
virtual void processNodeAddedCallback (DtEntityIdentifier eid)
virtual void enable ()
 Override to (re)add set data request callbacks.
virtual void disable ()
 Override to remove set data request callbacks.

Static Public Member Functions

static void setFormationCallback (DtSimMessage *msg, void *usr)
 Callback for DtSetFormationRequest set data requests.
static void setFormationTypeCallback (DtSimMessage *msg, void *usr)
 Callback for DtSetHeadingRequest set data requests.
static void setHeadingCallback (DtSimMessage *msg, void *usr)
 Callback for DtSetFormationTypeRequest set data requests.
static void setLocationCallback (DtSimMessage *msg, void *usr)
 Callback for DtSetLocationRequest set data requests.
static void snapIntoFormationCallback (DtSimMessage *msg, void *usr)
 Callback for DtSnapIntoFormationRequest set data requests.
static void subordinatesChangedCallback (DtEntityIdentifier entId, void *usr)
 Callback registered with DtVrfSubordinateManager invoked when contents of subordinate manager changes.
static void nodeAddedCallback (DtEntityIdentifier eid, void *userData)
 Callback registered with DtVrfSubordinateManager invoked when an org manager node is added.
static void onTaskNotifyCallback (const DtSimTask &task, const DtSimComponent &notifier, void *usr)
 Callback to be invoked when onNotify() is called in the local task manager to indicate entity is about to start a new task.
static DtSimComponentcreator (const DtString &name, DtVrfObject *owner, DtSimManager *simManager, DtComponentDescriptor *desc=0, DtReaderWriterRegistry *parentRegistry=0)
 (const DtString&,DtVrfObject*,DtSimManager*,

Protected Member Functions

virtual bool formationUpdateIsNeeded () const
 Walks list of subordinates in formation state.
virtual void processSetFormation (DtSimMessage *msg)
 Handler for setFormationCallback().
virtual void processSetFormationType (DtSimMessage *msg)
 Handler for setFormationTypeCallback().
virtual void processSetHeading (DtSimMessage *msg)
 Handler for setHeadingCallback().
virtual void processSetLocation (DtSimMessage *msg)
 Handler for setLocationCallback().
virtual void processSnapIntoFormation (DtSimMessage *msg)
 Handler for snapIntoFormationCallback().
virtual void processSubordinatesChanged (DtEntityIdentifier entId)
 Handler for subordinates changed callback.
virtual void snapIntoFormation (const DtString &formation, const DtVector &location, double heading, bool applyHeading)
 Puts the aggregate into the given formation, at the given location and heading.
virtual void getCurrentFormation (DtFormation &formation)
 Get current formation position and formation type.
virtual
DtOrgViewManagedObjectListConstPtr 
generateListOfSubordinatesEligibleForFormation ()
 Generates the subset of subordinates available to participate in formation.
virtual std::list< int > generateFormationPositions (DtOrgViewManagedObjectListConstPtr &entityInFormation)
 Generates a list of formation positions for each entity in the formation.
virtual int findPositionInVector (const std::vector< DtEntityIdentifier > subordinateList, const DtEntityIdentifier &entityId) const
 Helper function for generateFormationPositions().
virtual void generateFormationAtPositionAndOrientation (const DtVector &geocentricOrigin, const DtTaitBryan &geocentricOrientation, std::vector< DtVector > geocentricPositions, DtFormation &formation)
 Constructs an ad hoc formation (set of positional offsets of participants) based on current relative positioning of subordinates, at given location and orientation.
virtual void generateWorkingFormation (DtFormation &formation)
 Creates an ad hoc formation from the current eligible subordinates current positions relative to one another.
virtual void updateFormationState ()
 Recomputes and updates current working formation in process state repository, and updates subordinate list and formation positional data.
virtual void registerWithOrgManager ()
 Register subordinateOrderChangedCallback with the DtOrganizationManager.
virtual void unregisterWithOrgManager ()
 Unregister subordinateOrderChangedCallback with the DtOrganizationManager.
virtual void sendRequestToSelf (const DtSetDataRequest &request) const
 Send given request to ourself.
virtual void sendRequestToSubordinate (const DtSetDataRequest &request, const DtString &subordinateObjectName) const
 Send given request to one of our subordinates.
virtual bool createPSR ()
 Creates myProcessState data member, and adds it to our process state repository manager.
virtual void processOnTaskNotifyCallback (const DtSimTask &task, const DtSimComponent &notifier)
 Called when the entity is about to start a new task.
virtual void processRequestAvailableFormations (const DtVrfObjectMessage *msg)
virtual void addSetDataCallbacks ()
 Add set data request callbacks.
void removeSetDataCallbacks ()
 Callbacks are removed when component is disabled or destroyed.

Static Protected Member Functions

static void requestAvailableFormationsCallback (const DtVrfObjectMessage *msg, void *usr)

Protected Attributes

const
DtFormationControllerDescriptor
myFormationControllerDescriptor
 Descriptor used to configure this component.
DtVrfAggregateStateRepositorymyAggregateStateRepository
 Pointer to aggregate's state repository, cached in this class for convenience.
DtFormationStatemyFormationState
 Pointer to aggregate's formation state repository, cached in this for convenience.
bool myRegisteredWithOrgManager
 Flag used to indicate if the subordinateOrderChangedCallback() has been registered with the aggregate's organization manager.
DtCommandChannelRadiomyCommandChannelRadio
 Pointer to aggregate's command radio, cached in this class for convenience.
DtSetDataManagermySetDataManager
 Pointer to aggregate's DtSetDataManager, cached in this class for convenience.
DtFormationPSRmyProcessState
 Container for state data associated with this component.
bool myFormationCallbacksAreDisabled
 Flag used to indicate if formation-related callbacks are disabled (not registered).
bool myFirstTick
 Flag used to indicate first non-zero dT() tick.
bool myRegisteredForAddNodeCallback
const DtAggregateObjectParametersmyAggregateParameters
 Convenience pointer to the aggregate parameters for this entity.

Private Member Functions

 DtDisaggregatedFormationController ()
 Default constructor - not implemented.
 DtDisaggregatedFormationController (const DtDisaggregatedFormationController &orig)
 copy constructor - not implemented
DtDisaggregatedFormationControlleroperator= (const DtDisaggregatedFormationController &orig)
 assignment operator - not implemented

Detailed Description

Class DtAggregateFormationController is a controller that manages the formation state for an aggregate entity.

End User Description: The DtAggregateFormationController manages the state associated with an aggregate entity's formation. This includes determining who is eligible to participate in the formation, and who should be positioned relative to whom when participating in the formation.

It is intended to work in conjunction with the aggregate controllers that model the various movement behaviors (e.g. DtAggregateMoveAlongController, DtAggregatePatrolBetweenController). The DtAggregateFormationController sets formation state (keeping it up to date), and the movement controllers examine the formation state and use that information to execute movement in formation.

This controller may only be configured as a part of an entity that has a vrf-aggregate-state-repository.

Developer Description: The DtAggregateFormationController class handles all DtSetDataRequests that affect formation, including DtSetLocationRequests, DtSetHeadingRequests, and DtSnapIntoFormationRequests. It sets the state in the aggregate entity's DtFormationState object (owned by the DtVrfAggregateStateRepository class). Therefore it should only be configured as part of an aggregate entity that has a DtVrfAggregateStateRepository.

Uses Descriptor Type: DtFormationControllerDescriptor


Constructor & Destructor Documentation

Default constructor - not implemented.

copy constructor - not implemented

(const DtString&,DtVrfObject*,DtSimManager*,

Parameters:
nameReader writer name of this component.
ownerThe DtVrfObject that owns this component
simManagerThe simulation manager (provides access to terrain, message interface, simulation clock).
descThe component descriptor used to initialize this component.
parentRegistryPointer to the parent reader writer registry (the containing object that reads/writes this object).
(const DtString&,DtVrfObject*,DtSimManager*, DtComponentDescriptor*,DtReaderWriterRegistry* parentRegistry)


Member Function Documentation

DtDisaggregatedFormationController& DtDisaggregatedFormationController::operator= ( const DtDisaggregatedFormationController orig) [private]

assignment operator - not implemented

Initializes myCommandRadio and myAggregateStateRepository members.

Must be called before any other member functions are called. Disables callbacks in formation state object (will be enabled after first nonzero tick).

Returns:
True if component is completely successfully initialized, false if not.

Reimplemented from DtControllerComponent.

virtual void DtDisaggregatedFormationController::tick ( ) [virtual]

Calls formationUpdateIsNeeded().

If this returns true, calls updateFormation(). Enables callbacks in formation state object after first non-zero tick.

Reimplemented from DtSimComponent.

Returns a string identifies the class type of component.

Type values are defined in compTypes.h. DtSimComponent creation functions are registered with the DtSimComponentFactory using the type values as the key.

Returns:
DtAggregateFormationControllerType

Reimplemented from DtControllerComponent.

virtual void DtDisaggregatedFormationController::setRadio ( DtSimBaseRadio radio) [virtual]

Overridden to register for following radio messages: DtSetFormationTypeRequestType DtSetFormationRequestType DtSetLocationRequestType DtSnapIntoFormationRequestType.

Parameters:
radioCaches a pointer to the aggregate's radio in myCommandChannelRadio. Dynamically casts it to type DtCommandChannelRadio. Aggregates must be configured with radios of this type in order to be able to issue tasks/set data requests to subordinates.

Reimplemented from DtControllerComponent.

static void DtDisaggregatedFormationController::setFormationCallback ( DtSimMessage msg,
void *  usr 
) [static]

Callback for DtSetFormationRequest set data requests.

Calls processSetFormation().

Parameters:
msgMessage containing a DtSetFormationRequest.
usrPointer to an instance of this class.
static void DtDisaggregatedFormationController::setFormationTypeCallback ( DtSimMessage msg,
void *  usr 
) [static]

Callback for DtSetHeadingRequest set data requests.

Calls processSetFormationType().

Parameters:
msgMessage containing a DtSetFormationTypeRequest,
usrPointer to an instance of this class.
static void DtDisaggregatedFormationController::setHeadingCallback ( DtSimMessage msg,
void *  usr 
) [static]

Callback for DtSetFormationTypeRequest set data requests.

Calls processSetHeading().

Parameters:
msgMessage containing a DtSetHeadingRequest.
usrPointer to an instance of this class.
static void DtDisaggregatedFormationController::setLocationCallback ( DtSimMessage msg,
void *  usr 
) [static]

Callback for DtSetLocationRequest set data requests.

Calls processSetLocation().

Parameters:
msgMessage containing a DtSetLocationRequest.
usrPointer to an instance of this class.
static void DtDisaggregatedFormationController::snapIntoFormationCallback ( DtSimMessage msg,
void *  usr 
) [static]

Callback for DtSnapIntoFormationRequest set data requests.

Calls snapIntoFormationCallback().

Parameters:
msgMessage containing a DtSnapIntoFormationRequest.
usrPointer to an instance of this class.
static void DtDisaggregatedFormationController::subordinatesChangedCallback ( DtEntityIdentifier  entId,
void *  usr 
) [static]

Callback registered with DtVrfSubordinateManager invoked when contents of subordinate manager changes.

Calls processSubordinatesChanged().

Parameters:
entIdThe aggregate's entity Id.
usrPointer to an instance of this class.
static void DtDisaggregatedFormationController::nodeAddedCallback ( DtEntityIdentifier  eid,
void *  userData 
) [static]

Callback registered with DtVrfSubordinateManager invoked when an org manager node is added.

This will be set when trying to register with the org manager and cannot

Parameters:
entIdThe aggregate's entity Id.
usrPointer to an instance of this class.
virtual void DtDisaggregatedFormationController::processNodeAddedCallback ( DtEntityIdentifier  eid) [virtual]
virtual void DtDisaggregatedFormationController::enable ( ) [virtual]

Override to (re)add set data request callbacks.

Reimplemented from DtSimComponent.

virtual void DtDisaggregatedFormationController::disable ( ) [virtual]

Override to remove set data request callbacks.

Reimplemented from DtSimComponent.

static void DtDisaggregatedFormationController::onTaskNotifyCallback ( const DtSimTask task,
const DtSimComponent notifier,
void *  usr 
) [static]

Callback to be invoked when onNotify() is called in the local task manager to indicate entity is about to start a new task.

Calls processOnTaskNotify().

Parameters:
taskTask the aggregate is about to start.
notifierThe component that is responsible for executing the task.
usrPointer to an instance of this class.
static DtSimComponent* DtDisaggregatedFormationController::creator ( const DtString name,
DtVrfObject owner,
DtSimManager simManager,
DtComponentDescriptor desc = 0,
DtReaderWriterRegistry parentRegistry = 0 
) [static]

(const DtString&,DtVrfObject*,DtSimManager*,

Parameters:
nameReader writer name of this component.
ownerThe DtVrfObject that owns this component
simManagerThe simulation manager (provides access to terrain, message interface, simulation clock).
descThe component descriptor used to initialize this component.
parentRegistryPointer to the parent reader writer registry (the containing object that reads/writes this object).
(const DtString&,DtVrfObject*,DtSimManager*, DtComponentDescriptor*,DtReaderWriterRegistry* parentRegistry)

Returns:
New instance of this class.
virtual bool DtDisaggregatedFormationController::formationUpdateIsNeeded ( ) const [protected, virtual]

Walks list of subordinates in formation state.

Calls DtFormationState::isAvailableForFormation() for each subordinate. If any subordinate fails this test, returns true, otherwise returns false.

virtual void DtDisaggregatedFormationController::processSetFormation ( DtSimMessage msg) [protected, virtual]

Handler for setFormationCallback().

If aggregate is currently tasked, calls updateFormationState(). Issues a DtSnapIntoFormationRequest to itself at the formation given in the incoming message.

Parameters:
msgMessage containing a DtSetFormationRequest.
virtual void DtDisaggregatedFormationController::processSetFormationType ( DtSimMessage msg) [protected, virtual]

Handler for setFormationTypeCallback().

If aggregate is currently tasked, calls updateFormationState(). Sets formation in aggregate state repository to the value given in the message, and calls updateFormationState() again.

Parameters:
msgMessage containing a DtSetFormationTypeRequest.
virtual void DtDisaggregatedFormationController::processSetHeading ( DtSimMessage msg) [protected, virtual]

Handler for setHeadingCallback().

If aggregate is currently tasked, calls updateFormationState(). Issues a DtSnapIntoFormationRequest to itself at the heading given in the incoming message.

Parameters:
msgMessage containing a DtSetHeadingRequest.
virtual void DtDisaggregatedFormationController::processSetLocation ( DtSimMessage msg) [protected, virtual]

Handler for setLocationCallback().

If aggregate is currently tasked, calls updateFormationState(). Issues a DtSnapIntoFormationRequest to itself at the heading given in the incoming message.

Parameters:
msgMessage containing a DtSetHeadingRequest.
virtual void DtDisaggregatedFormationController::processSnapIntoFormation ( DtSimMessage msg) [protected, virtual]

Handler for snapIntoFormationCallback().

If aggregate is currently tasked, calls updateFormationState(). Then calls snapIntoFormation().

Parameters:
msgMessage containing a DtSnapIntoFromationRequest.
virtual void DtDisaggregatedFormationController::processSubordinatesChanged ( DtEntityIdentifier  entId) [protected, virtual]

Handler for subordinates changed callback.

If formation is of type DtOtherAggregateFormation, changes it to DtWorkingFormation. Next, if formation is of type DtWorkingFormation, calls generateWorkingFormation() to create a formation given the current aggregate location, orientation, and subordinate positions. Finally, calls updateFormationState().

Parameters:
entIdThe ID of the entity whose subordinates have changed (ID of the aggregate).
virtual void DtDisaggregatedFormationController::snapIntoFormation ( const DtString formation,
const DtVector location,
double  heading,
bool  applyHeading 
) [protected, virtual]

Puts the aggregate into the given formation, at the given location and heading.

Issues set data request messages to each subordinate in the aggregate. Computes the position for each subordinate needed to construct the formation at the given location and heading. For individual subordinates, issues DtSetLocationRequests and DtSetHeadingRequests at the computed location and given heading. If applyFormationToSubaggregates is true (recurse), then for aggregate subordinates, issues DtSnapIntoFormationRequests at the computed location and given heading, thereby recursively snapping the aggregate into formation. Otherwise (applyFormationToSubordinates is false, no recursion) issues DtSetLocationRequest and DtSetHeadingReuqest to aggregate subordinates in the same way as for individuals. This allows for mixed formation (don't recursively apply given formation to subordinate aggregates).

Parameters:
formationType of formation to snap into.
locationLocal position aggregate where aggregate should position itself in formation.
headingHeading in radians at which aggregate should position itself in formation.
virtual void DtDisaggregatedFormationController::getCurrentFormation ( DtFormation formation) [protected, virtual]

Get current formation position and formation type.

If aggregate has a working formation, returns the current ad hoc formation positions from the process state repository. Otherwise, looks up known type of formation (e.g. column, line, wedge), return the formation from the formation descriptor.

Parameters:
formationType of formation (see extendedAggregateEnums.h for list of available types).

Generates the subset of subordinates available to participate in formation.

Only subordinates that are alive and not independently tasked are included in the result.

Returns:
The list of subordinates able to participate in formation. (mySubordinateInFormation)
virtual std::list<int> DtDisaggregatedFormationController::generateFormationPositions ( DtOrgViewManagedObjectListConstPtr entityInFormation) [protected, virtual]

Generates a list of formation positions for each entity in the formation.

If auto-promote-in-formation is false, positions are skipped in the formation for any entities that that have left the formation or are destroyed. Otherwise, the first n positions in the formation are used, based on the number of entities to be placed into formation.

virtual int DtDisaggregatedFormationController::findPositionInVector ( const std::vector< DtEntityIdentifier >  subordinateList,
const DtEntityIdentifier &  entityId 
) const [protected, virtual]

Helper function for generateFormationPositions().

Returns:
The position of entityId in the vector subordinateList.
virtual void DtDisaggregatedFormationController::generateFormationAtPositionAndOrientation ( const DtVector geocentricOrigin,
const DtTaitBryan &  geocentricOrientation,
std::vector< DtVector geocentricPositions,
DtFormation formation 
) [protected, virtual]

Constructs an ad hoc formation (set of positional offsets of participants) based on current relative positioning of subordinates, at given location and orientation.

Parameters:
geocentricOriginOrigin of coordinate system in geocentric coordinates, in which relative formation positions are computed from geocentric subordinate positions.
geocentricOrientationOrientation of coordinate system in geocentric coordinates, to be used to compute formation positions from subordinate positions.
formationconstructed from relative subordinate positions.
virtual void DtDisaggregatedFormationController::generateWorkingFormation ( DtFormation formation) [protected, virtual]

Creates an ad hoc formation from the current eligible subordinates current positions relative to one another.

Parameters:
formationThe generated formation.
virtual void DtDisaggregatedFormationController::updateFormationState ( ) [protected, virtual]

Recomputes and updates current working formation in process state repository, and updates subordinate list and formation positional data.

virtual void DtDisaggregatedFormationController::registerWithOrgManager ( ) [protected, virtual]

Register subordinateOrderChangedCallback with the DtOrganizationManager.

virtual void DtDisaggregatedFormationController::unregisterWithOrgManager ( ) [protected, virtual]

Unregister subordinateOrderChangedCallback with the DtOrganizationManager.

virtual void DtDisaggregatedFormationController::sendRequestToSelf ( const DtSetDataRequest request) const [protected, virtual]

Send given request to ourself.

Fills out data request message and sends it through the aggregate's radio.

Parameters:
requestA set data request to be issued to ourself.
virtual void DtDisaggregatedFormationController::sendRequestToSubordinate ( const DtSetDataRequest request,
const DtString subordinateObjectName 
) const [protected, virtual]

Send given request to one of our subordinates.

Fills out data request message and sends it to subordinate through our entity's radio.

Parameters:
requestThe data request to send to the given subordinate.
subordinateObjectNameThe object name of the subordinate to be given the set data request.
virtual bool DtDisaggregatedFormationController::createPSR ( ) [protected, virtual]

Creates myProcessState data member, and adds it to our process state repository manager.

Passes in the name and type specified in the component descriptor (if they exist) to the DtVrfProcessStateRepository::createRepository factory method. If name and/or type is not specified, uses the appropriate default strings defined in procSRTypes.h.

virtual void DtDisaggregatedFormationController::processOnTaskNotifyCallback ( const DtSimTask task,
const DtSimComponent notifier 
) [protected, virtual]

Called when the entity is about to start a new task.

Checks to see if any subordinates need to be re-added into the formation This can occur when a subordinate is independently tasked, but is later set to be tasked by superior again. 'Rediscover' these subordinates and bring them back into the formation.

Parameters:
taskTask aggregate is about to start.
notifierComponent responsible for executing task.
static void DtDisaggregatedFormationController::requestAvailableFormationsCallback ( const DtVrfObjectMessage msg,
void *  usr 
) [static, protected]
virtual void DtDisaggregatedFormationController::addSetDataCallbacks ( ) [protected, virtual]

Add set data request callbacks.

Set data request callbacks are added when component is first created, and whenever component is enabled.

Callbacks are removed when component is disabled or destroyed.

Non-virtual because it is called from the destructor.


Member Data Documentation

Descriptor used to configure this component.

Pointer to aggregate's state repository, cached in this class for convenience.

Pointer to aggregate's formation state repository, cached in this for convenience.

Flag used to indicate if the subordinateOrderChangedCallback() has been registered with the aggregate's organization manager.

This registration cannot occur until the first tick of the entity. This flag is initially false, and gets set to true in the first non-zero dT() tick..

Pointer to aggregate's command radio, cached in this class for convenience.

Pointer to aggregate's DtSetDataManager, cached in this class for convenience.

Container for state data associated with this component.

This state is saved and restored as part of a scenario (or checkpoint).

Flag used to indicate if formation-related callbacks are disabled (not registered).

These callbacks are disabled until the first tick. Flag is initially false, and then set to true in the first non-zero dt() tick.

Flag used to indicate first non-zero dT() tick.

Convenience pointer to the aggregate parameters for this entity.


The documentation for this class was generated from the following file:

Document ID: Generated on Fri Jun 29 16:33:32 EDT 2012 from SVN revision 116588
Copyright © 2005-2012 VT MÄK Inc. All Rights Reserved (www.mak.com)