DtVirtualRealityControllerState.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file DtVirtualRealityControllerState.h
//! \brief Defines a class that encapsulates the state of a VR controller
//! \ingroup vrvVirtualRealityController
//!
//! This file contains the definition of the DtVirtualRealityControllerState class,
//! which represents the complete state of a VR controller at a specific point in time.
//! This includes its position, orientation, button states, touch states, and analog
//! input values. The class also tracks which aspects of the controller state have
//! changed since the last update cycle.
 
#pragma once
 
#include <vrvVirtualRealityController/vrvVirtualRealityController.h>
 
#include <vrvUtil/DtQuat.h>
#include <vrvMath/DtVector2.h>
 
#include <matrix/vlVector.h>
 
namespace makVrv
{
//! \brief Encapsulates the complete state of a virtual reality controller
//!
//! This class represents the state of a VR controller at a specific point in time,
//! including its position, orientation, button states, touch states, and analog
//! input values. It also tracks which aspects of the controller state have changed
//! since the last update cycle, making it easier for event handlers to respond
//! to specific types of input events (e.g., button presses, controller movements).
class DT_DLL_VRVVRCTLR DtVirtualRealityControllerState
{
public:
   //! \brief Type used for bit flags throughout the class
   //!
   //! This type is used for representing sets of buttons, touch surfaces,
   //! or axes as bit flags, where each bit corresponds to a specific item.
   using Bitfield = unsigned long long;
 
   //! \brief Type used for controller identification
   //!
   //! This type is used to uniquely identify controllers in the VR system.
   using ControllerId = unsigned int;
 
   //! \brief Type used for 2D vector values
   //!
   //! This type is used for representing 2D analog input values, such as
   //! thumbstick or touchpad positions.
   using DtVector2f = DtVector2<float32>;
 
   //! \brief Special value indicating no controller ID
   //!
   //! This constant is used to indicate that a controller ID is not set or
   //! not applicable in the current context.
   static const ControllerId NoId = ControllerId(-1);
 
   //! \brief Non-exclusive controller device properties
   enum DeviceType
   {
      Type_Undefined = 0,
      Type_Left = 1 << 1,          // Controller is associated with left hand
      Type_Right = 1 << 2,         // Associated with right hand
      Type_Tracked = 1 << 3,       // Position/orientation is tracked
      Type_Input = 1 << 4,         // Indicates a controller with buttons, touch and/or axes
      Type_HMD = 1 | Type_Tracked, // Only ever one HMD, not left nor right, is tracked, no input
      Type_LeftHand = Type_Left | Type_Input | Type_Tracked,   // Indicates left hand controller
      Type_RightHand = Type_Right | Type_Input | Type_Tracked, // Indicates right hand controller
   };
 
   //! \brief Unique known button IDs; controller may have additional buttons
   enum ButtonId
   {
      Button_System = 1 << 0,
      Button_Menu = 1 << 1,
      Button_Trigger = 1 << 2,
      Button_Grip = 1 << 3,
      Button_A = 1 << 4,
      Button_B = 1 << 5,
      Button_Thumb = 1 << 6,
      Button_Left = 1 << 7,
      Button_Up = 1 << 8,
      Button_Right = 1 << 9,
      Button_Down = 1 << 10,
   };
 
   //! \brief Unique known touch surface IDs; controller may have additional surfaces
   enum TouchId
   {
      Touch_Trigger = 1 << 0,
      Touch_Grip = 1 << 1,
      Touch_A = 1 << 2,
      Touch_B = 1 << 3,
      Touch_Thumb = 1 << 4,
   };
 
   //! \brief Unique known axis IDs; controller may have additional axes
   enum AxisId
   {
      Axis_Thumb = 0,
      Axis_Trigger = 1,
      Axis_Grip = 2,
      Axis_3 = 3,
      Axis_4 = 4,
   };
 
   //! \brief Gets the maximum number of analog axes supported by the system
   //! \return Maximum number of supported axes
   //!
   //! Returns the maximum number of analog axes that can be tracked for a controller.
   //! Not all controllers will have this many axes, but the system allocates
   //! space for this many to accommodate all supported controller types.
   static unsigned int MaxAxes();
 
