commanderHatchControlLogic.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file commanderHatchControlLogic.h
//! \brief Defines the DtCommanderHatchControlLogic component for controlling commander out-of-hatch view.
//!
//! This component provides functionality for controlling a vehicle commander's view when
//! looking from an open hatch, including look direction control and binocular/NVG usage.
//!
//! \ingroup vreCommonComponents
 
#pragma once
 
#include "vreCommonComponents/export.h"
 
#include "vrePlayerStation/entityControlLogic.h"
 
namespace makVre
{
namespace CommanderHatchControlLogicConfig
{
//! \ingroup RoleConfigParams
//! \defgroup CommanderHatchControlLogicRoleParams Commander Hatch Control Logic Role Parameters
//! \roleInherits{EntityControlLogicRoleParams}
//! Configuration Options for commander hatch control logic role.
//! @{
 
// (No specific configuration parameters are currently used by DtCommanderHatchControlLogic.)
 
//! @}
} // namespace CommanderHatchControlLogicConfig
 
//! \brief Type identifier for DtCommanderHatchControlLogic component
constexpr const char* DtCommanderHatchControlLogicType = "DtCommanderHatchControlLogic";
 
//! \brief Component for controlling commander view from open vehicle hatch
//!
//! The DtCommanderHatchControlLogic provides the capability to look around as a human
//! observer from a point of view on a vehicle (i.e., an open hatch) with support for
//! binoculars and night vision goggles (NVG). It handles head movement (yaw/pitch) and
//! equipment toggling (binoculars, NVG).
//!
//! Input handler details (for configuring in an SMS input configuration file):
//!
//! This class supports the following input handler functions that may be configured
//! to map to input devices in role input configuration files:
//! - "yaw": Controls horizontal head rotation
//! - "pitch": Controls vertical head tilt
//! - "toggle-binoculars": Toggles binocular use on/off
//! - "toggle-nvg": Toggles night vision goggles on/off
//!
//! The input group name is provided in the role configuration file and is used to
//! distinguish input handlers when multiple handlers are present on the entity.
//! The default input group is "commander-hatch".
class VRECOMMONCOMPONENTS_DLL DtCommanderHatchControlLogic : public makVre::DtEntityControlLogic
{
public:
   //! \brief Constructor for DtCommanderHatchControlLogic
   //!
   //! Initializes the component with the name "DtCommanderHatchControlLogic" and default values.
   //! Also checks out the required VR Engage Ground license.
   DtCommanderHatchControlLogic();
 
   //! \brief Virtual destructor for DtCommanderHatchControlLogic
   virtual ~DtCommanderHatchControlLogic() override;
 
   //! \brief Initializes the component with configuration from Lua
   //!
   //! Sets up input handlers for "yaw", "pitch", "toggle-binoculars", and "toggle-nvg".
   //! Initializes state attributes for equipment tracking:
   //! - "isCivilian": Boolean flag for civilian status (defaults to false)
   //! - "usingBinoculars": Boolean flag for binocular use (defaults to false)
   //! - "currentEquipment": Equipment enum value (defaults to NONE)
   //! - "NVG": Boolean flag for night vision goggles (defaults to false)
   //!
   //! \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(makVre::DtPlayerStation* player, makVre::DtInitTable& config) override;
 
   //! \brief Performs post-initialization setup
   //!
   //! Initializes yaw and pitch input to zero to prevent display shaking before any input is applied.
   //! Sets up a change callback for the "usingBinoculars" state attribute.
   //!
   //! \return True if post-initialization succeeds, false otherwise
   virtual bool postInitialize() override;
 
   //! \brief Updates the component state
   //!
   //! Called each frame to update observer yaw and pitch based on input values.
   //! Scales input by delta time and current view magnification to maintain consistent
   //! control regardless of frame rate or zoom level.
   //!
   //! \param dt Delta time in seconds since the last tick
   virtual void tick(double dt) override;
 
