vreInputManager.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies, Inc.
** All rights reserved.
******************************************************************************/
 
//! \file
//! \brief Input management system for handling device input and action mapping
 
#pragma once
 
#include "vreInput/export.h"
#include "vreInput/deviceMapping.h"
 
#include <vreUtil/delegate.h>
#include <vreUtil/factory.h>
 
#include <vrvUtil/DtVirtualBaseClass.h>
 
#include <string>
#include <vector>
#include <unordered_map>
#include <deque>
#include <memory>
#include <boost/signals2.hpp>
 
namespace makVre
{
   //! Forward declarations
   class DtInputConfigViewer;
   class DtPlayerStationApp;
   class DtInputDevice;
   class DtValueTransform;
   struct DtInputData;
   //! \brief Structure representing an input action with a name and value
   //! 
   //! This structure represents a logical action that can be triggered by an input device
   //! and processed by an action handler.
   struct DtAction
   {
      //! \brief Group name for categorizing actions (e.g., "movement", "combat")
      std::string group;
      
      //! \brief Name of the action to be performed
      std::string name;
      
      //! \brief Intensity or value of the action (range typically -1.0 to 1.0)
      float value;
   };
   
   // Only for pairs of std::hash-able types for simplicity.
   // You can of course template this struct to allow other hash functions
   struct pair_hash {
      template <class T1, class T2>
      std::size_t operator () (const std::pair<T1, T2>& p) const {
         auto h1 = std::hash<T1>{}(p.first);
         auto h2 = std::hash<T2>{}(p.second);
 
         // Mainly for demonstration purposes, i.e. works but is overly simple
         // In the real world, use sth. like boost.hash_combine
         return h1 ^ h2;
      }
   };
 
   //! \brief Delegate type for handling action events
   //! \param float The value/intensity of the action
   using DtActionDelegate = DtDelegate<void, float>;
   
   using ActionHandlerMap = std::unordered_map<std::pair<std::string, std::string>, DtActionDelegate, pair_hash>;
 
   //! \brief Delegate type for handling raw input data events
   //! \param DtInputData The raw input data from a device
   //! \return bool True if the input was handled, false to continue processing
   using DtInputDelegate = DtDelegate<bool, const DtInputData&>;
 
   //! \brief Central manager for input device handling, action mapping, and input processing
   //!
   //! This class manages the input device lifecycle, input processing, and mapping of
   //! device inputs to logical actions. It provides a layered approach to input configuration,
   //! allowing multiple mapping configurations to be active simultaneously with priority handling.
   class VREINPUT_DLL DtVreInputManager : public makVrv::DtVirtualBaseClass
   {
   public:
      //! \brief List type for storing managed input devices
      using DeviceList = std::vector<std::unique_ptr<DtInputDevice>>;
      //! \brief Structure representing a layer of input mapping configuration
      //!
      //! Each mapping layer contains configurations for one or more devices and can be
      //! arranged in a stack to provide priority-based input handling.
      struct MappingLayer
      {
         //! \brief Source configuration file name
         std::string config;
         
         //! \brief Mapping group name within the configuration
         std::string group;
         
         //! \brief Map of device name/type to its mapping configuration
         std::unordered_map<std::string, std::unique_ptr<DtDeviceMapping>> deviceMappings;
         
         //! \brief If true, keep this layer at the top of the stack regardless of other layers
         bool alwaysOnTop;
         
         //! \brief If true, this layer remains active even when player controls are disabled
         bool alwaysEnabled;
      };
      //! \brief Stack type for managing priority-ordered input mapping layers
      using MappingStack = std::deque<MappingLayer>;
      
      //! \brief Factory type for creating value transform objects
      using DtValueTransformFactory = DtFactory<DtValueTransform>;
      
      //! \brief Constructor for the input manager
      //! 
      //! Initializes the input manager with the player station application context,
      //! sets up value transform factories, and configures debug facilities.
      //! 
      //! \param app Reference to the player station application that owns this manager
      DtVreInputManager(DtPlayerStationApp& app);
      //! \brief Virtual destructor
      //! 
      //! Cleans up debug callbacks and resources owned by the input manager.
      virtual ~DtVreInputManager() override;
 
      //! \brief Copy constructor (deleted)
      //! 
      //! Input manager cannot be copied due to unique ownership of resources.
      DtVreInputManager(const DtVreInputManager& mapping) = delete;
      
      //! \brief Assignment operator (deleted)
      //! 
      //! Input manager cannot be assigned due to unique ownership of resources.
      DtVreInputManager& operator=(const DtVreInputManager&) = delete;
 
      //-----------------------Interface-------------------------------------
 
