vrePlayerLaserController.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vrePlayerLaserController.h
//! \ingroup vreVrfmodel
//! \brief Controller for player-controlled laser designation
//!
//! This file defines the DtVrePlayerLaserController class which provides an interface
//! that a VR-Engage player can use to control a laser designator. The interface between
//! the player in the front-end and this back-end controller uses these messages:
//!   - StartLasing - turn the laser on
//!   - StopLasing - turn the laser off
//!   - UpdateLasingState - update current laser target or spot location
//!
//! This class is intended to provide inputs to the VR-Forces DtLasingController, which
//! creates and manages the published designator object associated with the laser.
 
#pragma once
 
#include "vreVrfmodel/export.h"
#include "vreVrfmodel/vreSimComponent.h"
 
#include <vreMessageManager/vreMessage.h>
 
#include <vrfobjcore/controllerComponent.h>
 
class DtLasingPSR;
class DtBooleanOutputPort;
class DtVectorOutputPort;
class DtStringOutputPort;
 
namespace makVre
{
//! \brief Type identifier for the VRE player laser controller component
const char DtVrePlayerLaserControllerType[] = "vre-player-laser-controller";
 
//! \brief Controller for player-controlled laser designation functionality
//!
//! DtVrePlayerLaserController provides an interface for VR-Engage players to
//! control a laser designator. It handles messages from the front-end to activate,
//! deactivate, and update the laser's target. The controller sets appropriate output
//! ports that can be connected to a DtLasingController to actually create the
//! laser designation object in the simulation.
class VREVRFMODEL_DLL DtVrePlayerLaserController : public DtVreSimComponent<DtControllerComponent>
{
private:
   //! \brief Default constructor (not implemented)
   //!
   //! Default constructor is private and not implemented to prevent
   //! creation of instances without proper initialization.
   DtVrePlayerLaserController();
 
   //! \brief Copy constructor (not implemented)
   //!
   //! Copy constructor is private and not implemented to prevent
   //! copy construction.
   DtVrePlayerLaserController(const DtVrePlayerLaserController& orig);
 
