 |
VR-Forces Developer's Guide
|
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
|
VR-Forces Developer's Guide
|
To enable simulation objects to save and restore their state as part of a scenario (or checkpoint), each VR-Forces object has a set of DtVrfProcessStateRepositoryManager (procSRMgr.h) instances, which maintain a set of DtVrfProcessStateRepositories (processSR.h) used by a simulation object.
Process state repositories are also sometimes used to share state data among a set of related components (such as a weapon system, or movement system).
Each component system on a simulation object has its own process state repository manager, and the simulation object has one master process state repository manager at the top level. Components that are part of a system typically access only the process state repository manager that is part of their system. In this way, two systems that are very similar (or even identical) can be added to the same simulation object without interfering with each other. For example, it is possible to attach two of the same type of gun to an entity, and have them each operate independently.
The use of process state repositories is not intended to circumvent the use of ports and port groups for communication between components. Use ports and ports groups to communicate information such as the steering and throttle inputs between an automotive controller and an automotive actuator. (For details, please see Ports and Port Groups.) By contrast, the process state repository does not facilitate communication; it holds state information such as "how long have I been waiting?" or "what gear am I in?" which multiple components might want access to. The components should not have to connect to one another to exchange this data. By placing state information in a process state repository, we only have to maintain a single copy of the information, easily accessible to a number of components.
Process state repositories are derived from DtReaderWriter, which gives them the ability to read and write themselves to file, so state information can be saved to the order of battle file. The name inherited from DtReaderWriter is used as a key into the Process State Repository Manager, enabling lookup of process state repositories by name. A simulation object can have multiple process state repositories of the same type, but with different names. This makes it possible to configure an entity with multiple similar subsystems, such as multiple weapons.
The DtVrfProcessStateRepositoryManager holds the list of DtVrfProcessStateRepositories for a simulation object, keyed on their reader/writer name. It does not create or delete any of the process state repository objects used by the object. Specific components are responsible for creating and deleting them.
All process state repositories are derived from DtVrfProcessStateRepository (processSR.h). There is a comprehensive list of derived process state repository classes on the DtVrfProcessStateRepository page.
Derived process state repository classes contain parameters and state member data appropriate to different categories of processes. For example, the DtAutomotivePSR holds all of the state and parameters needed for processes associated with ground vehicle movement, It contains data members such as the name of the waypoint the simulation object was heading toward, and the current gear the vehicle is in. All of the components used to simulate ground vehicle movement use the DtAutomotivePSR to either examine or set states associated with that process.
Components use the process state repository as a place to set or retrieve state as needed. For example, the weapon process state repository (DtVrfWeaponPSR) holds the target-acquired state for a given weapon system. When the DtWeaponController acquires a target in its acquireTarget() member function, it sets the target-acquired status in the process state repository, for example:
The DtBallisticGunController queries the weapon process state repository for the target acquired status in its tick, for example:
Process state repositories are created through the standard factory mechanism used in VR-Forces. (For details, please see VR-Forces Factories.) The string constants used as keys to the process state repository factory are defined in procSRTypes.h.
A set of components working together to accomplish a task can be thought of as a subsystem. Typically the set of components making up a subsystem share a single process state repository. For example, the set of controllers and actuators that logically represent a single weapon share the same weapon process state repository. One of the components is responsible for creating and registering the process state repository with the Process State Repository Manager. The remaining components look up and cache a pointer to the process state repository. Typically, the actuator is the component that creates the process state repository, and the rest of the components (typically controllers) keep a pointer to it.
A component that creates a process state repository does so when it is initialized (by calling its createPSR() member function from its init() function, during the simulation object creation process). The component that creates the process state repository is also responsible for registering it with the entity’s Process State Repository Manager. The component tells the Process State Repository Manager the name of the object, and providing a pointer to the object. This makes the process state repository available for lookup-by-name by any interested components. It also ensures that the contents of the process state repository are saved and restored as part of the entity’s state in a scenario save or checkpoint. The component that creates the process state repository is also responsible for removing it from the Process State Repository Manager and deleting the memory associated with it. This typically happens in the component’s destructor.
If a component is responsible for creating a process state repository, its component descriptor specifies the type and name of the process state repository to create.
For example, the DtAutomotiveActuatorComponent creates the DtAutomotivePSR for ground vehicles. The entry in the object parameter database is as follows:
This tells the automotive actuator to create a process state repository of type DtAutomotivePSR with the name vrf-automotive-process-state.
Since one of the components in a subsystem has created the process state repository, the rest of the interested components must look up the process state repository by name in the Process State Repository Manager. Components that need to look up and cache a pointer to a process state repository override the postAddComponentsInit() member function (a member function that gets invoked by the Component Manager for each component, after all components have been created and initialized). The name of the process state repository to create is given in its component descriptor. For backwards compatibility, if no process state repository name is specified in the descriptor’s entry in the object parameter database, then the appropriate default name is used (default process state repository names are defined in procSRTypes.h).
For example, for ground vehicles, all controllers derived from DtGroundAutoControllerComponent need to look up the DtAutomotivePSR (created by the DtAutomotiveActuatorComponent). A typical set of descriptor entries for these components would look like the following:
This example indicates that both the move-to and move-along controllers should look up the process state repository by the name vrf-automotive-process-state in the Process State Repository Manager.
Because process state repositories are saved as part of an entity’s state in the order of battle file, all of the state member data that needs to be preserved in a scenario or checkpoint should be kept in a process state repository. Components are not saved as part of a scenario, so any state member data in those classes is not preserved when a scenario gets saved. If you are extending the toolkit by adding or extending components, you may want to extend the process state repositories to include any new process-related state you introduce.
The Add Sim Component (Controller and Process State Repository) (addSimComponent) example shows how to create a new controller with a process state repository that holds its current state and saves its state in the scenario.