vreLadderClimbingPSR.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreLadderClimbingPSR.h
//! \ingroup vreVrfobjcore
//! \brief Ladder climbing process state repository for VREngage
//!
//! This file defines the DtVreLadderClimbingPSR class, which provides a process state
//! repository for ladder climbing components in VREngage. It stores the shared and
//! checkpoint-able state for ladder climbing behavior, including the climbing state,
//! ladder access points, and related timing information needed for human entities
//! to realistically climb ladders in the simulation.
 
 
#pragma once
 
#include "vreVrfobjcore/export.h"
#include "vreVrfobjcore/ladder.h"
 
#include <vrfobjcore/vrfProcessStateRepository.h>
 
#include <matrix/vlVector.h>
#include <matrix/vlTaitBryan.h>
 
#include <readerWriter/rwInt.h>
#include <readerWriter/rwReal.h>
#include <readerWriter/rwVector.h>
 
namespace makVre
{
//! \brief Type identifier string for the ladder climbing process state repository
const char DtVreLadderClimbingPSRType[] = "vre-ladder-climbing-psr";
 
//! \brief Default name for the ladder climbing process state repository
const char DtVreLadderClimbingProcessStateRepositoryDefaultName[] =
   "vre-ladder-climbing-process-state-repository-default";
 
//! \brief Enumeration of ladder climbing states
//!
//! Defines the possible states of an entity in relation to ladder climbing.
//! These states are used to control the behavior and animations of the entity
//! throughout the ladder climbing process.
using DtLadderClimbingState = enum DtLadderClimbingState {
   DtOffLadder = 0,         //!< Entity is not on or near a ladder
   DtGettingOnLadder,       //!< Entity is in the process of mounting the ladder
   DtOnLadderAtAccessPoint, //!< Entity is on the ladder at the access point
   DtOnLadder,              //!< Entity is actively climbing the ladder
   DtGettingOffLadder,      //!< Entity is in the process of dismounting the ladder
   DtOffLadderAtExitPoint   //!< Entity has just dismounted and is at the exit point
};
 
//! \brief Process state repository for ladder climbing components
//!
//! This class provides storage and management for ladder climbing state data,
//! including the climbing state, ladder access points, and related timing information.
//! It is used by entities that need to climb ladders in the simulation, particularly
//! human entities, to maintain their state throughout the ladder climbing process.
class VREVRFOBJCORE_DLL DtVreLadderClimbingPSR : public DtVrfProcessStateRepository
{
public:
   //! \brief Constructor with VRF object and optional name
   //! \param vrfObject Pointer to the local object this PSR is associated with
   //! \param rwName Optional reader/writer name
   //! \param parentRegistry Optional parent registry for reader/writer functionality
   //!
   //! Creates a new ladder climbing PSR for the specified VRF object.
   DtVreLadderClimbingPSR(DtLocalObject* vrfObject, const DtString& rwName = DtString::nullString(),
      DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Copy constructor
   //! \param orig The source PSR to copy from
   //! \param rwName Optional reader/writer name
   //! \param parentRegistry Optional parent registry for reader/writer functionality
   //!
   //! Creates a new ladder climbing PSR as a copy of the provided original.
   DtVreLadderClimbingPSR(const DtVreLadderClimbingPSR& orig, const DtString& rwName = DtString::nullString(),
      DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the PSR.
   virtual ~DtVreLadderClimbingPSR() override;
 
   //! \brief Assignment operator (not implemented)
   //! \param orig The source PSR to copy from
   //! \return Reference to this PSR after assignment
   //!
   //! Assignment operator is declared but not implemented to prevent assignment.
   DtVreLadderClimbingPSR& operator=(const DtVreLadderClimbingPSR& orig);
 
   //! \brief Creates a clone of this PSR
   //! \param rwName Optional reader/writer name for the clone
   //! \param parentRegistry Optional parent registry for reader/writer functionality
   //! \return Pointer to a new PSR that is a clone of this one
   //!
   //! Creates a new ladder climbing PSR as a deep copy of this one.
   virtual DtVrfProcessStateRepository* clone(const DtString& rwName = DtString::nullString(),
      DtReaderWriterRegistry* parentRegistry = 0) const override;
 
   //! \brief Gets the type identifier for this PSR
   //! \return String identifying this PSR type
   //!
   //! Returns a unique type identifier string for this PSR type.
   //! Will return DtVreLadderClimbingPSRType.
   virtual DtString type() const override;
 
   //! \brief Sets the ladder climbing state
   //! \param state The new ladder climbing state to set
   //!
   //! Sets the current ladder climbing state of the entity.
   //! This affects how the entity behaves in relation to ladders.
   virtual void setLadderClimbingState(DtLadderClimbingState state);
 
   //! \brief Gets the ladder climbing state
   //! \return The current ladder climbing state
   //!
   //! Returns the current ladder climbing state of the entity.
   virtual DtLadderClimbingState ladderClimbingState() const;
 
   //! \brief Sets the current ladder
   //! \param ladder The ladder object this entity is interacting with
   //!
   //! Sets the ladder that the entity is currently interacting with.
   //! This includes all the ladder's properties such as base, top, and orientation.
   virtual void setLadder(const DtLadder& ladder);
 
   //! \brief Gets the current ladder
   //! \return The ladder object this entity is interacting with
   //!
   //! Returns the ladder that the entity is currently interacting with.
   virtual DtLadder ladder() const;
 
   //! \brief Sets the ladder entry point
   //! \param ladderAccessPoint The position where the entity mounts the ladder
   //!
   //! Sets the position where the entity mounts (gets on) the ladder.
   //! This is typically near the base of the ladder.
   virtual void setLadderEntryPoint(const DtVector& ladderAccessPoint);
 
   //! \brief Gets the ladder entry point
   //! \return The position where the entity mounts the ladder
   //!
   //! Returns the position where the entity mounts (gets on) the ladder.
   virtual DtVector ladderEntryPoint() const;
 
   //! \brief Sets the ladder exit point
   //! \param ladderAccessPoint The position where the entity dismounts the ladder
   //!
   //! Sets the position where the entity dismounts (gets off) the ladder.
   //! This is typically near the top of the ladder for upward climbing.
   virtual void setLadderExitPoint(const DtVector& ladderAccessPoint);
 
   //! \brief Gets the ladder exit point
   //! \return The position where the entity dismounts the ladder
   //!
   //! Returns the position where the entity dismounts (gets off) the ladder.
   virtual DtVector ladderExitPoint() const;
 
   //! \brief Sets the simulation time when the entity will finish mounting the ladder
   //! \param simTime The simulation time in seconds
   //!
   //! Sets the simulation time at which the entity will complete the process
   //! of mounting (getting on) the ladder. Used for timing the transition animation.
   virtual void setTimeToGetOnLadder(double simTime);
 
   //! \brief Gets the simulation time when the entity will finish mounting the ladder
   //! \return The simulation time in seconds
   //!
   //! Returns the simulation time at which the entity will complete the process
   //! of mounting (getting on) the ladder.
   virtual double timeToGetOnLadder() const;
 
   //! \brief Sets the simulation time when the entity will finish dismounting the ladder
   //! \param simTime The simulation time in seconds
   //!
   //! Sets the simulation time at which the entity will complete the process
   //! of dismounting (getting off) the ladder. Used for timing the transition animation.
   virtual void setTimeToGetOffLadder(double simTime);
 
   //! \brief Gets the simulation time when the entity will finish dismounting the ladder
   //! \return The simulation time in seconds
   //!
   //! Returns the simulation time at which the entity will complete the process
   //! of dismounting (getting off) the ladder.
   virtual double timeToGetOffLadder() const;
 
   //! \brief Sets the ladder standoff offset
   //! \param offset The offset vector in local coordinates
   //!
   //! Sets the offset vector used to position the entity relative to the ladder
   //! so that it doesn't appear embedded in the ladder geometry.
   virtual void setLadderStandoffOffset(const DtVector& offset);
 
   //! \brief Gets the ladder standoff offset
   //! \return The offset vector in local coordinates
   //!
   //! Returns the offset vector used to position the entity relative to the ladder.
   virtual DtVector ladderStandoffOffset() const;
 
   //! \brief Sets the entity's orientation when on the ground
   //! \param orientation The orientation in Tait-Bryan angles
   //!
   //! Sets the orientation of the entity when it's on the ground before mounting
   //! the ladder. This is saved to restore the entity's orientation after dismounting.
   virtual void setOrientationOnGround(const DtTaitBryan& orientation);
 
   //! \brief Gets the entity's orientation when on the ground
   //! \return The orientation in Tait-Bryan angles
   //!
   //! Returns the saved orientation of the entity when it was on the ground
   //! before mounting the ladder.
   virtual DtTaitBryan orientationOnGround() const;
 
   //! \brief Sets the terrain height in geodetic coordinates
   //! \param altitude The terrain height in geodetic coordinates
   //!
   //! Sets the height of the terrain in geodetic coordinates at the ladder location.
   //! This is used for positioning calculations when mounting and dismounting the ladder.
   virtual void setTerrainHeightGeodetic(double altitude);
 
   //! \brief Gets the terrain height in geodetic coordinates
   //! \return The terrain height in geodetic coordinates
   //!
   //! Returns the height of the terrain in geodetic coordinates at the ladder location.
   virtual double terrainHeightGeodetic() const;
 
   //! \brief Sets the ladder base position for search operations
   //! \param ladderBase The position of the ladder base in local coordinates
   //!
   //! Sets the position of the ladder base used in findNearestLadder() searches.
   //! This helps optimize ladder searches by providing a starting point.
   virtual void setLadderBaseForSearch(const DtVector& ladderBase);
 
   //! \brief Gets the ladder base position for search operations
   //! \return The position of the ladder base in local coordinates
   //!
   //! Returns the position of the ladder base used in findNearestLadder() searches.
   virtual DtVector ladderBaseForSearch() const;
 
   //! \brief Factory function to create a new instance of this PSR
   //! \param rwName The reader/writer name for the new instance
   //! \param vrfObject Pointer to the local object this PSR will be associated with
   //! \param parentRegistry Parent registry for reader/writer functionality
   //! \return Pointer to a newly created PSR instance
   //!
   //! Static factory function used by the PSR creation system to instantiate
   //! new instances of this PSR type.
   static DtVrfProcessStateRepository* creator(
      const DtString& rwName, DtLocalObject* vrfObject, DtReaderWriterRegistry* parentRegistry);
 
protected:
   //! \brief Current ladder climbing state
   //!
   //! Stores the current state of the entity in relation to ladder climbing.
   //! See DtLadderClimbingState enumeration for possible values.
   DtRwInt myLadderClimbingState;
 
   //! \brief Current ladder being used
   //!
   //! Stores the ladder that the entity is currently interacting with.
   //! This is valid when in the DtOnLadderAtAccessPoint or DtOnLadder states.
   DtLadder myLadder;
 
   //! \brief Ladder entry point
   //!
   //! Stores the position where the entity mounts (gets on) the ladder.
   //! This is typically near the base of the ladder.
   DtRwVector myLadderEntryPoint;
 
   //! \brief Ladder exit point
   //!
   //! Stores the position where the entity dismounts (gets off) the ladder.
   //! This is typically near the top of the ladder for upward climbing.
   DtRwVector myLadderExitPoint;
 
   //! \brief Time to finish mounting the ladder
   //!
   //! Stores the simulation time at which the entity will complete the process
   //! of mounting (getting on) the ladder. Used for timing the transition animation.
   DtRwReal myTimeToGetOnLadder;
 
   //! \brief Time to finish dismounting the ladder
   //!
   //! Stores the simulation time at which the entity will complete the process
   //! of dismounting (getting off) the ladder. Used for timing the transition animation.
   DtRwReal myTimeToGetOffLadder;
 
   //! \brief Ladder standoff offset
   //!
   //! Stores the offset vector in local coordinates, used to position the entity
   //! such that it doesn't appear embedded in the ladder geometry.
   DtRwVector myLadderStandoffOffset;
 
   //! \brief Entity orientation when on the ground
   //!
   //! Stores the orientation of the entity when it's on the ground before mounting
   //! the ladder. This is used to restore the entity's orientation after dismounting.
   DtTaitBryan myOrientationOnGround;
 
   //! \brief Terrain height in geodetic coordinates
   //!
   //! Stores the height of the terrain in geodetic coordinates at the ladder location.
   //! This is used for positioning calculations when mounting and dismounting the ladder.
   DtRwReal myTerrainHeightGeodetic;
 
   //! \brief Ladder base for search operations
   //!
   //! Stores the position of the ladder base used in findNearestLadder() searches.
   //! This helps optimize ladder searches by providing a starting point.
   DtRwVector myLadderBaseForSearch;
};
 
} // namespace makVre