humanHudUpdater.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file humanHudUpdater.h
//! \brief Defines DtHumanHudUpdater for managing human-specific HUD elements
//! \ingroup vreHumanFrontend
 
#pragma once
 
#include "vreHumanFrontend/export.h"
 
#include "vreHumanFrontend/hudUpdater.h"
#include "vreUtil/vector2DD.h"
#include <vrvCore/DtBoundingBox.h>
 
namespace makVre
{
 
namespace HumanHudUpdaterConfig
{
//! \ingroup RoleConfigParams
//! \defgroup HumanHudUpdaterRoleParams Human HUD Updater Role Parameters
//! \roleInherits{PlayerComponentRoleParams}
//! Configuration Options for human HUD updater component.
//! @{
 
//! \vreRoleParam{centerOfGuiLocation,DtVector2DD,"DtVector2DD(0.48333, 0.471296)",humanHudUpdater,Center location for GUI elements in normalized coordinates.}
constexpr const char* centerOfGuiLocation = "centerOfGuiLocation";
 
//! \vreRoleParam{fatigueBarColor,table,{},humanHudUpdater,Configuration table for fatigue bar color settings.}
constexpr const char* fatigueBarColor = "fatigueBarColor";
 
//! \vreRoleParam{hud,table,{},humanHudUpdater,Configuration table for HUD element definitions and layouts.}
constexpr const char* hud = "hud";
 
//! \vreRoleParam{maxAimingErrorCircleRadius,double,50.0,humanHudUpdater,Maximum radius for aiming error circle indicator.}
constexpr const char* maxAimingErrorCircleRadius = "maxAimingErrorCircleRadius";
 
//! \vreRoleParam{nvg,table,{},humanHudUpdater,Configuration table for night vision goggle overlay settings.}
constexpr const char* nvg = "nvg";
 
//! \vreRoleParam{parachute,table,{},humanHudUpdater,Configuration table for parachute-related HUD elements.}
constexpr const char* parachute = "parachute";
 
//! \vreRoleParam{reticleDirectionRandomTimerDuration,double,2.0,humanHudUpdater,Duration in seconds for reticle direction randomization timer.}
constexpr const char* reticleDirectionRandomTimerDuration = "reticleDirectionRandomTimerDuration";
 
//! \vreRoleParam{reticleSpeed,double,0.175,humanHudUpdater,Speed of reticle movement animations.}
constexpr const char* reticleSpeed = "reticleSpeed";
 
//! \vreRoleParam{showAmmoCounts,bool,true,humanHudUpdater,Whether to display ammunition count information on the HUD.}
constexpr const char* showAmmoCounts = "showAmmoCounts";
 
//! \vreRoleParam{showHUD,bool,true,humanHudUpdater,Whether to display the HUD elements.}
constexpr const char* showHUD = "showHUD";
 
//! \vreRoleParam{weaponAimingOverlay,table,{},humanHudUpdater,Configuration table for weapon aiming overlay elements.}
constexpr const char* weaponAimingOverlay = "weaponAimingOverlay";
 
//! @}
} // namespace HumanHudUpdaterConfig
 
} // namespace makVre
 
namespace makVrv
{
//! \brief Forward declaration of the OSG channel class
class DtOsgChannel;
 
//! \brief Forward declaration of the channel configuration class
class DtChannelConfiguration;
 
//! \brief Forward declaration of the quad proxy class
class DtQuadProxy;
 
//! \brief Forward declaration of the overlay renderer class
class DtOverlayRenderer;
} // namespace makVrv
 
namespace makVre
{
//! \brief Forward declaration of the weapon resource logic class
class DtWeaponResourceLogic;
 
//! \brief Type identifier for DtHumanHudUpdater component
constexpr const char* DtHumanHudUpdaterType = "DtHumanHudUpdater";
 
//! \brief HUD updater component for human-specific display elements
//!
//! DtHumanHudUpdater manages the HUD elements specific to the human role,
//! including weapon indicators, ammo counters, health and fatigue bars,
//! crosshairs, and posture indicators. It handles positioning, visibility,
//! and updates of these elements based on the player state.
class HUMAN_DLL DtHumanHudUpdater : public DtHudUpdater
{
public:
   //! \brief Default constructor
   DtHumanHudUpdater();
 
