virtualDpad.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file virtualDpad.h
//! \ingroup vreUtil
//! \brief Provides a virtual directional pad implementation
//!
//! This file defines the DtVirtualDpad class which simulates a directional pad (d-pad)
//! based on analog input values. It converts continuous x and y axis inputs into
//! discrete directional button states and tracks button press/release events.
 
#pragma once
 
//! \brief A class that simulates a directional pad from analog inputs
//!
//! The DtVirtualDpad converts analog x and y inputs (such as from a joystick or thumbstick)
//! into discrete directional button states (up, down, left, right). It tracks both the
//! current button states and state changes to provide pressed and released events.
class DtVirtualDpad
{
public:
   //! \brief Enumeration of d-pad button directions
   enum Button
   {
      Up,   //!< Up direction button
      Down, //!< Down direction button
      Left, //!< Left direction button
      Right //!< Right direction button
   };
 
   //! \brief Threshold value for axis activation (default 0.5)
   //!
   //! Axis values with magnitude greater than this threshold will
   //! trigger a button state change in the corresponding direction
   const float AxisThreshold = 0.5f;
 
   //! \brief Default constructor
   //!
   //! Initializes the d-pad with all buttons in the released state
   //! and no pending state changes
   DtVirtualDpad()
   {
      memset(&myButtonStates, 0, sizeof(myButtonStates));
      memset(&myButtonsChanged, 0, sizeof(myButtonsChanged));
   }
   //! \brief Virtual destructor
   virtual ~DtVirtualDpad() {}
 
   //! \brief Updates the d-pad state based on x and y input values
   //! \param x The x-axis input value (positive = right, negative = left)
   //! \param y The y-axis input value (positive = up, negative = down)
   //!
   //! This method converts the continuous x and y inputs into discrete directional
   //! button states based on the axis with the greater magnitude. Only one direction
   //! can be active at a time (up, down, left, or right).
   virtual void update(const float x, const float y)
   {
      clearEvents();
 
      int dpad = -1;
      if (abs(y) > abs(x)) // y wins, dpad is up/down or nothing
      {
         if (y > AxisThreshold)
         {
            dpad = Up;
         }
         else if (y < -AxisThreshold)
         {
            dpad = Down;
         }
      }
      else // x wins, dpad is left/right or nothing
      {
         if (x > AxisThreshold)
         {
            dpad = Right;
         }
         else if (x < -AxisThreshold)
         {
            dpad = Left;
         }
      }
 
      setButtonState(Up, dpad == Up);
      setButtonState(Down, dpad == Down);
      setButtonState(Right, dpad == Right);
      setButtonState(Left, dpad == Left);
   }
 
   //! \brief Checks if a button was just pressed
   //! \param button The button to check
   //! \return True if the button was just pressed, false otherwise
   //!
   //! A button is considered "just pressed" if its state changed from released to pressed
   //! since the last call to update().
   virtual bool buttonPressed(const Button button) { return myButtonsChanged[button] && myButtonStates[button]; }
   //! \brief Checks if a button was just released
   //! \param button The button to check
   //! \return True if the button was just released, false otherwise
   //!
   //! A button is considered "just released" if its state changed from pressed to released
   //! since the last call to update().
   virtual bool buttonReleased(const Button button) { return myButtonsChanged[button] && !myButtonStates[button]; }
 
   //! \brief Clears all button events (pressed/released flags)
   //!
   //! This method resets the state change tracking for all buttons without
   //! modifying their current pressed/released states. It is called automatically
   //! at the beginning of each update() call.
   virtual void clearEvents() { memset(&myButtonsChanged, 0, sizeof(myButtonsChanged)); }
 
private:
   //! \brief Sets the state of a specific button
   //! \param button The button to set the state for
   //! \param state True for pressed, false for released
   //!
   //! This method updates the button state and tracks state changes.
   //! If the new state is different from the current state, the button
   //! is marked as changed.
   virtual void setButtonState(const Button button, bool state)
   {
      if (myButtonStates[button] != state)
      {
         myButtonStates[button] = state;
         myButtonsChanged[button] = true;
      }
   }
 
   //! \brief Current state of each button (true = pressed, false = released)
   bool myButtonStates[4];
 
   //! \brief Tracks whether each button state has changed since last update
   bool myButtonsChanged[4];
};