minimapUpdater.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file minimapUpdater.h
//! \brief Component that provides minimap functionality in a separate channel
//! \ingroup vreCommonComponents
 
#pragma once
 
#include "vreCommonComponents/export.h"
#include "vreCommonComponents/overlayComponent.h"
 
#include <vreMessageManager/vreMessage.h>
 
#include <vreUtil/color.h>
 
namespace makVrv
{
class DtOsgChannel;
class DtWindowConfiguration;
class DtLineSegment;
class DtCameraNode;
} // namespace makVrv
 
namespace makVre
{
class DtVrvOverlay;
 
//! \brief Type identifier for DtMinimapUpdater component
constexpr const char* DtMinimapUpdaterType = "DtMinimapUpdater";
 
//! \brief Component that creates, updates, and manages a minimap display
//!
//! Creates, updates, and destroys a new channel, "Minimap", to display a 2D map in the main window.
//! The minimap can be configured with multiple view modes, ownship indicators, compass overlays,
//! and can be toggled on and off. It also adjusts visibility when binoculars are in use.
class VRECOMMONCOMPONENTS_DLL DtMinimapUpdater : public DtOverlayComponent
{
public:
   //! \brief Constructor for DtMinimapUpdater
   //!
   //! Initializes component state with default values
   DtMinimapUpdater();
 
   //! \brief Virtual destructor for DtMinimapUpdater
   virtual ~DtMinimapUpdater() override;
 
   //! \brief Initializes the minimap updater component
   //! \param player Pointer to the player station this component belongs to
   //! \param config Configuration table containing minimap settings
   //! \return True if initialization succeeded, false otherwise
   //!
   //! Processes configuration data and sets up the minimap channel based on the specified
   //! view modes. Configures position, size, frame properties, and ownship indicators.
   virtual bool initialize(makVre::DtPlayerStation* player, makVre::DtInitTable& config) override;
 
   //! \brief Performs post-initialization tasks after all components are initialized
   //! \return True if post-initialization succeeded, false otherwise
   //!
   //! Adds a callback to monitor changes to the binoculars state so the minimap
   //! can be hidden when binoculars are active
   virtual bool postInitialize() override;
 
   //! \brief Called every frame to update the minimap
   //! \param dt Delta time since the last frame in seconds
   //!
   //! Updates the heading of the compass overlay to match the player's current heading
   //! when the minimap is displayed
   virtual void tick(double dt) override;
 
   //! \brief Shuts down the minimap updater component
   //!
   //! Destroys the minimap channel, cleans up resources, and removes callbacks
   //! and message handlers. Restores the original icon scale setting.
   virtual void shutdown() override;
 
   //! \brief Returns the type identifier for this component
   //! \return The type string for DtMinimapUpdater
   virtual const char* type() const override;
 
protected:
   //! \brief Creates the overlay for displaying ownship indicators
   //!
   //! Sets up the VRV overlay that will contain the ownship dot and compass indicators
   //! on top of the minimap display
   virtual void createOverlay();
 
   //! \brief Handles changes to the usingBinoculars attribute
   //! \param usingBinoculars New value of the usingBinoculars attribute
   //!
   //! Shows or hides the minimap when the binoculars state changes,
   //! hiding the minimap when binoculars are in use
   virtual void handleUsingBinocularsChanged(bool usingBinoculars);
 
   //! \brief Structure defining a minimap view mode configuration
   struct ViewMode
   {
      //! \brief Name of the view mode for identification
      std::string name;
 
      //! \brief Left edge position (0.0-1.0 in normalized screen coordinates)
      double left;
 
      //! \brief Right edge position (0.0-1.0 in normalized screen coordinates)
      double right;
 
      //! \brief Bottom edge position (0.0-1.0 in normalized screen coordinates)
      double bottom;
 
      //! \brief Top edge position (0.0-1.0 in normalized screen coordinates)
      double top;
 
      //! \brief Flag indicating if the minimap should maintain a square aspect ratio
      bool square;
 
