lookAroundObserverUpdater.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file lookAroundObserverUpdater.h
//! \brief Component that handles observer view orientation and equipment effects
//! \ingroup vreCommonComponents
 
#pragma once
 
/*
 * The following parameters are available for configuration from the component
 * entry in a role configuration file:
 *
 *  -- Global variables
 *  enableBinoculars = false; -- should enable nightvision when using this updater
 *  enableNVG = false; -- should enable nightvision when using this updater
 *  enableLookAround = true; -- If this is set to true, then all the saved views in the supplementalSavedViewData will
 * enable freelook snapBackTimeMouse = 0.25; -- Time in seconds that will snap back the observer to the initial
 * viewpoint when controlling with mouse. snapBackTimeJoystick = 0.1; -- Time in seconds that will snap back the
 * observer to the initial viewpoint when controlling with joystick. pitchRange = {min = -45, max = 80}; -- Degrees in
 * both directions. yawRange = {min = -120, max = 120}; -- Degrees in both directions. observerName = "Observer 1"; --
 * name of observer, defaults to "Observer 1".
 *
 *  -- If the SavedViews updater is not present, these values are where the observer with attach to.
 *  attachedLocationOffset = { x = 0.45, y = -0.25, z = 1.25 }; -- x, y, z offset from the center point in meters.
 * Coordinates are +x is to the right, +y is to the front, and +z is up. attachedOrientationOffset = { x = 0.0, y = 0.0,
 * z = 0.0, w = 1.0 }; -- Orientation of the observer relative to the attached model.
 *
 *  -- If the SavedViews updater is present, this savedData provides additional configuration for finer control
 *  supplementalSavedViewData = {
 *     ["SAVED_VIEW_NAME"] = {
 *        enableLookAround = true; -- will enable look around for this view. If not specified, will use the default one
 * above. pitchRange = {min = -45, max = 80}; -- Degrees in both directions. If not specified, will use the default one
 * above. yawRange = {min = -120, max = 120}; -- Degrees in both directions. If not specified, will use the default one
 * above.
 *     };
 *     ...
 *  };
 */
 
#include "stateDefines.h"
 
#include "vreCommonComponents/lookAroundInputLogic.h"
#include "vreCommonComponents/observerUpdater.h"
 
#include "vreMessageManager/vreMessage.h"
 
#include "vreUtil/linearInterpolator.h"
#include "vreUtil/bezierInterpolator.h"
 
#include <matrix/vlVector.h>
#include <matrix/vlQuaternion.h>
 
#include <string>
 
namespace makVrv
{
class DtDe;
class DtEntityFacade;
class DtObserver;
class DtSceneObject;
class DtVirtualRealityDriver;
}; // namespace makVrv
 
namespace LookAroundObserverUpdaterConfig
{
//! \ingroup RoleConfigParams
//! \defgroup LookAroundObserverUpdaterRoleParams Look Around Observer Updater Role Parameters
//! \roleInherits{ObserverUpdaterRoleParams}
//! Configuration Options for look around observer updater role.
//! @{
 
//! \vreRoleParam{attachedLocationOffset,DtVector,"DtVector::zero()",lookAroundObserverUpdater,Position offset from the center point in meters for observer attachment.}
constexpr const char* attachedLocationOffset = "attachedLocationOffset";
 
//! \vreRoleParam{attachedOrientationOffset,DtQuaternion,"DtQuaternion()",lookAroundObserverUpdater,Orientation offset of the observer relative to the attached model.}
constexpr const char* attachedOrientationOffset = "attachedOrientationOffset";
 
//! \vreRoleParam{enableBinoculars,bool,false,lookAroundObserverUpdater,Enable binoculars functionality when using this updater.}
constexpr const char* enableBinoculars = "enableBinoculars";
 
//! \vreRoleParam{enableLookAround,bool,false,lookAroundObserverUpdater,Enable freelook capability for observer movement.}
constexpr const char* enableLookAround = "enableLookAround";
 
//! \vreRoleParam{enableNVG,bool,false,lookAroundObserverUpdater,Enable night vision goggles when using this updater.}
constexpr const char* enableNVG = "enableNVG";
 
//! \vreRoleParam{observerName,string,"Observer 1",lookAroundObserverUpdater,Name of the observer to use for view management.}
constexpr const char* observerName = "observerName";
 
//! \vreRoleParam{pitchRange,table,"",lookAroundObserverUpdater,Table defining min/max pitch angles in degrees for observer movement.}
constexpr const char* pitchRange = "pitchRange";
 
//! \vreRoleParam{snapBackTimeJoystick,double,0.1,lookAroundObserverUpdater,Time in seconds to snap back observer to initial viewpoint when using joystick.}
constexpr const char* snapBackTimeJoystick = "snapBackTimeJoystick";
 
//! \vreRoleParam{snapBackTimeMouse,double,0.25,lookAroundObserverUpdater,Time in seconds to snap back observer to initial viewpoint when using mouse.}
constexpr const char* snapBackTimeMouse = "snapBackTimeMouse";
 
//! \vreRoleParam{supplementalSavedViewData,table,"",lookAroundObserverUpdater,Additional configuration data for saved views with look-around settings.}
constexpr const char* supplementalSavedViewData = "supplementalSavedViewData";
 
//! \vreRoleParam{yawRange,table,"",lookAroundObserverUpdater,Table defining min/max yaw angles in degrees for observer movement.}
constexpr const char* yawRange = "yawRange";
 
//! @}
} // namespace LookAroundObserverUpdaterConfig
 
