vreBinocularsSimLogic.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreBinocularsSimLogic.h
//! \brief Component for binoculars zoom and simulation functionality
//! \ingroup vreCommonComponents
 
#pragma once
 
#include "vreCommonComponents/export.h"
#include "vreMessageManager/vreMessage.h"
#include "vrePlayerStation/playerComponent.h"
 
namespace makVrv
{
class DtVirtualRealityDriver;
}
 
namespace makVre
{
namespace BinocularsSimLogicConfig
{
//! \ingroup RoleConfigParams
//! \defgroup BinocularsSimLogicRoleParams Binoculars Sim Logic Role Parameters
//! \roleInherits{PlayerComponentRoleParams}
//! Configuration Options for binoculars simulation logic role.
//! @{
 
//! \vreRoleParam{hmdSmoothingAlpha,double,0.8,binocularsSimLogic,Alpha value for HMD orientation smoothing when using binoculars in VR mode.}
constexpr const char* hmdSmoothingAlpha = "hmdSmoothingAlpha";
 
//! \vreRoleParam{hmdSmoothingEnabled,bool,true,binocularsSimLogic,Whether to enable HMD orientation smoothing when using binoculars in VR mode.}
constexpr const char* hmdSmoothingEnabled = "hmdSmoothingEnabled";
 
//! \vreRoleParam{hmdSmoothingThreshold,double,60.0,binocularsSimLogic,Threshold angle in degrees for triggering HMD orientation smoothing.}
constexpr const char* hmdSmoothingThreshold = "hmdSmoothingThreshold";
 
//! \vreRoleParam{maxViewMagnification,double,10.0,binocularsSimLogic,Maximum zoom magnification level for the binoculars system.}
constexpr const char* maxViewMagnification = "maxViewMagnification";
 
//! @}
} // namespace BinocularsSimLogicConfig
 
//! \brief Type identifier for DtBinocularsSimLogic component
constexpr const char* DtBinocularsSimLogicType = "DtBinocularsSimLogic";
 
//! \brief Component for handling binoculars zoom simulation and VR-specific functionality
//!
//! DtBinocularsSimLogic manages binoculars zoom operations, handling zoom messages
//! and maintaining the current view magnification state. It provides specialized
//! functionality for VR environments, including head orientation smoothing when
//! using binoculars. The component supports both direct zoom-to values and
//! incremental zoom changes.
class VRECOMMONCOMPONENTS_DLL DtBinocularsSimLogic : public DtPlayerComponent
{
public:
   //! \brief Constructor for DtBinocularsSimLogic
   //!
   //! Initializes the component with default zoom and smoothing settings
   DtBinocularsSimLogic();
 
   //! \brief Virtual destructor for DtBinocularsSimLogic
   virtual ~DtBinocularsSimLogic() override;
 
   //! \brief Initializes the binoculars simulation logic component
   //! \param player Pointer to the player station this component belongs to
   //! \param config Configuration table containing binoculars settings
   //! \return True if initialization succeeded, false otherwise
   //!
   //! Reads configuration values for maximum view magnification and HMD smoothing
   //! settings, registers message handlers, and sets up attribute callbacks
   virtual bool initialize(makVre::DtPlayerStation* player, makVre::DtInitTable& config) override;
 
   //! \brief Performs post-initialization after all components are initialized
   //! \return True if post-initialization succeeded, false otherwise
   //!
   //! Sets up VR-specific configurations if applicable, including
   //! configuring the VR driver's orientation smoothing settings
   virtual bool postInitialize() override;
   
   //! \brief Called every frame to update the component state
   //! \param dt Delta time since the last frame in seconds
   //!
   //! Current implementation is empty as updates occur through message handlers
   //! and attribute change callbacks
   virtual void tick(double dt) override;
   
   //! \brief Shuts down the binoculars simulation logic component
   //!
   //! Removes message handlers and attribute change callbacks
   virtual void shutdown() override;
 
   //! \brief Returns the type identifier for this component
   //! \return The type string for DtBinocularsSimLogic
   virtual const char* type() const override;
 
   //! \brief Handles zoom-to messages for binoculars
   //! \param msg Zoom-to message
   //! \return Message handling result indicating the message was handled
   //!
   //! Sets the view magnification directly to the specified value,
   //! clamped between 1.0 and the maximum configured magnification
   virtual makVre::DtVreMessageResult handleZoomToEvent(makVre::DtVreMessage* msg);
 
   //! \brief Handles zoom-by messages for binoculars
   //! \param msg Zoom-by message
   //! \return Message handling result indicating the message was handled
   //!
   //! Adjusts the view magnification incrementally by the specified amount,
   //! either increasing or decreasing based on the sign of the zoom value
   virtual makVre::DtVreMessageResult handleZoomByEvent(makVre::DtVreMessage* msg);
 
   //! \brief Callback for view magnification attribute changes
   //! \param mag New magnification value
   //!
   //! Updates the usingBinoculars attribute based on the current magnification
   //! and handles VR-specific state changes, including mixed reality mode management
   virtual void onViewMagnificationChanged(double mag);
 
protected:
   //! \brief Maximum allowed view magnification value
   double myMaxViewMagnification;
 
   //! \brief Pointer to the VR driver if available
   makVrv::DtVirtualRealityDriver* myVrDriver;
 
   //! \brief Flag indicating if mixed reality was active before entering binoculars mode
   bool myMrWasActive;
 
   //! \brief Flag indicating if HMD orientation smoothing is enabled
   bool myHmdSmoothingEnabled;
 
   //! \brief Smoothing alpha parameter for HMD orientation smoothing
   //! \note Higher values (closer to 1.0) produce more smoothing
   double myHmdSmoothingAlpha;
 
   //! \brief Threshold parameter for HMD orientation smoothing in degrees per second
   //! \note Rotation speeds below this threshold will be smoothed
   double myHmdSmoothingThreshold;
};
} // namespace makVre