debugManager.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
#pragma once
 
//! \file debugManager.h
//! \ingroup vreDebugManager
//! \brief Contains the debug manager class declaration for the VREngage system.
//!
//! This file defines the DtVreDebugManager class which is the central interface for all
//! debugging functionality in VREngage. It controls debug rendering, menu system, and
//! debug message passing throughout the application.
//!
//! This file defines the DtVreDebugManager class, which is the primary interface
//! for managing debug functionality in VR-Engage. It provides access to the debug renderer,
//! debug menu configuration, and other debugging utilities.
 
#include "vreDebugManager/export.h"
#include "vreMessageManager/vreMessage.h"
#include "vreUtil/delegate.h"
#include "vreUtil/attribute.h"
 
#include <list>
 
//! \brief The DtVreDebugManager is the primary interface to and manager of all of the
//! debug aspects of VR-Engage.
//!
//! The primary purpose of this class is to provide a singular interface for
//! functions to access several aspects of debugging VR-Engage through IMGui.
//! You can access the debug renderer, the state manager, etc. You register for a callback
//! and then when the tab is live, the callback will be invoked.
//!
//! See the exampleDebugPlugin for implementation examples.
//!
//! \note Application developers will want to ensure that any additions or subtractions
//! to the physical elements in the environment, at a structural level, are accounted
//! for in this class's interface. For instance, if a new type of terrain element
//! is added to the simulation, such as an implicit surface instead of a polygon,
//! the queries of this class must be updated.
 
class DtSimulationAddress;
 
namespace makVrv
{
class DtDe;
}
 
namespace makVre
{
// Forward Declares
class DtDebugRenderer;
struct DtVreDebugMenuConfiguration;
class DtInitializer;
class DebugMetaRegisterMessage;
 
//! Defines the position where callbacks are registered in the callback list
enum class CallbackPosition
{
   FRONT = 0, //!< Add callback to the front of the list (executed first)
   BACK       //!< Add callback to the back of the list (executed last)
};
 
// Typedefs
using DtVreDebugMenuCallback = DtDelegate<void>;
using DebugMenuCallbackList = std::list<DtVreDebugMenuCallback>;
using DebugConfigurationValue = std::pair<DtVreDebugMenuConfiguration, DebugMenuCallbackList>;
using DebugMenuConfigurationMap = std::map<std::string, DebugConfigurationValue>;
 
using DtVreDebugEnabledCallback = DtDelegate<void, bool>;
using DebugEnabledCallbackList = std::list<DtVreDebugEnabledCallback>;
 
//! \brief Configuration structure for debug processes
//!
//! Contains the necessary information to configure and identify a debug process
//! within the VREngage debug system.
struct DEBUGMANAGER_DLL DtConfigurableDebugProcess
{
   //! \brief Enumeration of process types that can be debugged
   enum class Process
   {
      VRE_APP = 0, //!< VREngage application process
      VRF_APP,     //!< VRForces application process
      VRE_SIM,     //!< VREngage simulation process
      VRF_SIM      //!< VRForces simulation process
   };
 
   //! \brief Display name of the debug process
   std::string displayName;
   //! \brief Type identifier for the debug process
   std::string debugType;
   //! \brief Menu section where this process should appear
   std::string menuSection;
   //! \brief Type of process (VREngage or VRForces, app or sim)
   Process process;
   //! \brief Simulation address for this debug process
   DtSimulationAddress address;
   //! \brief Whether the debug process is enabled
   bool enabled;
   //! \brief Whether to show this process in the debug table
   bool showInTable;
   //! \brief Additional data associated with this debug process
   DtAttributeHandle extraData;
};
 
//! \brief Configuration structure for debug menus
//!
//! Contains the necessary information to configure a debug menu section
//! within the VREngage debug UI system.
struct DEBUGMANAGER_DLL DtVreDebugMenuConfiguration
{
   //! \brief Description of this debug menu section
   std::string description;
   //! \brief List of configurable debug processes in this menu section
   std::vector<DtConfigurableDebugProcess> configurableOptions;
 
   //! \brief Default constructor that initializes with empty values
   DtVreDebugMenuConfiguration()
      : description("")
      , configurableOptions({})
   {
   }
};
 
//! \brief Main debug manager class for VREngage
//!
//! This singleton class provides the central interface for all debugging
//! functionality in VREngage, including menu management, debug rendering,
//! and debug message passing throughout the application.
class DEBUGMANAGER_DLL DtVreDebugManager
{
public:
   //! \brief Gets the singleton debug manager instance
   //! \return Pointer to the singleton instance
   static DtVreDebugManager* instance();
 
   //! \brief Installs the full debug system with rendering capabilities
   //! \param de The graphics engine to attach the debug renderer to
   static void installFull(makVrv::DtDe&);
 
