virtualRealityLogic.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file virtualRealityLogic.h
//! \brief Component for managing VR hardware integration and controller input
//! \ingroup vreCommonComponents
 
#pragma once
 
#include "vreCommonComponents/export.h"
 
#include "vrePlayerStation/playerComponent.h"
#include "vrePlayerStation/inputLogic.h"
 
#include "vreUtil/virtualDpad.h"
#include <vreMessageManager/vreMessage.h>
 
 
#include <vrvVirtualRealityController/DtVirtualRealityEventManager.h>
#include <vrvVirtualRealityController/DtVirtualRealityControllerState.h>
 
namespace makVrv
{
class DtDe;
class DtObserver;
class DtVirtualRealityDriver;
class DtSubmitOverlayCallback;
} // namespace makVrv
 
namespace makVre
{
 
class DtVirtualRealityEventProcessor;
class DtActionMenuLogic;
 
namespace VirtualRealityLogicConfig
{
//! \ingroup RoleConfigParams
//! \defgroup VirtualRealityLogicRoleParams Virtual Reality Logic Role Parameters
//! \roleInherits{PlayerComponentRoleParams}
//! Configuration Options for virtual reality logic role.
//! @{
 
//! \vreRoleParam{rightHanded,bool,true,virtualRealityLogic,Determines whether the user is right-handed for controller orientation settings.}
constexpr const char* rightHanded = "rightHanded";
 
//! @}
} // namespace VirtualRealityLogicConfig
 
//! \brief Type identifier for DtVirtualRealityLogic component
constexpr const char* DtVirtualRealityLogicType = "DtVirtualRealityLogic";
 
//! \brief Component that integrates VR hardware with the simulation environment
//!
//! DtVirtualRealityLogic manages the connection between VR hardware (headsets and
//! controllers) and the simulation, processing controller input events and managing
//! the VR view state. It handles controller tracking, head position resetting,
//! menu interactions, and mixed reality mode toggling. This component enables
//! and disables VR mode during player state transitions, such as when entering menus.
class VRECOMMONCOMPONENTS_DLL DtVirtualRealityLogic : public makVre::DtPlayerComponent
{
public:
   //! \brief Type alias for a map of controller IDs to controller state pointers
   using ControllerStateMap = makVrv::DtVirtualRealityEventManager::ControllerStateMap;
 
   //! \brief Type alias for controller type bitfield values
   using Bitfield = makVrv::DtVirtualRealityControllerState::Bitfield;
 
   //! \brief Type alias for controller identifier values
   using ControllerId = makVrv::DtVirtualRealityControllerState::ControllerId;
 
   //! \brief Type alias for 2D vector used in controller inputs
   using DtVector2f = makVrv::DtVirtualRealityControllerState::DtVector2f;
 
   //! \brief Type alias for virtual reality controller state
   using ControllerState = makVrv::DtVirtualRealityControllerState;
 
   //! \brief Constructor for DtVirtualRealityLogic
   //!
   //! Initializes the component with default settings for controller identification
   //! and tracking state
   DtVirtualRealityLogic();
 
   //! \brief Virtual destructor for DtVirtualRealityLogic
   virtual ~DtVirtualRealityLogic() override;
 
   //! \brief Initializes the virtual reality logic component
   //! \param player Pointer to the player station this component belongs to
   //! \param config Configuration table containing VR settings
   //! \return True if initialization succeeded, false otherwise
   //!
   //! Sets up the VR driver connection, configures input handlers, and establishes
   //! message handlers for VR-related events
   virtual bool initialize(makVre::DtPlayerStation* player, makVre::DtInitTable& config) override;
   //! \brief Called every frame to update the VR state
   //! \param dt Delta time since the last frame in seconds
   //!
   //! Monitors VR enabled state changes, updates controller tracking,
   //! and manages overlay visibility
   virtual void tick(double dt) override;
   //! \brief Shuts down the virtual reality logic component
   //!
   //! Stops VR mode, disconnects message handlers, and performs cleanup operations
   virtual void shutdown() override;
 
   //! \brief Returns the type identifier for this component
   //! \return The type string for DtVirtualRealityLogic
   virtual const char* type() const override;
 
   //! \brief Processes the current state of all tracked VR controllers
   //! \param controllers Map of controller IDs to their current state
   //!
   //! Handles controller discovery/loss events, processes button presses and
   //! thumbstick movements, and translates them into simulation actions
   virtual void processControllerStates(const ControllerStateMap& controllers);
 
   //! \brief Resets the HMD head position tracking
   //!
   //! Calls the VR driver to reset the head position and orientation reference
   virtual void resetHeadPos();
 