   //! \brief Converts an integer to the corresponding bit in a bitfield
   //! \param n The bit position (0-63)
   //! \return A bitfield with only the nth bit set
   //!
   //! This convenience function converts an integer n to a bitfield with
   //! only the nth bit set (equivalent to 1 << n). This is useful for
   //! working with the various bitfields used throughout this class.
   static Bitfield bit(unsigned int n);
 
   //! \brief Overall status of this controller.
   //!
   //! The first time a controller is added to the map, the event
   //! type will be ControllerDiscovered, and all change flags will be true.
   //! When a controller is lost, it will appear for one more event with
   //! type ControllerLost, with the last known state. All change flags
   //! will be false, and the controller will be removed from the map
   //! after the event is processed.
   //!
   //! During normal operation, the event type for a controller will be
   //! either NoEvent or StateChanged, indicating whether there has been
   //! any change in the state of this controller. If event type is
   //! StateChanged, individual change flags can be used to determine
   //! what component or components have changed since the last event cycle.
   enum ControllerEventType
   {
      NoEvent = 0,
      ControllerDiscovered,
      ControllerLost,
      StateChanged
   };
 
   //! \brief Default constructor
   //!
   //! Initializes a new controller state with default values. The controller
   //! ID is set to NoId, event type is set to NoEvent, and all state values
   //! and change flags are initialized to zero/false.
   DtVirtualRealityControllerState();
 
   //! \brief Copy constructor
   //! \param orig The controller state to copy
   //!
   //! Creates a new controller state that is a copy of the original.
   DtVirtualRealityControllerState(const DtVirtualRealityControllerState& orig);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up any resources associated with the controller state.
   virtual ~DtVirtualRealityControllerState();
 
   //! \brief Assignment operator
   //! \param rhs The controller state to copy
   //! \return Reference to this object after assignment
   //!
   //! Assigns the contents of another controller state to this one.
   DtVirtualRealityControllerState& operator=(const DtVirtualRealityControllerState& rhs);
 
   //! \brief Unique integer identifier for this VR Controller device
   virtual ControllerId controllerId() const;
   virtual void setControllerId(ControllerId);
 
   //! \brief Bitfield of controller DeviceType properties
   virtual Bitfield controllerType() const;
   virtual void setControllerType(Bitfield);
 
   //! \brief Current position of this controller.
   //! This is an East-North-Up coordinate system with respect to the observer.
   virtual DtVector position() const;
   virtual void setPosition(const DtVector& pos);
 
   //! \brief Current orientation of this controller.
   //! This is an East-North-Up coordinate system with respect to the observer.
   virtual DtQuat orientation() const;
   virtual void setOrientation(const DtQuat& ori);
 
   //! \brief Bitfield of all the button states of the controller.
   //! Each bit represents a button state, as 1 << buttonId.
   //! See ButtonId enum for known button IDs.
   virtual Bitfield buttonStates() const;
   virtual void setButtonStates(Bitfield buttonStates);
 
   //! \brief Get an individual button state by unique buttonId.
   //! true == button down, buttonId must be < number of bits in long long.
   virtual bool buttonState(ButtonId buttonId) const;
   virtual void setButtonState(ButtonId buttonId, bool down);
 
   //! \brief Bitfield of all the touch surface states of the controller.
   //! Each bit represents a surface state, as 1 << touchId.
   //! See TouchId enum for known touch surface IDs.
   virtual Bitfield touchStates() const;
   virtual void setTouchStates(Bitfield touchStates);
 
   //! \brief Get an individual surface state by unique touchId.
   //! true == touched, touchId must be < number of bits in long long.
   virtual bool touchState(TouchId touchId) const;
   virtual void setTouchState(TouchId touchId, bool touched);
 
   //! \brief Returns the current values of a given axis.
   //! All axes are 2-dimensional, though some only use one, usually x.
   //! Values will be 0,0 if this controller does not have the given axis.
   //! See AxisId enum for known axes; axisId must be < MaxAxes().
   virtual DtVector2f axisPosition(AxisId axisId) const;
   virtual void setAxisPosition(AxisId axisId, const DtVector2f& value);
 