   //! \brief Installs a lightweight version of the debug system without rendering
   //!
   //! Use this when no graphics engine is available but debugging is still required
   static void installLite();
 
   //! \brief Cleans up and shuts down the debug system
   //!
   //! Releases all resources and destroys the singleton instance
   static void shutdown();
 
   //! \brief Registers a callback for a specific debug menu section
   //!
   //! The callback will be invoked when the specified debug menu section is active
   //! \param sec The section name to register the callback for
   //! \param cb The callback function to register
   //! \param position Where to place the callback in the execution order
   //! \return True if the callback was successfully registered
   virtual bool addDebugMenuCallback(
      const std::string& sec, const DtVreDebugMenuCallback& cb, CallbackPosition position = CallbackPosition::BACK);
   //! \brief Removes a previously registered debug menu callback
   //! \param cb The callback to remove
   //! \return True if the callback was found and removed
   virtual bool removeDebugMenuCallback(const DtVreDebugMenuCallback& cb);
 
   //! \brief Registers a callback that is triggered when debug rendering is enabled/disabled
   //!
   //! This callback will be invoked when the debug rendering enabled state changes
   //! \param cb The callback function to register
   //! \param position Where to place the callback in the execution order
   //! \return True if the callback was successfully registered
   virtual bool addDebugEnabledCallback(
      const DtVreDebugEnabledCallback& cb, CallbackPosition position = CallbackPosition::BACK);
   //! \brief Removes a previously registered debug enabled callback
   //! \param cb The callback to remove
   //! \return True if the callback was found and removed
   virtual bool removeDebugEnabledCallback(const DtVreDebugEnabledCallback& cb);
 
   //! \brief Adds a new debug menu entry to the debug UI
   //! \param name The name of the menu entry
   //! \param conf The configuration for this menu entry
   virtual void addDebugMenuEntry(const std::string& name, DtVreDebugMenuConfiguration conf);
   //! \brief Removes a debug menu entry from the debug UI
   //! \param name The name of the menu entry to remove
   virtual void removeDebugMenuEntry(const std::string& name);
 
   //! \brief Gets an iterator to a debug menu configuration by name
   //! \param name The name of the menu configuration to find
   //! \return Iterator to the debug menu configuration, or end() if not found
   DebugMenuConfigurationMap::iterator getDebugMenuConfiguration(const std::string& name);
   //! \brief Gets a debug process by type and simulation address
   //! \param type The type of debug process to find
   //! \param address The simulation address of the process
   //! \param proc The found debug process configuration (output parameter)
   //! \return True if the process was found, false otherwise
   bool getDebugProcess(const std::string& type, DtSimulationAddress address, DtConfigurableDebugProcess& proc);
 
   //! \brief Draws the VREngage debug menu using ImGui
   //!
   //! This is the main drawing function that renders all registered debug UI elements.
   //! It should be called from the application's ImGui rendering pass.
   virtual void drawVrEngageDebugMenu();
 
   //! \brief Checks if the debug window is currently visible
   //! \return True if the debug window is visible
   bool isDebugWindowVisible() const;
   //! \brief Sets the visibility of the debug window
   //! \param vis True to show the window, false to hide it
   void setDebugWindowVisible(bool vis);
 
   //! \brief Checks if debug messages are being sent
   //! \return True if debug messages are enabled
   bool getSendDebugMessages() const;
   //! \brief Enables or disables sending of debug messages
   //! \param send True to enable debug messages, false to disable
   void setSendDebugMessages(bool send);
 
   //! \brief Checks if the debug system is running in lite mode
   //! \return True if running in lite mode (without rendering)
   bool isLiteMode() const;
   //! \brief Checks if the debug system is running in full mode
   //! \return True if running in full mode (with rendering)
   bool isFullMode() const;
 
   //! \brief Gets the debug initializer
   //! \return Pointer to the debug initializer
   inline DtInitializer* getDebugInitializer();
 
   //! \brief Gets the debug renderer instance
   //! \return Pointer to the debug renderer
   inline DtDebugRenderer* debugRenderer();
 
public:
   //! \brief Pushes compact ImGui style settings
   //!
   //! Modifies ImGui style to use more compact layout for debug UI elements
   static void PushStyleCompact();
   //! \brief Pops compact ImGui style settings
   //!
   //! Restores the previous ImGui style settings after PushStyleCompact()
   static void PopStyleCompact();
   //! \brief Indents the ImGui content
   //!
   //! Adds indentation to subsequent ImGui elements
   static void Indent();
   //! \brief Unindents the ImGui content
   //!
   //! Removes indentation from subsequent ImGui elements
   static void Unindent();
   //! \brief Displays a help marker with description text
   //! \param desc The description text to display in the help tooltip
   static void HelpMarker(const std::string& desc);
   //! \brief Checks if a debugger is attached to the process
   //! \param recheck Force a recheck instead of using cached value
   //! \return True if a debugger is attached
   static bool IsDebuggerAttached(bool recheck = false);
   //! \brief Creates a checkbox that displays different strings based on its state
   //! \param enabledString Text to display when checkbox is checked
   //! \param disabledString Text to display when checkbox is unchecked
   //! \param val Pointer to the boolean value controlled by the checkbox
   //! \return True if the checkbox value was changed
   static bool ConditionalCheckbox(const std::string& enabledString, const std::string& disabledString, bool* val);
 
protected:
   //! \brief Constructor for DtVreDebugManager
   //!
   //! Protected since this is a singleton class
   //! \param de Pointer to the graphics engine (can be null for lite mode)
   explicit DtVreDebugManager(makVrv::DtDe*);
 