   //! \brief Virtual destructor
   virtual ~DtHumanHudUpdater() override;
 
   //! \brief Initializes the human 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 Returns the component type identifier
   //! \return The component type string
   virtual const char* type() const override;
 
protected:
   //! \brief Called when this HUD updater is started
   //!
   //! Initializes and shows HUD elements
   virtual void onStart() override;
 
   //! \brief Called when this HUD updater is stopped
   //!
   //! Hides and cleans up HUD elements
   virtual void onStop() override;
 
   //! \brief Loads weapon icon extent configuration
   //! \param initTable Initialization table containing configurations
   //! \param tableName Name of the table containing extent configuration
   //! \return True if loading was successful, false otherwise
   //!
   //! Weapon icons extent in range of 0-1 (for use with normalized screen coordinates).
   //! All weapon icons should have the same extent.
   virtual bool loadWeaponIconExtentConfig(makVre::DtInitTable& initTable, std::string tableName);
 
   //! \brief Loads weapon icon position configuration
   //! \param initTable Initialization table containing configurations
   //! \param tableName Name of the table containing position configuration
   //! \return True if loading was successful, false otherwise
   //!
   //! Placeholder positions for weapon icons, in normalized screen coordinates.
   virtual bool loadWeaponIconPositionsConfig(makVre::DtInitTable& initTable, std::string tableName);
 
   //! \brief Calculates position for a weapon icon
   //! \param i Index of the weapon
   //! \param total Total number of weapons
   //! \param x [out] Calculated x-coordinate
   //! \param y [out] Calculated y-coordinate
   virtual void weaponIconPosition(unsigned i, unsigned total, float& x, float& y) const;
 
   //! \brief Calculates position for an ammo text display
   //! \param i Index of the weapon
   //! \param total Total number of weapons
   //! \param x [out] Calculated x-coordinate
   //! \param y [out] Calculated y-coordinate
   virtual void ammoTextPosition(unsigned i, unsigned total, float& x, float& y) const;
 
   //! \brief Calculates position for a clip text display
   //! \param i Index of the weapon
   //! \param total Total number of weapons
   //! \param x [out] Calculated x-coordinate
   //! \param y [out] Calculated y-coordinate
   virtual void clipTextPosition(unsigned i, unsigned total, float& x, float& y) const;
 
   //! \brief Initializes parachute-related text elements
   virtual void initParachuteText();
 
   //! \brief Positions parachute-related text elements on the HUD
   virtual void positionParachuteText();
 
   //! \brief Handles changes in the current weapon index
   //! \param index New weapon index
   virtual void onWeaponIndexChanged(int index);
 
   //! \brief Handles changes in weapon state
   //! \param state New weapon state
   virtual void onWeaponStateChanged(int state);
 
   //! \brief Handles changes in the launcher entity ID
   //! \param id New launcher entity identifier
   virtual void onLauncherIdChanged(DtEntityIdentifier id);
 
   //! \brief Handles changes in the weapon list
   //! \param weapons New list of weapon names
   virtual void onWeaponListChanged(const DtAttributeHandle&);
 
   //! \brief Handles changes in weapon availability
   //! \param hasWeapons True if weapons are available, false otherwise
   virtual void onHasWeaponsChanged(bool hasWeapons);
 
   //! \brief Called when all HUD elements are being deleted
   virtual void onDeleteAll() override;
 
   //! \brief Handles changes in reload timer
   //! \param time Current reload timer value in seconds
   virtual void onReloadTimerChanged(float time);
 
   //! \brief Updates all HUD elements
   //!
   //! Refreshes the state and visibility of all HUD elements
   //! based on current player state
   virtual void updateAll() override;
 
