playerStationState.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file playerStationState.h
//! \brief Defines base classes for the VR-Engage state management system
//!
//! This file provides the foundational classes for state management in VR-Engage:
//! - DtPlayerStationStateArgs: Used to pass arguments between states during transitions
//! - DtPlayerStationState: Base class that all application states inherit from
//!
//! States in VR-Engage are organized in a stack, with the top state being "exposed"
//! and actively controlling the application. States can be pushed, popped, and
//! transitioned between to manage application flow.
 
#pragma once
 
#include "vrePlayerStation/export.h"
 
#include "vreMessageManager/vreMessage.h"
 
// #include <memory>
 
// Helper macro for logging
#define LOG_STATE_VERBOSE LOG_VERBOSE("State")
#define LOG_STATE_INFO LOG_INFO("State")
#define LOG_STATE_WARN LOG_WARN("State")
#define LOG_STATE_FATAL LOG_FATAL("State")
 
namespace makVre
{
//! \brief Forward declaration of the player station application class
class DtPlayerStationApp;
 
//! \brief Forward declaration of the VR-Engage message class
class DtVreMessage;
 
//! \brief Class for passing arguments during state transitions
//!
//! DtPlayerStationStateArgs provides a mechanism to pass information from one state
//! to another during state transitions. It includes the source state name and
//! an optional message containing additional data.
class DtPlayerStationStateArgs
{
public:
   //! \brief Constructor with raw message pointer
   //! \param fromStateType Name of the source state
   //! \param message Optional pointer to a message with additional data
   //!
   //! Creates a state arguments object, taking ownership of the message if provided
   DtPlayerStationStateArgs(const std::string& fromStateType, DtVreMessage* message = NULL);
 
   //! \brief Constructor with shared pointer to message
   //! \param fromStateType Name of the source state
   //! \param message Shared pointer to a message with additional data
   DtPlayerStationStateArgs(const std::string& fromStateType, std::shared_ptr<DtVreMessage> message);
 
   //! \brief Gets the name of the source state
   //! \return Reference to the source state name
   const std::string& fromState() const;
 
   //! \brief Gets the message as a raw pointer
   //! \return Raw pointer to the message, or NULL if not present
   const DtVreMessage* message() const;
 
   //! \brief Gets the message as a shared pointer
   //! \return Shared pointer to the message
   std::shared_ptr<DtVreMessage> message_ptr() const;
 
private:
   //! \brief Name of the source state
   std::string myFromState;
 
   //! \brief Shared pointer to the optional message
   std::shared_ptr<DtVreMessage> myMessage;
};
 
//! \brief Base class for all VR-Engage application states
//!
//! DtPlayerStationState serves as the foundation for all application states
//! in VR-Engage. It defines the lifecycle methods that states must implement
//! to respond to state stack operations, and provides utility methods for
//! transitioning between states.
class PLAYERSTATION_DLL DtPlayerStationState
{
   // Allow the state manager direct access to private methods
   friend class DtPlayerStationStateManager;
 
public:
   //! \brief Constructor
   //! \param app Reference to the player station application
   //! \param stateType String identifier for this state type
   //!
   //! Initializes a new state with its type name and a reference to the application.
   //! States are created by the application and registered with the state manager.
   DtPlayerStationState(DtPlayerStationApp& app, std::string stateType);
 
   //! \brief Virtual destructor
   //!
   //! Ensures proper cleanup of derived state classes.
   //! Only called when VR-Engage is shutting down.
   virtual ~DtPlayerStationState();
 
   //! \brief Deleted copy constructor
   //!
   //! Prevents copying of state instances
   DtPlayerStationState(const DtPlayerStationState&) = delete;
 
   //! \brief Deleted assignment operator
   //!
   //! Prevents assignment of state instances
   DtPlayerStationState& operator=(const DtPlayerStationState&) = delete;
 
   //! \brief Called when the state is added to the stack
   //! \param args Pointer to arguments from the previous state
   //!
   //! Invoked when this state is newly added to the stack, either via push or transition.
   //! Override to perform initialization specific to this state.
   virtual void onEnter(const DtPlayerStationStateArgs* args) {};
 
   //! \brief Overloaded version without arguments
   //!
   //! Provided for convenience when no arguments are needed.
   virtual void onEnter() {};
 
   //! \brief Called when a state is added to the stack on top of this one
   //!
   //! Invoked when another state is pushed on top of this state, causing
   //! this state to become inactive but remain in the stack.
   //! Override to pause operations that should resume later.
   virtual void onStacked() {};
 
   //! \brief Called when all states above this state are removed
   //! \param args Pointer to arguments from the previous state
   //!
   //! Invoked when this state becomes the top state on the stack again
   //! after states above it are popped. Override to resume operations.
   virtual void onExposed(const DtPlayerStationStateArgs* args) {};
 
   //! \brief Overloaded version without arguments
   //!
   //! Provided for convenience when no arguments are needed.
   virtual void onExposed() {};
 
   //! \brief Called when this state is being removed from the stack
   //!
   //! Invoked just before this state is removed from the stack,
   //! either via pop or transition. Override to perform cleanup.
   virtual void onExit() {};
 
