playerStationStateManager.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file playerStationStateManager.h
//! \brief Defines the DtPlayerStationStateManager class for managing application states
//!
//! This class implements a state stack manager for VR-Engage, providing functionality
//! for registering states, managing state transitions, and maintaining a stack of
//! active states. It uses a queue-based approach to ensure orderly state changes.
 
#pragma once
 
#include "vrePlayerStation/export.h"
 
#include <list>
#include <map>
#include <deque>
#include <tuple>
#include <string>
#include <memory>
 
namespace makVre
{
//! \brief Forward declaration of the player station application class
class DtPlayerStationApp;
 
//! \brief Forward declaration of the player station state class
class DtPlayerStationState;
 
//! \brief Forward declaration of the player station state arguments class
class DtPlayerStationStateArgs;
 
//! \brief Manager for player station states and state transitions
//!
//! DtPlayerStationStateManager provides a robust state management system for VR-Engage.
//! It maintains a stack of states and handles transitions between them in a controlled
//! manner. State operations are queued and processed during the tick cycle to ensure
//! proper ordering and prevent state inconsistencies.
class PLAYERSTATION_DLL DtPlayerStationStateManager
{
public:
   //! \brief Type definition for the state stack
   using DtStateList = std::list<DtPlayerStationState*>;
 
   //! \brief Type definition for the map of registered states
   using DtRegisteredStates = std::map<std::string, DtPlayerStationState*>;
 
   //! \brief Enumeration of possible stack operations
   enum DtStackOp
   {
      NO_OP,         //!< No operation
      OP_PUSH,       //!< Push a new state onto the stack
      OP_TRANSITION, //!< Replace the current state
      OP_POP,        //!< Pop the top state from the stack
      OP_POP_UNTIL   //!< Pop states until a specific state is at the top
   };
 
   //! \brief Type definition for a queued state operation
   //! Contains operation type, state name, and arguments
   using DtQueuedOp = std::tuple<DtStackOp, std::string, std::shared_ptr<DtPlayerStationStateArgs>>;
 
   //! \brief Type definition for the queue of state operations
   using DtStackOpQueue = std::deque<DtQueuedOp>;
 
   //! \brief Deleted copy constructor
   //!
   //! Prevents copying of the state manager instance
   DtPlayerStationStateManager(const DtPlayerStationStateManager&) = delete;
 
   //! \brief Deleted assignment operator
   //!
   //! Prevents assignment of the state manager instance
   DtPlayerStationStateManager& operator=(const DtPlayerStationStateManager&) = delete;
 
   //! \brief Registers a new state with the manager
   //! \param state Pointer to the state to register
   //!
   //! Adds a state to the internal map of registered states, making it
   //! available for transitions. The state name is used as the key.
   virtual void registerState(DtPlayerStationState* state);
 
   //! \brief Main tick function called from the player station tick
   //! \param dt Delta time since the last tick in seconds
   //!
   //! Processes any queued state operations and calls the tick method
   //! of the current active state. State operations are processed in
   //! the order they were queued.
   virtual void tick(double dt);
 
   //! \brief Queues a state to push onto the stack
   //! \param state Name of the state to push
   //! \param args Optional arguments to pass to the state
   //!
   //! The pushed state becomes the new active state, but the previous
   //! state remains on the stack. When the new state is later popped,
   //! the previous state will become active again.
   virtual void push(const std::string& state, DtPlayerStationStateArgs* args = NULL);
 
   //! \brief Queues a state to transition from the current active state
   //! \param state Name of the state to transition to
   //! \param args Optional arguments to pass to the new state
   //!
   //! Replaces the current active state with the new state. The previous
   //! state is removed from the stack and its exit method is called.
   virtual void transition(const std::string& state, DtPlayerStationStateArgs* args = NULL);
 
   //! \brief Queues an operation to pop the active state off the stack
   //!
   //! Removes the current active state from the stack and makes the
   //! state below it the new active state. If there is no state
   //! below, the stack will be empty after this operation.
   virtual void pop();
 
   //! \brief Queues an operation to pop states until a specific state is exposed
   //! \param state Name of the state to expose
   //! \param args Optional arguments to pass to the exposed state
   //!
   //! Pops states from the stack until the specified state becomes the
   //! active state. If the state is not in the stack, this will result
   //! in an empty stack.
   virtual void popUntil(const std::string& state, DtPlayerStationStateArgs* args = NULL);
 
