humanObserverUpdater.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file humanObserverUpdater.h
//! \brief Defines DtHumanObserverUpdater for managing human-specific observer behavior
//! \ingroup vreHumanFrontend
 
#pragma once
 
#include "vreHumanFrontend/export.h"
 
#include "vreCommonComponents/stateDefines.h"
 
#include "vreCommonComponents/observerUpdater.h"
 
#include "vreMessageManager/vreMessage.h"
#include "vreUtil/linearInterpolator.h"
 
#include <vrvCore/DtUniqueID.h>
 
namespace makVre
{
 
namespace HumanObserverUpdaterConfig
{
//! \ingroup RoleConfigParams
//! \defgroup HumanObserverUpdaterRoleParams Human Observer Updater Role Parameters
//! \roleInherits{PlayerComponentRoleParams}
//! Configuration Options for human observer updater component.
//! @{
 
//! \vreRoleParam{attachModeTransitionSpeed,double,8.0,humanObserverUpdater,Speed of transitions when changing attachment modes.}
constexpr const char* attachModeTransitionSpeed = "attachModeTransitionSpeed";
 
//! \vreRoleParam{cutToFirstPersonDist,double,0.4,humanObserverUpdater,Distance threshold for cutting to first-person view.}
constexpr const char* cutToFirstPersonDist = "cutToFirstPersonDist";
 
//! \vreRoleParam{nightVisionSensorMode,string,NVG,humanObserverUpdater,Sensor mode name for night vision goggles.}
constexpr const char* nightVisionSensorMode = "nightVisionSensorMode";
 
//! \vreRoleParam{offsets,table,{},humanObserverUpdater,Table of observer offset configurations for different postures and view modes.}
constexpr const char* offsets = "offsets";
 
//! \vreRoleParam{postureChangeSpeed,double,2.0,humanObserverUpdater,Speed of observer position changes when posture changes.}
constexpr const char* postureChangeSpeed = "postureChangeSpeed";
 
//! \vreRoleParam{scopeChannelName,string,RemoteView,humanObserverUpdater,Channel name for scope rendering.}
constexpr const char* scopeChannelName = "scopeChannelName";
 
//! \vreRoleParam{scopeWalkingPitch,double,-45.0,humanObserverUpdater,Pitch angle for scope view when walking.}
constexpr const char* scopeWalkingPitch = "scopeWalkingPitch";
 
//! \vreRoleParam{thirdPersonAimSpeed,double,9.0,humanObserverUpdater,Speed of observer movements in third-person aiming mode.}
constexpr const char* thirdPersonAimSpeed = "thirdPersonAimSpeed";
 
//! @}
} // namespace HumanObserverUpdaterConfig
 
} // namespace makVre
 
namespace makVrv
{
//! \brief Forward declaration of the display element class
class DtDe;
 
//! \brief Forward declaration of the observer class
class DtObserver;
 
//! \brief Forward declaration of the scene object class
class DtSceneObject;
}; // namespace makVrv
 
namespace makVre
{
//! \brief Forward declaration of the initialization table class
class DtInitTable;
 
//! \brief Forward declaration of the entity resolver class
class DtEntityResolver;
 
//! \brief Type identifier for DtHumanObserverUpdater component
constexpr const char* DtHumanObserverUpdaterType = "DtHumanObserverUpdater";
 
//! \brief Observer updater component for the human role
//!
//! DtHumanObserverUpdater manages the observer (camera) behavior for the human role,
//! including handling different view modes, player postures, attachments, and special
//! effects like NVG and flashlights. It handles positioning, orientation, and updates
//! of the observer based on the player state.
class HUMAN_DLL DtHumanObserverUpdater : public DtObserverUpdater
{
public:
   //! \brief Default constructor
   DtHumanObserverUpdater();
 
   //! \brief Virtual destructor
   virtual ~DtHumanObserverUpdater() override;
 
   //! \brief Initializes the observer updater component
   //! \param player Pointer to the player station
   //! \param config Configuration settings for initialization
   //! \return True if initialization was successful, false otherwise
   virtual bool initialize(DtPlayerStation* player, DtInitTable& config) override;
 
