vortexMovementActuatorDescriptor.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vortexMovementActuatorDescriptor.h
//! \brief Defines DtVortexMovementActuatorDescriptor for Vortex physics-based movement simulation
//! \ingroup vreVrfVortexObjparam
 
#pragma once
 
#include "vreVrfVortexObjparam/export.h"
#include "vreVrfVortexObjparam/vortexArtPartDescriptorList.h"
#include "vreVrfVortexObjparam/vortexInterfaceDescriptor.h"
#include "vreVrfVortexObjparam/vortexConfigurationDescriptor.h"
 
#include <vrfobjparam/actuatorComponentDescriptor.h>
#include <vrfutil/rwResource.h>
 
//! \brief Type identifier string for the DtVortexMovementActuatorDescriptor class
const char DtVortexMovementActuatorDescriptorType[] = "vortex-movement-actuator-descriptor";
 
//! \brief Descriptor for Vortex physics-based movement simulation
//!
//! DtVortexMovementActuatorDescriptor provides configuration for a Vortex physics-based
//! movement actuator. It stores the mechanism name, articulated part mappings, interface
//! descriptors, and configuration parameters for the Vortex physics engine. It also defines
//! various thresholds for position, orientation, velocity, and other physics properties
//! that control when updates are triggered.
//!
//! This descriptor is used for configuring vehicle movement and other entity physics
//! in the simulation using the Vortex physics engine.
class VREVRFVORTEXOBJPARAM_DLL DtVortexMovementActuatorDescriptor : public DtActuatorComponentDescriptor
{
private:
   //! \brief Default constructor (not implemented)
   //!
   //! Private to prevent use - requires component name
   DtVortexMovementActuatorDescriptor();
 
public:
   //! \brief Constructor with component name and registry
   //! \param componentName Name of the actuator component
   //! \param parentRegistry Optional parent registry for reader/writer operations
   DtVortexMovementActuatorDescriptor(const DtString& componentName, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Constructor with symbol component name and registry
   //! \param componentName Symbol string name of the actuator component
   //! \param parentRegistry Optional parent registry for reader/writer operations
   DtVortexMovementActuatorDescriptor(
      const DtSymbolString& componentName, DtReaderWriterRegistry* parentRegistry = NULL);
 
   //! \brief Copy constructor
   //! \param orig Original actuator descriptor to copy from
   //! \param parentRegistry Optional parent registry for reader/writer operations
   DtVortexMovementActuatorDescriptor(
      const DtVortexMovementActuatorDescriptor& orig, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Virtual destructor
   virtual ~DtVortexMovementActuatorDescriptor() override;
 
   //! \brief Assignment operator
   //! \param orig Original actuator descriptor to copy from
   //! \return Reference to this actuator descriptor after assignment
   DtVortexMovementActuatorDescriptor& operator=(const DtVortexMovementActuatorDescriptor& orig);
 
   //! \brief Gets the type of this component descriptor
   //! \return The type string for this component descriptor
   //!
   //! Implementation of the DtComponentDescriptor::type() method
   virtual DtString type() const override;
 
   //! \brief Creates a clone of this actuator descriptor
   //! \param parentRegistry Optional parent registry for reader/writer operations
   //! \return Pointer to a new descriptor that is a copy of this one
   //!
   //! Implementation of the DtComponentDescriptor::clone() method
   virtual DtComponentDescriptor* clone(DtReaderWriterRegistry* parentRegistry = 0) const override;
 
   //! \brief Factory method for creating instances of this class
   //! \return Pointer to a new default instance of this descriptor
   //!
   //! Implementation of the DtComponentDescriptor::creator() method
   static DtComponentDescriptor* creator();
 
   //! \brief Gets the name of the Vortex mechanism
   //! \return The name of the mechanism file used by this actuator
   virtual std::string mechanismName() const;
 
   //! \brief Sets the name of the Vortex mechanism
   //! \param name The name of the mechanism file to use
   virtual void setMechanismName(const std::string& name);
 
   //! \brief Sets the list of Vortex articulated part descriptors
   //! \param artPartDescriptorList The list of articulated part descriptors to set
   //!
   //! Defines the articulated parts that will be mapped to Vortex physics components
   virtual void setVortexArtPartDescriptorList(const makVre::DtVortexSimArtPartDescriptorList& artPartDescriptorList);
 
   //! \brief Gets the list of Vortex articulated part descriptors
   //! \return Constant reference to the list of articulated part descriptors
   virtual const makVre::DtVortexSimArtPartDescriptorList& vortexArtPartDescriptorList() const;
 
   //! \brief Sets the list of Vortex interface descriptors
   //! \param interfaceDescriptorList The list of interface descriptors to set
   //!
   //! Defines the interfaces for communication with the Vortex physics engine
   virtual void setVortexInterfaceDescriptorList(
      const makVre::DtVortexInterfaceDescriptorList& interfaceDescriptorList);
 
   //! \brief Gets the list of Vortex interface descriptors
   //! \return Constant reference to the list of interface descriptors
   virtual const makVre::DtVortexInterfaceDescriptorList& vortexInterfaceDescriptorList() const;
 
   //! \brief Sets the Vortex configuration descriptor
   //! \param configurationDescriptor The configuration descriptor to set
   //!
   //! Defines the configuration parameters for the Vortex physics engine
   virtual void setVortexConfigurationDescriptor(
      const makVre::DtVortexConfigurationDescriptor& configurationDescriptor);
 
   //! \brief Gets the Vortex configuration descriptor
   //! \return Constant reference to the configuration descriptor
   virtual const makVre::DtVortexConfigurationDescriptor& vortexConfigurationDescriptor() const;
 
   //! \brief Gets the position threshold value
   //! \return The threshold value for position updates in meters
   //!
   //! Position changes below this threshold will not trigger updates
   virtual double positionThreshold() const;
 
   //! \brief Sets the position threshold value
   //! \param val The threshold value to set for position updates in meters
   virtual void setPositionThreshold(double val);
 
   //! \brief Gets the orientation threshold value
   //! \return The threshold value for orientation updates in radians
   //!
   //! Orientation changes below this threshold will not trigger updates
   virtual double orientationThreshold() const;
 
   //! \brief Sets the orientation threshold value
   //! \param val The threshold value to set for orientation updates in radians
   virtual void setOrientationThreshold(double val);
 
   //! \brief Gets the velocity threshold value
   //! \return The threshold value for velocity updates in meters per second
   //!
   //! Velocity changes below this threshold will not trigger updates
   virtual double velocityThreshold() const;
 
   //! \brief Sets the velocity threshold value
   //! \param val The threshold value to set for velocity updates in meters per second
   virtual void setVelocityThreshold(double val);
 
   //! \brief Gets the angular velocity threshold value
   //! \return The threshold value for angular velocity updates in radians per second
   //!
   //! Angular velocity changes below this threshold will not trigger updates
   virtual double angularVelocityThreshold() const;
 
   //! \brief Sets the angular velocity threshold value
   //! \param val The threshold value to set for angular velocity updates in radians per second
   virtual void setAngularVelocityThreshold(double val);
 
   //! \brief Gets the acceleration threshold value
   //! \return The threshold value for acceleration updates in meters per second squared
   //!
   //! Acceleration changes below this threshold will not trigger updates
   virtual double accelerationThreshold() const;
 
   //! \brief Sets the acceleration threshold value
   //! \param val The threshold value to set for acceleration updates in meters per second squared
   virtual void setAccelerationThreshold(double val);
 
   //! \brief Gets the articulated part position threshold value
   //! \return The threshold value for part position updates in meters
   //!
   //! Part position changes below this threshold will not trigger updates
   virtual double partPositionThreshold() const;
 
   //! \brief Sets the articulated part position threshold value
   //! \param val The threshold value to set for part position updates in meters
   virtual void setPartPositionThreshold(double val);
 
   //! \brief Gets the articulated part orientation threshold value
   //! \return The threshold value for part orientation updates in radians
   //!
   //! Part orientation changes below this threshold will not trigger updates
   virtual double partOrientationThreshold() const;
 
   //! \brief Sets the articulated part orientation threshold value
   //! \param val The threshold value to set for part orientation updates in radians
   virtual void setPartOrientationThreshold(double val);
 
   //! \brief Gets the articulated part velocity threshold value
   //! \return The threshold value for part velocity updates in meters per second
   //!
   //! Part velocity changes below this threshold will not trigger updates
   virtual double partVelocityThreshold() const;
 
   //! \brief Sets the articulated part velocity threshold value
   //! \param val The threshold value to set for part velocity updates in meters per second
   virtual void setPartVelocityThreshold(double val);
 
   //! \brief Gets the articulated part angular velocity threshold value
   //! \return The threshold value for part angular velocity updates in radians per second
   //!
   //! Part angular velocity changes below this threshold will not trigger updates
   virtual double partAngularVelocityThreshold() const;
 
   //! \brief Sets the articulated part angular velocity threshold value
   //! \param val The threshold value to set for part angular velocity updates in radians per second
   virtual void setPartAngularVelocityThreshold(double val);
 
   //! \brief Gets the extended data threshold value
   //! \return The threshold value for extended data updates
   //!
   //! Extended data changes below this threshold will not trigger updates
   virtual double extendedDataThreshold() const;
 
   //! \brief Sets the extended data threshold value
   //! \param val The threshold value to set for extended data updates
   virtual void setExtendedDataThreshold(double val);
 
   //! \brief Sets whether to use articulated part wheel positions
   //! \param yesNo True to use wheel positions from articulated parts, false to use positions from Vortex model
   //!
   //! When true, wheel positions in the Vortex model will be adjusted to match the positions
   //! specified in articulated parts. When false, the wheel positions in the Vortex model
   //! are used as-is. Default is true.
   virtual void setUseArtPartWheelPositions(const bool yesNo);
 
   //! \brief Checks if articulated part wheel positions are being used
   //! \return True if wheel positions from articulated parts are being used, false otherwise
   virtual bool useArtPartWheelPositions() const;
 
   //! \brief Sets whether to use mass from the entity
   //! \param yesNo True to use mass from entity definition, false to use mass from Vortex model
   //!
   //! When true, the Vortex model will use the mass value specified in the entity definition.
   //! When false, the mass value defined in the Vortex mechanism model is used as-is.
   virtual void setUseMassFromEntity(const bool yesNo);
 
   //! \brief Checks if entity mass is being used instead of Vortex model mass
   //! \return True if mass from entity definition is being used, false if Vortex model mass is used
   virtual bool useMassFromEntity() const;
 
   //! \brief Gets the fuel efficiency value
   //! \return The fuel efficiency value in fuel units per distance traveled
   //!
   //! Determines how much fuel is consumed when a ground vehicle moves
   virtual double fuelEfficiency() const;
 
   //! \brief Sets the fuel efficiency value
   //! \param d The fuel efficiency value in fuel units per distance traveled
   virtual void setFuelEfficiency(double d);
 
   //! \brief Gets the additional height to add when dropping a vehicle above terrain
   //! \return The additional drop height in meters (default: 0.5)
   //!
   //! This value is used by dropAboveTerrain() to position the vehicle slightly above
   //! the calculated terrain height to prevent the vehicle from getting stuck in or
   //! clipping through the terrain surface.
   //!
   //! \see setAdditionalDropHeight()
   //! \see DtVortexMovementActuator::dropAboveTerrain()
   virtual double additionalDropHeight() const;
 
   //! \brief Sets the additional height to add when dropping a vehicle above terrain
   //! \param d The additional drop height in meters (default: 0.5)
   //!
   //! Configures the vertical offset added to the terrain height when positioning
   //! a vehicle using dropAboveTerrain(). This ensures the vehicle spawns slightly
   //! above the terrain to avoid intersection issues.
   //!
   //! \see additionalDropHeight()
   //! \see DtVortexMovementActuator::dropAboveTerrain()
   virtual void setAdditionalDropHeight(double d);
 
   //! Accessor/mutator for #myFuelType.
   //! @{
   virtual const DtEntityType& fuelType() const;
   virtual void setFuelType(const DtEntityType& fuelType);
   //! @}
 
   //! \brief Gets the allow-vortex-while-destroyed flag
   //! \return True if Vortex physics should continue for destroyed entities, false otherwise
   //!
   //! When this flag is true, Vortex physics simulation will remain active even when
   //! the entity is destroyed or mobility-killed. This allows for realistic physics
   //! behavior of destroyed vehicles (e.g., continued rolling, settling, debris physics).
   //!
   //! When false (default), Vortex control is disabled for destroyed or mobility-killed
   //! entities, and the entity uses standard movement behavior.
   //!
   //! \note Default value is false.
   //! \see setAllowVortexWhileDestroyed()
   virtual bool allowVortexWhileDestroyed() const;
 
   //! \brief Sets the allow-vortex-while-destroyed flag
   //! \param allow True to allow Vortex physics for destroyed entities, false to disable
   //!
   //! Controls whether Vortex physics simulation continues when the entity is destroyed
   //! or mobility-killed. Set to true to enable realistic post-destruction physics
   //! (vehicle settling, rolling, etc.). Set to false to use standard movement behavior
   //! for destroyed entities.
   //!
   //! This setting is read during the actuator's initialization phase and stored in
   //! the actuator's myAllowVortexWhileDestroyed member variable.
   //!
   //! \note The default is false, which disables Vortex for destroyed entities.
   //! \see allowVortexWhileDestroyed()
   virtual void setAllowVortexWhileDestroyed(bool allow);
 
   //! \brief Gets the detect-terrain-fallthrough flag
   //! \return True if terrain fallthrough detection is enabled, false otherwise
   //!
   //! When this flag is true, the actuator will check for terrain availability during
   //! Vortex simulation and log diagnostic information when the vehicle falls through
   //! the terrain due to missing terrain data.
   //!
   //! When false (default), terrain fallthrough detection is disabled.
   //!
   //! \note Default value is false.
   //! \see setDetectTerrainFallthrough()
   virtual bool detectTerrainFallthrough() const;
 
   //! \brief Sets the detect-terrain-fallthrough flag
   //! \param detect True to enable terrain fallthrough detection, false to disable
   //!
   //! Controls whether the actuator monitors for terrain fallthrough conditions.
   //! When enabled, the actuator will check terrain availability and log warnings
   //! when the vehicle position indicates a fall-through scenario.
   //!
   //! This setting is read during the actuator's initialization phase.
   //!
   //! \note The default is false, which disables fallthrough detection.
   //! \see detectTerrainFallthrough()
   virtual void setDetectTerrainFallthrough(bool detect);
 
protected:
   //! \brief The name of the Vortex mechanism file
   DtRwString myMechanismFilename;
 
   //! \brief Flag indicating whether to use wheel positions from articulated parts
   DtRwBoolean myUseArtPartWheelPositions;
 
   //! \brief Flag indicating whether to use wheel positions from articulated parts
   DtRwBoolean myUseMassFromEntity;
 
   //! \brief List of articulated part descriptors for Vortex physics
   makVre::DtVortexSimArtPartDescriptorList myVortexArtPartDescriptorList;
 
   //! \brief List of interface descriptors for communication with Vortex
   makVre::DtVortexInterfaceDescriptorList myVortexInterfaceDescriptorList;
 
   //! \brief Configuration descriptor for Vortex physics parameters
   makVre::DtVortexConfigurationDescriptor myVortexConfigurationDescriptor;
 
   //! \brief Threshold for vehicle position updates in meters
   DtRwReal myPositionThreshold;
 
   //! \brief Threshold for vehicle orientation updates in radians
   DtRwReal myOrientationThreshold;
 
   //! \brief Threshold for vehicle velocity updates in meters per second
   DtRwReal myVelocityThreshold;
 
   //! \brief Threshold for vehicle angular velocity updates in radians per second
   DtRwReal myAngularVelocityThreshold;
 
   //! \brief Threshold for articulated part position updates in meters
   DtRwReal myPartPositionThreshold;
 
   //! \brief Threshold for articulated part orientation updates in radians
   DtRwReal myPartOrientationThreshold;
 
   //! \brief Threshold for vehicle acceleration updates in meters per second squared
   DtRwReal myAccelerationThreshold;
 
   //! \brief Threshold for articulated part velocity updates in meters per second
   DtRwReal myPartLinearVelocityThreshold;
 
   //! \brief Threshold for articulated part angular velocity updates in radians per second
   DtRwReal myPartAngularVelocityThreshold;
 
   //! Parameter Name: fuel-type\n
   //! Parameter Description: The fuel that will be consumed by the surface vessel.\n
   //! Parameter Default Value: 6:3:0:2:1:0:0 Gasoline\n
   //! Parameter Units: Entity Type\n
   DtRwResource myFuelType;
 
   //! \brief Fuel efficiency value in fuel units per distance traveled
   //!
   //! When a ground vehicle moves, this determines how much fuel is consumed.
   //! The value is dependent on the unit of measurement of the resource.
   //! Default value is 100.
   DtRwReal myFuelEfficiency;
 
   //! \brief Threshold for extended data updates
   //!
   //! Controls the rate at which extended data changes trigger updates.
   DtRwReal myExtendedDataThreshold;
 
   //! \brief Controls whether Vortex physics continues for destroyed entities
   //!
   //! When true, Vortex physics simulation remains active even when the entity
   //! is destroyed or mobility-killed. When false (default), Vortex control
   //! is disabled for destroyed or mobility-killed entities.
   //!
   //! This setting allows for realistic post-destruction physics behavior, such as
   //! a destroyed vehicle continuing to roll down a hill or settle into position.
   //!
   //! The value is read by DtVortexMovementActuator during initialization and
   //! affects the entity's physics simulation behavior.
   //!
   //! \note Default value is false.
   //! \see allowVortexWhileDestroyed()
   //! \see setAllowVortexWhileDestroyed()
   DtRwBoolean myAllowVortexWhileDestroyed;
 
   //! \brief Controls whether terrain fallthrough detection is enabled
   //!
   //! When true, the actuator monitors terrain availability during Vortex simulation
   //! and logs diagnostic information when terrain fallthrough is detected. When false
   //! (default), fallthrough detection is disabled.
   //!
   //! This setting is read by DtVortexMovementActuator during initialization and
   //! controls whether detectTerrainFallthrough() is called during simulation.
   //!
   //! \note Default value is false.
   //! \see detectTerrainFallthrough()
   //! \see setDetectTerrainFallthrough()
   DtRwBoolean myDetectTerrainFallthrough;
 
   //! \brief Additional height offset applied when dropping vehicles above terrain
   //!
   //! Specifies the vertical distance (in meters) to add above the calculated terrain
   //! height when positioning a vehicle using dropAboveTerrain(). This offset prevents
   //! the vehicle from spawning at exactly the terrain surface level, which could cause
   //! clipping or intersection issues with the terrain geometry.
   //!
   //! The value is used by DtVortexMovementActuator::dropAboveTerrain() to ensure
   //! the vehicle's lowest bounding point is positioned slightly above the terrain.
   //!
   //! Sysdef parameter: `additional-drop-height`
   //!
   //! \note Default value is 0.5 meters.
   //! \see additionalDropHeight()
   //! \see setAdditionalDropHeight()
   //! \see DtVortexMovementActuator::dropAboveTerrain()
   DtRwReal myAdditionalHeightToDrop;
};