entityResolver.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file entityResolver.h
//! \brief Defines the entity resolver for mapping between entity representations
//!
//! This file contains the DtEntityResolver class which provides a central system
//! for resolving and translating between different entity representation schemes.
//! It maps between display names, object IDs, entity IDs, and scene objects, enabling
//! the application to work with entities regardless of their underlying protocol.
 
#pragma once
 
#include "vrePlayerStation/export.h"
#include <vrvCore/DtDataBank.h>
#include <vrvCore/DtUniqueID.h>
#include <vrvCore/DtElementAttributeManager.h>
#include <vlpi/entityIdentifier.h>
#include <vreMessageManager/vreMessage.h>
#include <vrfutil/rwUUID.h>
 
// #include <boost/unordered_map.hpp>
#include <map>
 
#include <string>
#include <boost/signals2/signal.hpp>
 
namespace makVrv
{
class DtDe;
class DtSceneObject;
}; // namespace makVrv
 
namespace makVre
{
//! \brief Forward declaration of the entity discovered message class
class EntityDiscoveredMessage;
 
//! \brief Entity resolution and mapping system
//!
//! DtEntityResolver provides a central service for mapping between different
//! representations of entities in the simulation. It maintains mappings between
//! display names (marking text), object IDs, element IDs, and scene objects.
//! This enables the application to find and work with entities regardless of
//! which identifier system is used to reference them.
//!
//! The resolver also emits signals when entities are added or removed,
//! allowing other components to react to entity lifecycle events.
class PLAYERSTATION_DLL DtEntityResolver
{
public:
   //! \brief Type definition for mapping from strings to element IDs
   using StringToElementIdMap = std::map<std::string, makVrv::DtElementID>;
 
   //! \brief Type definition for mapping from element IDs to strings
   using ElementIdToStringMap = std::map<makVrv::DtElementID, std::string>;
 
   //! \brief Type definition for mapping from element IDs to scene objects
   using SceneObjectMap = std::map<makVrv::DtElementID, makVrv::DtSceneObject*>;
 
   //! \brief Constructor
   //! \param de Reference to the display engine
   //!
   //! Creates a new entity resolver associated with the given display engine.
   //! The display engine provides access to the visual representation of entities.
   DtEntityResolver(makVrv::DtDe& de);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the entity resolver.
   virtual ~DtEntityResolver();
 
   //! \brief Retrieves a scene object from an element ID
   //! \param elementId Element ID to look up
   //! \param modelSet Model set to search in
   //! \return Pointer to the scene object, or NULL if not found
   //!
   //! Utility function to find a scene object associated with an element ID
   //! in the specified model set. This is useful for accessing the visual
   //! representation of an entity when only its element ID is known.
   makVrv::DtSceneObject* sceneObjectFromElementId(makVrv::DtElementID elementId, makVrv::DtModelSetId modelSet);
 
   //! \brief Gets the map of all display names to element IDs
   //! \return Constant reference to the display name mapping
   //!
   //! Provides access to the complete mapping of display names to element IDs.
   //! When iterating through this map, iterator->first provides the display name,
   //! and iterator->second provides the corresponding element ID.
   const StringToElementIdMap& displayNames() const;
 
   //! \brief Gets the map of all scene objects
   //! \return Constant reference to the scene object mapping
   //!
   //! Provides access to the complete mapping of element IDs to scene objects.
   //! When iterating through this map, iterator->first provides the element ID,
   //! and iterator->second provides the corresponding scene object pointer.
   const DtEntityResolver::SceneObjectMap& sceneObjects() const;
 
   //! \brief Element ID lookup methods
   //! @{
 
   //! \brief Finds the element ID for an entity by its display name
   //! \param displayName Display name (marking text) of the entity
   //! \return Element ID of the entity, or NULL_ELEMENT_ID if not found
   //!
   //! Looks up the element ID associated with a particular display name.
   //! This is typically used to find an entity by its visible name or marking text.
   makVrv::DtElementID findElementID(const std::string& displayName) const;
 
   //! \brief Finds the element ID for an entity by its object ID
   //! \param objectId Object ID of the entity
   //! \return Element ID of the entity, or NULL_ELEMENT_ID if not found
   //!
   //! Looks up the element ID associated with a particular object ID.
   //! The object ID is typically a unique identifier from the network protocol.
   makVrv::DtElementID findElementIdByObjectId(const std::string& objectId) const;
   //! \brief Finds the element ID for an entity by its entity identifier
   //! \param entityId Entity identifier of the entity
   //! \return Element ID of the entity, or NULL_ELEMENT_ID if not found
   //!
   //! Looks up the element ID associated with a particular entity identifier.
   //! In DIS and RPR HLA, the VRL Connection Object ID is a string representation
   //! of a DtEntityIdentifier, so this delegates to findElementIdByObjectId.
   makVrv::DtElementID findElementIdByEntityId(const DtEntityIdentifier& entityId) const
   {
      return findElementIdByObjectId(entityId.string());
   }
   //! @}
 