   //! \brief Gets a state by its name
   //! \param state Name of the state to retrieve
   //! \return Pointer to the state, or NULL if not found
   //!
   //! Looks up a registered state by its name and returns a pointer to it.
   //! Returns NULL if the state is not registered.
   DtPlayerStationState* getState(const std::string& state);
 
   //! \brief Gets the currently active state
   //! \return Pointer to the current active state, or NULL if no state is active
   //!
   //! Returns the state at the top of the stack, which is the currently
   //! active state. Returns NULL if the stack is empty.
   virtual DtPlayerStationState* currentState();
 
   //! \brief Checks if a specific state type is in the stack
   //! \param state Name of the state to check for
   //! \return True if the state is in the stack, false otherwise
   //!
   //! Searches the state stack for a state with the specified name.
   //! Returns true if found, false otherwise.
   virtual bool containsStateType(const std::string& state);
 
   //! \brief Finds the position of a state in the stack
   //! \param state Name of the state to find
   //! \return Zero-based position in the stack, or -1 if not found
   //!
   //! Searches for a state in the stack and returns its position.
   //! Position 0 is the bottom of the stack, with higher indices moving toward the top.
   //! Returns -1 if the state is not in the stack.
   int findStackPos(const std::string& state);
 
   //! \brief Dumps the contents of the operation queue for debugging
   //!
   //! Outputs the current contents of the operation queue to the debug log,
   //! showing each pending operation and its associated state and arguments.
   const void debugDumpDeque();
 
   //! \brief Debug callback function
   //!
   //! Called during debugging to allow inspection of the state manager
   virtual void debugCallback();
 
protected:
   // These classes can access protected members and methods
   friend class DtPlayerStationApp;
   friend class DtVreDebugManager;
 
   //! \brief Constructor
   //! \param app Reference to the player station application
   //!
   //! Initializes the state manager with a reference to the app.
   //! Constructor is protected to ensure only DtPlayerStationApp can create instances.
   DtPlayerStationStateManager(DtPlayerStationApp& app);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up any remaining states and resources
   virtual ~DtPlayerStationStateManager();
 
   //! \brief Performs a state transition operation
   //! \param toState Name of the state to transition to
   //! \param args Pointer to arguments for the new state
   //!
   //! Internal implementation for transitioning from the current state
   //! to a new state. Calls exit on the old state and enter on the new state.
   void doTransition(const std::string& toState, const DtPlayerStationStateArgs* args);
 
   //! \brief Performs a pop operation on the state stack
   //! \param args Optional arguments to pass to the newly exposed state
   //!
   //! Internal implementation for popping the top state off the stack.
   //! Calls exit on the popped state and resume on the newly exposed state.
   void doPop(const DtPlayerStationStateArgs* args = NULL);
 
   //! \brief Performs a push operation on the state stack
   //! \param newState Name of the state to push
   //! \param args Pointer to arguments for the new state
   //!
   //! Internal implementation for pushing a new state onto the stack.
   //! Calls pause on the current state and enter on the new state.
   void doPush(const std::string& newState, const DtPlayerStationStateArgs* args);
 
   //! \brief Performs a popUntil operation on the state stack
   //! \param exposeState Name of the state to expose
   //! \param args Pointer to arguments for the exposed state
   //!
   //! Internal implementation for popping states until a specific state is exposed.
   //! Calls exit on all popped states and resume on the newly exposed state.
   void doPopUntil(const std::string& exposeState, const DtPlayerStationStateArgs* args);
 
   //! \brief Checks if a state is registered
   //! \param state Name of the state to check
   //! \return True if the state is registered, false otherwise
   //!
   //! Internal function that verifies if a state with the given name
   //! is registered in the state manager.
   bool isRegistered(const std::string& state);
 
protected:
   //! \brief The state stack
   //!
   //! Contains the currently active states with the most recent at the front
   DtStateList myStateStack;
 
   //! \brief Map of all registered states
   //!
   //! Maps state names to their corresponding state objects
   DtRegisteredStates myRegisteredStates;
 
   //! \brief Reference to the player station application
   //!
   //! Provides access to the application for states that need it
   DtPlayerStationApp& myApp;
 
   //! \brief Queue of pending state operations
   //!
   //! Contains operations to be processed during the next tick,
   //! each with an operation type, state name, and arguments
   DtStackOpQueue myStackOpQueue;
};
} // namespace makVre