 |
VR-Forces 4.7 Class Documentation
|
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
|
VR-Forces 4.7 Class Documentation
|
The Settings Manager DtSettingsManager (settingsManager.h) lets you save run-time settings in an XML file.
It is based on the boost::serialization library (for details, please see 17.9 - The Boost Serialization Library). The DtVrfSettingsManager (vrfSettingsManager.h) is a subclass that lets you remotely query and edit settings through custom messages that are supported by DtVrfRemoteController. The DtVrfSimSettingsManager (vrfSimSettingsManager.h) is the subclass that is used by the VR-Forces back-end. It specifies the name of the back-end settings file (vrfSimSettings.xml) and registers all the independent settings used by the back-end (for details, please see 17.3.2.2 Independent Settings).
Related settings are grouped into a settings object derived from DtSettingsObject (settingsObject.h). For instance, a dead reckoning object would have the translation, rotation, and aggregate threshold values. If a class wants to register a single value without creating a settings object class, it can use DtBoolSetting (boolSetting.h), DtIntSetting (intSetting.h), DtDoubleSetting (doubleSetting.h), or DtStringSetting (stringSetting.h). The settings objects are there strictly for serialization - it is expected that the current values will be stored in a class that uses the Settings Manager to save them. When the current values for the settings objects are needed (to write out the settings file or to respond to a front-end request), the settings object is passed back to the client that is responsible for updating it. This means that the client does not have to ensure that the settings object is always up to date - it just needs to provide a function to do the updating. DtSettingsObjects are created by a DtSettingsObjectFactory (settingsObjectFactory.h).
The DtSettingsManager class can be used from any application. DtVrfSimSettingsManager is the subclass that is specific to the VR-Forces back-end. The back-end needs to have persistent storage for back-end-wide settings. The settings stored in this file represent the run-time configuration of a back-end. In most cases these are settings provided from a front-end, but any case in which a back-end setting is changed at run time would apply. These settings are not meant to affect the back-end before its initialization.
The functionality of this file is as follows:
The Settings Manager can save two types of settings - those that are owned by a client of the Settings Manager, and those that are maintained by the Settings Manager itself.
Any DtSettingsObject that will be produced by a client of the DtSettingsManager must be registered with the Settings Manager by the client. The client calls DtSettingsManager::registerProducer() with the type and the name of the setting and a DtSettingsProducerFcn and void* user pointer. The DtSettingsObject is not passed in; the client never transfers an actual object instance. The client just needs to tell the Settings Manager that it is responsible for the setting. The Settings Manager creates the object when necessary, and calls the DtSettingsProducerFcn any time it needs to access the value. For example, this happens when a call to DtSettingsManager::lookupSetting() or write() is made.
DtSettingsManager can also maintain settings on behalf of a client. In general this is only done when there is no central object that is responsible for the setting. For example, the spot reports "on/off" state is used by every DtVrfObject that has a spot report generator, but there is no central spot report manager class to maintain this state. In this case DtVrfSimSettingsManager::init() calls DtSettingsManager::addIndependentBool() to add a DtBoolSettingsObject to the map of settings objects. There is no producer responsible for updating this value, however it can be changed by calling DtSettingsManager::setSetting() or through the remote setting mechanism.
Any object that wants to adjust itself based on a DtSettingsObject can access the DtVrfSimSettingsManager through the DtSimManager. This could happen at any time, but it is expected that this would usually happen during initialization. DtSettingsManager::lookupSetting() takes the name of the object the client is looking for. If the file fails to read, a null pointer is always returned to indicate that the value was not read in. If the name lookup in the settings map is successful, a const pointer to the requested member is returned.
Any object that wants to get a callback when a setting is changed can register itself as a consumer of that setting by calling DtSettingsManager::registerConsumer(). If the setting is designed to be changed remotely (for details, please see 17.3.5 Querying Settings from Remote Applications), the client registered as a producer must also register as a consumer so it can change itself when the setting is modified. The consumer function takes the name of the setting to be monitored, a DtSettingsConsumerFcn and a void* user pointer. These values are stored in a multi-map inside DtSettingsManager, which means that more than one DtSettingsConsumerFcn can be registered on a single setting. This makes it easier to support settings on an individual entity or component level, which do not have an intermediate manager class to deal them. The DtSettingsConsumerFcn returns a const DtSettingsObject and the void* user pointer to allow the client to update itself based on the new values.
The Settings Manager supports queries from DtVrfRemoteController based on string keys, and returns a copy of the same settings object being used in the back-end. This saves a lot of time because the custom messaging and callbacks required for the front-end to interrogate the back-ends are not necessary for each type of setting that needs to be transferred. The values returned are processed by the DtVrfBackendListener. The DtBackend class maintains a std::map() of DtSettingsObject for each back-end. DtBackend has a lookup method that takes the name of a settings object and returns a const pointer to the object, or 0 if it does not exist in the map.
DtVrfSimSettingsManager registers for the DtIfRequestSetting message, which allows retrieval of settings objects returned through the DtIfSetting message. DtIfRequestSetting contains a string that corresponds to a name of a setting registered in the manager. The DtIfSetting message contains a serialized copy of the settings object. When the DtVrfSimSettingsManager processes a DtIfRequestSetting message, the settings object is looked up through DtSettingsManager::lookupSetting() to insure that its DtSettingsProducerFcn gets called, so that the latest data from the settings producer is returned.
DtVrfRemoteController has a requestBackendSetting() method that takes a string that corresponds to the name of the DtSettingsObject, a DtSimulationAddress to address the query to, and a callback function, which will be called once the responses are received. In most cases, the address will be DtSimSendToAll, but it is also possible to pass in the address of a specific back-end. The DtVrfRemoteController passes the request to the DtVrfBackendListener. The DtVrfBackendListener receives the DtIfSettingResponse messages and stores the settings objects received in the corresponding DtBackends. It keeps track of each request made including the name of the setting requested, the back-ends that have not yet responded, and the callback function to call when the request is completed. Once the request is completed, the callback is called to indicate that all the responses have been received and it is now safe to iterate over the DtBackends and look up the setting by calling DtBackend::lookupSetting().
Remote VR-Forces applications can update the state of client objects by sending a DtIfModifySetting message. This message carries a serialized DtSettingsObject. The DtVrfSimSettingsManager listens for the modification messages, deserializes their payloads, and updates the existing object with the new one by calling DtSettingsManager::setSetting(). Objects that do not match any existing objects by name are ignored.
DtVrfRemoteController has a modifyBackEndSettingMethod() method, which takes a DtSettingsObject and a DtSimulationAddress. The object's name must correspond to a pre-existing back-end setting. The address defaults to DtSimSendToAll, but can also be targeted at specific back-ends. DtVrfRemoteController also has specialized methods to make the modify call on behalf of the user, for example setSpotReportsGloballyEnabled().
The settingsManager example demonstrates many techniques for working with the Settings Manager. The settingsManagerSim portion of the example is a back-end plug-in which demonstrates adding a new setting type, extending a built-in type, and creating a new instance of a Settings Manager which writes out its own file. The settingsManagerRemote portion of the example is a minimal front-end application which queries and modifies the Settings Managers in a back-end running with the settingsManagerSim plug-in.
[<< The Physical World] [Home] [Top of Page] [Spatial Subdivisions >>]