vreHumanJoystickMovementControllerDescriptor.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreHumanJoystickMovementControllerDescriptor.h
//! \ingroup vreVrfobjparam
//! \brief Human joystick movement controller descriptor for VREngage
//!
//! This file defines the DtVreHumanJoystickMovementControllerDescriptor class, which configures
//! human joystick movement controller components in VREngage. It extends the base human joystick
//! movement controller descriptor to add speed multipliers for different postures (prone, kneeling,
//! and crouching).
 
#pragma once
#include "vreVrfobjparam/humanJoystickMovementControllerDescriptor.h"
 
#include <vreVrfobjparam/export.h>
 
namespace makVre
{
//! \brief Type identifier string for the human joystick movement controller descriptor
const char DtVreHumanJoystickMovementControllerDescriptorType[] = "vre-human-joystick-movement-controller-descriptor";
 
//! \brief Human joystick movement controller descriptor for VREngage
//!
//! This class extends the base human joystick movement controller descriptor to add
//! configuration for posture-specific speed multipliers. It allows the movement speed
//! of human entities to be adjusted based on their current posture (prone, kneeling,
//! or crouching), creating more realistic movement behavior in VREngage simulations.
class VREVRFOBJPARAM_DLL DtVreHumanJoystickMovementControllerDescriptor
   : public DtHumanJoystickMovementControllerDescriptor
{
public:
   //! \brief Constructor with component name
   //! \param name The name of this component
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //!
   //! Creates a new human joystick movement controller descriptor with the specified name.
   DtVreHumanJoystickMovementControllerDescriptor(const DtString& name, DtReaderWriterRegistry* parentRegistry = NULL);
 
   //! \brief Constructor with component name as symbol string
   //! \param name The name of this component as a symbol string
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //!
   //! Creates a new human joystick movement controller descriptor with the specified name.
   DtVreHumanJoystickMovementControllerDescriptor(
      const DtSymbolString& name, DtReaderWriterRegistry* parentRegistry = NULL);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the descriptor.
   virtual ~DtVreHumanJoystickMovementControllerDescriptor() override;
 
   //! \brief Copy constructor
   //! \param orig The source descriptor to copy from
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //!
   //! Creates a new human joystick movement controller descriptor as a copy of the provided original.
   DtVreHumanJoystickMovementControllerDescriptor(
      const DtVreHumanJoystickMovementControllerDescriptor& orig, DtReaderWriterRegistry* parentRegistry = NULL);
 
   //! \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.
   DtVreHumanJoystickMovementControllerDescriptor& operator=(
      const DtVreHumanJoystickMovementControllerDescriptor& orig);
 
   //! \brief Gets the type identifier for this descriptor
   //! \return String identifying this descriptor type
   //!
   //! Returns a unique type identifier string for this descriptor type.
   //! Will return DtVreHumanJoystickMovementControllerDescriptorType.
   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 human joystick movement controller descriptor as a deep copy of this one.
   virtual DtComponentDescriptor* clone(DtReaderWriterRegistry* parentRegistry = NULL) const override;
 
   //! \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();
 
   //! \brief Gets the prone speed multiplier
   //! \return The speed multiplier for prone posture
   //!
   //! Returns the multiplier applied to movement speed when the entity is in prone posture.
   //! A value of 1.0 represents normal speed, values less than 1.0 reduce speed, and
   //! values greater than 1.0 increase speed.
   virtual double proneSpeedMultiplier() const;
 
   //! \brief Sets the prone speed multiplier
   //! \param val The speed multiplier for prone posture
   //!
   //! Sets the multiplier applied to movement speed when the entity is in prone posture.
   //! A value of 1.0 represents normal speed, values less than 1.0 reduce speed, and
   //! values greater than 1.0 increase speed.
   virtual void setProneSpeedMultiplier(double val);
 
   //! \brief Gets the kneeling speed multiplier
   //! \return The speed multiplier for kneeling posture
   //!
   //! Returns the multiplier applied to movement speed when the entity is in kneeling posture.
   //! A value of 1.0 represents normal speed, values less than 1.0 reduce speed, and
   //! values greater than 1.0 increase speed.
   virtual double kneelingSpeedMultiplier() const;
 
   //! \brief Sets the kneeling speed multiplier
   //! \param val The speed multiplier for kneeling posture
   //!
   //! Sets the multiplier applied to movement speed when the entity is in kneeling posture.
   //! A value of 1.0 represents normal speed, values less than 1.0 reduce speed, and
   //! values greater than 1.0 increase speed.
   virtual void setKneelingSpeedMultiplier(double val);
 
   //! \brief Gets the crouching speed multiplier
   //! \return The speed multiplier for crouching posture
   //!
   //! Returns the multiplier applied to movement speed when the entity is in crouching posture.
   //! A value of 1.0 represents normal speed, values less than 1.0 reduce speed, and
   //! values greater than 1.0 increase speed.
   virtual double crouchingSpeedMultiplier() const;
 
   //! \brief Sets the crouching speed multiplier
   //! \param val The speed multiplier for crouching posture
   //!
   //! Sets the multiplier applied to movement speed when the entity is in crouching posture.
   //! A value of 1.0 represents normal speed, values less than 1.0 reduce speed, and
   //! values greater than 1.0 increase speed.
   virtual void setCrouchingSpeedMultipler(double val);
 
 
protected:
   //! \brief Default constructor (not implemented)
   //!
   //! Default constructor is protected and not implemented to prevent
   //! creation of instances without proper initialization.
   DtVreHumanJoystickMovementControllerDescriptor();
 
   //! \brief Speed multiplier for prone posture
   //!
   //! Multiplier applied to movement speed when the entity is in prone posture.
   //! A value of 1.0 represents normal speed, values less than 1.0 reduce speed,
   //! and values greater than 1.0 increase speed.
   DtRwReal myProneSpeedMultiplier;
 
   //! \brief Speed multiplier for kneeling posture
   //!
   //! Multiplier applied to movement speed when the entity is in kneeling posture.
   //! A value of 1.0 represents normal speed, values less than 1.0 reduce speed,
   //! and values greater than 1.0 increase speed.
   DtRwReal myKneelingSpeedMultiplier;
 
   //! \brief Speed multiplier for crouching posture
   //!
   //! Multiplier applied to movement speed when the entity is in crouching posture.
   //! A value of 1.0 represents normal speed, values less than 1.0 reduce speed,
   //! and values greater than 1.0 increase speed.
   DtRwReal myCrouchingSpeedMultiplier;
};
 
} // namespace makVre