   //! \brief Input handler for resetting head position
   //! \param val Input value (1 to trigger reset)
   //!
   //! Handles the reset head position input action from bound controls
   virtual void handleResetHeadPosInput(int val);
 
protected:
   //! \brief Structure for identifying and tracking VR controllers
   //!
   //! Contains both the controller type (HMD, left hand, right hand) and
   //! its unique identifier used for consistent tracking between frames
   struct ControllerIdentifier
   {
      //! \brief Constructor that initializes with a controller type
      //! \param type Bitfield value representing the controller type
      ControllerIdentifier(Bitfield type)
         : controllerType(type)
         , controllerId(ControllerState::NoId)
      {
      }
 
      //! \brief Type of the controller (HMD, left hand, right hand)
      Bitfield controllerType;
 
      //! \brief Unique identifier for the controller instance
      ControllerId controllerId;
   };
 
   //! \brief Starts VR mode
   //!
   //! Assigns observers to the HMD, sets up event handlers, configures
   //! post-processing, and updates state attributes
   virtual void startVr();
 
   //! \brief Stops VR mode
   //!
   //! Removes event handlers, cleans up resources, and resets channel render orders
   virtual void stopVr();
 
   //! \brief Handles reset VR head position message
   //! \param msg The reset head position message
   //! \return Message handling result indicating if the message was handled
   //!
   //! Processes request to reset the VR headset position tracking
   virtual makVre::DtVreMessageResult handleResetVrHeadPos(makVre::DtVreMessage* msg);
 
   //! \brief Handles toggle mixed reality message
   //! \param msg The toggle mixed reality message
   //! \return Message handling result indicating if the message was handled
   //!
   //! Toggles between normal VR and mixed reality mode
   virtual makVre::DtVreMessageResult handleToggleMixedReality(makVre::DtVreMessage* msg);
 
   //! \brief Handles player entering a state
   //! \param msg The enter player state message
   //! \return Message handling result indicating if the message was handled
   //!
   //! Processes state changes, particularly disabling VR when entering the menu state
   virtual makVre::DtVreMessageResult handleEnterPlayerState(makVre::DtVreMessage* msg);
 
   //! \brief Handles player exiting a state
   //! \param msg The exit player state message
   //! \return Message handling result indicating if the message was handled
   //!
   //! Processes state changes, particularly re-enabling VR when exiting the menu state
   //! if VR was previously enabled
   virtual makVre::DtVreMessageResult handleExitPlayerState(makVre::DtVreMessage* msg);
 
   //! \brief Finds a controller in the controller state map
   //! \param identifier Controller identifier to find and update with current ID
   //! \param controllers Map of controller IDs to their current state
   //! \return Pointer to the controller state if found, nullptr otherwise
   //!
   //! Locates a controller either by cached ID or by searching for a matching type,
   //! updating the identifier's controllerId if found
   virtual const ControllerState* findController(
      ControllerIdentifier& identifier, const ControllerStateMap& controllers);
 
   //! \brief Pointer to the VR driver for hardware interaction
   makVrv::DtVirtualRealityDriver* myVrDriver;
 
   //! \brief Processor for VR controller events
   DtVirtualRealityEventProcessor* myEventProcessor;
 
   //! \brief Menu logic component for handling VR menu interactions
   DtActionMenuLogic* myMenuLogic;
 
   //! \brief Callback for submitting overlay graphics to VR display
   makVrv::DtSubmitOverlayCallback* myVrOverlay;
 
   //! \brief Flag indicating if VR is currently enabled
   bool myVrEnabled;
 
   //! \brief Flag indicating if VR was enabled before entering a menu
   bool myVrWasEnabled;
 
   //! \brief Flag indicating if the player uses right hand as dominant
   bool myRightHanded;
 
   //! \brief Flag tracking if hand motion was detected in the current frame
   bool myDidHaveHandMotion;
 
   //! \brief Identifier for the HMD controller
   ControllerIdentifier myHeadId;
 
   //! \brief Identifier for the left hand controller
   ControllerIdentifier myLeftHandId;
 
   //! \brief Identifier for the right hand controller
   ControllerIdentifier myRightHandId;
 
   //! \brief Counter for frames elapsed since menu interaction
   int myFramesSinceMenu;
 
   //! \brief Virtual D-pad for converting analog input to digital directions
   DtVirtualDpad myVirtualDpad;
 
   //! \brief Input logic for mapping actions to VR functions
   DtInputLogic myInputLogic;
 
   //! \brief Cached render order for the main channel to restore when exiting VR
   int myLastMainChannelRenderOrder;
};
 
} // namespace makVre