vreJoystickController.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreJoystickController.h
//! \ingroup vreVrfmodel
//! \brief Controller for handling joystick input
//!
//! This file defines the DtVreJoystickController class which enables joystick
//! control for entities and automatically creates output ports for joystick inputs.
//! It serves as a bridge between physical joystick inputs and entity controls.
 
#pragma once
 
#include "vreVrfmodel/export.h"
#include "vreVrfModel/vreSimComponent.h"
 
#include <vreMessageManager/vreMessage.h>
 
#include <vrfmodel/joystickControllerInterface.h>
 
#include <vrfobjcore/controllerComponent.h>
 
class DtString;
class DtSimulationServices;
class DtGroundVehicleStateRepository;
class DtBooleanOutputPort;
class DtAnalogOutputPort;
 
namespace makVre
{
 
//! \brief Type identifier for the VRE joystick controller component
const char DtVreJoystickControllerType[] = "vre-joystick-controller";
 
//! \brief Controller that enables joystick control for entities
//!
//! DtVreJoystickController enables joystick control for entities by creating
//! and managing the appropriate output ports for joystick inputs. It serves as a
//! bridge between physical joystick inputs and the simulation, translating joystick
//! actions into appropriate entity control commands. The controller handles connect
//! and disconnect events, commander override states, and port value updates.
//!
//! Uses Descriptor Type: DtVreJoystickControllerDescriptor
class VREVRFMODEL_DLL DtVreJoystickController : public DtVreSimComponent<DtControllerComponent>,
                                                public DtJoystickControllerInterface
{
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 joystick controller component with the specified parameters.
   //! The descriptor contains configuration information for setting up appropriate
   //! output ports based on the controlled entity type.
   DtVreJoystickController(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the joystick controller component, including
   //! output ports and port groups.
   virtual ~DtVreJoystickController() override;
 
   //! \brief Gets the type identifier for this component
   //! \return String identifying the component type (DtVreJoystickControllerType)
   //!
   //! Implements the DtSimComponent::type() method to return the
   //! type identifier for this component.
   virtual const char* type() const override;
 
   //! \brief Initializes the joystick controller
   //! \return True if initialization is successful, false otherwise
   //!
   //! Performs initial setup of the joystick controller, including creating
   //! port groups and ports for joystick inputs. This method is called during
   //! component initialization.
   virtual bool init() override;
 
   //! \brief Creates output port groups for joystick inputs
   //! \return True if port groups are successfully created, false otherwise
   //!
   //! Creates and initializes the output port groups needed for joystick control.
   //! These port groups organize the output ports by function (movement controls,
   //! weapon controls, etc.) for proper routing to other components.
   virtual bool createPortGroups() override;
 
   //! \brief Creates output ports for joystick inputs
   //! \return True if ports are successfully created, false otherwise
   //!
   //! Creates and initializes the output ports needed for joystick control.
   //! These ports transmit joystick input values to other components that
   //! handle actual entity movement and actions.
   virtual bool createPorts() 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);
 
private:
   //! \brief Default constructor (not implemented)
   //!
   //! Default constructor is private and not implemented to prevent
   //! creation of instances without proper initialization.
   DtVreJoystickController();
 
   //! \brief Copy constructor (not implemented)
   //!
   //! Copy constructor is private and not implemented to prevent
   //! copy construction.
   DtVreJoystickController(const DtVreJoystickController& orig);
 
   //! \brief Assignment operator (not implemented)
   //! \return Reference to this object
   //!
   //! Assignment operator is private and not implemented to prevent assignment.
   DtVreJoystickController& operator=(const DtVreJoystickController& orig);
 
protected:
   //! \brief Handles commander override messages
   //! \param msg The message containing override parameters
   //! \return Message processing result indicating success or failure
   //!
   //! Processes CommanderOverride messages, which activate or deactivate commander
   //! override mode. When in commander override mode, direct control inputs take
   //! precedence over AI control or other input methods.
   virtual DtVreMessageResult handleCommanderOverride(DtVreMessage* msg);
 
   //! \brief Calculates and sets port values based on function input
   //! \param functionGroup The function group identifier
   //! \param function The specific function name
   //! \param value The input value to process
   //! \param repeat Flag indicating whether the function should repeat
   //!
   //! Processes input from joystick functions and applies the appropriate
   //! transforms to set the corresponding output port values. This is the main
   //! method for translating joystick inputs to simulation control values.
   virtual void calcAndSetPortValues(
      const DtString& functionGroup, const DtString& function, double value, bool repeat) override;
   //! \brief Handles joystick connection events
   //!
   //! Called when a joystick is connected to the system. Updates internal state
   //! and performs any necessary setup to begin processing joystick inputs.
   virtual void joystickConnected() override;
   //! \brief Handles joystick disconnection events
   //!
   //! Called when a joystick is disconnected from the system. Updates internal state
   //! and performs any necessary cleanup to handle the loss of joystick input.
   virtual void joystickDisconnected() override;
 
   //! \brief Updates the controller state each simulation frame
   //!
   //! Processes joystick inputs and updates output port values during each
   //! simulation frame. This ensures that the entity's behavior reflects the
   //! current joystick state.
   virtual void tick() override;
 
protected:
   //! \brief Name of the output port group
   //!
   //! Stores the name of the output port group used for organizing
   //! joystick control output ports.
   std::string myOutputPortGroupName;
 
   //! \brief Pointer to the output port group
   //!
   //! Contains all the output ports used to transmit joystick control values.
   DtOutputPortGroup* myOutputGroup;
 
   //! \brief Type definition for mapping port names to port objects
   using OutputPortMap = std::map<std::string, DtOutputPort*>;
 
   //! \brief Map of output ports indexed by name
   //!
   //! Stores all output ports created for joystick control, indexed by their names
   //! for easy access when updating port values.
   OutputPortMap myOutputPorts;
 
   //! \brief Flag indicating whether commander override mode is active
   //!
   //! When true, indicates that commander override mode is active, which gives
   //! direct control inputs precedence over AI control or other input methods.
   bool myCommanderOverrideActive;
};
 
} // namespace makVre