hudUpdater.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file hudUpdater.h
//! \brief Defines DtHudUpdater base class for managing HUD elements in the human role
//! \ingroup vreHumanFrontend
 
#pragma once
 
#include "vreHumanFrontend/export.h"
 
#include "vrePlayerStation/playerComponent.h"
#include "vreUtil/attribute.h"
#include "vreMessageManager/vreMessage.h"
 
#include <vrvGraphics/DtGlFontManager.h>
 
#include <osg/ref_ptr>
#include <vreUtil/color.h>
 
namespace makVrv
{
//! \brief Forward declaration of the display element class
class DtDe;
 
//! \brief Forward declaration of the quad proxy class
class DtQuadProxy;
 
//! \brief Forward declaration of the text proxy class
class DtTextProxy;
 
//! \brief Forward declaration of the OSG channel class
class DtOsgChannel;
 
//! \brief Forward declaration of the overlay renderer class
class DtOverlayRenderer;
} // namespace makVrv
 
namespace osg
{
//! \brief Forward declaration of the OSG texture class
class Texture;
 
//! \brief Forward declaration of the OSG geode class
class Geode;
} // namespace osg
 
namespace makVre
{
namespace HudUpdaterConfig
{
//! \ingroup RoleConfigParams
//! \defgroup HudUpdaterRoleParams HUD Updater Role Parameters
//! \roleInherits{PlayerComponentRoleParams}
//! Configuration Options for HUD updater role.
//! @{
 
//! \vreRoleParam{fontPath,string,"$(SHARED_DATA_DIR)/Fonts/Furore.otf",hudUpdater,Font file path for HUD text rendering.}
constexpr const char* fontPath = "fontPath";
 
//! \vreRoleParam{fontSize,float,16.0,hudUpdater,Font size for HUD text elements.}
constexpr const char* fontSize = "fontSize";
 
//! @}
} // namespace HudUpdaterConfig
 
//! \brief Forward declaration of the menu cursor class
class DtMenuCursor;
 
//! \brief Forward declaration of the entity resolver class
class DtEntityResolver;
 
//! \brief Forward declaration of the base HUD item class
class HudItem;
 
//! \brief Forward declaration of the HUD text item class
class HudTextItem;
 
//! \brief Forward declaration of the HUD image item class
class HudImageItem;
 
//! \brief Type identifier constant for DtHudUpdater components
//!
//! This constant defines the string identifier used to identify DtHudUpdater
//! component types within the VR-Engage framework. It is used for component
//! registration, type checking, and serialization operations.
constexpr const char* DtHudUpdaterType = "DtHudUpdater";
 
//! \brief Base class for HUD (Heads-Up Display) updaters in the human role
//!
//! DtHudUpdater provides a base framework for creating and managing HUD elements
//! such as text, images, and colored quads. It handles visibility, positioning,
//! and updates of HUD elements based on player state. This class is designed to be
//! extended by specific HUD implementations for different gameplay purposes.
class HUMAN_DLL DtHudUpdater : public makVre::DtPlayerComponent
{
public:
   //! \brief Constructor
   //!
   //! Creates a new HUD updater component with default state.
   DtHudUpdater();
 
   //! \brief Virtual destructor
   virtual ~DtHudUpdater() override;
 
   //! \brief Initializes the HUD updater
   //! \param player Pointer to the player station
   //! \param config Configuration settings for initialization
   //! \return True if initialization was successful, false otherwise
   virtual bool initialize(makVre::DtPlayerStation* player, makVre::DtInitTable& config) override;
 
   //! \brief Performs post-initialization setup
   //! \return True if post-initialization was successful, false otherwise
   virtual bool postInitialize() override;
 
   //! \brief Updates the HUD elements for the current frame
   //! \param dt Delta time since the last frame in seconds
   virtual void tick(double dt) override;
 
   //! \brief Cleans up resources when the component is being shut down
   virtual void shutdown() override;
 
   //! \brief Returns the component type identifier
   //! \return String identifier for this component type
   //!
   //! Returns the type identifier string for this component, which is used
   //! by the VR-Engage framework for component identification and management.
   //! The returned value matches DtHudUpdaterType.
   virtual const char* type() const override;
 
   //! \brief Adds a HUD item to this updater
   //! \param item Pointer to the HUD item to add
   void addItem(makVre::HudItem* item);
 
