cigiHostControl.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file cigiHostControl.h
//! \brief Defines the CIGI host control component for VREngage
//!
//! This file contains the DtCigiHostControl class which implements a player
//! component that manages the Common Image Generator Interface (CIGI) host
//! functionality. It handles communication with image generators through the
//! CIGI protocol, managing session state, view updates, and other CIGI-related
//! operations in the VREngage system.
 
#pragma once
 
#include "vreCigiHostControlPlugin/export.h"
 
#include "vrePlayerStation/playerComponent.h"
 
#include "vreMessageManager/vreMessage.h"
 
#include <vlpi/simulationAddress.h>
 
#include <matrix/vlVector.h>
#include <matrix/vlTaitBryan.h>
 
#include <vlutil/vlPerformanceStats.h>
 
#include <boost/signals2.hpp>
 
#include <memory>
 
namespace makVre
{
namespace CigiHostControlConfig
{
//! \ingroup RoleConfigParams
//! \defgroup CigiHostControlRoleParams CIGI Host Control Role Parameters
//! \roleInherits{PlayerComponentRoleParams}
//! Configuration Options for CIGI host control role.
//! @{
 
//! \vreRoleParam{displayConfiguration,string,"",cigiHostControl,Display configuration (.dcx) file path for defining view windows and parameters.}
constexpr const char* displayConfiguration = "displayConfiguration";
 
//! \vreRoleParam{framerateLimit,double,0.0,cigiHostControl,Framerate limit for CIGI host communication (0.0 for no limit).}
constexpr const char* framerateLimit = "framerateLimit";
 
//! \vreRoleParam{hostConfig,string,"",cigiHostControl,Required host configuration file path for CIGI session parameters.}
constexpr const char* hostConfig = "hostConfig";
 
//! \vreRoleParam{hostSimAddress,string,"",cigiHostControl,Host simulation address for the target backend (optional).}
constexpr const char* hostSimAddress = "hostSimAddress";
 
//! \vreRoleParam{igAddress,string,"",cigiHostControl,Image generator address for CIGI communication (optional).}
constexpr const char* igAddress = "igAddress";
 
//! \vreRoleParam{maxFireFxDistance,float,0.0,cigiHostControl,Maximum distance for fire effects rendering in view definitions.}
constexpr const char* maxFireFxDistance = "maxFireFxDistance";
 
//! \vreRoleParam{maxViewDistance,float,0.0,cigiHostControl,Maximum view distance for view definitions.}
constexpr const char* maxViewDistance = "maxViewDistance";
 
//! @}
} // namespace CigiHostControlConfig
 
//! \brief Type identifier constant for DtCigiHostControl components
//!
//! This constant defines the string identifier used to identify DtCigiHostControl
//! component types within the VR-Engage framework. It is used for component
//! registration, type checking, and serialization operations.
constexpr const char* DtCigiHostControlType = "DtCigiHostControl";
 
//! \brief CIGI host control component for VREngage
//!
//! This class implements a player component that manages the Common Image Generator
//! Interface (CIGI) host functionality. It handles communication with image generators
//! through the CIGI protocol, managing session state, view definitions, entity
//! synchronization, and other CIGI-related operations in the VREngage system.
//!
//! The component initializes CIGI communication, processes messages from the
//! VREngage messaging system, and synchronizes the state of the simulation with
//! the image generator during each tick of the simulation loop.
class CIGIHOSTCONTROL_DLL DtCigiHostControl : public makVre::DtPlayerComponent
{
public:
   //! \brief Default constructor
   //!
   //! Initializes a new instance of the CIGI host control component with
   //! default settings.
   DtCigiHostControl();
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources and terminates any active CIGI sessions.
   virtual ~DtCigiHostControl() override;
 
   //! \brief Initializes the CIGI host control component
   //! \param player Pointer to the player station that owns this component
   //! \param config Configuration table with initialization parameters
   //! \return True if initialization succeeded, false otherwise
   //!
   //! This method initializes the CIGI host control component with the specified
   //! player station and configuration. It sets up the CIGI session parameters,
   //! registers message handlers, and initializes the view definitions.
   virtual bool initialize(DtPlayerStation* player, DtInitTable& config) override;
 
   //! \brief Updates the CIGI host control during each simulation tick
   //! \param dt Delta time in seconds since the last tick
   //!
   //! This method is called during each simulation tick to update the CIGI
   //! host control component. It processes pending messages, updates entity
   //! positions and states, and sends updates to the image generator.
   virtual void tick(double dt) override;
 
   //! \brief Performs post-tick processing for the CIGI host control
   //!
   //! This method is called after all components have been ticked to perform
   //! any final processing before the next simulation frame begins.
   virtual void postTick();
 
   //! \brief Shuts down the CIGI host control component
   //!
   //! This method terminates the CIGI session, unregisters message handlers,
   //! and releases any resources used by the component.
   virtual void shutdown() override;
 
   //! \brief Returns the component type identifier
   //! \return String identifier for this component type
   //!
   //! Returns the type identifier string for this component, which is used
   //! by the VR-Engage framework for component identification and management.
   //! The returned value matches DtCigiHostControlType.
   virtual const char* type() const override;
 
protected:
   //! \brief Initializes the state attributes for the CIGI host control
   //!
   //! This method sets up the state attributes that will be synchronized
   //! with the image generator through the CIGI protocol.
   virtual void initializeStateAttributes() override;
 
   //! \brief Handles CIGI session status messages
   //! \param msg Pointer to the received message
   //! \return Message processing result
   //!
   //! This method processes messages related to CIGI session status,
   //! such as session creation, connection, disconnection, etc.
   DtVreMessageResult handleCigiSessionStatusMessage(DtVreMessage* msg);
 
   //! \brief Initializes view definitions for the CIGI session
   //!
   //! This method sets up the initial view definitions that will be
   //! synchronized with the image generator.
   virtual void initViews();
 
   //! \brief Updates view definitions during simulation
   //!
   //! This method updates the view definitions based on the current
   //! state of the simulation and sends the updates to the image generator.
   virtual void updateViews();
 
   //! \brief Simulation address for the CIGI host
   DtSimulationAddress mySimAddress;
 
   //! \brief Name of the CIGI session
   std::string mySessionName;
 
   //! \brief Flag indicating whether the CIGI session is started
   bool mySessionStarted;
 
   //! \brief Group ID for the out-the-window (OTW) view
   int myOtwGroupId;
 
   //! \brief Position offset for the observer in the CIGI coordinate system
   DtVector32 myObserverPositionOffset;
 
   //! \brief Rotation offset for the observer in the CIGI coordinate system
   DtTaitBryan myObserverRotationOffset;
 
   //! \brief Framerate limit for CIGI updates in Hz
   double myFramerateLimit;
 
   //! \brief Performance timer for measuring CIGI processing time
   std::shared_ptr<DtTimedSection> myPerformanceTimer;
 
   //! \brief Connection for the post-tick signal
   boost::signals2::scoped_connection myPostTickConnection;
};
 
} // namespace makVre