      //! \brief Flag indicating if this view mode is visible or off-screen
      bool visible;
   };
 
   //! \brief Switches to the next minimap view mode
   //!
   //! Cycles through the view modes defined in the configuration,
   //! updating the minimap's position, size, and visibility
   virtual void cycleMinimapMode();
 
   //! \brief Handles window creation messages
   //! \param msg The window created message
   //! \return Message handling result indicating if the message was handled
   //!
   //! Captures the minimap channel when it's created and sets up node masks and observer settings
   virtual DtVreMessageResult handleWindowCreated(DtVreMessage* msg);
 
   //! \brief Handles window destruction messages
   //! \param msg The window destroyed message
   //! \return Message handling result indicating if the message was handled
   //!
   //! Clears references to the destroyed minimap channel
   virtual DtVreMessageResult handleWindowDestroyed(DtVreMessage* msg);
 
   //! \brief Handles minimap-specific messages
   //! \param msg The minimap message (cycle or reset zoom)
   //! \return Message handling result indicating if the message was handled
   //!
   //! Processes messages to cycle minimap view modes or reset the zoom level
   virtual DtVreMessageResult handleMinimapMessage(DtVreMessage* msg);
 
   //! \brief Callback for window configuration change events
   //! \param deName Name of the distributed environment
   //! \param windowName Name of the window that changed
   //! \param windowConfig New window configuration
   //!
   //! Updates the minimap channel's viewport when the window is resized
   //! to maintain the correct position and proportions
   virtual void slot_onWindowConfigurationChanged(
      const std::string& deName, const std::string& windowName, const makVrv::DtWindowConfiguration& windowConfig);
 
   //! \brief Creates the minimap channel using the specified view mode
   //! \param mode The view mode configuration to use for the minimap
   //!
   //! Creates a new minimap channel with the appropriate position and size
   virtual void createMinimap(const ViewMode& mode);
 
   //! \brief Modifies an existing minimap channel using the specified view mode
   //! \param mode The view mode configuration to apply to the minimap
   //!
   //! Updates the position, size, and visibility of the minimap channel
   virtual void modifyMinimap(const ViewMode& mode);
 
   //! \brief Destroys the minimap channel
   //!
   //! Removes the minimap channel from the window manager
   virtual void destroyMinimap();
 
   //! \brief Registers message handlers for minimap-related messages
   //!
   //! Sets up handlers for window creation/destruction and minimap control messages
   virtual void registerHandlers();
 
   //! \brief Unregisters message handlers
   //!
   //! Removes all handlers for minimap-related messages
   virtual void unregisterHandlers();
 
   //! \brief Adds channel event processor association
   //!
   //! Associates the minimap channel with a target channel for event processing
   virtual void addChannelEventProcessorAssociation();
 
   //! \brief Removes channel event processor association
   //!
   //! Removes the association between the minimap channel and the target channel
   virtual void removeChannelEventProcessorAssociation();
 
   //! \brief Builds frame elements around the minimap
   //! \param elements Configuration table containing element definitions
   //!
   //! Overrides the base class function to programmatically create a frame
   //! around the minimap based on the current view mode
   virtual void buildElements(DtInitTable& elements) override;
 
   //! \brief Calculates screen coordinates for a minimap view mode
   //! \param mode The view mode to calculate coordinates for
   //! \param left Output parameter for the left coordinate
   //! \param right Output parameter for the right coordinate
   //! \param bottom Output parameter for the bottom coordinate
   //! \param top Output parameter for the top coordinate
   //!
   //! Calculates the actual screen coordinates for the minimap based on the view mode settings.
   //! If square is true, the right coordinate is adjusted to maintain a square aspect ratio.
   //! If visible is false, coordinates are set to place the channel off-screen.
   virtual void getViewModeScreenCoordinates(
      const ViewMode& mode, double& left, double& right, double& bottom, double& top);
 
   //! \brief Updates the minimap visibility based on current state
   //!
   //! Shows or hides the minimap only when the visibility state changes,
   //! avoiding redundant calls to showMinimap or hideMinimap
   virtual void updateMinimapVisibility();
 
