loadingState.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file loadingState.h
//! \brief Defines the loading state for terrain and scenario data in VR-Engage
//!
//! This file contains the DtLoadingState class which manages the application state
//! during terrain and scenario loading operations. It provides a UI for displaying
//! loading progress, handles the loading sequence, and transitions to the appropriate
//! state once loading is complete.
 
#pragma once
 
#include "vrePlayerStation/export.h"
 
#include "vrePlayerStation/playerStationState.h"
 
#include <chrono>
 
#include <vreMessages/backendStatus.h>
 
namespace makArchives
{
class DtObserverStateRecordsList;
}
 
namespace makVre
{
//! \brief Forward declaration of the session load data message class
class SessionLoadDataMessage;
 
//! \brief Forward declaration of the loading page UI class
class DtVreLoadingPage;
 
//! \brief Forward declaration of the external loading page logic class
class DtVreExternalLoadingPageLogic;
 
//! \brief Application state for loading terrain and scenario data
//!
//! DtLoadingState is responsible for loading terrain and scenario data
//! into VR-Engage. It presents a loading UI with progress information,
//! coordinates the loading sequence between simulation and visualization
//! components, and handles transitions to the appropriate state once
//! loading is complete.
class PLAYERSTATION_DLL DtLoadingState : virtual public DtPlayerStationState
{
public:
   //! \brief Constructor
   //! \param app Reference to the player station application
   //!
   //! Creates a new loading state associated with the given application.
   DtLoadingState(DtPlayerStationApp& app);
 
   //! \brief Virtual destructor
   //!
   //! Ensures proper cleanup of loading state resources.
   virtual ~DtLoadingState() override;
 
   //! \brief Called when the state is entered
   //! \param args Pointer to arguments from the previous state
   //!
   //! Initializes the loading process, sets up the loading UI, and begins
   //! the sequence of loading terrain and scenario data. The args parameter
   //! typically contains information about what needs to be loaded.
   virtual void onEnter(const DtPlayerStationStateArgs* args) override;
 
   //! \brief Called when the state is exited
   //!
   //! Cleans up loading resources, hides the loading UI, and prepares for
   //! the transition to the next state (typically a session state).
   virtual void onExit() override;
 
   //! \brief Updates the state each frame
   //! \param dt Time in seconds since the last update
   //!
   //! Monitors loading progress, updates the loading UI, and checks for
   //! completion conditions to determine when to transition to the next state.
   virtual void tick(double dt) override;
 
protected:
   //! \brief Handles backend status update messages
   //! \param msg Pointer to the backend status message
   //! \return Message handling result
   //!
   //! Processes status updates from the backend system, updating the loading
   //! progress based on the current state of backend components.
   virtual DtVreMessageResult handleBackendStatus(DtVreMessage* msg);
 
   //! \brief Handles SMS load completion messages
   //! \param msg Pointer to the load complete message
   //! \return Message handling result
   //!
   //! Processes notifications that the Simulation Management System has
   //! completed loading the requested terrain or scenario data.
   virtual DtVreMessageResult handleSmsLoadComplete(DtVreMessage* msg);
 
   //! \brief Handles session status messages
   //! \param msg Pointer to the session status message
   //! \return Message handling result
   //!
   //! Processes updates about the current session status, which may indicate
   //! when the session is ready for player engagement after loading.
   virtual DtVreMessageResult handleSessionStatus(DtVreMessage* msg);
 
   //! \brief Initiates terrain loading in the simulation component
   //!
   //! Starts the loading process for terrain data in the simulation system.
   //! This prepares the terrain for simulation physics and entity interactions.
   virtual void loadSimTerrain();
 
   //! \brief Initiates terrain loading in the GUI/visualization component
   //!
   //! Starts the loading process for terrain data in the visualization system.
   //! This prepares the terrain for visual rendering and display.
   virtual void loadGuiTerrain();
 
   //! \brief Loads observer views defined in the scenario file
   //! \return True if observer views were loaded successfully, false otherwise
   //!
   //! Attempts to load pre-defined observer views from the scenario file,
   //! which provide camera positions and orientations for observing the simulation.
   virtual bool loadScenarioObserverViews();
 
   virtual bool parseObserverViewsXml(const DtString& xml, makArchives::DtObserverStateRecordsList& record);
 
   //! \brief Searches recursively for a file in a directory
   //! \param directory Directory to start the search from
   //! \param filenameToFind Filename to search for
   //! \param foundPath [out] Path to the found file if successful
   //! \return True if the file was found, false otherwise
   //!
   //! Performs a recursive search for a specified file within a directory
   //! and its subdirectories. If found, the full path is stored in foundPath.
   virtual bool findFileRecursive(
      const std::string& directory, const std::string& filenameToFind, DtFilename& foundPath);
 
   //! \brief Sets the status text in the loading UI
   //! \param msg Text message to display
   //!
   //! Updates the status text shown in the loading UI to inform the user
   //! about the current loading activity or progress.
   virtual void setStatusText(const QString& msg);
 
   //! \brief Sets the estimated loading time
   //! \param ms Estimated time in milliseconds
   //!
   //! Sets the estimated time required to complete the loading process,
   //! which may be used to update the progress indicator in the UI.
   virtual void setTimeToLoad(const int ms);
 
   //! \brief Gets the estimated loading time for a file
   //! \param file Path to the scenario or terrain file
   //! \return Estimated loading time in milliseconds, or -1 if file not found
   //!
   //! Calculates the estimated time needed to load the specified scenario
   //! or terrain file. This starts a timer if not already started and may use
   //! historical data to provide an estimate. Returns -1 if the file is not found.
   int getEstimatedTimeToLoad(const std::string& file);
 
   //! \brief Stops the loading timer and logs statistics
   //! \param file Path to the scenario or terrain file that was loaded
   //!
   //! Stops the loading timer started by getEstimatedTimeToLoad() and logs
   //! the actual loading time to a data file for future reference. This helps
   //! improve future loading time estimates.
   void logEstimatedTimeToLoad(const std::string& file);
 
protected:
   //! \brief Data message containing loading parameters
   //!
   //! Contains information about what terrain or scenario to load
   //! and how it should be loaded.
   std::shared_ptr<SessionLoadDataMessage> myLoadData;
 
   //! \brief Loading page UI component
   //!
   //! Provides the user interface for displaying loading progress.
   std::shared_ptr<DtVreLoadingPage> myLoadingPage;
 
   //! \brief External loading page logic
   //!
   //! Handles advanced loading UI functionality and interactions.
   std::shared_ptr<DtVreExternalLoadingPageLogic> myExternalLoadingLogic;
 
   //! \brief SMS loading status bitmask
   //!
   //! Tracks which components of the Simulation Management System
   //! have completed loading through a bitmask of status flags.
   int mySmsLoadStatusBits;
 
   //! \brief Flag indicating if terrain load command was sent
   bool mySentTerrainLoad;
 
   //! \brief Flag indicating if simulation terrain loading is complete
   bool myDidSimLoad;
 
   //! \brief Flag indicating if GUI terrain loading is complete
   bool myDidGuiLoad;
 
   //! \brief Server port number for the loaded session
   int myServerPort;
 
   //! \brief Timer start timestamp
   //!
   //! Records when loading began for performance measurement.
   std::chrono::time_point<std::chrono::steady_clock> myTimerStart;
 
   //! \brief Timer end timestamp
   //!
   //! Records when loading completed for performance measurement.
   std::chrono::time_point<std::chrono::steady_clock> myTimerEnd;
};
 
} // namespace makVre