vreRtdGlobal.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreRtdGlobal.h
//! \ingroup vreVrfRtd
//! \brief Global singleton manager for VREngage RTD components
//!
//! This file defines the DtVreRtdGlobal class, which provides global state management
//! and coordination for the VREngage Real-Time Dynamics (RTD) system. It manages the
//! RTD world, event callbacks, terrain queries, and message logging.
 
#pragma once
 
#include <RTD/World.h>
#include <vreVrfRtd/vreRtdBackendLibCommon.h>
 
class DtCgf;
class DtScenario;
 
namespace vreRtd
{
 
//! \brief Message forwarding listener from RTD to VRF Sim
//!
//! This class is responsible for forwarding messages from the RTD system
//! to the VRF simulation environment, ensuring proper logging and message
//! display in the user interface.
class RTD_VRF_BACKEND_PLUGIN_EXPORT DtVreRtdPrinterListener : public smPrinter::Listener
{
public:
   //! \brief Default constructor
   DtVreRtdPrinterListener() = default;
 
   //! \brief Default destructor
   ~DtVreRtdPrinterListener() = default;
 
   //! \brief Converts MAK notification level to RTD notification level
   //! \param nl The MAK notification level to convert
   //! \return The equivalent RTD notification level
   //!
   //! Translates between the MAK notification levels and the RTD notification
   //! levels to ensure consistent severity mapping in log messages.
   static smPrinter::NotifyLevel makNotifyLevelToRTD(int nl);
 
   //! \brief Prints a message to the RTD logging system
   //! \param msg The message to print
   //!
   //! Forwards a message to the RTD logging system with default severity.
   virtual void print(const std::string& msg) override;
 
   //! \brief Prints a message to the RTD logging system
   //! \param msg The message to print
   //!
   //! Forwards a message to the RTD logging system with default severity.
   virtual void print(const char* msg) override;
 
   //! \brief Prints a message to the RTD logging system with specified severity
   //! \param notLevel The notification level (severity) of the message
   //! \param msg The message to print
   //!
   //! Forwards a message to the RTD logging system with the specified severity level.
   virtual void print(smPrinter::NotifyLevel notLevel, const std::string& msg) override;
 
   //! \brief Prints a message to the RTD logging system with specified severity
   //! \param notLevel The notification level (severity) of the message
   //! \param msg The message to print
   //!
   //! Forwards a message to the RTD logging system with the specified severity level.
   virtual void print(smPrinter::NotifyLevel notLevel, const char* msg) override;
};
 
//! \brief Global singleton manager for VREngage RTD components
//!
//! This singleton class provides global state management and coordination for
//! the VREngage Real-Time Dynamics (RTD) system. It manages the RTD world object,
//! scenario event callbacks, configuration settings, and message logging.
class RTD_VRF_BACKEND_PLUGIN_EXPORT DtVreRtdGlobal
{
public:
   //! \brief Initializes the RTD plugin library
   //!
   //! Performs one-time initialization of the RTD plugin library, setting up
   //! global resources and configurations. This should be called once during
   //! application startup before using any RTD functionality.
   static void pluginLibInit();
 
   //! \brief Gets the singleton instance of the global RTD manager
   //! \return Pointer to the singleton instance
   //!
   //! Returns the singleton instance of the global RTD manager, creating it
   //! if it doesn't already exist. This is the proper way to access the global RTD state.
   static DtVreRtdGlobal* getInstance();
 
   //! \brief Constructor
   //!
   //! Initializes a new instance of the global RTD manager. Normally this should
   //! not be called directly - use getInstance() instead to access the singleton instance.
   DtVreRtdGlobal();
 
   //! \brief Resets the global RTD state
   //!
   //! Resets the global RTD state to its initial configuration, clearing any
   //! existing world state but preserving the RTD world object itself.
   void reset();
 
   //! \brief Destroys the global RTD manager
   //!
   //! Completely destroys the global RTD manager and all its resources,
   //! including the RTD world object. This should be called during
   //! application shutdown to ensure proper cleanup.
   void destroy();
 
   //! \brief Resets the RTD world
   //!
   //! Resets just the RTD world to its initial state, clearing all simulation
   //! objects but preserving the world configuration.
   void resetRTDWorld();
 
   //! \brief Destroys the RTD world
   //!
   //! Completely destroys the RTD world and all its resources. This is more
   //! thorough than resetRTDWorld() and requires the world to be recreated
   //! before it can be used again.
   void destroyRTDWorld();
 
   //! \brief Initializes the scenario event callbacks
   //!
   //! Sets up the callback functions that link the VRF scenario lifecycle events
   //! (load, run, reset) to the appropriate RTD system responses.
   void initializeCallbacks();
 
   //! \brief Static callback for scenario rollback events
   //! \param data User data passed by the callback system
   //!
   //! Static callback function invoked before a scenario is rolled back.
   //! Routes the callback to the processPreScenarioRollbackCallback method.
   static void preScenarioRollbackCallback(void* data);
 
   //! \brief Processes a scenario rollback event
   //!
   //! Handles the pre-scenario rollback event, preparing the RTD system
   //! for the scenario to be rolled back to a previous state.
   virtual void processPreScenarioRollbackCallback();
 
   //! \brief Static callback for scenario load events
   //! \param scenario The scenario being loaded
   //! \param data User data passed by the callback system
   //!
   //! Static callback function invoked before a scenario is loaded.
   //! Routes the callback to the processPreLoadScenario method.
   static void preLoadScenarioCallback(DtScenario& scenario, void* data);
 