   //! \brief Sets up health bar and related HUD elements
   //!
   //! Initializes health indicators and their positions
   virtual void setupHealthElements();
 
   //! \brief Updates health-related HUD elements
   //! \param visible Flag indicating if the elements should be visible
   virtual void updateHealthElements(bool visible);
 
   //! \brief Sets up fatigue bar and related HUD elements
   //!
   //! Initializes fatigue indicators and their positions
   virtual void setupFatigueElements();
 
   //! \brief Updates fatigue-related HUD elements
   //! \param visible Flag indicating if the elements should be visible
   virtual void updateFatigueElements(bool visible);
 
   //! \brief Updates all HUD elements based on visibility
   //! \param visible Flag indicating if the reticle is visible
   //!
   //! Overrides base class method to update human-specific HUD elements
   virtual void updateHudElements(bool visible) override;
 
   //! \brief Updates vision enhancement overlays like NVG
   //! \param visible Flag indicating if the overlays should be visible
   virtual void updateVisionOverlays(bool visible);
 
   //! \brief Updates the weapon reticle display
   //! \param visible Flag indicating if the reticle should be visible
   //!
   //! Updates position, size, and visibility of the reticle based on current weapon and state
   virtual void updateReticle(bool visible);
 
   //! \brief Computes a new random direction for reticle movement
   //! \param deltaTime Delta time since the last frame in seconds
   //!
   //! Computes a new reticle direction if the random timer expires
   virtual void computeReticleRandomDirection(double deltaTime);
 
   //! \brief Repositions reticle to keep it within the aiming error circle
   //! \param newReticlePosition Reference to the reticle position vector to update
   //! \param aimingErrorCircleRadius Radius of the aiming error circle
   //!
   //! If the reticle's position goes outside the aiming error circle, this function
   //! moves the reticle's position back inside the aiming error circle.
   virtual void repositionReticleIntoAimingErrorCircle(
      makVre::DtVector2DD& newReticlePosition, double aimingErrorCircleRadius);
 
   //! \brief Checks if the reticle is inside the aiming error circle
   //! \param aimingErrorCircleRadius Radius of the aiming error circle
   //! \param reticleTestPosition Position to test
   //! \return True if the position is inside the circle, false otherwise
   virtual bool isReticleInsideAimingErrorCircle(
      double aimingErrorCircleRadius, makVre::DtVector2DD& reticleTestPosition);
 
   //! \brief Computes a new direction for the reticle when it reaches the edge
   //!
   //! When the reticle reaches the edge of the aiming error circle, this function
   //! computes a new direction for the reticle to travel
   virtual void redirectReticleIntoAimingErrorCircle();
 
   //! \brief Updates the position of the gun reticle
   //! \param newReticlePosition [in,out] The reticle position vector to update
   //! \param myCrosshairQuad Pointer to the crosshair quad
   //! \param dt Delta time since the last frame in seconds
   //!
   //! Updates the position of the gun reticle based on current aiming factors
   virtual void updateGunReticlePosition(
      makVre::DtVector2DD& newReticlePosition, makVrv::DtQuadProxy* myCrosshairQuad, double dt);
 
   //! \brief Computes the aiming error based on current factors
   //! \param newReticlePosition Current position of the reticle
   virtual void computeAimingError(const makVre::DtVector2DD& newReticlePosition);
 
   //! \brief Updates gun crosshair display
   //! \param visible Flag indicating if the crosshair should be visible
   virtual void updateGunReticles(bool visible);
 
   //! \brief Updates grenade reticle display
   //! \param visible Flag indicating if the reticle should be visible
   virtual void updateGrenadeReticle(bool visible);
 
   //! \brief Updates missile launcher display elements
   //! \param visible Flag indicating if the elements should be visible
   //! \param reset Flag indicating if the elements should be reset to default state
   virtual void updateMissileLauncher(bool visible = true, bool reset = false);
 