//! \brief Structure containing configuration data for a saved view
//!
//! Stores the name, look-around capabilities, and observer rotation limits
//! for specific saved views in a vehicle
struct VRECOMMONCOMPONENTS_DLL SavedViewData
{
   //! \brief Constructor that initializes the saved view with a name
   //! \param name The name of the saved view
   explicit SavedViewData(std::string name)
      : savedViewName(name)
      , enableLookAround() {};
 
   //! \brief The name of the saved view
   std::string savedViewName;
 
   //! \brief Flag indicating if look-around functionality is enabled for this view
   bool enableLookAround;
 
   //! \brief Range of vertical rotation (pitch) allowed for this view
   ObserverRange pitchRange;
 
   //! \brief Range of horizontal rotation (yaw) allowed for this view
   ObserverRange yawRange;
};
 
namespace makVre
{
 
//! \brief Type identifier for DtLookAroundObserverUpdater component
constexpr const char* DtLookAroundObserverUpdaterType = "DtLookAroundObserverUpdater";
 
//! \brief Component that manages observer orientation and equipment visuals
//!
//! DtLookAroundObserverUpdater updates the visual aspects of the player's view.
//! It orients the observer based on input and provides support for special equipment
//! visual effects like binoculars (with zooming capability) and night vision goggles.
//! It can be configured to work with saved views and to limit the range of movement
//! for different viewing positions.
//!
//! The component supports:
//! - Configurable yaw and pitch ranges for head movement
//! - Binoculars with zoom capability
//! - Night vision goggles with special visual effects
//! - Look-around functionality with mouse or joystick control
//! - VR head tracking integration
//! - Saved view positions with per-view configuration
class VRECOMMONCOMPONENTS_DLL DtLookAroundObserverUpdater : public DtObserverUpdater
{
public:
   //! \brief Constructor for DtLookAroundObserverUpdater
   //!
   //! Initializes component state with default values
   DtLookAroundObserverUpdater();
 
   //! \brief Virtual destructor for DtLookAroundObserverUpdater
   virtual ~DtLookAroundObserverUpdater() override;
 
   //! \brief Initializes the look-around observer updater component
   //! \param player Pointer to the player station this component belongs to
   //! \param config Configuration table containing observer settings
   //! \return True if initialization succeeded, false otherwise
   //!
   //! Initializes member variables from the configuration table, caches pointer to the observer,
   //! adds handlers for PlayerCreatedMessage, and creates the input logic component
   virtual bool initialize(DtPlayerStation* player, DtInitTable& config) override;
 
   //! \brief Called every frame to update the observer orientation and visual effects
   //! \param dt Delta time since the last frame in seconds
   //!
   //! Updates the observer's orientation based on input, manages binoculars and NVG effects,
   //! and handles smooth transitions between different states
   virtual void tick(double dt) override;
 
   //! \brief Performs post-initialization after all components are initialized
   //! \return True if post-initialization succeeded, false otherwise
   //!
   //! Sets up saved view handling, initializes binoculars and NVG state,
   //! and configures VR support if enabled
   virtual bool postInitialize() override;
 
   //! \brief Shuts down the look-around observer updater component
   //!
   //! Shuts down the input logic component, removes message handlers and
   //! attribute callbacks, and performs cleanup operations
   virtual void shutdown() override;
 
   //! \brief Returns the type identifier for this component
   //! \return The type string for DtLookAroundObserverUpdater
   virtual const char* type() const override;
 
   //! \brief Updates the binoculars zoom state
   //! \param dt Delta time since the last frame in seconds
   //!
   //! Checks for the "viewMagnification" state attribute and creates, updates,
   //! or deletes the zoom interpolator as needed. Updates the observer view
   //! magnification based on the interpolator's current value for smooth transitions.
   virtual void updateBinocularsState(double dt);
 
   //! \brief Updates the night vision goggles (NVG) state
   //!
   //! Checks for the "NVG" state attribute and applies the appropriate
   //! sensor mode to the observer when the state changes
   virtual void updateNVGState();
 
   //! \brief Updates the observer's orientation state
   //! \param dT Delta time since the last frame in seconds
   //!
   //! Handles both VR and non-VR observer orientation updates, including
   //! interpolation for smooth transitions when returning to initial views
   virtual void updateObserverState(double dT);
 