   //! \brief Virtual destructor
   //!
   //! Handles cleanup of debug manager resources
   virtual ~DtVreDebugManager();
 
   //! \brief Copy constructor (deleted)
   DtVreDebugManager(DtVreDebugManager&) = delete;
   //! \brief Move constructor (deleted)
   DtVreDebugManager(DtVreDebugManager&&) = delete;
   //! \brief Copy assignment operator (deleted)
   DtVreDebugManager& operator=(DtVreDebugManager&) = delete;
   //! \brief Move assignment operator (deleted)
   DtVreDebugManager& operator=(DtVreDebugManager&&) = delete;
 
   //! \brief General callback for debug events
   //!
   //! Called when general debug events need to be processed
   virtual void generalCallback();
   //! \brief Simulation-specific callback for debug events
   //!
   //! Called when simulation-specific debug events need to be processed
   virtual void simCallback();
 
   //! \brief Loads debug configuration settings
   //!
   //! Initializes the debug configuration from saved settings
   virtual void loadDebugConfiguration();
 
   //! \brief Installs default debug message handlers
   //!
   //! Sets up the standard debug message handlers for the system
   virtual void installDefaultDebugMessages();
 
   //! \brief Draws the "Show VR-Engage Debug Menu" option
   //!
   //! Renders the toggle option for showing/hiding the debug menu
   void drawVrEngageDebugOption();
 
   //! \brief Handles debug metadata messages
   //! \param msg The message to process
   //! \return Result of the message handling
   DtVreMessageResult handleDebugMetaData(DtVreMessage* msg);
   //! \brief Handles debug meta enable/disable messages
   //! \param msg The message to process
   //! \return Result of the message handling
   DtVreMessageResult handleDebugMetaEnable(DtVreMessage* msg);
   //! \brief Handles debug meta registration messages
   //! \param msg The message to process
   //! \return Result of the message handling
   DtVreMessageResult handleDebugMetaRegister(DtVreMessage* msg);
   //! \brief Handles global debug enable/disable messages
   //! \param msg The message to process
   //! \return Result of the message handling
   DtVreMessageResult handleDebugGlobalEnable(DtVreMessage* msg);
 
protected:
   //! \brief Singleton instance of the debug manager
   static DtVreDebugManager* theDebugManager;
   //! \brief Pointer to the graphics engine
   makVrv::DtDe* myDe;
 
   //! \brief Map of debug menu configurations and their callbacks
   DebugMenuConfigurationMap myDebugConfigurationMap;
 
   //! \brief List of callbacks to invoke when debug is enabled/disabled
   DebugEnabledCallbackList myDebugEnabledCallbackList;
 
   //! \brief Debug renderer instance owned by the manager
   std::unique_ptr<DtDebugRenderer> myDebugRenderer;
 
   //! \brief Debug initializer instance
   std::unique_ptr<DtInitializer> myDebugInitializer;
 
   //! \brief Flag indicating if the debug window should be drawn
   bool myDrawWindow;
   //! \brief Width of indentation for ImGui elements
   float myIndentWidth;
 
   //! \brief Flag indicating if a debugger is attached to the process
   bool myDebuggerAttached;
   //! \brief Flag indicating if debug messages should be sent
   bool mySendingDebugMessages;
   //! \brief Flag indicating if running in lite mode
   bool myLiteDebugManager;
   //! \brief Flag indicating if the debug console is shown
   bool myConsoleShown;
};
} // namespace makVre
 
// Callback for safely removing callbacks.
#define DEBUG_MANAGER_REMOVE_MENU_CALLBACK(delegate)                                                                   \
   if (DtVreDebugManager::instance())                                                                                  \
   {                                                                                                                   \
      DtVreDebugManager::instance()->removeDebugMenuCallback(delegate);                                                \
   }
 
#define DEBUG_MANAGER_REMOVE_ENABLED_CALLBACK(delegate)                                                                \
   if (DtVreDebugManager::instance())                                                                                  \
   {                                                                                                                   \
      DtVreDebugManager::instance()->removeDebugEnabledCallback(delegate);                                             \
   }