   //! \brief Assignment operator (not implemented)
   //! \return Reference to this object
   //!
   //! Assignment operator is private and not implemented to prevent assignment.
   const DtVrePlayerLaserController& operator=(const DtVrePlayerLaserController& orig);
 
public:
   //! \brief Constructor
   //! \param name The name of this component
   //! \param owner The local object that owns this component
   //! \param simManager The simulation services manager
   //! \param desc Component descriptor with configuration parameters
   //! \param parentRegistry Optional parent registry for reader/writer functionality
   //!
   //! Creates a new player laser controller component with the specified parameters.
   DtVrePlayerLaserController(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc = 0, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the player laser controller component.
   virtual ~DtVrePlayerLaserController() override;
 
   //! \brief Gets the type identifier for this component
   //! \return String identifying the component type (DtVrePlayerLaserControllerType)
   //!
   //! Implements the DtSimComponent::type() method to return the
   //! type identifier for this component.
   virtual const char* type() const override;
 
   //! \brief Performs initialization before the first simulation tick
   //!
   //! Gets initial laser designator code from the Process State Repository (PSR)
   //! and copies it to the state property "laserCode". This ensures that the
   //! GUI displays the correct laser code when the simulation starts.
   virtual void preFirstTickInit() override;
 
   //! \brief Updates the controller state each simulation frame
   //!
   //! Processes laser controller logic each simulation frame, updating
   //! output ports based on the current lasing state and target information.
   virtual void tick() override;
 
   //! \brief Initializes the player laser controller
   //! \return True if initialization is successful, false otherwise
   //!
   //! Sets the state property named "HasLaser" to True. This property is defined
   //! in the platform sysdef file under state-data and is used by the VR-Engage menu
   //! system to determine whether to show laser designation options in the user interface.
   //! Also creates necessary ports and registers message callbacks.
   virtual bool init() override;
 
   //! \brief Factory method to create a new instance of this component
   //! \param name The name for the new component
   //! \param owner The local object that will own this component
   //! \param simManager The simulation services manager
   //! \param desc Optional component descriptor
   //! \param parentRegistry Optional parent registry for reader/writer functionality
   //! \return Pointer to the newly created component
   //!
   //! Static factory method used by the component creation system to instantiate
   //! new instances of this component type.
   static DtSimComponent* creator(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc = 0, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Callback for entity restoration events
   //! \param msg The message containing restoration information
   //! \param usrData User data pointer, typically pointing to the instance of this class
   //!
   //! Static callback function invoked when an entity is restored. This function forwards
   //! the message to the instance's processSetRestore method to reinitialize state properties.
   static void setRestoreCallback(DtSimMessage* msg, void* usrData);
 
   //! \brief Callback for laser code change requests
   //! \param msg The message containing the new laser code
   //! \param usrData User data pointer, typically pointing to the instance of this class
   //!
   //! Static callback function invoked when a request to change the laser code is received.
   //! This function forwards the message to the instance's processSetLaserCodeRequestMessage method.
   static void setLaserCodeRequestCallback(DtSimMessage* msg, void* usrData);
 
protected:
   //! \brief Handles messages to start lasing
   //! \param msg The message containing lasing start request
   //! \return Message processing result indicating success or failure
   //!
   //! Processes StartLasing messages from the front-end, which activate
   //! the laser designator. Sets the appropriate output ports to enable
   //! the laser in the simulation.
   virtual makVre::DtVreMessageResult handleStartLasing(makVre::DtVreMessage* msg);
 
   //! \brief Handles messages to stop lasing
   //! \param msg The message containing lasing stop request
   //! \return Message processing result indicating success or failure
   //!
   //! Processes StopLasing messages from the front-end, which deactivate
   //! the laser designator. Sets the appropriate output ports to disable
   //! the laser in the simulation.
   virtual makVre::DtVreMessageResult handleStopLasing(makVre::DtVreMessage* msg);
 
   //! \brief Handles messages to update the lasing state
   //! \param msg The message containing updated lasing information
   //! \return Message processing result indicating success or failure
   //!
   //! Processes UpdateLasingState messages from the front-end, which update
   //! the location being designated by the laser. Updates the appropriate output
   //! ports with the new target information.
   virtual makVre::DtVreMessageResult handleUpdateLasingState(makVre::DtVreMessage* msg);
 
   //! \brief Processes entity restoration messages
   //! \param msg The message containing restoration information
   //!
   //! Reinitializes the state property "HasLaser" when a set restore operation
   //! is executed. This ensures that the entity's laser capabilities are properly
   //! restored after entity restoration, allowing the VR-Engage menu to correctly
   //! display laser options.
   virtual void processSetRestore(DtSimMessage* msg);
 
   //! \brief Processes laser code change requests
   //! \param msg The message containing the new laser code
   //!
   //! Sets the state property for laser code based on the message contents,
   //! so the updated code can be reflected in the GUI. This allows users to
   //! change laser codes through the user interface, ensuring that laser-guided
   //! weapons are properly configured for the selected code.
   virtual void processSetLaserCodeRequestMessage(DtSimMessage* msg);
 
   //! \brief Creates input and output ports for the component
   //! \return True if ports are successfully created, false otherwise
   //!
   //! Creates and initializes all the output ports needed by this component,
   //! including ports for laser state (on/off), target location, and target object.
   //! These ports connect to the actual laser controller component.
   virtual bool createPorts() override;
 
   //! \brief Retrieves the process state repository
   //!
   //! Gets the process state repository (PSR) for this component, storing
   //! it in the myProcessState member variable for later access. The PSR
   //! contains persistent state information for the controller.
   void getProcessSR();
 
   //! \brief Pointer to the lasing process state repository
   //!
   //! Contains the persistent state information for the laser controller,
   //! including the laser code and target information.
   DtLasingPSR* myProcessState;
 
   //! \brief Flag indicating whether the player is currently lasing
   //!
   //! When true, indicates that the player has activated the laser designator
   //! and is currently designating a target.
   bool myPlayerIsLasing;
 
   //! \brief Flag indicating whether the player was lasing a target in the previous tick
   //!
   //! Used to track changes in lasing state between ticks, for determining
   //! when state transitions occur.
   bool myLasingTargetLastTick;
 
   //! \brief Output port for the laser on/off state
   //!
   //! Boolean output port that controls whether the laser is active.
   //! When true, the laser is on and designating a target.
   DtBooleanOutputPort* myLaserOnOutputPort;
 
   //! \brief Output port for the laser target location
   //!
   //! Vector output port that specifies the 3D location being designated
   //! by the laser when targeting a location rather than an object.
   DtVectorOutputPort* myTargetLocationOutputPort;
 
   //! \brief Output port for the laser target object
   //!
   //! String output port that specifies the unique identifier of an object
   //! being designated by the laser when targeting an object rather than a location.
   DtStringOutputPort* myTargetObjectOutputPort;
};
} // namespace makVre