   //! \brief Removes a HUD item from this updater
   //! \param item Pointer to the HUD item to remove
   void removeItem(makVre::HudItem* item);
 
   //! \brief Gets the overlay renderer used by this HUD updater
   //! \return Pointer to the overlay renderer
   makVrv::DtOverlayRenderer* getOverlay() const;
 
   //! \brief Converts normalized x-coordinate to pixel x-coordinate
   //! \param norm Normalized x-coordinate (0.0 to 1.0)
   //! \return Pixel x-coordinate
   inline float xPixel(const float norm) const;
 
   //! \brief Converts normalized y-coordinate to pixel y-coordinate
   //! \param norm Normalized y-coordinate (0.0 to 1.0)
   //! \return Pixel y-coordinate
   inline float yPixel(const float norm) const;
 
   //! \brief Converts normalized width to pixel width
   //! \param norm Normalized width (0.0 to 1.0)
   //! \return Pixel width
   inline float pixelW(const float norm) const;
 
   //! \brief Converts normalized height to pixel height
   //! \param norm Normalized height (0.0 to 1.0)
   //! \return Pixel height
   inline float pixelH(const float norm) const;
 
protected:
   //! \brief Calculates heading angle between observer and target positions
   //! \param geocentricObserverPosition Geocentric position of the observer
   //! \param geocentricTargetPosition Geocentric position of the target
   //! \return Heading angle in degrees
   //!
   //! Utility function used by derived classes to calculate heading for HUD elements
   double headingAngleTo(const DtVector& geocentricObserverPosition, const DtVector& geocentricTargetPosition);
 
protected:
   //! \brief Starts this HUD updater
   //!
   //! Initializes and shows HUD elements
   virtual void start();
 
   //! \brief Stops this HUD updater
   //!
   //! Hides and cleans up HUD elements
   virtual void stop();
 
   //! \brief Called when this HUD updater is started
   //!
   //! Pure virtual method implemented by derived classes to handle initialization
   //! of specific HUD elements when the updater is started
   virtual void onStart() = 0;
 
   //! \brief Called when this HUD updater is stopped
   //!
   //! Pure virtual method implemented by derived classes to handle cleanup
   //! of specific HUD elements when the updater is stopped
   virtual void onStop() = 0;
 
   //! \brief Updates all HUD elements
   //!
   //! Updates the state and visibility of all HUD elements managed by this updater
   virtual void updateAll();
 
   //! \brief Sets up overlay renderers for HUD elements
   //!
   //! Creates and configures overlay renderers for displaying HUD elements
   virtual void setupOverlays();
 
   //! \brief Updates HUD elements based on visibility
   //! \param visible Flag indicating if the reticle is visible
   //!
   //! Pure virtual method called during tick to update HUD elements based on
   //! visibility. Implemented by derived classes to handle specific HUD element updates.
   virtual void updateHudElements(bool visible) = 0;
 
   //! \brief Handles channel destruction event
   //! \param displayName Name of the display
   //! \param windowName Name of the window
   //! \param channelName Name of the channel that was destroyed
   virtual void channelDestroyed(
      const std::string& displayName, const std::string& windowName, const std::string& channelName);
 
   //! \brief Handles viewport change events
   //!
   //! Called when the viewport size or properties change
   virtual void onViewportChanged();
 
   //! \brief Deletes all HUD elements
   //!
   //! Removes all HUD elements managed by this updater
   virtual void deleteAll();
 
   //! \brief Called when all HUD elements are being deleted
   //!
   //! Pure virtual method implemented by derived classes to handle cleanup
   //! of specific HUD elements when all elements are being deleted
   virtual void onDeleteAll() = 0;
 
   //! \brief Finds a channel by name
   //! \param channelName Name of the channel to find, defaults to "Channel 1"
   //! \return Pointer to the found channel, or nullptr if not found
   //!
   //! Looks up a channel by name. Finds the first channel if channelName is blank.
   virtual makVrv::DtOsgChannel* findChannel(const std::string& channelName = "Channel 1");
 
   //! \brief Creates an overlay renderer for the specified channel
   //! \param channel Pointer to the channel to create the overlay for
   //! \param geodeOut [out] Reference to the geode that will contain the overlay
   //! \return Pointer to the created overlay renderer
   virtual makVrv::DtOverlayRenderer* createOverlay(makVrv::DtOsgChannel* channel, osg::Geode*& geodeOut);
 
