vortexMovementActuator.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2024 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file    vortexMovementActuator.h
//! \brief   Movement actuator that integrates Vortex physics for vehicle dynamics
//! \ingroup vreVrfVortex
 
#pragma once
 
#include <vreVrfVortex/export.h>
 
#include <vrfobjcore/actuatorComponent.h>
#include <vrfobjcore/platformLocalObjectFacade.h>
 
#include <string>
 
#include <Vx/VxTransform.h>
#include <Vx/VxPart.h>
#include <VxSim/VxSmartInterface.h>
#include <VxSim/VxVHLInterface.h>
#include <VxSim/IDynamics.h>
#include <VxSim/VxSimulationFileManagerFacade.h>
#include <VxDynamics/Mechanism.h>
 
#include "vreUtil/coordConverter.h"
 
#include <terrainInterface/terrainImplementation.h>
 
#include <readerWriter/symbolString.h>
#include <vrfobjcore/localObject.h>
#include <vlpi/articulatedPartCollection.h>
 
// forward defs
class DtVortexStateRepository;
class DtUpdateRepositoryOutputPortGroup;
class DtVortexBasePart;
class DtVortexInterface;
class DtVortexMovementActuatorDescriptor;
 
class DtInputPortGroup;
class DtOutputPortGroup;
class DtAnalogInputPort;
class DtBooleanInputPort;
class DtSingleConnectionInputPort;
class DtSingleConnectionOutputPort;
class DtGroundVehicleStateRepository;
 
class DtStringOutputPort;
class DtMechAddon;
class DtVxSimulationFileManagerFacadeListener;
 
namespace VxSim
{
class VxExtension;
class VxPluginExtension;
class VxVHLInterface;
class VxSimulationState;
} // namespace VxSim
 
namespace makVre
{
class DtVortexPhysicalWorld;
class DtVortexConfiguration;
class DtVortexInterfaceDescriptor;
class DtVortexSimArtPartDescriptor;
class DtVortexConfigurationDescriptor;
class DtVortexMovementPSR;
} // namespace makVre
 
//! \brief Type identifier for the Vortex movement actuator
const char DtVortexMovementActuatorType[] = "vortex-movement-actuator";
 