      ////----Factory functions used by DeviceMappers
      
      //! \brief Access the value transform factory used by device mappers
      //! 
      //! Provides access to the factory that creates value transformation objects
      //! used to modify input values (like scaling, inversion, etc.)
      //! 
      //! \return Reference to the value transform factory
      virtual DtValueTransformFactory& valueTransformFactory() const;
 
      //----Startup/Shutdown operations
      
      //! \brief Creates and initializes input devices from the provided list of device types
      //! 
      //! This method should be called once at application startup to instantiate all the
      //! input devices that will be used. Each device is created using the input device factory
      //! and then initialized with this manager as context.
      //! 
      //! \param hardwareHandlerList List of device type names to create and initialize
      //! \return True if all devices were created successfully, false otherwise
      virtual bool realizeHardwareHandlers(const std::vector<std::string>& hardwareHandlerList);
 
      //! \brief Shuts down the input manager and releases all resources
      //! 
      //! Clears all mapping layers, disconnects action handlers, and shuts down
      //! all input devices. This should be called before application exit.
      //! 
      //! \return True if shutdown was successful, false otherwise
      virtual bool shutdown();
 
 
      //----Configuration operations
 
      //! \brief Creates and adds an input mapping layer to the mapping stack
      //! 
      //! Loads mapping configuration from the specified config file and group,
      //! and adds it to the mapping stack with the specified priority parameters.
      //! If a layer with the same config and group already exists, it will not be added again.
      //! 
      //! \param configName Name of the configuration file (without path) to load
      //! \param group Group name within the configuration to activate
      //! \param alwaysOnTop If true, layer will be kept at the top of the stack
      //! \param alwaysEnabled If true, layer will remain active even when player controls are disabled
      //! \return True if the layer was added successfully, false otherwise
      virtual bool addMappingLayer(const std::string& configName, const std::string& group, bool alwaysOnTop, bool alwaysEnabled);
 
      //! \brief Removes a mapping layer from the stack
      //! 
      //! Finds and removes a mapping layer with the specified configuration and group name.
      //! If no matching layer is found, this operation has no effect.
      //! 
      //! \param configName Name of the configuration file that was used to create the layer
      //! \param group Group name within the configuration to remove
      virtual void removeMappingLayer(const std::string& configName, const std::string& group);
 
      //! \brief Sets a raw input data handler
      //! 
      //! This handler will be called before any mapping layer processing occurs,
      //! allowing for pre-processing or interception of raw input data.
      //! 
      //! \param inputDelegate Delegate to be called with input data before mapping occurs
      virtual void setRawInputHandler(const DtInputDelegate& inputDelegate);
 
      //! \brief Removes the previously set raw input handler
      //! 
      //! After this call, raw input will no longer be pre-processed and will go
      //! directly to the mapping layers.
      virtual void removeRawInputHandler();
 
 
      //----Runtime operations
      
      //! \brief Updates the input system for the current frame
      //! 
      //! This method should be called once per frame to allow devices and mappings
      //! to update their state and process time-dependent operations.
      //! 
      //! \param dt Delta time in seconds since the last frame
      virtual void tick(double dt);
 
      //! \brief Processes raw input data from a device
      //! 
      //! Called by input devices when they receive input to be processed. This method
      //! handles passing the data to the raw input handler (if set) and through the mapping
      //! layers based on device type and name until it is processed or falls through.
      //! 
      //! \param data The input data structure containing all input information
      //! \return True if the input was processed by a handler, false if it was not handled
      virtual bool processInput(const DtInputData& data);
 
 
      //---Accessors to internal data structures, may be useful
 
      //! \brief Finds an input device by its numeric ID
      //! 
      //! \param id The numeric ID of the device to find
      //! \return Reference to the unique pointer containing the device
      virtual const std::unique_ptr<DtInputDevice>& findDevice(int id) const;
 
      //! \brief Gets the list of all input devices
      //! 
      //! \return Reference to the list of all input devices managed by this manager
      virtual const DeviceList& deviceList() const;
 
      //! \brief Gets the full path to the input settings directory
      //! 
      //! Returns the directory where input configuration files are stored.
      //! This path is resolved based on the application's path configuration.
      //! 
      //! \return String containing the full path to the input settings directory
      virtual std::string inputSettingsPath() const;
 
      //! \brief Gets the current simulation time
      //! 
      //! \return Current simulation time in seconds
      virtual double simulationTime() const;
 
      //! \brief Gets the player station application associated with this manager
      //! 
      //! \return Reference to the player station application
      DtPlayerStationApp& app() const;
 
 
      //----Action handling
 