   //! \brief Updates ammunition count displays for all weapons
   virtual void updateWeaponAmmoCounts();
 
   //! \brief Updates missile launcher ammunition count display
   //! \param count Current ammunition count
   virtual void updateMissileLauncherAmmoCount(float count);
 
   //! \brief Sets up the current weapon indicator quad
   //! \param pos Position index of the current weapon, -1 for default
   //! \param total Total number of weapons, -1 for default
   //! \param state Current weapon state, -1 for default
   virtual void setupCurrentWeaponQuad(int pos = -1, int total = -1, int state = -1);
 
   //! \brief Updates wind indicator display
   //!
   //! Updates wind indicator displays with current wind direction and speed
   virtual void updateWindOverlay();
 
   //! \brief Handles wind update messages
   //! \param msg Pointer to the message being processed
   //! \return Message processing result
   virtual makVre::DtVreMessageResult handleWindUpdate(makVre::DtVreMessage* msg);
 
   //! \brief Handles resource update messages
   //! \param msg Pointer to the message being processed
   //! \return Message processing result
   virtual makVre::DtVreMessageResult handleResourceUpdate(makVre::DtVreMessage* msg);
 
   //! \brief Handles viewport change events
   //!
   //! Called when the viewport size or properties change to update HUD element positions
   virtual void onViewportChanged() override;
 
   //! \brief Resets weapon indicator quads
   //!
   //! Resets the state of weapon indicator quads to default
   virtual void resetWeaponQuads();
 
   //! \brief Resets posture indicator quads
   //! \param overlay Pointer to the overlay renderer
   //! \param configs Vector of image configurations to create quads from
   virtual void resetPostureQuads(makVrv::DtOverlayRenderer* overlay, const std::vector<HudImageConfig>& configs);
 
   //! \brief Checks if this updater provides the reticle
   //! \return True if this updater provides the reticle, false otherwise
   virtual bool amReticleProvider() const;
 
   //! \brief Enumeration of texture indices used in the HUD
   enum Textures
   {
      NVG_OVERLAY,            //!< Night vision goggles overlay texture
      WEAPON_AIMING_OVERLAY,  //!< Weapon aiming overlay texture
      HEALTH_BAR_BACKER,      //!< Background for health bar
      FATIGUE_BAR_BACKER,     //!< Background for fatigue bar
      STANDING_TEX,           //!< Standing posture indicator texture
      CROUCHING_TEX,          //!< Crouching posture indicator texture
      PRONE_TEX,              //!< Prone posture indicator texture
      KNEELING_TEX,           //!< Kneeling posture indicator texture
      CIVILIAN_STANDING_TEX,  //!< Civilian standing posture indicator texture
      CIVILIAN_CROUCHING_TEX, //!< Civilian crouching posture indicator texture
      CIVILIAN_PRONE_TEX,     //!< Civilian prone posture indicator texture
      CIVILIAN_KNEELING_TEX,  //!< Civilian kneeling posture indicator texture
      CROSSHAIR,              //!< Standard crosshair texture
      NVG_CROSSHAIR,          //!< Night vision crosshair texture
      CURRENT_WEAPON,         //!< Current weapon indicator texture
      CURRENT_WEAPON_STOWED,  //!< Current weapon stowed indicator texture
      CURRENT_WEAPON_DOWN,    //!< Current weapon down indicator texture
      WEAPON_PROTOTYPE,       //!< Generic weapon prototype texture
      MISSILE_LAUNCHER,       //!< Missile launcher texture
      DRONE_TEX,              //!< Drone indicator texture
      DRONE_VIEW_FRAME,       //!< Drone view frame texture
      FIRST_WEAPON_TEXTURE,   //!< Index of first weapon-specific texture
      TEXTURES_CONFIG_COUNT   //!< Total number of texture configurations
   };
 
