humanJoystickMovementControllerDescriptor.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file humanJoystickMovementControllerDescriptor.h
//! \ingroup vreVrfobjparam
//! \brief Human joystick movement controller descriptor for VREngage
//!
//! This file defines the DtHumanJoystickMovementControllerDescriptor class, which configures
//! joystick-controlled human movement in VREngage. It provides parameters for mapping joystick
//! axes to human entity movement controls, enabling realistic humanoid locomotion via joystick input.
 
#pragma once
 
#include "vreVrfobjparam/export.h"
#include <vrfobjparam/joyDeviceControllerDescriptor.h>
 
namespace makVre
{
//! \brief Type identifier string for the human joystick movement controller descriptor
const char DtHumanJoystickMovementControllerDescriptorType[] = "human-joystick-movement-controller-descriptor";
 
//! \brief Human joystick movement controller descriptor for VREngage
//!
//! This class defines a descriptor for the human joystick movement controller component,
//! which enables human entity movement via joystick input devices. It provides configuration
//! for mapping joystick axes to character movement controls, such as turning rate and
//! forward/backward motion, to create realistic humanoid locomotion in VREngage simulations.
class VREVRFOBJPARAM_DLL DtHumanJoystickMovementControllerDescriptor : public DtJoyDeviceControllerDescriptor
{
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.
   DtHumanJoystickMovementControllerDescriptor(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.
   DtHumanJoystickMovementControllerDescriptor(
      const DtSymbolString& name, DtReaderWriterRegistry* parentRegistry = NULL);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the descriptor.
   virtual ~DtHumanJoystickMovementControllerDescriptor() 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.
   DtHumanJoystickMovementControllerDescriptor(
      const DtHumanJoystickMovementControllerDescriptor& 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.
   DtHumanJoystickMovementControllerDescriptor& operator=(const DtHumanJoystickMovementControllerDescriptor& orig);
 
   //! \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 Gets the type identifier for this descriptor
   //! \return String identifying this descriptor type
   //!
   //! Returns a unique type identifier string for this descriptor type.
   //! Used for creating descriptors from MTL files.
   virtual DtString type() const override;
 
   //! \brief Sets the maximum turning rate
   //! \param rate The maximum turning rate in radians per second
   //!
   //! Sets the maximum rate at which the human entity can turn when controlled by a joystick.
   virtual void setMaxTurningRate(double rate);
 
   //! \brief Gets the maximum turning rate
   //! \return The maximum turning rate in radians per second
   //!
   //! Returns the maximum rate at which the human entity can turn when controlled by a joystick.
   virtual double maxTurningRate() const;
 
   //! \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.
   DtHumanJoystickMovementControllerDescriptor();
 
protected:
   //! \name Configuration Parameters
   //! These parameters are available for setting in the OPD files.
   //! @{
 
   //! \brief Maximum turning rate for the human entity
   //!
   //! Defines the maximum rate at which the human entity can turn when controlled
   //! by a joystick. Higher values allow for faster turning, while lower values
   //! result in more gradual turns.
   //!
   //! Default value: 3.14 (approximately PI)
   //! Units: radians/second
   DtRwReal myMaxTurningRate;
 
   //! @}
};
} // namespace makVre