   //! \brief Shows the minimap by enabling rendering
   //!
   //! Restores the node masks for the minimap cameras to make the minimap visible
   virtual void showMinimap();
 
   //! \brief Hides the minimap by disabling rendering
   //!
   //! Sets the node masks for the minimap cameras to zero to hide the minimap
   virtual void hideMinimap();
 
   //! \brief Handles resizing of the map overlay
   //!
   //! Adjusts the position and size of the ownship indicators
   //! when the map overlay is resized
   virtual void handleMapOverlayResized();
 
   //! \brief Sets the node mask on a camera node
   //! \param node The camera node to modify
   //! \param newMode The new node mask to apply
   //! \param currentExpected The expected current node mask
   //! \param setIfUnexpected Whether to set the mask if the current value is unexpected
   //!
   //! Sets the node mask on the specified camera node, with validation to detect
   //! if the node mask has been changed by another component
   virtual void setNodeMask(
      makVrv::DtCameraNode* node, unsigned int newMode, unsigned int currentExpected, bool setIfUnexpected = true);
 
   //! \brief Collection of available minimap view modes
   std::vector<ViewMode> myModes;
 
   //! \brief Index of the currently active view mode
   unsigned int myCurrentMode;
 
   //! \brief Initial map scale to restore on shutdown
   int myInitialMapScale;
 
   //! \brief Color of the frame around the minimap
   DtColor myFrameColor;
 
   //! \brief Width of the frame around the minimap in pixels
   double myFrameWidth;
 
   //! \brief Name of the minimap channel
   std::string myMinimapChannelName;
 
   //! \brief Name of the window containing the minimap
   std::string myWindowName;
 
   //! \brief Name of the channel that will receive events from the minimap
   std::string myEventProcessorTargetChannel;
 
   //! \brief Flag indicating if the minimap is currently visible
   bool myIsMinimapVisible;
 
   //! \brief Flag indicating if the minimap is disabled
   bool myDisableMinimap;
 
   //! \brief Flag indicating if the minimap should be created at engagement
   bool myInitializeMinimapOnEngage;
 
   //! \brief Pointer to the OSG channel used for the minimap
   makVrv::DtOsgChannel* myMinimapChannel;
 
   //! \brief Width of the map in screen coordinates
   double myMapWidth;
 
   //! \brief Height of the map in screen coordinates
   double myMapHeight;
 
   //! \brief Reference height for sizing ownship indicators
   double myReferenceHeight;
 
   //! \brief Filename of the texture for the ownship dot indicator
   std::string myOwnshipDotTextureFilename;
 
   //! \brief Filename of the texture for the ownship compass indicator
   std::string myOwnshipCompassTextureFilename;
 
   //! \brief Size of the ownship dot indicator as a fraction of map height
   double myOwnshipDotSize;
 
   //! \brief Size of the ownship compass indicator as a fraction of map height
   double myOwnshipCompassSize;
 
   //! \brief Color of the ownship dot indicator
   DtColor myOwnshipDotColor;
 
   //! \brief Overlay for displaying ownship indicators on the minimap
   DtVrvOverlay* myMapOverlay;
 
   //! \brief Quad proxy for the ownship dot indicator
   makVrv::DtQuadProxy* myOwnshipDotQuadProxy;
 
   //! \brief Quad proxy for the ownship compass indicator
   makVrv::DtQuadProxy* myOwnshipCompassQuadProxy;
 
   //! \brief Initial icon scale value to restore on shutdown
   float myInitialIconScale;
 
   //! \brief Cached node mask for the scene camera
   unsigned int mySceneNodeMask;
 
   //! \brief Cached node mask for the RTT camera
   unsigned int myRttNodeMask;
 
   //! \brief Cached node mask for the overlay camera
   unsigned int myOverlayNodeMask;
 
   //! \brief Cached node mask for the normalized overlay camera
   unsigned int myNormalizedOverlayNodeMask;
};
} // namespace makVre