   //! \brief Enumeration of colored quad indices used in the HUD
   enum ColorQuads
   {
      HEALTH_BAR,              //!< Health bar colored quad
      FATIGUE_BAR,             //!< Fatigue bar colored quad
      COLOR_QUADS_CONFIG_COUNT //!< Total number of colored quad configurations
   };
 
   //! \brief Enumeration of text element indices used in the HUD
   enum Texts
   {
      PARACHUTE_WIND_SPEED,     //!< Parachute wind speed text
      PARACHUTE_WIND_DIRECTION, //!< Parachute wind direction text
      PARACHUTE_OXYGEN_PERCENT, //!< Parachute oxygen percentage text
      PARACHUTE_ALTITUDE,       //!< Parachute altitude text
      TEXT_HEALTH,              //!< Health value text
      TEXT_FATIGUE,             //!< Fatigue value text
      TEXT_CONFIG_COUNT         //!< Total number of text configurations
   };
 
   //! \brief Creates quad elements for the HUD
   //! \param overlay Pointer to the overlay renderer
   //! \param configs Vector of image configurations to create quads from
   //!
   //! Implements the pure virtual method from base class to create HUD quad elements
   virtual void createQuads(makVrv::DtOverlayRenderer* overlay, const std::vector<HudImageConfig>& configs) override;
 
   //! \brief Creates and initializes a text proxy for a specific text element
   //! \param index Index of the text element to create
   //! \return Pointer to the created text proxy
   makVrv::DtTextProxy* createAndInitTextProxy(Texts index);
 
   //! \brief Night vision goggles overlay quad
   makVrv::DtQuadProxy* myNVGOverlayQuad;
 
   //! \brief Standard crosshair quad
   makVrv::DtQuadProxy* myCrosshairQuad;
 
   //! \brief Night vision crosshair quad
   makVrv::DtQuadProxy* myNVGCrosshairQuad;
 
   //! \brief Original bounding box of the standard crosshair
   //!
   //! Saved so that scaling can be done based on the original size
   makVrv::DtBoundingBox myCrosshairOriginalBoundingBox;
 
   //! \brief Original bounding box of the NVG crosshair
   //!
   //! Saved so that scaling can be done based on the original size
   makVrv::DtBoundingBox myNVGCrosshairOriginalBoundingBox;
 
   //! \brief missile launcher indicator quad
   makVrv::DtQuadProxy* myLauncherQuad;
 
   //! \brief launcher ammunition count text
   makVrv::DtTextProxy* myLauncherAmmoText;
 
   //! \brief Flag indicating if the launcher HUD is visible
   bool myLauncherHudVisible;
 
   //! \brief Vector of weapon icon quads
   std::vector<makVrv::DtQuadProxy*> myWeaponIcons;
 
   //! \brief Vector of ammunition count text proxies
   std::vector<makVrv::DtTextProxy*> myAmmoTexts;
 
   //! \brief Vector of clip count text proxies
   std::vector<makVrv::DtTextProxy*> myClipTexts;
 
   //! \brief Flag indicating if ammunition counts should be shown
   bool myShowAmmoCounts;
 
   //! \brief Altitude text display for parachute mode
   makVrv::DtTextProxy* myAltText;
 
   //! \brief Oxygen percentage text display for parachute mode
   makVrv::DtTextProxy* myOxygenText;
 
   //! \brief Wind speed text display
   makVrv::DtTextProxy* myWindSpeedText;
 
   //! \brief Wind direction text display
   makVrv::DtTextProxy* myWindDirectionText;
 
   //! \brief Current weapon indicator quad
   makVrv::DtQuadProxy* myCurrentWeaponIndicator;
 
   //! \brief Standing posture indicator quad
   makVrv::DtQuadProxy* myStandingQuad;
 
   //! \brief Prone posture indicator quad
   makVrv::DtQuadProxy* myProneQuad;
 
   //! \brief Crouching posture indicator quad
   makVrv::DtQuadProxy* myCrouchingQuad;
 
   //! \brief Kneeling posture indicator quad
   makVrv::DtQuadProxy* myKneelingQuad;
 