   //! \brief Sets up quad elements for the HUD
   //!
   //! Initializes and configures quad elements used in the HUD
   virtual void setupQuads();
 
   //! \brief Map of text items to their proxies
   //!
   //! Maps HUD text items to pairs of the item and its text proxy
   std::map<const makVre::HudTextItem*, std::pair<makVre::HudTextItem*, makVrv::DtTextProxy*>> myTextItemMap;
 
   //! \brief Map of image items to their proxies
   //!
   //! Maps HUD image items to pairs of the item and its quad proxy
   std::map<const makVre::HudImageItem*, std::pair<makVre::HudImageItem*, makVrv::DtQuadProxy*>> myImageItemMap;
 
   //! \brief Flag indicating if this HUD updater is active
   bool myActive;
 
   //! \brief Handle to Attribute indicating if VR mode is currently enabled
   DtAttributeHandleType<bool> myUsingVr;
 
   //! \brief Handles channel creation event
   //!
   //! Sets myChannelsUpdated to true. In the next tick call, the updater
   //! will check to see if its channel exists.
   void slot_onChannelCreated();
 
   //! \brief Handles channel destruction notification
   //!
   //! Called when a channel is about to be destroyed
   void slot_onChannelToBeDestroyed();
 
   //! \brief Configuration structure for HUD image elements
   struct HudImageConfig
   {
      //! \brief Default constructor
      HudImageConfig();
 
      //! \brief Texture for the image
      osg::ref_ptr<osg::Texture> texture;
 
      //! \brief Filename of the image texture
      std::string filename;
 
      //! \brief Normalized x-coordinate of the image (0.0 to 1.0)
      float x;
 
      //! \brief Normalized y-coordinate of the image (0.0 to 1.0)
      float y;
 
      //! \brief Normalized width of the image (0.0 to 1.0)
      float width;
 
      //! \brief Normalized height of the image (0.0 to 1.0)
      float height;
   };
 
   //! \brief Configuration structure for colored quad HUD elements
   struct HudColorQuadConfig
   {
      //! \brief Default constructor
      HudColorQuadConfig();
 
      //! \brief Color information for the quad
      makVre::DtColor colorInfo;
 
      //! \brief Normalized x-coordinate of the quad (0.0 to 1.0)
      float x;
 
      //! \brief Normalized y-coordinate of the quad (0.0 to 1.0)
      float y;
 
      //! \brief Normalized width of the quad (0.0 to 1.0)
      float width;
 
      //! \brief Normalized height of the quad (0.0 to 1.0)
      float height;
   };
 
   //! \brief Configuration structure for text HUD elements
   struct HudTextConfig
   {
      //! \brief Default constructor
      HudTextConfig();
 
      //! \brief Normalized x-coordinate of the text (0.0 to 1.0)
      float x;
 
      //! \brief Normalized y-coordinate of the text (0.0 to 1.0)
      float y;
   };
 
   //! \brief Structure for associating values with colors in HUD elements
   struct HudValueColorPair
   {
      //! \brief Integer value
      int value;
 
      //! \brief Color information associated with the value
      makVre::DtColor colorInfo;
   };
 
   //! \brief Enumeration of display layers for HUD elements
   enum Layers
   {
      //! \brief Hidden layer (not visible)
      HIDDEN = 0,
 
      //! \brief Overlay layer (normal HUD elements)
      OVERLAY = 1,
 
      //! \brief UI layer (user interface elements)
      UI = 2,
   };
 
   //! \brief Creates a texture from an image file
   //! \param path Path to the image file
   //! \return Pointer to the created texture, or nullptr if creation failed
   virtual osg::Texture* createTexture(std::string path);
 
   //! \brief Creates all quad elements needed by a derived class
   //! \param overlay Pointer to the overlay renderer to create quads in
   //! \param configs Vector of image configurations to create quads from
   //!
   //! Pure virtual method that must be implemented by derived classes to
   //! create all quads needed for their specific HUD elements.
   virtual void createQuads(makVrv::DtOverlayRenderer* overlay, const std::vector<HudImageConfig>& configs) = 0;
 
