artPartActuatorDescriptor.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file artPartActuatorDescriptor.h
//! \ingroup vreVrfobjparam
//! \brief Stabilized articulated part actuator descriptor for VREngage
//!
//! This file defines the DtVreStabilizedArtPartActuatorDescriptor class, which provides
//! configuration parameters for stabilized articulated parts in VREngage. This includes
//! parameters for rotation limits, slew rates, stabilization settings, and player control.
 
#pragma once
 
#include "vreVrfobjparam/export.h"
 
#include <vrfobjparam/actuatorComponentDescriptor.h>
#include <readerWriter/rwReal.h>
#include <readerWriter/rwInt.h>
 
class DtReaderWriterRegistry;
 
//! \brief Type identifier string for the stabilized articulated part actuator descriptor
const char DtVreStabilizedArtPartActuatorDescriptorType[] = "vre-stabilized-art-part-actuator-descriptor";
 
//! \brief Stabilized articulated part actuator descriptor for VREngage
//!
//! This class extends the base actuator component descriptor with additional parameters
//! specific to stabilized articulated parts in VREngage. It provides configuration
//! for rotation limits, slew rates, stabilization settings, and player control roles.
 
//! \brief Stabilized articulated part actuator descriptor for VREngage
//!
//! This class extends the base actuator component descriptor with additional parameters
//! specific to stabilized articulated parts in VREngage. It provides configuration
//! for rotation limits, slew rates, stabilization settings, and player control roles.
class VREVRFOBJPARAM_DLL DtVreStabilizedArtPartActuatorDescriptor : public DtActuatorComponentDescriptor
{
public:
   //! \brief Constructor with component name
   //! \param componentName The name of this component
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //!
   //! Creates a new stabilized articulated part actuator descriptor with the specified name.
   DtVreStabilizedArtPartActuatorDescriptor(const DtString& componentName, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Copy constructor
   //! \param orig The source descriptor to copy from
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //!
   //! Creates a new stabilized articulated part actuator descriptor as a copy of the provided original.
   DtVreStabilizedArtPartActuatorDescriptor(
      const DtVreStabilizedArtPartActuatorDescriptor& orig, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Assignment operator
   //! \param orig The source descriptor to copy from
   //! \return Reference to this descriptor after assignment
   //!
   //! Assigns the contents of the provided descriptor to this one.
   DtVreStabilizedArtPartActuatorDescriptor& operator=(const DtVreStabilizedArtPartActuatorDescriptor& orig);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the descriptor.
   virtual ~DtVreStabilizedArtPartActuatorDescriptor() override;
 
   //! \brief Gets the type identifier for this descriptor
   //! \return String identifying this descriptor type
   //!
   //! Returns a unique type identifier string for this descriptor type.
   virtual DtString type() const override;
 
   //! \brief Creates a clone of this descriptor
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //! \return Pointer to a new descriptor that is a clone of this one
   //!
   //! Creates a new stabilized articulated part actuator descriptor as a deep copy of this one.
   virtual DtComponentDescriptor* clone(DtReaderWriterRegistry* parentRegistry = 0) const override;
 
   //! \brief Gets the rotation axis for this actuator
   //! \return The axis index (0 for azimuth, 1 for elevation, 2 for roll)
   //!
   //! Returns the axis of rotation that this actuator controls.
   virtual DtU16 axis() const;
 
   //! \brief Gets the maximum slew rate
   //! \return The maximum slew rate in radians per second
   //!
   //! Returns the maximum rate at which the articulated part can rotate.
   virtual DtReal maxSlewRate() const;
 
   //! \brief Sets the maximum slew rate
   //! \param maxSlewRate The maximum slew rate in radians per second
   //!
   //! Sets the maximum rate at which the articulated part can rotate.
   virtual void setMaxSlewRate(DtReal maxSlewRate);
 
   //! \brief Checks if the actuator has rotation limits
   //! \return True if the actuator has rotation limits, false otherwise
   //!
   //! Returns whether the articulated part has limited rotation or can rotate freely.
   virtual bool hasLimits() const;
 
   //! \brief Sets whether the actuator has rotation limits
   //! \param hasLimits True to enable rotation limits, false for free rotation
   //!
   //! Sets whether the articulated part has limited rotation or can rotate freely.
   virtual void setHasLimits(bool hasLimits);
 
   //! \brief Gets the upper rotation limit
   //! \return The upper (clockwise) rotation limit in radians
   //!
   //! Returns the maximum clockwise rotation limit for this articulated part.
   virtual DtReal upperLimit() const;
 
   //! \brief Gets the lower rotation limit
   //! \return The lower (counter-clockwise) rotation limit in radians
   //!
   //! Returns the maximum counter-clockwise rotation limit for this articulated part.
   virtual DtReal lowerLimit() const;
 
   //! \brief Checks if slew direction is inverted
   //! \return True if slew direction is inverted, false otherwise
   //!
   //! Returns whether the sense of input relative to slew direction is inverted.
   virtual bool invertSlew() const;
 
   //! \brief Sets whether slew direction is inverted
   //! \param invert True to invert slew direction, false otherwise
   //!
   //! Sets whether the sense of input relative to slew direction is inverted.
   virtual void setInvertSlew(bool invert);
 
   //! \brief Checks if stabilization is enabled by default
   //! \return True if stabilization is enabled by default, false otherwise
   //!
   //! Returns whether the articulated part is stabilized when initialized.
   virtual bool stabilizedByDefault() const;
 
   //! \brief Sets whether stabilization is enabled by default
   //! \param onOff True to enable stabilization by default, false otherwise
   //!
   //! Sets whether the articulated part is stabilized when initialized.
   virtual void setStabilizedByDefault(bool onOff);
 
   //! \brief Gets the player control role
   //! \return String identifying the player role required for control
   //!
   //! Returns the role string required for player control of this actuator.
   virtual DtString playerControlRole() const;
 
   //! \brief Sets the player control role
   //! \param role String identifying the player role required for control
   //!
   //! Sets the role string required for player control of this actuator.
   virtual void setPlayerControlRole(DtString role);
 
   //! \brief Factory function to create a new instance of this descriptor
   //! \return Pointer to a newly created descriptor
   //!
   //! Static factory function used by the descriptor creation system to instantiate
   //! new instances of this descriptor type.
   static DtComponentDescriptor* creator();
 
protected:
   //! \brief Default constructor (not implemented)
   //!
   //! Default constructor is protected and not implemented to prevent
   //! creation of instances without proper initialization.
   DtVreStabilizedArtPartActuatorDescriptor();
 
protected:
   //! \name Configuration Parameters
   //! These parameters are available for setting in the OPD files.
   //! The values are copied to the PSR so that the articulated part controller
   //! can access them during simulation.
   //! @{
 
   //! \brief The rotation axis controlled by this actuator
   //!
   //! Defines which axis of rotation this actuator controls:
   //! - 0: Azimuth (rotation around vertical axis)
   //! - 1: Elevation (rotation around horizontal axis)
   //! - 2: Roll (rotation around longitudinal axis)
   //!
   //! Default value: 0
   DtRwInt myAxis;
 
   //! \brief Maximum rotation rate for the articulated part
   //!
   //! Maximum rate at which the articulated part can rotate.
   //! Units: radians/second
   //!
   //! Default value: 0.0
   DtRwReal myMaxSlewRate;
 
   //! \brief Flag indicating whether rotation limits are enabled
   //!
   //! Indicates whether the articulated part has rotation limits or can rotate freely.
   //!
   //! Default value: False
   DtRwBoolean myHasLimits;
 
   //! \brief Lower (counter-clockwise) rotation limit
   //!
   //! The lower limit (maximum counter-clockwise rotation) of the articulated part.
   //! Zero is taken to be forward (1, 0, 0), and positive angles go clockwise
   //! when viewed from above (because the entity z-axis points down).
   //!
   //! If the part can rotate 360 degrees, both lower and upper limits should be set to 0.0.
   //! If the part is fixed, this lower limit is taken to be the fixed position.
   //!
   //! Units: radians
   //! Default value: 0.0
   DtRwReal myLowerLimit;
 
   //! \brief Upper (clockwise) rotation limit
   //!
   //! The upper limit (maximum clockwise rotation) of the articulated part.
   //! Zero is taken to be forward, and this parameter is ignored if the part is fixed.
   //!
   //! If the part can rotate 360 degrees, both lower and upper limits should be set to 0.0.
   //!
   //! Units: radians
   //! Default value: 0.0
   DtRwReal myUpperLimit;
 
   //! \brief Flag to invert slew direction
   //!
   //! When set to true, inverts the sense of input relative to slew direction.
   //!
   //! Default value: False
   DtRwBoolean myInvertSlew;
 
   //! \brief Flag to enable stabilization by default
   //!
   //! Defines the initial state of articulated part stabilization.
   //! When stabilized, the part maintains its orientation in world space
   //! despite movement of the parent entity.
   //!
   //! Default value: False
   DtRwBoolean myStabilizedByDefault;
 
   //! \brief Player role required for control of this actuator
   //!
   //! Specifies the role string required for player control of this actuator.
   //! This allows for role-based access control to different articulated parts
   //! on a multi-crew entity.
   //!
   //! Default value: "Gunner"
   DtRwString myPlayerControlRole;
 
   //! @}
};