   //! \brief UUID lookup methods
   //! @{
 
   //! \brief Finds the UUID for an entity by its element ID
   //! \param elementID Element ID of the entity
   //! \return UUID of the entity
   //!
   //! Retrieves the UUID associated with a particular element ID.
   //! Currently this performs the lookup by marking text, which may be ambiguous
   //! if multiple elements have the same marking text.
   DtUUID findUUID(makVrv::DtElementID elementID) const;
   //! \brief Finds the UUID for an entity by its entity identifier
   //! \param entityId Entity identifier of the entity
   //! \return UUID of the entity
   //!
   //! Convenience method that combines findElementIdByEntityId and findUUID
   //! to retrieve the UUID associated with a particular entity identifier.
   DtUUID findUUID(const DtEntityIdentifier& entityId) const { return findUUID(findElementIdByEntityId(entityId)); }
   //! @}
 
   //! \brief Display name lookup methods
   //! @{
 
   //! \brief Finds the display name for an entity by its element ID
   //! \param elementID Element ID of the entity
   //! \return Display name of the entity, or empty string if not found
   //!
   //! Retrieves the display name (marking text) associated with a particular element ID.
   //! This is typically the human-readable name of the entity as shown in the UI.
   std::string findDisplayName(makVrv::DtElementID elementID) const;
   //! \brief Finds the display name for an entity by its entity identifier
   //! \param entityId Entity identifier of the entity
   //! \return Display name of the entity, or empty string if not found
   //!
   //! Convenience method that combines findElementIdByEntityId and findDisplayName
   //! to retrieve the display name associated with a particular entity identifier.
   std::string findDisplayName(const DtEntityIdentifier& entityId) const
   {
      return findDisplayName(findElementIdByEntityId(entityId));
   }
   //! @}
 
   //! \brief Object ID lookup methods
   //! @{
 
   //! \brief Finds the object ID for an entity by its element ID
   //! \param elementID Element ID of the entity
   //! \return Object ID of the entity, or empty string if not found
   //!
   //! Retrieves the object ID associated with a particular element ID.
   //! The object ID is typically a unique identifier from the network protocol.
   std::string findObjectId(makVrv::DtElementID elementID) const;
   //! @}
 
   //! \brief Entity identifier lookup methods
   //! @{
 
   //! \brief Finds the entity identifier for an entity by its element ID
   //! \param elementID Element ID of the entity
   //! \return Entity identifier of the entity
   //!
   //! Retrieves the entity identifier associated with a particular element ID.
   //! In DIS and RPR HLA, the VRL Connection Object ID is a string representation
   //! of a DtEntityIdentifier, so this converts the object ID to an entity identifier.
   DtEntityIdentifier findEntityId(makVrv::DtElementID elementID) const
   {
      // In DIS and RPR HLA, the VRL Connection Object ID is a string rep of a DtEntityIdentifier
      return DtEntityIdentifier(findObjectId(elementID).c_str());
   }
 
   //! \brief Finds the entity identifier for an entity by its display name
   //! \param displayName Display name (marking text) of the entity
   //! \return Entity identifier of the entity
   //!
   //! Convenience method that combines findElementID and findEntityId
   //! to retrieve the entity identifier associated with a particular display name.
   DtEntityIdentifier findEntityId(const std::string& displayName) const
   {
      return findEntityId(findElementID(displayName));
   }
   //! @}
 
   //! \brief Object type lookup methods
   //! @{
 
   //! \brief Finds the object type for an entity by its element ID
   //! \param elementID Element ID of the entity
   //! \return Object type of the entity, or empty string if not found
   //!
   //! Retrieves the object type associated with a particular element ID.
   //! The object type describes the kind of entity (e.g., "Tank", "Aircraft").
   std::string findObjectType(makVrv::DtElementID elementID) const;
   //! \brief Finds the object type for an entity by its entity identifier
   //! \param entityId Entity identifier of the entity
   //! \return Object type of the entity, or empty string if not found
   //!
   //! Convenience method that combines findElementIdByEntityId and findObjectType
   //! to retrieve the object type associated with a particular entity identifier.
   std::string findObjectType(const DtEntityIdentifier& entityId) const
   {
      return findObjectType(findElementIdByEntityId(entityId));
   }
   //! @}
 
   //! \brief Message handlers
   //! @{
 
   //! \brief Handles entity discovered messages
   //! \param msg Pointer to the entity discovered message
   //! \return Message handling result
   //!
   //! Processes notifications about newly discovered entities, adding them
   //! to the resolver's tracking system and pending realization list.
   makVre::DtVreMessageResult handleEntityDiscovered(makVre::DtVreMessage* msg);
 
   //! \brief Handles entity removed messages
   //! \param msg Pointer to the entity removed message
   //! \return Message handling result
   //!
   //! Processes notifications about entities being removed from the simulation,
   //! removing them from the resolver's tracking system.
   makVre::DtVreMessageResult handleEntityRemoved(makVre::DtVreMessage* msg);
 
