commanderHatchViewUpdater.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file commanderHatchViewUpdater.h
//! \brief Defines the DtCommanderHatchViewUpdater component for managing commander view visuals.
//!
//! This component handles the visual aspects of a commander-hatch role, including observer orientation,
//! binocular effects (zooming, reticle overlay), and night vision mode switching.
//!
//! \ingroup vreCommonComponents
 
#pragma once
 
#include "vreCommonComponents/observerUpdater.h"
#include "vreMessageManager/vreMessage.h"
#include "vreUtil/linearInterpolator.h"
 
#include <matrix/vlVector.h>
#include <matrix/vlQuaternion.h>
 
namespace makVrv
{
class DtDe;
class DtEntityFacade;
class DtObserver;
class DtSceneObject;
}; // namespace makVrv
 
namespace makVre
{
 
namespace CommanderHatchViewUpdaterConfig
{
//! \ingroup RoleConfigParams
//! \defgroup CommanderHatchViewUpdaterRoleParams Commander Hatch View Updater Role Parameters
//! \roleInherits{PlayerComponentRoleParams}
//! Configuration Options for commander hatch view updater component.
//! @{
 
//! \vreRoleParam{attachedLocationOffset,DtVector,DtVector::zero(),commanderHatchViewUpdater,Position offset from the attachment point for the observer camera in vehicle coordinates.}
constexpr const char* attachedLocationOffset = "attachedLocationOffset";
 
//! \vreRoleParam{observerName,string,Observer 1,commanderHatchViewUpdater,Name of the observer to control for the commander hatch view.}
constexpr const char* observerName = "observerName";
 
//! \vreRoleParam{partAttachment,int,-1,commanderHatchViewUpdater,DIS enumeration for the vehicle part to attach the eyepoint to (-1 for base vehicle).}
constexpr const char* partAttachment = "partAttachment";
 
//! \vreRoleParam{pitchRange,table,"",commanderHatchViewUpdater,Table defining min/max pitch angles in degrees for observer movement. Contains 'min' and 'max' keys.}
constexpr const char* pitchRange = "pitchRange";
 
//! \vreRoleParam{yawRange,table,"",commanderHatchViewUpdater,Table defining min/max yaw angles in degrees for observer movement. Contains 'min' and 'max' keys.}
constexpr const char* yawRange = "yawRange";
 
//! @}
} // namespace CommanderHatchViewUpdaterConfig
 
//! \brief Type identifier for DtCommanderHatchViewUpdater component
constexpr const char* DtCommanderHatchViewUpdaterType = "DtCommanderHatchViewUpdater";
 
//! \brief Component for managing visual aspects of a commander-hatch role
//!
//! The DtCommanderHatchViewUpdater updates the visual aspects of the commander-hatch
//! role. It orients the observer based on state attributes and provides specialized
//! visual effects such as binocular zoom and night vision goggles.
//!
//! The following parameters are available for configuration in the role file:
//! - "observerName": Name of the observer to control (defaults to "Observer 1")
//! - "partAttachment": DIS enumeration for the vehicle part to attach the eyepoint
//!   (defaults to -1, which represents the base part/vehicle itself)
//! - "attachedLocationOffset": Vector offset from attachment point in meters
//!   (coordinates: +x right, +y front, +z up)
class VRECOMMONCOMPONENTS_DLL DtCommanderHatchViewUpdater : public DtObserverUpdater
{
public:
   //! \brief Constructor for DtCommanderHatchViewUpdater
   //!
   //! Initializes the component with default values including identity rotation offset
   //! and no zoom interpolator.
   DtCommanderHatchViewUpdater();
 
   //! \brief Virtual destructor for DtCommanderHatchViewUpdater
   virtual ~DtCommanderHatchViewUpdater() override;
 
   //! \brief Initializes the component with configuration from Lua
   //!
   //! Reads configuration values including observer name, part attachment ID,
   //! and attached location offset. Caches a pointer to the observer and adds
   //! handlers for PlayerCreatedMessage and ResetMessage.
   //!
   //! \param player Pointer to the player station this component belongs to
   //! \param config Configuration table containing initialization parameters
   //! \return True if initialization succeeds, false otherwise
   virtual bool initialize(DtPlayerStation* player, DtInitTable& config) override;
 
