 |
VR-Forces 4.1.1 Class Documentation
|
|
VR-Forces 4.1.1 Class Documentation
|
In VR-Forces 3.12 DtModelKey was used to find object information in various dictionaries, most notable the DtModelDataDictionary. In VR-Forces 4.x this has been replaced with DtElementId. The DtElementId is the main key to use to look up data in the system. For details, please see Storing Data.
The API extends the element ID with the scene object ID. The scene object ID (DtUniqueId) represents an individual screen representation of an object, given a particular model set. For example, the 2D representation of an object has a different scene object ID than the 3D representation. If you have a scene object ID, you can use the DtElementData object to retrieve the element ID based on scene object ID. If you need a scene object ID from an element ID, the DtElementData can also do that mapping.
Selection sets (discussed in Managing Object Selection) contain the DtElementId of the objects selected. You can use these IDs to retrieve information about selected objects.
In VR-Forces 3.12, DtModelData was used as the foundation for data storage, symbol creation, and symbol updating. The DtModelData class does not exist in VR-Forces 4.x. It has been replaced with DtObjectDataInterface. This class (and subclasses) let you access data for any simulated object in the system:
To retrieve information about objects, you can either use the object's element ID or the object's name (marking text) from the DtVrfStateViewCollectionManager. The DtVrf- StateViewCollectionManager class is analogous to the DtModelDataDictionary in VRForces 3.12. In the DtVrfStateViewCollectionManager class you will use the lookupAnd- CastObjectData() method to return a shared data pointer to the data you need. For example, if you want to find an entity data:
Also, the IDs in the current selection set can be used to look up data for selected objects.
In VR-Forces 3.12, as soon as an object update was received over the network, it was immediately updated. In VR-Forces 4.x this is not the case. Each object is updated at a certain frame rate. This allows for better performance and control over when object information is updated. For example, if an object is selected, its object update rate is increased, assuming the user might want to know more information about this object. This means all other objects continue to update at a default rate, or not at all. This does not effect the position, speed, or orientation of the object, simply the additional data that is transmitted to the front-end for that object.
This information is stored in DtStateViewCollection classes. Each DtStateViewCollection keeps a list of all particular objects of a state view type and can be used to retrieve information about that object type. So, for example, there are collections of entities, aggregates, and environmental processes.
In VR-Forces the DtVrfStateViewCollectionManager manages all these collections. It is your way of retrieving information about a particular object and its DtStateView information. The DtVrfStateViewCollectionManager is analogous to the VR-Forces 3.12 DtModelDataDictionary class.
In the DtVrfStateViewCollectionManager, all objects that are in the system are stored in the mySimulatedBaseStateViewCollection member. This member holds all structures that are of a DtVrlinkSimulatedBaseState (which all state view objects subclass from). Using the findStateView() methods of the DtVrfStateViewCollectionManager, you can find the basic state view information about any object. This information can be retrieved by marking text name or by DtElementId of the object. If you know that an item is specifically an entity, aggregate, or environmental, you can use the state view collection that is appropriate to find the state data for that object.
The guiObjectDataInterface example details how to use these data interface classes.
In VR-Forces 3.12 you would use the map area of the currently active window to get a list of objects that were currently selected. In VR-Forces 4.x you use the DtSelection- Manager class to get the list of object selected, as follows:
You can then iterate over the list to get information about these objects from the DtVrfStateViewCollectionManager:
VR-Forces 4.x also supplies a convenience class called the DtVrfSelectionHandler. This class has methods for retrieving information about current selections. For example, if you want to get data for all the currently selected objects, you can use the code in the previous example or you could do the following:
Remember that each DtSimEntry contains the list of all available data for that object. Most objects in VR-Forces have two DtSimEntry views of data: the VR-Link State Repository data (DtVrlinkSimulatedEntityState) and the VR-Forces-specific object data (DtVrfObjectDataState). You can iterate over the simStates() of the state entry, dynamically casting to the object in question that you want. Once the dynamic cast succeeds, you can use that data.
In VR-Forces 3.12 if you wanted to affect the way that symbols were created, you would override the DtMtlSymbolMapper, and install your own version.
In VR-Forces 4.x, symbols are created from DtVisualDefinitionSets. These visualizer sets are organized in DtObjectDictionary classes. Each class of object (entity, aggregate, environmental, interaction) has its own object dictionary. In order to affect the look of a symbol, you can modify the object dictionary, adding your own DtVisualDefinition or DtVisualDefinitionSet. The exampleObjectDictionary, exampleRangeLine and exampleVisualDefinitionSet examples show how this is done.
Mapping entity type enumerations to models is now done in the Entity Type Mappings dialog box rather than in symbol map files. Entity types are mapped to entity definitions that contain the correct visualizer information for that entity type.
In VR-Forces 4.x, the actual visual definitions are not created in the main GUI thread. A DtElement object (or a subclass) is created. It contains all the visualizers needed to visualize an object. DtElement objects are created in the network thread and are protected from the main thread. If you want to, in code, change how these items look, you will need to do that before creation by changing the visual definition set for that particular object. Individual visualizers, however, can be created to self configure given certain conditions. The point being stressed here is that there has been an attempt to move away from direct manipulation of the symbols and move towards a more object oriented approach for symbol manipulation.
If you need to get access to an individual symbol, you can do this through the DtAgent- Manager. Since each object is scene dependent, you will need to know the model set you are referencing to get the scene object ID of the object you care about:
Please refer to the DtSceneObject class for the information you can retrieve.
In VR-Forces 3.12 you could create unpublished symbols by creating an appropriate DtModelData subclass and adding that model data into the application's Model Data Dictionary. You would then update that model data and mark it for update in the application to change the symbol.
In VR-Forces 4.x, there is now a DtLocalObjectManager class that does this for you. The guiLocalCreateObject example shows how to use this new class.
In VR-Forces 3.12, in order to affect how a symbol was updated, you would have either subclassed and installed your own version of the DtVrfGuiSymbolUpdater class or added post update callbacks.
In VR-Forces 4.x there is no centralized symbol updater. Each visualizer is responsible for doing its own updating. When a visualizer is created, it is handed a subclass of a DtStateListener. This class contains all the simulation data necessary to drive the visuals of an object. Signals are defined in these state listener subclasses that visualizers can connect to in order to update their state.
If you want to change how an existing object is updating, you must subclass and install that object into the DtVrlinkStateVisualizerFactory if this object has a VR-Link representation, or the DtStateVisualizerFactory if it does not.
To add subclasses to the VR-Link state visualizer factory you must create driver accessories for the VR-Link protocol you want to change. (Please see the addAttr example for an example of how to create an accessory.) You can then reference the VR-Link state visualizer factory as in the slot_onSimCreated() method (in DtAddAttrGuiAccessory.inl):
The same methodology can be used for the state visualizer factory:
In VR-Forces 3.12, to communicate with the back-end (sending sets, tasks or interface content messages), the remote controller was used: DtVrfGuiAppEventController:: remoteController().
In VR-Forces 4.x there is no direct access to the remote controller from the GUI thread. Since the GUI is not network dependent, the DtGuiThreadVrfRemoteController class interfaces the GUI to the back-end. Use this class to send all messages. The interface content example and the guiThreadVrfRemoteController example show how to send interface content messages using DtGuiThreadVrfRemoteController.
In VR-Forces 3.12 the DtVrfMessageInterface class was used to register callback messages for message types. In VR-Forces 4.x the DtNetworkMessageCallbackManager class is used. The DtGuiThreadVrfRemoteController also interfaces with this class, and that can be used as well. The interface content example and the networkCallbackManager example show how to register for a callback message using DtNetworkMessageCallbackManager.
In VR-Forces 3.12 you would subclass and install an event handler to handle mouse events and keyboard events. You might also have subclassed and installed your own version of the DtPvdMapArea or connected to signals to handle events.
In VR-Forces 4.x you subclass and install a DtEventProcessor. The DtEventProcessor subclasses have methods for mouse and keyboard messages. If you want to handle a mouse or keyboard message, override the appropriate method (processKeyboardEvent() or processMouseEvent()). If you handle the message you can return true or false. You can also be notified of events that were handled by other event processors before your event processor got a chance, by overriding the above methods and handling the case of a MouseLost event.
Add your event processor subclass into the DtInputDriver class. The DtInputDriver object is referenced through the driver manager:
The event processor can be added to the front or the back of the list (addEventProcessorToFront() or addEventProcessorToBack()). You can also get the list of event processors and insert it directly (eventProcessorList()). The exampleEventProcessor example has an example of how to use an event processor.
VR-Forces 3.12 mostly used Qt signals. VR-Forces 4.x mostly uses Boost signals. While some Qt signals are used in the Qt layer, they are usually translated back into Boost signals.
To use a Boost signal you must connect to a signal and give a method to call when the signal is invoked.
The following examples show how to connect to signals without parameters (preTick), and with parameters (postTick). The binding is done to an object class and an instance of that object.
In VR-Forces 3.12 there was no way to be notified when the application was about to tick or had completed a tick. In VR-Forces 4.x, you can get this information. The main class of a VR-Vantage application is DtDe. The DtDe class is typically passed to any object that might need to use it, and is available to any plug-in on startup.
To be notified when the application is about to tick, connect to the signal_preTick signal.
On a post tick, connect to the signal_postTick signal.
In VR-Forces 3.12, to find out when selections had changed, you would connect to the Qt signal sent by the map area on selection changed (selectionUpdated, selectionChanged, and so on). In VR-Forces 4.x, you use the Selection Manager and its signals to be notified when selections have changed. You can get a reference to the Selection Manager as follows:
The signal_currentSelectionChanged signal is sent any time the current selection is changed. It supplies the following parameters:
The IDs supplied are element IDs, which can be used to retrieve data about the selected objects. Managing Object Selection explains how to use this information.
The signal_vertexSelected and signal_vertexDeselected signals are sent when vertices on a line are selected or unselected.
In VR-Forces 3.12, to find out when an object was added, you would have used the modelDataAdded signal. In VR-Forces 4.x you use the DtElementData object. You can get to the DtElementData as follows:
The signal signal_elementsAdded is sent for any elements added during that tick. You can then use the State View Collection Manager to find information about the elements added. Due to the nature of the multi-threading of the application, it is possible that the state view data does not yet exist for those elements. In that case, for the state view collection you want to retrieve information for, connect to the signal_stateViewAdded signal. For example:
When the state view is added you can then get information about that object.
The object data interface allows you to change how often you want to have data refreshed into the object and to be notified when that data is updated. The setUpdateRate() method lets you set the update frequency. The boost signal_dataUpdated signal is sent when data has been updated.
To track resources for entities, you can connect to the signal_resourcesChanged() method of the data interface class and then inspect the resources() method to see the resources. You can request new resources by calling the requestResources() method.
In VR-Forces 3.12 you would have used the modelDataAboutToBeRemoved signal. In VR-Forces 4.x, you use the element data's signal_elementsToBeRemoved signal. This provides a list of all the elements that are being removed in this tick. Please see Tracking New Objects for how to retrieve a reference to the DtElementData.
You can also track the removal of specific objects. The boost signal_dataRemoved is sent from the data interface when a simulated object is removed.
[<< VR-Forces 3.12.x to 4.0.3 Simulation Model Set Changes] [Home] [Top of Page] [VR-Forces 4.0.3 to 4.0.4 Simulation Model Set Changes >>]