//! \brief Actuator component that integrates Vortex physics for vehicle dynamics
//!
//! This actuator provides high-fidelity vehicle physics by connecting a VR-Forces
//! entity to a Vortex physics model. It handles vehicle dynamics simulation,
//! terrain interaction, articulated parts, and player control.
//!
//! Uses Descriptor Type: DtVortexMovementActuatorDescriptor
class VREVRFVORTEX_DLL DtVortexMovementActuator : public DtActuatorComponent
{
public:
   //! \brief Type definition for a map of Vortex interfaces by name
   using VortexInterfaceMap = std::map<std::string, DtVortexInterface*>;
 
public:
   //! \brief Constructor
   //!
   //! Initializes the actuator with the specified parameters.
   //!
   //! \param name Component name
   //! \param owner Owner local object
   //! \param simManager Simulation services
   //! \param desc Component descriptor
   //! \param parentRegistry Parent reader/writer registry
   DtVortexMovementActuator(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc = 0, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Destructor
   virtual ~DtVortexMovementActuator() override;
 
   //! \brief Assignment operator and copy constructor not implemented
   DtVortexMovementActuator& operator=(const DtVortexMovementActuator& orig) = delete;
   DtVortexMovementActuator(const DtVortexMovementActuator& orig) = delete;
 
   //! \brief Initializes the actuator
   //!
   //! Registers set callbacks and queues the loading of the physics mechanism.
   //!
   //! \return True on success, false otherwise
   virtual bool init() override;
 
   //! \brief Updates the actuator each simulation frame
   //!
   //! Manages the state of the Vortex mechanism, updates input/output ports,
   //! and synchronizes between VR-Forces and Vortex.
   virtual void tick() override;
 
   //! \brief Gets the type of this actuator
   //!
   //! \return DtVortexMovementActuatorType
   virtual const char* type() const override;
 
   //! \brief Creates the ports required for actuator operation
   //!
   //! Creates the ports from the VHL Interface.
   //!
   //! \return True on success, false otherwise
   virtual bool createPorts() override;
 
   //! \brief Creates the port groups for the actuator
   //!
   //! Creates the input and output port groups from the VHL Interface.
   //!
   //! \return True on success, false otherwise
   virtual bool createPortGroups() override;
 
   //! \brief Factory method for creating instances of this actuator
   //!
   //! \param name Component name
   //! \param owner Owner local object
   //! \param simManager Simulation services
   //! \param desc Component descriptor
   //! \param parentRegistry Parent reader/writer registry
   //! \return New instance of this class
   static DtSimComponent* creator(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc = 0, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Initializes the actuator before the first simulation tick
   //!
   //! Calls initializeMovementChooserName() and dropAboveTerrain() to initially place
   //! the vehicle on the terrain. Also passes any specified Vortex parameters from the
   //! system definition file.
   virtual void preFirstTickInit() override;
 
   //! \brief Gets the list of all Vortex parts in this actuator
   //!
   //! \return Vector of pointers to Vortex parts
   virtual const std::vector<DtVortexBasePart*>& getParts() const;
 
   //! \brief Checks if high-fidelity Vortex physics should be active
   //!
   //! Vortex should be active if the player is driving the vehicle OR if the vehicle
   //! is stationary and high-fidelity collision physics are enabled for this vehicle.
   //!
   //! \return True if Vortex physics should be active, false otherwise
   virtual bool isInVortexWorld() const;
 
   //! \brief Checks if the entity is player controlled
   //!
   //! \return True if the entity is player controlled, false otherwise
   virtual bool isVortexPlayerControlled() const;
 
   //! \brief Checks if the entity is being towed by another Vortex entity
   //!
   //! \return True if the entity is being towed, false otherwise
   virtual bool isBeingTowed() const;
 
   //! \brief Drops the vehicle above the terrain at a specified position
   //!
   //! Calculates the terrain height at the new location and positions the vehicle
   //! at the appropriate height above the terrain. The additional height above terrain
   //! is determined by the descriptor's additionalDropHeight() value (default: 0.5 meters).
   //!
   //! This method checks all bounding points of the vehicle mechanism to ensure no part
   //! of the vehicle is placed below the terrain surface. The vehicle is positioned such
   //! that its lowest point is at the terrain height plus the additional drop height.
   //!
   //! \param newLocalPosition Where to drop the vehicle (in local coordinates)
   //! \param heading The heading to set the vehicle at (in radians)
   //!
   //! \note The additional height value is now configured via DtVortexMovementActuatorDescriptor::setAdditionalDropHeight()
   //! \see DtVortexMovementActuatorDescriptor::additionalDropHeight()
   virtual void dropAboveTerrain(
      const DtVector& newLocalPosition, double heading);
 
   //! \brief Gets the next frame's location and orientation as a VxMatrix
   //!
   //! \return Matrix containing orientation and position in NWU coordinates
   VxMath::Matrix44 getNextFrameVortexTransform() const;
 
   //! \brief Gets the current mechanism associated with the actuator
   //!
   //! \return Smart interface to the current mechanism
   VxSim::VxSmartInterface<VxDynamics::Mechanism> getMechanism();
 
   //! \brief Gets the next frame Vortex location from the entity
   //!
   //! \return Location vector in Vortex coordinates
   Vx::VxVector3 getNextFrameVortexPosition() const;
 
   //! \brief Gets the next frame Vortex orientation from the entity
   //!
   //! \return Euler angles in Vortex coordinates
   Vx::VxEulerAngles getNextFrameVortexOrientation() const;
 
   //! \brief Disables the vehicle dynamics
   //!
   //! Sets the parts to static and disables vehicle dynamics.
   void disableVehicleDynamics();
 
   //! \brief Enables the vehicle dynamics
   //!
   //! Sets the parts to dynamic and enables vehicle dynamics.
   void enableVehicleDynamics();
 
protected:
   friend class DtVxSimulationFileManagerFacadeListener;
 
   //! \brief Updates Vortex model parameters with data from VR-Forces
   //!
   //! Updates vehicle mass and wheel articulated part positions from VR-Forces entity parameters.
   //! Called by loadMechanism.
   void updateParametersFromModel();
 
   //! \brief Loads the Vortex mechanism
   //!
   //! Performs the main loading of the mechanism. Called by the Listener in Vortex
   //! at a safe time.
   void loadMechanism();
 
   //! \brief Static callback for terrain change notifications
   //!
   //! \param terrainChangeInfo Information about the terrain change
   //! \param usr Pointer to this actuator
   static void terrainChangeNotification(const DtTerrainChangeNotificationInfo& terrainChangeInfo, void* usr);
 
   //! \brief Processes terrain change notifications
   //!
   //! Checks if the entity is within the spatial extents of the terrain change
   //! notification and sets the terrain change flag if needed.
   //!
   //! \param terrainChangeInfo Information about the terrain change
   void processTerrainChangeNotification(const DtTerrainChangeNotificationInfo& terrainChangeInfo);
 
protected:
   //! \brief Callback for scripted set data request message
   //!
   //! Calls processUseHiFiCollisionsInStationaryCgfState() to process the message.
   //!
   //! \param msg The message to process
   //! \param usrData User data
   static void setVortexWhileUntaskedCallback(DtSimMessage* msg, void* usrData);
 
   //! \brief Gets the Vortex part associated with an articulated part ID
   //!
   //! \param partId The part ID of the Vortex part to look for
   //! \return Pointer to the base part, or nullptr if not found
   DtVortexBasePart* findPart(int partId) const;
 
   //! \brief Checks if the Vortex mechanism is valid
   //!
   //! Valid means the following conditions are all true:
   //! - myMechanism.getExtension() != nullptr
   //! - myMechanism.getInterface() != nullptr
   //! - myMechanism.getObject() != nullptr
   //! - myMechanism.valid()
   //!
   //! \return True if the mechanism is valid, false otherwise
   virtual bool isVortexMechanismValid() const;
 
   //! \brief Gets the lowest bounding points of the current mechanism
   //!
   //! The values are returned in NWU (Vortex Coordinate System).
   //!
   //! \param outputPoints Vector to store the lowest bounding points in current world space
   virtual void getLowestBoundingPointsOfMechanism(std::vector<DtVector>& outputPoints);
 
   //! \brief Processes a set data request to enable/disable high-fidelity physics
   //!
   //! Sets the value for useHiFiCollisionInStationaryCgfState in the process state repository
   //! from the incoming scripted set data request message.
   //!
   //! \param msg The message to process
   virtual void processSetVortexWhileUntasked(DtSimMessage* msg);
 
   //! \brief Creates a process state repository for this component
   //!
   //! Creates a DtVortexMovementPSR for holding state associated with this component,
   //! specifically the useHiFiCollisionInStationaryCgfState flag.
   //!
   //! \return True on success, false otherwise
   virtual bool createPSR();
 
   //! \brief Checks if the entity is currently a high-fidelity CGF
   //!
   //! Returns true if entity is currently executing a high-fidelity Vortex model,
   //! false otherwise. Checks if the movement-chooser controller is actively tasked.
   //!
   //! \return True if high-fidelity, false otherwise
   virtual bool isHighFidelityCGF() const;
 
   //! \brief Checks if the entity is player controlled in a specific role
   //!
   //! Note that there may be multiple roles associated with a vehicle, so
   //! responsibilities for controlling the vehicle may be split across multiple role players,
   //! and/or shared with CGF control.
   //!
   //! \param role The role to check (e.g., "Driver")
   //! \return True if player controlled in the specified role, false otherwise
   virtual bool isPlayerControlledAs(std::string role) const;
 
   //! \brief Updates the Vortex state based on current conditions
   //!
   //! Adds or removes the Vortex mechanism from the Vortex scene and registers or unregisters
   //! this entity as a Vortex entity in the Collision Proxy Generator, as appropriate for the
   //! current Vortex Active state.
   virtual void realizeVortexState();
 
   //! \brief Checks if terrain is available below the vehicle
   //!
   //! \return True if terrain is available below the center of the vehicle, false otherwise
   virtual bool isTerrainAvailable() const;
 
   //! \brief Detects and logs terrain fall-through conditions
   //!
   //! Checks if the vehicle has fallen through the terrain when terrain data is not available.
   //! Logs diagnostic information to help identify terrain loading issues.
   //! Called when terrain is unavailable during Vortex simulation.
   virtual void detectTerrainFallthrough();
 
   //! \brief Sets the Vortex mechanism's location and orientation
   //!
   //! Sets the Vortex mechanism's transform using the location and heading and
   //! resets wheel parts to be attached to the mechanism.
   //!
   //! \param nwuLocation The location in NWU coordinates
   //! \param heading The heading in radians
   virtual void setVortexMechanismLocation(const Vx::VxVector3& nwuLocation, double heading);
 
   //! \brief Converts local coordinates to Vortex coordinates
   //!
   //! \param inputCoords The coordinates in local database coordinates
   //! \return The corresponding coordinates in NWU (Vortex) coordinates
   Vx::VxVector3 getVortexLocation(const DtVector& inputCoords) const;
 
   //! \brief Sends a vehicle dynamics update event
   //!
   //! Internal function that sends the vehicle dynamics update event to Vortex.
   //!
   //! \param enable True to enable dynamics, false to disable
   virtual void sendVehicleDynamicsUpdate(bool enable);
 
   //! \brief Updates the control state of all vehicle parts
   //!
   //! Sets the control type of all parts to disable or enable collisions and simulation.
   //!
   //! \param control The control type (Static or Dynamic)
   virtual void sendVehiclePartsUpdate(Vx::VxPart::EntityControlTypeEnum control);
 
   //! \brief Adds set callbacks for location and heading
   virtual void addSetCallbacks();
 
   //! \brief Removes set callbacks for location and heading
   virtual void removeSetCallbacks();
 
   //! \brief Callback for heading changes
   //!
   //! \param heading The new heading
   //! \param usrData User data
   static void setHeadingCallback(DtReal heading, void* usrData);
 
   //! \brief Callback for location changes
   //!
   //! \param location The new location
   //! \param usrData User data
   static void setLocationCallback(const DtVector& location, void* usrData);
 
   //! \brief Handles a location change request
   //!
   //! \param location The new location
   virtual void handleSetLocation(const DtVector& location);
 
   //! \brief Handles a heading change request
   //!
   //! \param heading The new heading
   virtual void handleSetHeading(DtReal heading);
 
   //! \brief Resets wheel parts to their default positions
   //!
   //! Resets all wheel parts to zero position on the network.
   virtual void resetWheelParts();
 
   //! \brief Manages wheel part state transitions when entering or exiting Vortex world
   //!
   //! Handles the logic for resetting or restoring wheel parts based on whether the vehicle
   //! is in the Vortex physics simulation. When exiting Vortex, resets wheel parts to prevent
   //! network updates that interfere with VRV automatic wheel control. When entering Vortex,
   //! restores the original wheel part collection.
   //!
   //! \param inVortexWorld True if the vehicle is currently in the Vortex physics world
   virtual void manageWheelPartStateTransitions(bool inVortexWorld);
 
   //! \brief Updates state properties
   virtual void updateState();
 
   //! \brief Restores wheel articulated parts
   //!
   //! Restores wheels in the articulated part collection.
   virtual void restoreWheels();
 
   //! \brief Automatically engages parking brake when disengaging from driver role
   //!
   //! Automatically engages the parking brake when a player disengages from the driver
   //! role if the brake is not already engaged. Simulates a two-tick button press
   //! (down then up) to activate the brake.
   //!
   //! \param isDriver True if currently controlled as driver, false otherwise
   virtual void engageParkingBrakeOnDisengage(bool isDriver);
 
   //! \brief Updates fuel level
   virtual void updateFuel();
 
   virtual void updateDestroyedState();
 
   //! \brief Gets the current fuel level
   //!
   //! \return The amount of fuel left
   virtual double fuelLeft() const;
 
   //! \brief Consumes fuel
   //!
   //! \param fuelUsed The amount of fuel to consume
   virtual void useFuel(double fuelUsed);
 
   //! \brief Creates a Vortex part from a descriptor
   //!
   //! \param desc The part descriptor
   //! \return Pointer to the created part
   DtVortexBasePart* createPart(makVre::DtVortexSimArtPartDescriptor* desc);
 
   //! \brief Creates all Vortex parts defined in the descriptor
   void createVortexPartsFromDescriptor();
 
   //! \brief Sets precision thresholds based on the descriptor
   void setThresholdsFromDescriptor();
 
   //! \brief Updates the ground interaction point under the vehicle
   //!
   //! This is used by the DtGroundVehicleTrailingEffectController to determine
   //! the soil type under the vehicle.
   //!
   //! \param localOrientation Orientation relative to terrain or parent entity
   //! \param localPosition Position relative to terrain or parent entity
   //! \param terrain The attached terrain (database or parent entity)
   //! \param dataAvailable Set to true if terrain data is available
   void updateGroundInteractionPoint(
      const DtDcm& localOrientation, const DtVector& localPosition,
      const DtAttachedTerrain& terrain, bool& dataAvailable) const;
 
   //! \brief Creates Vortex configurations from the descriptor
   //!
   //! Creates a Vortex Configuration from the configuration section of the descriptor.
   void createVortexConfigurationsFromDescriptor();
 
   //! \brief Creates Vortex interfaces defined in the descriptor
   //!
   //! Also creates input/output ports and port groups.
   void createVortexInterfacesFromDescriptor();
 
   //! \brief Connects interfaces to ports
   //!
   //! Connects all the values defined in VHL interfaces to Vortex.
   void connectInterfacesToPorts();
 
   //! \brief Queues the mechanism for loading
   //!
   //! Queues the mechanism to load in a thread-safe manner.
   void queueMechanismLoad();
 
   //! \brief Updates ports with data from Vortex interfaces
   virtual void updatePorts();
 
   //! \brief Recursively finds a part from a path
   //!
   //! \param objectToLookThroughWeak Object to search for the part
   //! \param pathToLookForPart Path defined in the system definition file
   //! \param index Current index in the path
   //! \return Smart pointer to the part, or null if not found
   VxSim::VxSmartInterface<VxDynamics::Part> findPartFromPathRecursive(
      const VxSim::VxWeakInterface<VxSim::IObject>& objectToLookThroughWeak, const std::vector<std::string>& pathToLookForPart,
      int index);
 
   //! \brief Checks if the incoming position is further than distance
   //! \param position incoming position. Pass position in geocentric (DIS)
   //! \param distance distance
   //! \return True if enuPosition is further than distance
   virtual bool checkDistanceFromCoordinateOriginOverLimit(const DtVector& position, double distance);
 
protected:
   // Descriptors and state repos
   const DtVortexMovementActuatorDescriptor* myDescriptor;
   DtGroundVehicleStateRepository* myGroundVehicleState;
   DtVortexStateRepository* myVehicleRepository;
   DtPlatformLocalObjectFacade myPlatformLocalObjectFacade;
   DtArticulatedPartCollection myCollectionWithWheels;
 
   // Vortex
   VxSim::VxSmartInterface<VxDynamics::Mechanism> myMechanism;
   VxSim::VxSmartInterface<DtMechAddon> myMechAddon;
   VxSim::VxExtension* myVehicleExt;
   std::vector<DtVortexBasePart*> myParts;
   VortexInterfaceMap myInterfaces;
   std::shared_ptr<VxSim::VxSimulationFileManagerFacade> mySimulationFileManagerFacade;
   Vx::VxSmartPtr<DtVxSimulationFileManagerFacadeListener> myListener;
 
   // Configuration
   std::shared_ptr<makVre::DtVortexConfiguration> myConfiguration;
 
   // Ports and Port Groups
   DtUpdateRepositoryOutputPortGroup* myUpdateRepositoryOutputPortGroup;
   DtStringOutputPort* myAimingModePort;
 
   bool myWasInVortexWorldLastTick;
 
   bool myWasDriverLastTick;
   bool myAutoParkButtonDown;
   bool myNeedsWheelPartRemoval;
   bool myHaveVortexTurretInterface;
 
   bool myIsVortexDynamicsActive;
   bool mySpawnedFromSpawnPoint;
 
   // For mechanism loading
   enum MechanismLoadStatus
   {
      NOT_LOADED = 0,
      LOADING = 1,
      LOADED = 2
   };
   MechanismLoadStatus myMechanismLoadStatus;
   VxSim::VxUuid myLoadObjectRequestId;
 
   makVre::DtVortexPhysicalWorld* myVortexPhysicalWorld;
 
   double myPositionThreshold;
   double myOrientationThreshold;
   double myVelocityThreshold;
   double myAngularVelocityThreshold;
   double myAccelerationThreshold;
   double myPartPositionThreshold;
   double myPartOrientationThreshold;
   double myPartLinearVelocityThreshold;
   double myPartAngularVelocityThreshold;
   double myDropTimer;
 
   //! \brief Controls whether Vortex physics simulation continues for destroyed entities
   //!
   //! When true, allows Vortex physics to remain active even when the entity is
   //! destroyed or mobility-killed. When false (default), Vortex control is disabled
   //! for destroyed or mobility-killed entities.
   //!
   //! This flag is initialized from the descriptor's allowVortexWhileDestroyed setting
   //! during the actuator initialization phase.
   //!
   //! \note Default value is false.
   //! \see DtVortexMovementActuatorDescriptor::allowVortexWhileDestroyed()
   bool myAllowVortexWhileDestroyed;
 
   //! \brief Controls whether terrain fallthrough detection is enabled
   //!
   //! When true, the actuator monitors for terrain availability issues during Vortex
   //! simulation and logs diagnostic information when fallthrough conditions are detected.
   //! When false (default), fallthrough detection is disabled.
   //!
   //! This flag is initialized from the descriptor's detectTerrainFallthrough setting
   //! during the actuator initialization phase.
   //!
   //! \note Default value is false.
   //! \see DtVortexMovementActuatorDescriptor::detectTerrainFallthrough()
   bool myDetectTerrainFallthrough;
 
   DtVector myPreviousPosition;
   DtTaitBryan myPreviousOrientation;
   DtSymbolString myMovementChooserControllerName;
 
   makVre::DtVortexMovementPSR* myProcessState;
};
 
//! \brief Listener for Vortex file loading events
//!
//! Handles callbacks for file loading operations and notifies the
//! movement actuator when loading is complete.
class DtVxSimulationFileManagerFacadeListener : public VxSim::VxSimulationFileManagerFacade::Listener
{
public:
   //! \brief Constructor
   //!
   //! \param actuator Pointer to the movement actuator
   DtVxSimulationFileManagerFacadeListener(DtVortexMovementActuator* actuator);
 
   //! \brief Destructor
   virtual ~DtVxSimulationFileManagerFacadeListener() override;
 
   //! \brief Called when a requested object has been loaded
   //!
   //! \param requestId Unique ID of the request
   //! \param name Name of the loaded object
   //! \param result Result of the loading operation
   virtual void onRequestedObjectLoaded(const VxSim::VxUuid& requestId, const std::string& name, RequestResult result) override;
 
protected:
   DtVortexMovementActuator* myMovementActuator; //!< The movement actuator
};
 
//! \brief Addon extension for Vortex mechanisms
//!
//! Provides additional functionality for Vortex mechanisms,
//! including pre-step callbacks for synchronizing with VR-Forces.
class DtMechAddon : public VxSim::IExtension, public VxSim::IDynamics, public VxDynamics::IMechanismAddOn
{
public:
   //! \brief Factory key for creating instances of this addon
   static const VxSim::VxFactoryKey kFactoryKey;
 
public:
   //! \brief Constructor
   //!
   //! \param proxy Pointer to the extension proxy
   explicit DtMechAddon(VxSim::VxExtension* proxy);
 
   //! \brief Destructor
   virtual ~DtMechAddon() override;
 
   //! \brief Called before each physics step
   //!
   //! Updates the Vortex mechanism from VR-Forces data.
   virtual void preStep() override;
 
   //! \brief Sets the movement actuator to communicate with
   //!
   //! \param obj Pointer to the movement actuator
   void setVortexMovementActuator(DtVortexMovementActuator* obj);
 
   //! \brief Sets whether updates come from CGF
   //!
   //! \param cgfDriven True if driven by CGF, false if player-controlled
   void setUpdatingFromCGF(bool cgfDriven);
 
protected:
   DtVortexMovementActuator* myMovementActuator; //!< The movement actuator
   bool myUpdatingFromCGF;                       //!< Flag indicating if updates come from CGF
};