   //! \brief Main update function called while this state is active
   //! \param dt Delta time in seconds since the last tick
   //!
   //! Called once per frame while this state is in the stack.
   //! This is where most of the state's logic should be implemented.
   virtual void tick(double dt) {};
 
   //! \brief Checks if this state is currently in the stack
   //! \return True if the state is in the stack, false otherwise
   //!
   //! A state is active when it's somewhere in the state stack,
   //! regardless of whether it's the topmost state.
   bool active() const;
 
   //! \brief Checks if this state is currently the topmost state
   //! \return True if the state is at the top of the stack, false otherwise
   //!
   //! A state is exposed when it's at the top of the state stack,
   //! making it the currently controlling state in the application.
   bool exposed() const;
 
   //! \brief Checks if this state is queued to be exited
   //! \return True if the state is marked for exit, false otherwise
   //!
   //! Indicates that an operation has been queued that will remove
   //! this state from the stack during the next tick.
   bool exiting() const;
 
   //! \brief Checks if this state is queued to be stacked
   //! \return True if the state is marked for stacking, false otherwise
   //!
   //! Indicates that an operation has been queued that will push
   //! another state on top of this one during the next tick.
   bool stacking() const;
 
   //! \brief Gets the string identifier for this state's type
   //! \return Constant reference to the state type string
   //!
   //! This is the unique name used to identify and look up the state.
   const std::string& stateType() const;
 
   //! \brief Gets a reference to the player station application
   //! \return Reference to the application object
   //!
   //! Provides access to the application for states that need it.
   DtPlayerStationApp& app() const;
 
protected:
   //! \brief Pushes a new state onto the stack
   //! \param newState Name of the state to push
   //! \param args Optional arguments to pass to the new state
   //! \return True if the operation was queued successfully, false otherwise
   //!
   //! Queues an operation to push the specified state onto the stack,
   //! making it the new active state while preserving this state.
   bool pushState(const std::string& newState, DtPlayerStationStateArgs* args = NULL);
 
   //! \brief Pops this state from the stack
   //! \return True if the operation was queued successfully, false otherwise
   //!
   //! Queues an operation to remove this state from the stack,
   //! exposing the state beneath it.
   bool popSelf();
 
   //! \brief Pops states until this state is exposed
   //! \return True if the operation was queued successfully, false otherwise
   //!
   //! Queues an operation to pop all states above this one,
   //! making this state the active state.
   bool popUntilSelf();
 
   //! \brief Pops states until a specific parent state is exposed
   //! \param parentState Name of the state to expose
   //! \param args Optional arguments to pass to the exposed state
   //! \return True if the operation was queued successfully, false otherwise
   //!
   //! Queues an operation to pop states until the specified parent
   //! state is at the top of the stack.
   bool popUntilState(const std::string& parentState, DtPlayerStationStateArgs* args = NULL);
 
   //! \brief Transitions from this state to a new state
   //! \param newState Name of the state to transition to
   //! \param args Optional arguments to pass to the new state
   //! \return True if the operation was queued successfully, false otherwise
   //!
   //! Queues an operation to replace this state with the specified state.
   bool switchToState(const std::string& newState, DtPlayerStationStateArgs* args = NULL);
 
   //! \brief Pushes a copy of this state onto the stack
   //! \return True if the operation was queued successfully, false otherwise
   //!
   //! Queues an operation to push the same state type onto the stack.
   //! Note: This creates a new instance of the state class.
   bool pushSelf();
 
   //! \brief Reference to the player station application
   DtPlayerStationApp& myApp;
 
private:
   //! \brief Internal implementation of onEnter
   //! \param args Pointer to arguments from the previous state
   //!
   //! Handles common functionality for state entry, including sending
   //! an "EnterPlayerStationStateMessage", then calls the public onEnter.
   void _onEnter(const DtPlayerStationStateArgs* args);
 
   //! \brief Internal implementation of onStacked
   //!
   //! Handles common functionality when a state is stacked, then
   //! calls the public onStacked.
   void _onStacked();
 
   //! \brief Internal implementation of onExposed
   //! \param args Pointer to arguments for resuming
   //!
   //! Handles common functionality when a state becomes exposed again,
   //! then calls the public onExposed.
   void _onExposed(const DtPlayerStationStateArgs* args);
 
   //! \brief Internal implementation of onExit
   //!
   //! Handles common functionality for state exit, including sending
   //! an "ExitPlayerStationStateMessage", then calls the public onExit.
   void _onExit();
 
   //! \brief String identifier for this state's type
   std::string myStateType;
 
   //! \brief Position of this state in the stack (0 is bottom)
   int myStackPos;
 
   //! \brief Flag indicating whether this state is in the stack
   bool myActive;
 
   //! \brief Flag indicating whether this state is at the top of the stack
   bool myExposed;
 
   //! \brief Flag indicating whether a state transition is pending
   bool myExiting;
 
   //! \brief Flag indicating whether a state push is pending
   bool myStacking;
 
   //! \brief Flag indicating whether the state is currently processing
   //!
   //! Set true during event methods and tick, false otherwise.
   //! Used to manage error checking in state stack operations differently
   //! depending on whether we are in one of our event functions,
   //! or outside of them (e.g., in a message handler).
   bool myProcessing;
};
} // namespace makVre