   //! \brief Creates a textured quad in the overlay
   //! \param overlay Pointer to the overlay renderer
   //! \param config Configuration for the image quad
   //! \return Pointer to the created quad proxy
   //!
   //! Creates a textured quad from the provided configuration.
   //! The x and y coordinates are percentages of screen in 0.0 to 1.0 range.
   virtual makVrv::DtQuadProxy* createQuad(makVrv::DtOverlayRenderer* overlay, const HudImageConfig& config);
 
   //! \brief Creates a colored quad in the overlay
   //! \param overlay Pointer to the overlay renderer
   //! \param element Configuration for the colored quad
   //! \return Pointer to the created quad proxy
   virtual makVrv::DtQuadProxy* createQuadWithColor(
      makVrv::DtOverlayRenderer* overlay, const HudColorQuadConfig& element);
 
   //! \brief Loads image configuration from an initialization table
   //! \param e Index of the image configuration
   //! \param imageTable Initialization table containing image configurations
   //! \param imageName Name of the image configuration
   //! \param loadDimensions Flag indicating if dimensions should be loaded
   //! \return True if loading was successful, false otherwise
   virtual bool loadImageConfig(
      unsigned int e, makVre::DtInitTable& imageTable, std::string imageName, bool loadDimensions = true);
 
   //! \brief Loads text configuration from an initialization table
   //! \param t Index of the text configuration
   //! \param textTable Initialization table containing text configurations
   //! \param textName Name of the text configuration
   //! \return True if loading was successful, false otherwise
   virtual bool loadTextConfig(unsigned int t, makVre::DtInitTable& textTable, std::string textName);
 
   //! \brief Loads color quad configuration from an initialization table
   //! \param quadIndex Index of the color quad configuration
   //! \param colorQuadTable Initialization table containing color quad configurations
   //! \param colorQuadName Name of the color quad configuration
   //! \param loadDimensions Flag indicating if dimensions should be loaded
   //! \return True if loading was successful, false otherwise
   virtual bool loadColorQuadConfig(unsigned int quadIndex, makVre::DtInitTable& colorQuadTable,
      std::string colorQuadName, bool loadDimensions = true);
 
   //! \brief Loads color configuration from an initialization table
   //! \param colorInfo Color information to load
   //! \param colorTable Initialization table containing color configurations
   //! \param colorName Name of the color configuration
   //! \return True if loading was successful, false otherwise
   virtual bool loadColorConfig(makVre::DtColor& colorInfo, makVre::DtInitTable& colorTable, std::string colorName);
 
   //! \brief Loads value-color pairs configuration from an initialization table
   //! \param valueColorPairsContainer Container for value-color pairs
   //! \param hudTable Initialization table containing HUD configurations
   //! \param valueColorPairsName Name of the value-color pairs configuration
   //! \return True if loading was successful, false otherwise
   virtual bool loadValueColorPairsConfig(std::vector<HudValueColorPair>& valueColorPairsContainer,
      makVre::DtInitTable& hudTable, const std::string& valueColorPairsName);
   virtual bool loadValueColorPairConfig(HudValueColorPair& valueColorPair, makVre::DtInitTable& valueColorPairConfig);
 
   makVrv::DtTextProxy* createAndInitTextProxy(double normalizedX, double normalizedY, const std::string& defaultText);
 
   // If incoming message is for entering the menu state, set myShowOverlays to false.
   // This will hide overlays while we're in the menu state.
   virtual makVre::DtVreMessageResult handleEnterPlayerState(makVre::DtVreMessage* msg);
 
   // If incoming message is for exiting the menu state, set showOverlays to true.
   // This show overlays while in the running state.
   virtual makVre::DtVreMessageResult handleExitPlayerState(makVre::DtVreMessage* msg);
 
   // Returns OVERLAY if myShowOverlays is true, HIDDEN otherwise
   virtual enum Layers overlayGroup();
 
protected:
   std::vector<HudImageConfig> myImages;
   std::vector<HudColorQuadConfig> myColorQuads;
   std::vector<HudTextConfig> myTexts;
 
   // cached vars
   makVrv::DtOverlayRenderer* myOverlayInterface;
   makVrv::DtOsgChannel* myChannel;
 
   float myFontSize;
   makVrv::DtFontInterface* myFont;
   std::string myFontFilePath;
   int myLineHeight;
 
   // overlays
   osg::Geode* myGeode;
 
   bool myChannelsUpdated;
 
   bool myShowOverlays;
};
} // namespace makVre