vreExternalLoadingPageLogic.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file vreExternalLoadingPageLogic.h
//! \brief Defines the logic for managing external loading screens in VR-Engage
//!
//! This file contains the DtVreExternalLoadingPageLogic class which manages
//! an external loading screen process. It handles communication with the
//! loading screen through a TCP socket connection, allowing VR-Engage
//! to display loading progress and status updates during resource-intensive operations.
 
#pragma once
 
#include "vrePlayerStation/export.h"
 
#include "vreMessageManager/vreMessage.h"
 
#include <QObject>
#include <QProcess>
#include <QtNetwork/QTcpSocket>
 
class QQuickItem;
class QTcpServer;
class QTcpSocket;
 
namespace makVre
{
//! \brief Manager class for external loading screen process and communication
//!
//! DtVreExternalLoadingPageLogic manages a separate process that displays a
//! loading screen with a progress bar. It communicates with this process via
//! TCP sockets to update loading status, progress, and estimated completion time.
//! This allows resource-intensive operations like terrain loading to display
//! progress without blocking the main application.
class PLAYERSTATION_DLL DtVreExternalLoadingPageLogic : public QObject
{
   Q_OBJECT;
 
public:
   //! \brief Constructor
   //!
   //! Creates a new external loading page logic manager with default state.
   DtVreExternalLoadingPageLogic();
 
   //! \brief Destructor
   //!
   //! Cleans up resources, including shutting down the TCP server and
   //! terminating the external process if they are still running.
   virtual ~DtVreExternalLoadingPageLogic() override;
 
   //! \brief Initializes the TCP server for loading screen communication
   //! \param port Specific port to use for the server, or 0 to use process ID
   //!
   //! Sets up the TCP server that will communicate with the external loading
   //! screen process. If port is 0, the server will use the current process ID
   //! as the port number to avoid conflicts with other instances.
   virtual void initializeServer(unsigned short int port = 0);
 
   //! \brief Starts the external loading page process
   //! \param timeoutTime Maximum expected loading time in milliseconds
   //! \param currentTime Current loading progress in milliseconds
   //! \param seed Random seed for loading screen visuals
   //! \param initialMessage Initial status message to display
   //!
   //! Launches the external loading screen process with initial parameters.
   //! The process will display a progress bar based on the current and maximum times,
   //! along with the provided status message. The seed parameter can be used
   //! to generate consistent random visuals across multiple launches.
   virtual void initializeProcess(
      int timeoutTime, int currentTime, int seed, const QString& initialMessage = "Loading...");
 
   //! \brief Shuts down the external process and TCP server
   //!
   //! Terminates the external loading screen process if it's running
   //! and stops the TCP server. This should be called when loading
   //! is complete or if the loading operation is canceled.
   virtual void shutdown();
 
   //! \brief Sends a status message to the loading screen
   //! \param msg Text message to display on the loading screen
   //!
   //! Updates the status text displayed on the loading screen.
   //! This is typically used to indicate the current operation being performed,
   //! such as "Loading terrain..." or "Initializing entities...".
   virtual void sendStatus(const QString& msg);
 
   //! \brief Updates the current progress time
   //! \param ms Current progress time in milliseconds
   //!
   //! Updates the current progress value displayed on the loading screen.
   //! This affects the position of the progress bar indicator and any
   //! numerical progress display. The value should be between 0 and
   //! the maximum time set with sendMaximumTime().
   virtual void sendCurrentTime(int ms);
 
   //! \brief Sets the maximum expected loading time
   //! \param ms Maximum loading time in milliseconds
   //!
   //! Updates the maximum expected loading time for the progress bar.
   //! This affects the scale of the progress bar, allowing it to provide
   //! an accurate visual representation of progress. The current time
   //! sent with sendCurrentTime() will be shown as a proportion of this maximum.
   virtual void sendMaximumTime(int ms);
 
   //! \brief Checks if the loading screen is ready
   //! \return True if the loading screen is connected and ready, false otherwise
   //!
   //! Determines whether the external loading screen process has
   //! connected to the TCP server and is ready to receive updates.
   //! This can be used to ensure the loading screen is functioning
   //! before attempting to send status or progress updates.
   virtual bool isLoadingScreenReady();
 
public slots:
   //! \brief Handles new client connections to the TCP server
   //!
   //! Slot called when a new client (the loading screen process)
   //! connects to the TCP server. Sets up the connection and
   //! updates the internal state to reflect the connection.
   virtual void newConnection();
 
   //! \brief Handles client disconnections
   //!
   //! Slot called when a client disconnects from the TCP server.
   //! Updates the internal state and emits the smbDisconnected signal.
   void gotDisconnection();
 
   //! \brief Processes data received from clients
   //!
   //! Slot called when data is received from a connected client.
   //! Parses and processes the messages sent by the loading screen process.
   void readClient();
 
signals:
   //! \brief Signal emitted when a client disconnects
   //!
   //! This signal is emitted when the loading screen process
   //! disconnects from the TCP server. It can be used by the
   //! application to respond to unexpected disconnections.
   void smbDisconnected();
 
protected:
   //! \brief Sends data to all connected clients
   //! \param msg Message to send to clients
   //!
   //! Internal method that handles the low-level details of sending
   //! messages to all connected clients. This is used by the public
   //! methods to communicate with the loading screen process.
   virtual void sendData(const QString& msg);
 
protected:
   //! \brief List of connected client sockets
   //!
   //! Contains pointers to all TCP socket connections to clients.
   //! Typically there will be only one client (the loading screen process).
   QList<QTcpSocket*> myClients;
 
   //! \brief TCP server for communicating with the loading screen
   //!
   //! Manages the TCP server that listens for connections from
   //! the external loading screen process.
   std::shared_ptr<QTcpServer> myTCPServer;
 
   //! \brief Size of the next block to read
   //!
   //! Used during message parsing to determine the size of the
   //! next block of data to read from the socket.
   quint16 myNextBlockSize;
 
   //! \brief External process for the loading screen
   //!
   //! Manages the external process that displays the loading screen.
   QProcess myProcess;
 
   //! \brief Flag indicating whether the loading screen is ready
   //!
   //! When true, indicates that the loading screen process has connected
   //! to the TCP server and is ready to receive updates.
   bool myScreenReady;
};
 
} // namespace makVre