   //! \brief Updates the visual aspects of the commander view
   //!
   //! Reads "observerYaw" and "observerPitch" state attributes and updates the observer's
   //! attached orientation accordingly. Calls updateBinocularsState() to handle zoom effects
   //! and updateNVGState() to handle night vision mode switching.
   //!
   //! \param dt Delta time in seconds since the last tick
   virtual void tick(double dt) override;
 
   //! \brief Updates binocular zoom effects
   //!
   //! Checks the "viewMagnification" state attribute and manages the zoom interpolator
   //! to create smooth transitions between zoom levels. Creates the interpolator when needed,
   //! updates its endpoint if the target zoom changes, and applies the interpolated value
   //! to the observer's view magnification.
   //!
   //! \param dt Delta time in seconds since the last tick
   void updateBinocularsState(double dt);
 
   //! \brief Updates night vision goggles state
   //!
   //! Checks the boolean "NVG" state attribute and, if it has changed since the last update,
   //! sets the observer's sensor mode accordingly. When NVG is activated, uses the VR-Engage
   //! sensor mode mapper to find the appropriate VR-Vantage sensor mode.
   void updateNVGState();
 
   //! \brief Shuts down the component
   //!
   //! Removes message handlers for PlayerCreatedMessage and ResetMessage.
   virtual void shutdown() override;
 
   //! \brief Returns the component type identifier
   //! \return The component type string
   virtual const char* type() const override;
 
protected:
   //! \brief Handles player created messages
   //!
   //! Called when a player is created in the simulation. Calls setupObserver()
   //! to configure the observer attachment details.
   //!
   //! \param msg The player created message
   //! \return HANDLED to indicate the message was processed
   virtual makVre::DtVreMessageResult handlePlayerCreated(makVre::DtVreMessage* msg);
 
   //! \brief Handles reset messages
   //!
   //! This method currently has no implementation (TODO in the code).
   //!
   //! \param msg The reset message
   //! \return HANDLED to indicate the message was processed
   virtual makVre::DtVreMessageResult handlePlayerReset(makVre::DtVreMessage* msg);
 
   //! \brief Sets up observer attachment configuration
   //!
   //! Configures the observer with AttachTypeMimic, attaching it to the player's element
   //! with the part and location/rotation offsets specified in the role config file.
   virtual void setupObserver();
 
protected:
   //! \brief DIS enumeration for the vehicle part to attach the eyepoint to
   //!
   //! Defaults to -1, which represents the base part (the vehicle itself).
   int myPartAttachment;
 
   //! \brief Offset vector from the attachment point in meters
   //!
   //! Coordinates are: +x right, +y front, +z up
   DtVector myAttachedLocationOffset;
 
   //! \brief Rotation offset quaternion from the attachment point
   //!
   //! Defaults to identity quaternion (1,0,0,0) - no rotation
   DtQuaternion myAttachedRotationOffset;
 
   //! \brief Interpolator for smooth zoom transitions
   //!
   //! Created as needed when zoom level changes and deleted when transition completes
   makVre::DtLinearInterpolator<double>* myZoomInterpolator;
 
   //! \brief Cached pointer to the observer being controlled
   makVrv::DtObserver* myObserver;
 
   //! \brief Flag indicating whether observer rotation is constrained
   //!
   //! When true, observer yaw and pitch are clamped to the ranges defined
   //! by myYawRange and myPitchRange. Set to true if either pitchRange or
   //! yawRange configuration parameters are provided.
   bool myLimitObserverRange;
 
   //! \brief Yaw range limits in radians
   ObserverRange myYawRange;
 
   //! \brief Pitch range limits in radians
   ObserverRange myPitchRange;
 
   //! \brief Tracks the last known state of night vision goggles
   //!
   //! Used to detect changes in NVG state to avoid unnecessary sensor mode changes
   bool myLastNVGState;
};
} // namespace makVre