deviceMapping.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies, Inc.
** All rights reserved.
******************************************************************************/
 
//! \file
//! \brief Defines mapping between device inputs and actions
 
#pragma once
 
#include "vreInput/export.h"
 
#include <unordered_map>
#include <memory>
#include <string>
#include <vector>
 
namespace makVre
{
//! Forward declarations
class DtVreInputManager;
class DtInputEvaluator;
class DtInitTable;
struct DtInputData;
 
//! \brief Maps device inputs to actions through evaluators
//!
//! This class manages the mapping between raw device inputs and logical actions
//! using evaluators. It maintains the current state of device inputs and processes
//! incoming input events, forwarding them to the appropriate evaluators.
class VREINPUT_DLL DtDeviceMapping
{
public:
   //! \brief Type for storing the current state of device inputs
   //!
   //! Maps input IDs to their current values
   using DeviceState = std::unordered_map<int, float>;
 
   //! \brief Constructor that initializes the device mapping
   //!
   //! Creates a new device mapping with the given input manager and configuration.
   //! The configuration defines which evaluators to create and how to map inputs.
   //!
   //! \param mgr Reference to the input manager that owns this mapping
   //! \param group The input group name for organizing related input mappings
   //! \param config Pointer to the configuration data for this mapping
   DtDeviceMapping(DtVreInputManager& mgr, const std::string& group, DtInitTable* config);
   //! \brief Virtual destructor
   //!
   //! Cleans up resources owned by this mapping
   virtual ~DtDeviceMapping();
 
   //! \brief Copy constructor (deleted)
   //!
   //! Device mappings cannot be copied due to unique ownership of evaluators
   DtDeviceMapping(const DtDeviceMapping& mapping) = delete;
 
   //! \brief Assignment operator (deleted)
   //!
   //! Device mappings cannot be assigned due to unique ownership of evaluators
   DtDeviceMapping& operator=(const DtDeviceMapping&) = delete;
 
   //! \brief Initialize the mapper and all evaluators
   //!
   //! Resets the device state and initializes all evaluators. Called during construction
   //! and can be called again to reset the mapping to its initial state.
   virtual void initialize();
 
   //! \brief Process an input event from a device
   //!
   //! Updates the device state with the new input value and passes the input
   //! to any evaluators registered for that input ID. If any evaluator handles
   //! the input, processing stops.
   //!
   //! \param data The input data structure containing the event information
   //! \return True if this mapping handled the input and processing should stop, false otherwise
   virtual bool processInput(const DtInputData& data);
 
   //! \brief Update method called each frame
   //!
   //! Updates all evaluators, allowing them to check for time-based triggers
   //! and other conditions based on the current device state.
   //!
   //! \param dt Delta time in seconds since the last frame
   virtual void tick(double dt);
 
   //! \brief Get the current state of all device inputs
   //!
   //! Returns a map of input IDs to their current values, representing
   //! the current state of the device's inputs.
   //!
   //! \return Constant reference to the device state map
   virtual const DeviceState& deviceState() const;
 
   //! \brief Structure for representing a single input mapping
   //!
   //! Contains information about how a specific input maps to an action
   struct InputMapping
   {
      //! \brief Type of input (button, axis, key, etc.)
      int inputType;
 
      //! \brief Input ID (button number, axis number, key code, etc.)
      int inputId;
 
      //! \brief Input flags (hat position, axis direction, etc.)
      int inputFlags;
 
      //! \brief Input modifiers (alt, ctrl, shift for keys)
      int inputModifiers;
 
      //! \brief Name of the action this input triggers
      std::string actionName;
 
      //! \brief Human-readable description of the input
      std::string inputDescription;
   };
 
   //! \brief Get all input mappings configured for this device
   //!
   //! Returns a list of all input mappings that have been configured
   //! for this device, including the input details and associated actions.
   //!
   //! \return Vector of InputMapping structures describing all configured mappings
   virtual std::vector<InputMapping> getInputMappings() const;
 
   virtual std::string getGroup() const { return myGroup; }
 
   using EvaluatorMap = std::unordered_map<int, std::vector<std::unique_ptr<DtInputEvaluator>>>;
 
protected:
   //! \brief Clear the current device input state
   //!
   //! Virtual method that can be overridden by derived classes to provide
   //! custom state clearing behavior.
   virtual void clearInputState() {};
 
   //! \brief Current state of all device inputs (input ID -> value)
   DeviceState myDeviceState;
   
   //! \brief Map of input IDs to their associated evaluators
   //!
   //! Each input ID can have multiple evaluators that process its values
   EvaluatorMap myEvaluators;
 
   std::string myGroup;
 
   //! \brief Reference to the input manager that owns this mapping
   DtVreInputManager& myManager;
 
private:
   //! \brief Helper method to create human-readable input descriptions
   std::string createInputDescription(int inputType, int inputId, int inputFlags, int inputModifiers) const;
      
   //! \brief Helper method to convert input ID to key name
   std::string inputIdToKeyName(int keyId) const;
      
   //! \brief Helper method to convert hat flags to string
   std::string hatFlagsToString(int hatFlags) const;
      
   //! \brief Helper method to convert axis flags to string  
   std::string axisFlagsToString(int axisFlags) const;
};
 
} // namespace makVre