   //! \brief Resets the observer to its initial orientation
   //! \param period Time in seconds for the smooth transition (default:.25 seconds)
   //!
   //! Creates an interpolator to smoothly transition from the current view
   //! back to the initial saved view orientation
   void resetToInitialView(double period = 0.25);
   //! \brief Refreshes the observer yaw and pitch values
   //!
   //! Updates the observer's orientation attributes based on the current saved view
   //! or attached orientation offset, and sets appropriate range limits
   void refreshObserverYawAndPitch();
 
   //! \brief Gets the current pitch range limits
   //! \return Reference to the pitch range structure
   virtual const ObserverRange& getPitchRange();
 
   //! \brief Gets the current yaw range limits
   //! \return Reference to the yaw range structure
   virtual const ObserverRange& getYawRange();
 
   //! \brief Checks if look-around functionality is enabled
   //! \return True if look-around is enabled, false otherwise
   virtual bool isLookAroundEnabled() const;
 
   //! \brief Checks if binoculars functionality is enabled
   //! \return True if binoculars are enabled, false otherwise
   virtual bool isBinocularsEnabled() const;
 
   //! \brief Checks if night vision goggles functionality is enabled
   //! \return True if NVG is enabled, false otherwise
   virtual bool isNVGEnabled() const;
 
   //! \brief Gets the associated input logic component
   //! \return Shared pointer to the input logic component
   std::shared_ptr<DtLookAroundInputLogic> getInputLogic();
 
   //! \brief Checks if the player is currently looking around
   //! \return True if looking around is active and enabled, false otherwise
   virtual bool isLookingAround() const;
 
   //! \brief Enables or disables active looking around
   //! \param look True to enable looking around, false to disable
   //! \param mouse True if input is from mouse, false if from joystick
   //!
   //! When disabling looking around, initiates a smooth transition back
   //! to the initial view orientation
   virtual void setLookingAround(bool look, bool mouse = true);
 
protected:
   //! \brief Handles changes to the current view name
   //! \param viewName The new view name
   //!
   //! Called when the current view changes, refreshes observer orientation
   //! and updates range limits based on the new view
   virtual void onCurrentViewNameChanged(const std::string& viewName);
 
   //! \brief Handles player creation messages
   //! \param msg The player created message
   //! \return Message handling result indicating the message was handled
   //!
   //! Calls setupObserver() to set up the observer attachment details
   virtual makVre::DtVreMessageResult handlePlayerCreated(makVre::DtVreMessage* msg);
 
   //! \brief Sets up the observer's attachment to the player entity
   //!
   //! Configures the observer attachment as AttachTypeMimic, with the part
   //! and location/rotation offsets specified in the configuration
   virtual void setupObserver();
 
protected:
   //! \brief Shared pointer to the associated input logic component
   std::shared_ptr<DtLookAroundInputLogic> myInputLogic;
 
   //! \brief Pointer to the observer being controlled
   makVrv::DtObserver* myObserver;
 
   //! \brief Interpolator for smooth zoom level transitions
   makVre::DtLinearInterpolator<double>* myZoomInterpolator;
 
   //! \brief Position offset from the attachment point
   DtVector myAttachedLocationOffset;
 
   //! \brief Orientation offset from the attachment point
   DtQuaternion myAttachedOrientationOffset;
 
   //! \brief Flag indicating if binoculars functionality is enabled
   bool myEnableBinoculars;
 
   //! \brief Flag indicating if night vision goggles functionality is enabled
   bool myEnableNVG;
 
   //! \brief Flag indicating if look-around functionality is enabled
   bool myEnableLookAround;
 
   //! \brief Last known state of night vision goggles
   bool myLastNVGState;
 
   //! \brief Flag indicating if the player is currently looking around
   bool myLookingAround;
 
   //! \brief Current yaw range limits in radians
   ObserverRange myCurrentYawRange;
 
   //! \brief Current pitch range limits in radians
   ObserverRange myCurrentPitchRange;
 
   //! \brief Default yaw range limits in radians
   ObserverRange myDefaultYawRange;
 
   //! \brief Default pitch range limits in radians
   ObserverRange myDefaultPitchRange;
 
   //! \brief Time in seconds to transition back to initial view when using mouse
   double mySnapBackTimeMouse;
 
   //! \brief Time in seconds to transition back to initial view when using joystick
   double mySnapBackTimeJoystick;
 
   //! \brief Flag indicating if saved views system is in use
   bool myUseSavedViews;
 
   //! \brief Last active sensor view mode
   SensorViews myLastSensorViewMode;
 
   //! \brief Collection of supplemental configuration data for saved views
   std::vector<SavedViewData> mySupplementalSavedViewData;
 
   //! \brief Interpolator for smooth transitions between observer orientations
   makVre::DtBezierInterpolator<DtVector>* myObserverInterpolator;
 
   //! \brief Flag indicating if VR mode is enabled
   bool myVrEnabled;
 
   //! \brief Pointer to the VR driver if VR is enabled
   makVrv::DtVirtualRealityDriver* myVrDriver;
};
} // namespace makVre