   //! \brief Returns the dead-zone values of a given axis.
   //! Dead-zones are defined independently for x and y axis components.
   //! Default dead-zone values are 0.01 for both dimensions.
   //! See AxisId enum for known axes; axisId must be < MaxAxes().
   virtual DtVector2f axisDeadZone(AxisId axisId) const;
   virtual void setAxisDeadZone(AxisId axisId, const DtVector2f& value);
 
   //! \brief Marks this controller as lost; event type is set to
   //! ControllerLost. Is is expected that this controller state will be
   //! deleted after the event processor has processed this final state.
   virtual void setControllerAsLost();
   virtual bool controllerWasLost() const;
 
   //! \brief Returns a bitfield identifying all the buttons which
   //! have changed since the last event cycle. Each bit represents a
   //! button that changed, as 1 << buttonId.
   //! See enum ButtonId for known button IDs.
   virtual Bitfield buttonsChanged() const;
 
   //! \brief Returns whether a particular button with specified ID
   //! has changed state since the last event cycle.
   virtual bool buttonChanged(ButtonId buttonId) const;
 
   //! \brief Returns whether the button with specified ID was
   //! pressed/released since the last event cycle.
   virtual bool buttonPressed(ButtonId buttonId) const;
   virtual bool buttonReleased(ButtonId buttonId) const;
 
   //! \brief Returns a bitfield identifying all the surfaces which
   //! have changed touch state since the last event cycle. Each bit
   //! represents a touch surface that changed, as 1 << touchId.
   //! See enum TouchId for known button IDs.
   virtual Bitfield touchChanged() const;
 
   //! \brief Returns whether a particular surface with specified ID
   //! has changed touch state since the last event cycle.
   virtual bool touchChanged(TouchId touchid) const;
 
   //! \brief Returns whether the specified touch surface was
   //! touched or un-touched since the last event cycle.
   virtual bool touchStarted(TouchId touchId) const;
   virtual bool touchEnded(TouchId touchId) const;
 
   //! \brief Returns bitfield identifying all axes which have changed
   //! since the last event cycle. Each bit represents an axis, as
   //! 1 << axisId. See enum AxisId for known axes.
   virtual Bitfield axesChanged() const;
 
   //! \brief Returns whether a particular axis with specified ID
   //! has had a value changed since the last event cycle.
   virtual bool axisChanged(AxisId axisId) const;
 
   //! \brief Returns whether there has been any change to the
   //! tracked position or orientation of this controller since the
   //! last event cycle.
   virtual bool controllerMoved() const;
 
   //! \brief Returns ControllerEventType describing the state
   //! of this controller after the most recent update.
   virtual ControllerEventType controllerEvent() const;
 
   //! \brief Resets all change flags to 0/false and event type to NoEvent.
   //! This should be called after the event processor has processed the
   //! current state of events, before this controller state is updated.
   virtual void clearEvent();
 
protected:
   // Called by all component set functions to indicate that the
   // controller state has changed. If myEventType is NoEvent,
   // it will be set to StateChanged.
   inline virtual void markStateChanged();
 
   // Properties of this controller, which should not change
   //-------------------------------------------------------
   ControllerId myControllerId; // unique id
   Bitfield myControllerType;   // bitfield of DeviceType(s)
 
   // Current state of this controller
   //---------------------------------
   DtVector myPosition;
   DtQuat myOrientation;
 
   Bitfield myButtonStates; // bitfield
   Bitfield myTouchStates;  // bitfield
 
   std::vector<DtVector2f> myAxisStates;
   std::vector<DtVector2f> myAxisDeadZones;
 
   // Flags indicating a change in state
   //-----------------------------------
   ControllerEventType myEventType;
 
   Bitfield myButtonsChanged;
   Bitfield myTouchChanged;
   Bitfield myAxesChanged;
   bool myControllerMoved;
};
} // namespace makVrv