   //! \brief Handles element ID realization
   //! \param id Element ID that has been realized
   //!
   //! Called when an element ID has been fully realized in the simulation.
   //! This triggers the sending of EntityRealizedMessages for pending entities.
   void onElementIdRealized(makVrv::DtElementID id);
   //! @}
 
   //! \brief Scene object lookup methods
   //! @{
 
   //! \brief Finds the scene object for an entity by its element ID
   //! \param elementId Element ID of the entity
   //! \return Pointer to the scene object, or NULL if not found
   //!
   //! Retrieves the scene object associated with a particular element ID.
   //! Note that DtSceneObject has an elementID method, so given a DtSceneObject,
   //! you can also look up the display name (which, when using DIS or HLA/RPR is
   //! the marking text).
   makVrv::DtSceneObject* findSceneObject(makVrv::DtElementID elementId) const;
 
   //! \brief Finds the scene object for an entity by its display name
   //! \param displayName Display name (marking text) of the entity
   //! \return Pointer to the scene object, or NULL if not found
   //!
   //! Retrieves the scene object associated with a particular display name.
   makVrv::DtSceneObject* findSceneObject(const std::string& displayName) const;
 
   //! \brief Finds the scene object for an entity by its object ID
   //! \param objectId Object ID of the entity
   //! \return Pointer to the scene object, or NULL if not found
   //!
   //! Retrieves the scene object associated with a particular object ID.
   makVrv::DtSceneObject* findSceneObjectByObjectId(const std::string& objectId) const;
   //! \brief Finds the scene object for an entity by its entity identifier
   //! \param entityId Entity identifier of the entity
   //! \return Pointer to the scene object, or NULL if not found
   //!
   //! Convenience method that retrieves the scene object associated with
   //! a particular entity identifier. In DIS and RPR HLA, the VRL Connection
   //! Object ID is a string representation of a DtEntityIdentifier.
   makVrv::DtSceneObject* findSceneObjectByEntityId(const DtEntityIdentifier& entityId) const
   {
      // In DIS and RPR HLA, the VRL Connection Object ID is a string rep of a DtEntityIdentifier
      return findSceneObjectByObjectId(entityId.string());
   }
   //! @}
 
   //! \brief Signal emitted when an entity is added
   //!
   //! This signal is emitted whenever a new entity is added to the simulation.
   //! Handlers can connect to this signal to perform initialization or other
   //! operations when new entities are added.
   boost::signalslib::signal<void(makVrv::DtElementID entity)> signal_entityAdded;
 
   //! \brief Signal emitted when an entity is removed
   //!
   //! This signal is emitted whenever an entity is removed from the simulation.
   //! Handlers can connect to this signal to perform cleanup or other operations
   //! when entities are removed.
   boost::signalslib::signal<void(makVrv::DtElementID entity)> signal_entityRemoved;
 
protected:
   //! \brief Element processing slots
   //! @{
 
   //! \brief Slot called when elements are ready to process
   //! \param elements List of element IDs that are ready
   //!
   //! Internal handler that processes element ready notifications,
   //! updating the resolver's tracking system with the new elements.
   void slot_elementsReadyToProcess(const makVrv::DtElementData::ElementIdList& elements);
 
   //! \brief Slot called when elements are removed
   //! \param elements List of element IDs that were removed
   //!
   //! Internal handler that processes element removal notifications,
   //! removing the elements from the resolver's tracking system and
   //! emitting the signal_entityRemoved signal.
   void slot_elementsRemoved(const makVrv::DtElementData::ElementIdList& elements);
 
   //! \brief Slot called when element attributes are changed
   //! \param attrs List of element attributes that were changed
   //!
   //! Internal handler that processes element attribute change notifications,
   //! updating the resolver's tracking system with the modified attributes.
   void slot_elementsChanged(const makVrv::DtElementAttributeManager::EntryAttributesList& attrs);
   //! @}
 
protected:
   //! \brief Reference to the display engine
   //!
   //! Provides access to the 3D visualization and scene management system.
   makVrv::DtDe& myDe;
 
   //! \brief Mapping from display names to element IDs
   StringToElementIdMap myDisplayNameToElementIdMap;
 
   //! \brief Mapping from element IDs to display names
   ElementIdToStringMap myElementIdToDisplayNameMap;
 
   //! \brief Mapping from object IDs to element IDs
   StringToElementIdMap myObjectIdToElementIdMap;
 
   //! \brief Mapping from element IDs to object IDs
   ElementIdToStringMap myElementIdToObjectIdMap;
 
   //! \brief Mapping from element IDs to scene objects
   SceneObjectMap mySceneObjectMap;
 
   //! \brief List of discovered entities awaiting realization
   //!
   //! When an entity is discovered but not yet fully realized in the system,
   //! it is added to this list. Once realized, an EntityRealizedMessage is sent.
   std::vector<std::shared_ptr<EntityDiscoveredMessage>> myPendingRealization;
};
} // namespace makVre