vreFwlActuator.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreFwlActuator.h
//! \ingroup vreVrfRtd
//! \brief Fixed-wing aircraft actuator component for VREngage
//!
//! This file defines the DtVreFwlActuator class, which provides real-time
//! dynamics integration for fixed-wing aircraft controlled through VREngage.
//! It handles joystick input, updates control surfaces, and maintains
//! proper kinematic state.
 
#pragma once
 
#include <vreVrfRtd/vreRtdBackendLibCommon.h>
#include <vrfmodel/fixedWingActuatorComponent.h>
 
class DtSetJoyDeviceSwitchRequest;
class DtSimMessage;
class DtBooleanInputPort;
class DtIntegerInputPort;
class DtBooleanOutputPort;
class DtSetRestoreRequest;
class DtSetLocationRequest;
class DtSetHeadingRequest;
 
namespace FixedWingLibCGF
{
class AirplaneDynamics;
}
 
namespace FwlCgfVrf
{
class StateRepository;
 
//! \brief Type string for VREngage fixed-wing actuator component
//!
//! Constant used to identify this component type in the simulation system.
const char TS_VREngageActuator[] = "fixedwinglib-cgf-vr-engage-actuator";
 
class Cgf;
class DtVreFwlParameters;
 
//! \brief Fixed-wing aircraft actuator component for VREngage
//!
//! This class provides the real-time dynamics integration for fixed-wing aircraft
//! controlled through VREngage. It processes joystick inputs, handles control surface
//! movement, and maintains proper kinematic state.
//!
//! \note Generally the VREngage actuator should not directly write the kinematic
//! state to the state repository but use its output ports instead. This
//! allows to use the Update Repository Actuator which in turn allows to
//! mix the RTD VREngageActuator with the VRF Flight Kinematics Actuator.
//! However, there are exceptions:
//! - setRestore() and setLocation() (same if player takes control) use
//!   state repository methods like processSetRestore() and checkAndClampAircraftOnGround()
//!   which directly write the kinematic state to the state repository.
//!
//! Reason:
//! - VRF often calls DtVrfMovingObjectStateRepository::clampToGround() after
//!   a setLocation request. This method considers the current kinematic state
//!   of the state repository which has to be assigned beforehand.
//! - The kinematic state is written to the state repository only
//!   at certain situations (setRestore, setLocation etc.) while the
//!   RTD actuator is active (see isPlayerControlled()). Hence, there should
//!   be no critical interference with other actuators.
class RTD_VRF_BACKEND_PLUGIN_EXPORT DtVreFwlActuator : public DtFixedWingActuatorComponent
{
public:
   //! \brief Constructor
   //! \param name The name of the component
   //! \param object The local object this component belongs to
   //! \param simManager The simulation services manager
   //! \param compDescriptor Component descriptor containing configuration
   //! \param parentRegistry Parent registry for reader/writer functionality
   //!
   //! Initializes a new fixed-wing actuator component for VREngage control.
   DtVreFwlActuator(const DtString& name, DtLocalObject* object, DtSimulationServices* simManager,
      DtComponentDescriptor* compDescriptor, DtReaderWriterRegistry* parentRegistry);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the actuator component.
   virtual ~DtVreFwlActuator() override;
 
   //! \brief Gets the component type
   //! \return The type string for this component
   //!
   //! Returns TS_VREngageActuator as the component type identifier.
   virtual const char* type() const override;
 
   //! \brief Sets the radio interface for this component
   //! \param radio The radio interface to use
   //!
   //! Configures the radio interface used for communication with this component.
   virtual void setRadio(DtSimRadio* radio) override;
 
   //! \brief Performs per-frame processing
   //!
   //! Called once per simulation frame to update the component state,
   //! process inputs, and generate outputs.
   virtual void tick() override;
 
   //! \brief Creates component ports
   //! \return True if port creation was successful
   //!
   //! Creates input and output ports for joystick control, landing gear,
   //! flaps, and other control surfaces.
   virtual bool createPorts() override;
 
   //! \brief Creates port groups
   //! \return True if port group creation was successful
   //!
   //! Creates logical groupings of related ports such as control surfaces.
   virtual bool createPortGroups() override;
 
   //! \brief Updates the control surface positions
   //! \param resetToZero If true, resets all control surfaces to neutral positions
   //!
   //! Updates the positions of all aircraft control surfaces based on current inputs
   //! or resets them to neutral positions if resetToZero is true.
   virtual void updateControlSurfaces(bool resetToZero = false);
 
   //! \brief Component factory function
   //! \param name The name for the new component
   //! \param object The local object the component will belong to
   //! \param simManager The simulation services manager
   //! \param compDescriptor Component descriptor containing configuration
   //! \param parentRegistry Parent registry for reader/writer functionality
   //! \return Pointer to the newly created component
   //!
   //! Static factory function used for component creation through the component registry.
   static DtSimComponent* creator(const DtString& name, DtLocalObject* object, DtSimulationServices* simManager,
      DtComponentDescriptor* compDescriptor, DtReaderWriterRegistry* parentRegistry);
 
   //! \brief Static callback for radio messages
   //! \param msg The received message
   //! \param usr User data pointer (points to the actuator instance)
   //!
   //! Static callback function invoked when a radio message is received.
   //! Routes the message to the appropriate instance.
   static void radioMsgCallback(DtSimMessage* msg, void* usr);
 
   //! \brief Processes a radio message
   //! \param msg The message to process
   //!
   //! Handles incoming radio messages directed to this component.
   virtual void processRadioMsg(DtSimMessage* msg);
 
   //! \brief Processes a restore request
   //! \param req The restore request to process
   //!
   //! Restores the entity to a previously saved state.
   //! Note: This method directly writes to the state repository. See class notes.
   virtual void processSetRestore(DtSetRestoreRequest* req);
 