   //! \brief Processes a scenario load event
   //!
   //! Handles the pre-load scenario event, preparing the RTD system
   //! for a new scenario to be loaded.
   virtual void processPreLoadScenario();
 
   //! \brief Static callback after scenario load completes
   //! \param scenario The scenario that was loaded
   //! \param data User data passed by the callback system
   //!
   //! Static callback function invoked after a scenario is loaded.
   //! Routes the callback to the processPostLoadScenario method.
   static void postLoadScenarioCallback(const DtScenario& scenario, void* data);
 
   //! \brief Processes post-scenario load event
   //!
   //! Handles the post-load scenario event, finalizing RTD setup
   //! after a new scenario has been loaded.
   virtual void processPostLoadScenario();
 
   //! \brief Static callback for scenario run events
   //! \param data User data passed by the callback system
   //!
   //! Static callback function invoked when a scenario starts running.
   //! Routes the callback to the processScenarioRunCallback method.
   static void scenarioRunCallback(void* data);
 
   //! \brief Processes a scenario run event
   //!
   //! Handles the scenario run event, preparing the RTD system
   //! to begin active simulation.
   virtual void processScenarioRunCallback();
 
   //! \brief Gets the RTD world object
   //! \return Pointer to the RTD world
   //!
   //! Returns the current RTD world object being used for simulation.
   RTD::World* rtdWorld() { return myRtdWorld; }
 
   //! \brief Gets the RTD world object (const version)
   //! \return Const pointer to the RTD world
   //!
   //! Returns the current RTD world object being used for simulation.
   RTD::World* rtdWorld() const { return myRtdWorld; }
 
   //! \brief Sets the RTD world object
   //! \param val The new RTD world object
   //!
   //! Sets the RTD world object to be used for simulation.
   void setRtdWorld(RTD::World* val) { myRtdWorld = val; }
 
   //! \brief Gets the CGF object (const version)
   //! \return Const pointer to the CGF object
   //!
   //! Returns the current CGF (Computer Generated Forces) object.
   DtCgf* cgf() const { return myCgf; }
 
   //! \brief Gets the CGF object
   //! \return Pointer to the CGF object
   //!
   //! Returns the current CGF (Computer Generated Forces) object.
   DtCgf* cgf() { return myCgf; }
 
   //! \brief Sets the CGF object
   //! \param val The new CGF object
   //!
   //! Sets the CGF (Computer Generated Forces) object to be used.
   void setCgf(DtCgf* val) { myCgf = val; }
 
   //! \brief Gets the default RTD fixed delta time (const version)
   //! \return The default fixed delta time value
   //!
   //! Returns the default fixed delta time (in seconds) used for RTD simulation steps.
   smDouble defaultRtdFixedDeltaTime() const { return myDefaultRtdFixedDeltaTime; }
 
   //! \brief Gets the default RTD fixed delta time
   //! \return The default fixed delta time value
   //!
   //! Returns the default fixed delta time (in seconds) used for RTD simulation steps.
   smDouble defaultRtdFixedDeltaTime() { return myDefaultRtdFixedDeltaTime; }
 
   //! \brief Sets the default RTD fixed delta time
   //! \param val The new default fixed delta time value
   //!
   //! Sets the default fixed delta time (in seconds) used for RTD simulation steps.
   void setDefaultRtdFixedDeltaTime(smDouble val) { myDefaultRtdFixedDeltaTime = val; }
 
   //! \brief Checks if terrain queries are blocking (const version)
   //! \return True if terrain queries are blocking, false otherwise
   //!
   //! Returns whether terrain queries are set to block until completed.
   bool isTerrainQueryBlocking() const { return myTerrainQueryBlocking; }
 
   //! \brief Checks if terrain queries are blocking
   //! \return True if terrain queries are blocking, false otherwise
   //!
   //! Returns whether terrain queries are set to block until completed.
   bool isTerrainQueryBlocking() { return myTerrainQueryBlocking; }
 
   //! \brief Sets whether terrain queries are blocking
   //! \param val True to make terrain queries blocking, false for non-blocking
   //!
   //! Sets whether terrain queries should block until completed or
   //! operate asynchronously.
   void setTerrainQueryBlocking(bool val) { myTerrainQueryBlocking = val; }
 
   //! \brief Gets the printer listener (const version)
   //! \return Const pointer to the printer listener
   //!
   //! Returns the current printer listener used for message forwarding.
   vreRtd::DtVreRtdPrinterListener* printerListener() const { return myListener; }
 
   //! \brief Gets the printer listener
   //! \return Pointer to the printer listener
   //!
   //! Returns the current printer listener used for message forwarding.
   vreRtd::DtVreRtdPrinterListener* printerListener() { return myListener; }
 
   //! \brief Sets the printer listener
   //! \param val The new printer listener
   //!
   //! Sets the printer listener to be used for message forwarding.
   void setPrinterListener(vreRtd::DtVreRtdPrinterListener* val) { myListener = val; }
 
protected:
   //! \brief Singleton instance of the global RTD manager
   static DtVreRtdGlobal* theRtdGlobalInstance;
 
   //! \brief The RTD world object
   RTD::World* myRtdWorld;
 
   //! \brief Flag indicating whether terrain queries are blocking
   bool myTerrainQueryBlocking;
 
   //! \brief Pointer to the CGF object
   DtCgf* myCgf;
 
   //! \brief Default fixed delta time for RTD simulation steps
   smDouble myDefaultRtdFixedDeltaTime;
 
   //! \brief Printer listener for message forwarding
   DtVreRtdPrinterListener* myListener;
};
 
} // namespace vreRtd