   //! \brief Performs post-initialization setup
   //! \return True if post-initialization was successful, false otherwise
   virtual bool postInitialize() override;
 
   //! \brief Updates the observer 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 The component type string
   virtual const char* type() const override;
 
   //! \brief Gets the current observer attachment mode
   //! \return Current observer attachment mode
   virtual ObserverAttachMode getAttachMode();
 
protected:
   //! \brief Updates the observer attachment offset based on current state
   //! \param dt Delta time since the last frame in seconds
   void updateAttachmentOffset(double dt);
 
   //! \brief Gets the current pitch angle of the player
   //! \return Current pitch angle in radians
   double getPitch();
 
   //! \brief Gets the current yaw angle of the player
   //! \return Current yaw angle in radians
   double getYaw();
 
   //! \brief Gets the current camera offset from the player
   //! \return Camera offset vector
   DtVector getCameraOffset();
 
   //! \brief Updates the target zoom level based on current observer state and equipment
   //!
   //! This function calculates and sets the appropriate zoom level based on the current
   //! observer attach mode, aiming state, and equipped weapon type. When aiming from
   //! first person view (and not using VR), it applies equipment-specific zoom levels:
   //! - Guns: Uses currentGunZoomLevel attribute (default 2.2x if not set)
   //! - Launchers: Uses viewMagnification attribute (default 1.0x if not set)
   //! When not aiming or not in first person mode, zoom is reset to 1.0x.
   //!
   //! \note This function modifies the myTargetZoom member variable
   //! \note VR mode disables zoom functionality
   //! \note Gun zoom levels are now configured per weapon via currentGunZoomLevel attribute
   virtual void updateZoomLevel();
 
   //! \brief Rotates a vector by the specified pitch and yaw angles
   //! \param localSpineToCamera Vector to rotate
   //! \param pitch Pitch angle in radians
   //! \param yaw Yaw angle in radians
   //! \return Rotated vector
   DtVector rotateVector(const DtVector& localSpineToCamera, double pitch, double yaw = 0.0);
 
   //! \brief Updates the observer position and orientation based on current state
   void updateObserverPositionAndOrientation();
 
   //! \brief Updates the scope observer properties
   //! \param observer Pointer to the scope observer to update
   void updateScopeObserver(makVrv::DtObserver* observer);
 
   //! \brief Updates the observer view magnification (zoom)
   //! \param dt Delta time since the last frame in seconds
   void updateObserverViewMagnification(double dt);
 
   //! \brief Sets the destination offset for the observer
   //! \param mode Observer attachment mode
   //! \param posture Current human posture
   virtual void setDestinationOffset(ObserverAttachMode mode, HumanPosture posture);
 
   //! \brief Updates the flashlight state based on current player state
   virtual void updateFlashlightState();
 
   //! \brief Updates the compass display state
   //!
   //! Updates DisplayCompass state attribute in the DtObserverModeManager, with value
   //! of the makVre::DtState attribute "compass". This shows/hides the built-in VR-Vantage
   //! compass widget.
   virtual void updateCompassState();
 
   //! \brief Handles changes in night vision goggles state
   //! \param nvg True if NVG is enabled, false otherwise
   virtual void onNVGChanged(bool nvg);
 
   //! \brief Checks if the observer pitch is at an angle above the terrain
   //! \return True if the observer pitch is above the threshold (0.8), false otherwise
   virtual bool observerPitchCheck();
 
   //! \brief Updates state attributes based on current observer state
   virtual void updateStateAttributes() override;
 
   //! \brief Handles observer mode setting changes
   //! \param mode Observer mode that changed
   //! \param setting Setting that changed
   //!
   //! Called when an observer mode's setting changes; if it's the mode our observer is
   //! using and the setting is DisplayCompass, update corresponding state attribute.
   virtual void slot_observerModeSettingChanged(int mode, int setting);
 
protected:
   //! \brief Pointer to the managed observer
   makVrv::DtObserver* myObserver;
 
   //! \brief Unique ID of the player element
   makVrv::DtUniqueID myPlayerElementID;
 