   //! \brief Shuts down the component
   //!
   //! Removes menu action message handler and usingBinoculars state attribute change callback.
   //! Also shuts down the input logic.
   virtual void shutdown() override;
 
   //! \brief Returns the component type identifier
   //! \return The component type string
   virtual const char* type() const override;
 
   //! \brief Input handler for horizontal head rotation (yaw)
   //!
   //! Stores the input value in myYawInput for processing during tick().
   //!
   //! \param val The yaw input value, typically from -1.0 to 1.0
   virtual void yaw(double val);
 
   //! \brief Input handler for vertical head tilt (pitch)
   //!
   //! Stores the input value in myPitchInput for processing during tick().
   //!
   //! \param val The pitch input value, typically from -1.0 to 1.0
   virtual void pitch(double val);
 
   //! \brief Toggles binocular use on or off
   //!
   //! When triggered with a value of 1.0, toggles the "usingBinoculars" state attribute.
   //! If binoculars are activated:
   //! - Sets zoom level to the value of "maxViewMagnification" state attribute
   //! - Sets "currentEquipment" state attribute to BINOCULARS
   //! - Disables NVG if active
   //! If binoculars are deactivated:
   //! - Sets zoom level to 1.0
   //!
   //! \param val The input value, a value of 1.0 triggers the toggle
   virtual void toggleBinoculars(double val);
 
   //! \brief Enables or disables binocular-specific input controls
   //!
   //! When enabled, loads the "binoculars" input configuration and sets up the
   //! "zoom" action handler. When disabled, unloads the binoculars input configuration.
   //!
   //! \param enabled True to enable binocular controls, false to disable
   virtual void setBinocularsControls(bool enabled);
 
   //! \brief Reduces binocular zoom level
   //!
   //! Sends a BinocularsZoomByMessage with a negative zoom value.
   //!
   //! \param value The amount to zoom out (positive value)
   virtual void zoomOut(double value);
 
   //! \brief Increases binocular zoom level
   //!
   //! Sends a BinocularsZoomByMessage with a positive zoom value.
   //!
   //! \param value The amount to zoom in (positive value)
   virtual void zoomIn(double value);
 
   //! \brief Combined input handler for binocular zoom
   //!
   //! Routes to zoomIn or zoomOut based on whether the input value is positive or negative.
   //!
   //! \param value The zoom input value, positive for zoom in, negative for zoom out
   virtual void zoom(double value);
 
   //! \brief Toggles night vision goggles (NVG) on or off
   //!
   //! When triggered with a value of 1.0, toggles the "NVG" state attribute.
   //! If NVG is activated:
   //! - Disables binoculars if active
   //! - Resets zoom level to 1.0
   //!
   //! \param val The input value, a value of 1.0 triggers the toggle
   virtual void toggleNVG(double val);
 
protected:
   //! \brief Handles menu action messages
   //!
   //! Processes menu actions, particularly the "toggleBinoculars" action which
   //! triggers the toggleBinoculars functionality.
   //!
   //! \param msg The message to process
   //! \return HANDLED if the message was processed, IGNORED otherwise
   virtual DtVreMessageResult handleMenuMessage(makVre::DtVreMessage* msg);
 
   //! \brief Callback for changes to the "usingBinoculars" state attribute
   //!
   //! Updates the "currentEquipment" state attribute and enables/disables
   //! binocular-specific input controls based on the new value.
   //!
   //! \param usingBinoculars The new value of the usingBinoculars state attribute
   void onBinocularsChanged(bool usingBinoculars);
 
protected:
   //! \brief Input handler logic for processing input device events
   DtInputLogic myInputLogic;
 
   //! \brief Main control group name from configuration
   //!
   //! Used to identify the function group when sending joystick messages.
   std::string myMainControlGroup;
 
   //! \brief Current yaw input value
   //!
   //! Stored during input handler calls and applied during tick().
   float myYawInput;
 
   //! \brief Current pitch input value
   //!
   //! Stored during input handler calls and applied during tick().
   float myPitchInput;
};
 
} // namespace makVre