   //! \brief Drone indicator quad
   makVrv::DtQuadProxy* myDrone;
 
   //! \brief Drone view frame quad
   makVrv::DtQuadProxy* myDroneViewFrame;
 
   //! \brief Drone battery text display
   makVrv::DtTextProxy* myDroneBatteryText;
 
   //! \brief Drone distance text display
   makVrv::DtTextProxy* myDroneDistance;
 
   //! \brief Drone altitude text display
   makVrv::DtTextProxy* myDroneAltitude;
 
   //! \brief Drone bearing text display
   makVrv::DtTextProxy* myDroneBearing;
 
   //! \brief Current time in seconds
   double myCurrentTime;
 
   //! \brief Time of last wind speed request in seconds
   double myTimeLastWindSpeedRequested;
 
   //! \brief Drone battery amount
   double myDroneBatteryAmount;
 
   //! \brief Location of last wind request
   DtVector myWindRequestLocation;
 
   //!
   //! Health status gui related variables
   //!
   //! \brief Health value text display
   makVrv::DtTextProxy* myHealthText;
 
   //! \brief Health bar colored quad
   makVrv::DtQuadProxy* myHealthBar;
 
   //! \brief Health bar background quad
   makVrv::DtQuadProxy* myHealthBarBacker;
 
   //! \brief Original width of the health bar
   float myOriginalHealthBarWidth; // save original width so that scaling can be done based on the original size.
 
   //! \brief Vector of health bar value-color pairs
   std::vector<HudValueColorPair> myHealthBarValueColorPairs; // the values in this vector must be descending
 
   //!
   //! Fatigue status gui related variables
   //!
   //! \brief Fatigue value text display
   makVrv::DtTextProxy* myFatigueText;
 
   //! \brief Fatigue bar colored quad
   makVrv::DtQuadProxy* myFatigueBar;
 
   //! \brief Fatigue bar background quad
   makVrv::DtQuadProxy* myFatigueBarBacker;
 
   //! \brief Original width of the fatigue bar
   float myOriginalFatigueBarWidth; // save original width so that scaling can be done based on the original size.
 
   //!
   //! Reticle gui related variables
   //!
   //! \brief Center of the GUI in normalized screen coordinates
   makVre::DtVector2DD myCenterOfGuiLocation; // center of gui.  Specified as a percentage of the screen size.
 
   //! \brief Maximum aiming error circle radius in pixels
   double myMaxAimingErrorCircleRadius; // This value is in pixels.
 
   //! \brief Reticle speed in pixels per second
   double myReticleSpeed; // This value is set empirically.
 
   //! \brief Maximum aiming error in radians
   double myMaxAimingError; // 0.016632 is the radians of 1.4 degrees, the maximum aiming error at 50 meters with 96 max
                            // spread
 
   //! \brief Timer for random reticle position updates in seconds
   double myReticleDirectionRandomTimerDuration;
 
   //! \brief Current reticle position in normalized screen coordinates
   //!
   //! Range is -0.5 to 0.5, where (0,0) is the center of the screen
   makVre::DtVector2DD myReticleRandomDirection;
 
   makVre::DtMenuCursor* myLocationCursor;
 
   //! \brief Cached launcher marking
   std::string myCachedLauncherMarking;
 
   //! \brief Pointer to the weapon resource logic
   DtWeaponResourceLogic* myWeaponResourceLogic;
 
   //! \brief Structure for 2D extent
   struct Extent2D
   {
      double width;
      double height;
   };
 
   //! \brief Extent of weapon icons in normalized screen coordinates
   Extent2D myWeaponIconExtent;
 
   //! \brief Vector of weapon icon positions in normalized screen coordinates
   std::vector<makVre::DtVector2DD> myWeaponIconPositions;
 
   DtAttributeHandleType<std::vector<std::string>> myWeaponList;
   DtAttributeHandleType<DtEntityIdentifier> myLauncherId;
};
} // namespace makVre