   //! \brief Flag indicating if the observer is currently attached
   bool myObserverIsAttached;
 
   //! \brief Position of the spine end point
   //!
   //! These two should really be pulled from the gun/arms model
   //! once vrvDiguy can getLinkPosition
   DtVector mySpineEndPosition;
 
   //! \brief Vector from spine to camera position
   DtVector mySpineToCameraVector;
 
   //! \brief Distance threshold for switching to first-person view
   double myCutToFirstPersonDist;
 
   //! \brief Speed of posture change transition
   double myPostureChangeSpeed;
 
   //! \brief Speed of attachment mode transition
   double myAttachModeSpeed;
 
   //! \brief Speed of third-person aiming transition
   double myThirdPersonAimSpeed;
 
   //! \brief Structure representing an observer offset configuration
   struct Offset
   {
      DtVector pos;            //!< Position offset vector
      HumanPosture posture;    //!< Human posture associated with this offset
      ObserverAttachMode mode; //!< Observer attachment mode associated with this offset
 
      //! \brief Equality comparison operator
      //! \param other Offset to compare with
      //! \return True if offsets are equal, false otherwise
      bool operator==(const Offset& other)
      {
         return pos == other.pos && posture == other.posture && mode == other.mode;
      }
 
      //! \brief Inequality comparison operator
      //! \param other Offset to compare with
      //! \return True if offsets are not equal, false otherwise
      bool operator!=(const Offset& other)
      {
         return pos != other.pos || posture != other.posture || mode != other.mode;
      }
 
      //! \brief Assignment operator
      //! \param other Offset to assign from
      //! \return Reference to this offset
      Offset& operator=(const Offset& other)
      {
         pos = other.pos;
         posture = other.posture;
         mode = other.mode;
         return *this;
      }
   };
   //! \brief Map of observer offsets indexed by a combined posture and mode key
   std::map<int, Offset> myOffsets;
 
   //! \brief Builds a lookup key for the offset map from posture and mode
   //! \param mode Observer attachment mode
   //! \param posture Human posture
   //! \return Combined integer key for offset lookup
   int buildOffsetKey(ObserverAttachMode mode, HumanPosture posture) { return int(mode) | (int(posture) << 16); }
   //! \brief Previous observer offset
   Offset myPriorOffset;
 
   //! \brief Current observer offset
   Offset myCurrentOffset;
 
   //! \brief Target destination observer offset
   Offset myDestinationOffset;
 
   //! \brief Flag indicating if posture has changed this frame
   bool myPostureChanged;
 
   //! \brief Target zoom level for the observer
   double myTargetZoom;
 
   //! \brief Interpolator for smooth zoom transitions
   makVre::DtLinearInterpolator<double>* myZoomInterpolator;
 
   //! \brief Last known state of the flashlight
   bool myLastFlashlightState;
 
   //! \brief Last known state of the compass
   bool myLastCompassState;
 
   //! \brief Last known state of night vision goggles
   bool myLastNVGState;
 
   //! \brief Last flashlight pitch angle
   double myLastFlashlightPitch;
 
   //! \brief Last flashlight yaw angle
   double myLastFlashlightYaw;
 
   //! \brief Flag indicating if using VR mode
   bool myUsingVr;
 
   //! \brief Interpolator for first-person model translation offset
   makVre::DtLinearInterpolator<DtVector>* myFirstPersonModelTranslationOffsetInterpolator;
 
   //! \brief Interpolator for first-person model rotation offset
   makVre::DtLinearInterpolator<DtVector>* myFirstPersonModelRotateOffsetInterpolator;
 
   //! \brief Flag indicating if the player was aiming in the previous frame
   bool myWasAiming;
 
   //! \brief Name of the scope channel
   std::string myScopeChannelName;
 
   //! \brief Scope walking pitch adjustment
   double myScopeWalkingPitch;
 
   //! \brief Maximum allowed observer pitch angle
   double myMaxObserverPitch;
 
   //! \brief Name of the observer mode to use for NVG
   //!
   //! DtObserverMode to use for night vision goggles mode
   std::string myNightVisionSensorMode;
};
} // namespace makVre