   //! \brief Processes a location change request
   //! \param req The location request to process
   //!
   //! Changes the entity's location.
   //! Note: This method directly writes to the state repository. See class notes.
   virtual void processSetLocation(DtSetLocationRequest* req);
 
   //! \brief Processes a heading change request
   //! \param req The heading request to process
   //!
   //! Changes the entity's heading.
   virtual void processSetHeading(DtSetHeadingRequest* req);
 
   //! \brief Gets the state repository
   //! \return Pointer to the fixed-wing entity state repository
   //!
   //! Returns the state repository used by this fixed-wing aircraft.
   DtFixedWingEntityStateRepository* getStateRepository();
 
protected:
   //! \brief Checks if the entity is currently player-controlled
   //! \return True if the entity is player-controlled, false otherwise
   //!
   //! Determines whether the entity is currently under player control
   //! through VREngage or AI control.
   bool isPlayerControlled();
 
   //! \brief Writes output data to ports
   //!
   //! Updates all output ports with current state data.
   void writeOutputData();
 
   //! \brief Enables or disables state propagation thresholding
   //! \param enable True to enable thresholding, false to disable
   //!
   //! Enables or disables thresholding for state propagation to reduce
   //! network traffic by only sending significant state changes.
   void enableStatePropThresholding(bool enable);
 
   //! \brief Sets the aircraft speed
   //! \param speed The new speed value to set
   //!
   //! Sets the current speed of the aircraft.
   virtual void setSpeed(DtReal speed);
 
   //! \brief Checks and adjusts the aircraft position to keep it on the ground
   //! \param localPosition The current local position to check
   //!
   //! Ensures the aircraft doesn't sink into or float above the ground
   //! when it should be in contact with the terrain.
   virtual void checkAndClampAircraftOnGround(const DtVector& localPosition);
 
   //! \brief Copies state from RTD to the state repository
   //!
   //! Copies the current state from the real-time dynamics engine to
   //! the state repository to synchronize the simulation state.
   virtual void copyStateFromRTD();
 
   //! \brief Copies state from RTD to provided parameters
   //! \param position Output parameter for position
   //! \param velocity Output parameter for velocity
   //! \param acceleration Output parameter for acceleration
   //! \param orientation Output parameter for orientation
   //! \param rotVelocity Output parameter for rotational velocity
   //!
   //! Copies the current state from the real-time dynamics engine to
   //! the provided output parameters.
   virtual void copyStateFromRTD(
      DtVector& position, DtVector& velocity, DtVector& acceleration, DtTaitBryan& orientation, DtVector& rotVelocity);
 
   //! \brief Copies state from the state repository to RTD
   //!
   //! Copies the current state from the state repository to the real-time
   //! dynamics engine to synchronize the simulation state.
   virtual void copyStateToRTD();
 
   //! \brief Gets the fixed-wing parameters
   //! \return Pointer to the fixed-wing parameters
   //!
   //! Returns the parameters used to configure this fixed-wing aircraft.
   const DtVreFwlParameters* getFWParameters();
 
   UNIMPLEMENTED_COPYCTOR_AND_ASSIGNMENT_OPERATOR(DtVreFwlActuator);
 
   //! \brief Input port for joystick enabled state
   DtBooleanInputPort* myJoystickEnabledPort;
 
   //! \brief Input port for landing gear control
   DtBooleanInputPort* myLandingGearPort;
 
   //! \brief Input port for flap setting
   DtIntegerInputPort* myFlapSettingPort;
 
   //! \brief Input port for air brake control
   DtAnalogInputPort* myAirBrakePort;
 
   //! \brief Input port for wheel brake control
   DtAnalogInputPort* myWheelBrakePort;
 
   //! \brief Input port for control stick (pitch/roll)
   DtConstrainedDualAxisAnalogInputPort* myStickPort;
 
   //! \brief Input port for rudder pedals (yaw)
   DtConstrainedAnalogInputPort* myPedalPort;
 
   //! \brief Input port for throttle control
   DtConstrainedAnalogInputPort* myThrottlePort;
 
   //! \brief Output port for landing gear state
   DtBooleanOutputPort* myLandingGearState;
 
   //! \brief Output port for rudder position
   DtAnalogOutputPort* myRudderPort;
 
   //! \brief Output port for left aileron position
   DtAnalogOutputPort* myLeftAileronPort;
 
   //! \brief Output port for right aileron position
   DtAnalogOutputPort* myRightAileronPort;
 
   //! \brief Output port for left elevator position
   DtAnalogOutputPort* myLeftElevatorPort;
 
   //! \brief Output port for right elevator position
   DtAnalogOutputPort* myRightElevatorPort;
 
   //! \brief Output port for left flap position
   DtAnalogOutputPort* myLeftFlapPort;
 
   //! \brief Output port for right flap position
   DtAnalogOutputPort* myRightFlapPort;
 
   //! \brief Output port group for all control surfaces
   DtOutputPortGroup* myControlSurfacesGroup;
 
   //! \brief Pointer to the real-time dynamics model
   FixedWingLibCGF::AirplaneDynamics* myDynamics;
 
   //! \brief Flag indicating whether the entity is player-controlled
   bool myPlayerControlled;
 
   //! \brief Last recorded speed value
   DtReal myLastSpeed;
 
   //! \brief Flag to keep landing gear extended when on ground
   //!
   //! Keep gears extended if vehicle is placed on ground even if isTouchingGround is (still) false.
   //! This is required to avoid that gears are retracted due to joystick input while vehicle is on ground.
   //! Lock is automatically released as soon as isTouchingGround becomes true.
   bool myExtendedGearsLocked;
};
} // namespace FwlCgfVrf