      //! \brief Registers a handler for a named action
      //! 
      //! Associates the specified action name with a delegate that will be called
      //! whenever that action is triggered by input mappings. The group and action
      //! name combination uniquely identifies the handler in the system.
      //! 
      //! \param group Group name for categorizing the action (e.g., "movement", "combat", "ui")
      //! \param action Name of the action to register a handler for
      //! \param handler Delegate to be called when the action is triggered
      virtual void addActionHandler(const std::string& group, const std::string& action, const DtActionDelegate& handler);
 
      //! \brief Removes a previously registered action handler
      //! 
      //! Removes the handler associated with the specified group and action name.
      //! If no handler is registered for the action, this has no effect.
      //! 
      //! \param group Group name for categorizing the action
      //! \param action Name of the action to remove the handler for
      virtual void removeActionHandler(const std::string& group, const std::string& action);
 
      //! \brief Checks if an action has a registered handler
      //! 
      //! Determines whether the specified group and action name combination has a handler registered.
      //! 
      //! \param group Group name for categorizing the action
      //! \param action Name of the action to check
      //! \return True if the action has a handler, false otherwise
      virtual bool isActionApplicable(const std::string& group, const std::string& action) const;
 
      //! \brief Processes an action by calling its registered handler
      //! 
      //! This is called by input mapping evaluators when an action is triggered.
      //! The method assumes that the action is applicable (has a registered handler).
      //! Logs actions for debugging if action logging is enabled.
      //! 
      //! \param action The action structure containing the name and value
      virtual void handleAction(const DtAction& action);
 
      //! \brief Checks if player controls are currently enabled
      //! 
      //! When player controls are disabled, only mapping layers with alwaysEnabled=true
      //! will be processed.
      //! 
      //! \return True if player controls are enabled, false otherwise
      virtual bool isPlayerControlsEnabled() const;
      
      //! \brief Sets whether player controls are enabled
      //! 
      //! Enables or disables player controls, affecting which mapping layers are active.
      //! 
      //! \param enabled True to enable player controls, false to disable
      virtual void setPlayerControlsEnabled(bool enabled);
 
      //----Debugging
      
      //! \brief Checks if input event logging is enabled
      //! 
      //! \return True if input events are being logged, false otherwise
      virtual bool loggingEvents() const;
      
      //! \brief Callback for the debug menu
      //! 
      //! Renders debug UI options for the input system when accessed through
      //! the debug menu (Shift-F4). Allows toggling of input event logging and
      //! viewing input event history.
      virtual void debugMenuCallback();
      
      //! \brief Gets the action handlers map (for debugging/configuration purposes)
      //! 
      //! \return Constant reference to the action handlers map
      const ActionHandlerMap& getActionHandlers() const { return myActionHandlers; }
      
      //! \brief Gets the mapping stack (for debugging/configuration purposes)
      //! 
      //! \return Constant reference to the mapping stack
      const MappingStack& getMappingStack() const { return myMappingStack; }
   protected:
      //! \brief Reference to the parent player station application
      DtPlayerStationApp& myApp;
      
      //! \brief List of all input devices managed by this manager
      DeviceList myDevices;
      
      //! \brief Stack of mapping layers in priority order (front = highest priority)
      MappingStack myMappingStack;
      
      //! \brief Map of action names to their handler delegates
      ActionHandlerMap myActionHandlers;
      
      //! \brief Optional delegate for handling raw input before mapping
      DtInputDelegate myRawInputHandler;
      
      //! \brief Factory for creating value transformation objects
      DtValueTransformFactory myValueTransformFactory;
 
      //! \brief Path to the directory containing input configuration files
      std::string myInputSettingsPath;
 
      //! \brief Flag indicating if player controls are currently enabled
      bool myPlayerControlsEnabled;
      
      //! \brief Flag indicating if the simulation is currently playing
      bool myIsPlaying;
 
      // For debugging: enable through Shift-F4 Debug Menu
      //! \brief Flag indicating if input event logging is enabled
      bool myLoggingEvents;
      
      //! \brief Counter for assigning unique IDs to logged events
      int myLastEventDebugId;
      
      //! \brief Map of event IDs to their log messages
      std::map<int, std::string> myLatestEventLog;
      
      //! \brief Flag indicating if direct action logging is enabled
      bool myLoggingDirectActions;
      
      //! \brief Map of event IDs to their direct action log messages
      std::map<int, std::vector<std::string>> myLatestDirectActionLog;
      
      //! \brief Queue of tick-based action log messages
      std::deque<std::string> myLatestsTickedActionLog;
 
      //! \brief Input configuration viewer instance
      std::unique_ptr<DtInputConfigViewer> myInputConfigViewer;
   };
 
} //::makVre