ladderLocator.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file ladderLocator.h
//! \ingroup vreVrfobjcore
//! \brief Ladder locator class for VREngage
//!
//! This file defines the DtLadderLocator class, which provides functionality for finding
//! the nearest ladder and its access points in VREngage simulations. It enables human entities
//! to locate and interact with nearby ladders for climbing operations.
 
#pragma once
 
#include "vreVrfobjcore/export.h"
 
#include <matrix/vlVector.h>
 
#include <vlutil/vlString.h>
 
class DtVrfNavAreaManager;
class DtPhysicalWorld;
 
namespace makVre
{
class DtLadder;
 
//! \brief Helper class for finding ladders and their access points in simulations
//!
//! This class provides functionality to locate the nearest ladder and determine
//! the optimal access points (points at which a human could mount or dismount a ladder).
//! It works with the navigation system to find and prepare ladder data for use by
//! human entities that need to climb ladders in the simulation.
class VREVRFOBJCORE_DLL DtLadderLocator
{
public:
   //! \brief Constructor with navigation area manager and profile
   //! \param navAreaManager Reference to the simulation manager's navigation area manager
   //! \param navigationProfile The string name of the navigation profile
   //!
   //! Creates a new ladder locator with the specified navigation area manager and profile.
   //! The navigation profile is typically available in the parameter entry for a given
   //! entity type (e.g., "lifeform") and determines navigational capabilities.
   DtLadderLocator(DtVrfNavAreaManager& navAreaManager, const DtString& navigationProfile);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the ladder locator.
   virtual ~DtLadderLocator();
 
   //! \brief Sets the area to search for nearby ladders
   //! \param localPosition The center position of the search area in local coordinates
   //! \param range The search radius in meters
   //!
   //! Defines the area in which to search for ladders. This can be called repeatedly
   //! to change the search area as needed, such as when the entity moves to a new location.
   //! The search area is defined as a sphere with the specified position as its center
   //! and the specified range as its radius.
   virtual void setSearchArea(const DtVector& localPosition, double range);
 
   //! \brief Finds the nearest ladder and its access point
   //! \param physicalWorld Reference to the physical world for terrain queries
   //! \param ladder Reference to a ladder object to be filled with the found ladder data
   //! \param ladderAccessPoint Reference to a vector to be filled with the nearest access point
   //! \return True if a ladder was found within the search area, false otherwise
   //!
   //! Searches for the nearest ladder within the previously set search area.
   //! If a ladder is found, the ladder parameter is filled with the ladder data,
   //! and the ladderAccessPoint parameter is filled with the coordinates of the
   //! nearest point at which an entity could access (mount/dismount) the ladder.
   virtual bool findNearestLadder(
      const DtPhysicalWorld& physicalWorld, DtLadder& ladder, DtVector& ladderAccessPoint) const;
 
private:
   //! \brief Default constructor (not implemented)
   //!
   //! Default constructor is private and not implemented to prevent
   //! creation of instances without proper initialization.
   DtLadderLocator();
 
   //! \brief Copy constructor (not implemented)
   //! \param orig The source locator to copy from
   //!
   //! Copy constructor is private and not implemented to prevent copying.
   DtLadderLocator(const DtLadderLocator& orig);
 
   //! \brief Assignment operator (not implemented)
   //! \param orig The source locator to copy from
   //! \return Reference to this locator after assignment
   //!
   //! Assignment operator is private and not implemented to prevent assignment.
   DtLadderLocator& operator=(const DtLadderLocator& orig);
 
protected:
   //! \brief Reference to the navigation area manager
   //!
   //! Cached reference to the navigation area manager that provides access to
   //! navigation areas and ladders in the simulation.
   DtVrfNavAreaManager& myNavAreaManager;
 
   //! \brief Navigation profile for ladder searches
   //!
   //! The navigation profile to use in searches, typically available in the
   //! object parameter entry for a given entity type (e.g., "lifeform").
   //! This determines which navigation areas are accessible to the entity.
   DtString myNavigationProfile;
 
   //! \brief Origin of the current search area
   //!
   //! The center position of the current ladder search area in local coordinates.
   DtVector mySearchAreaOrigin;
 
   //! \brief Radius of the current search area
   //!
   //! The radius in meters defining the current ladder search area.
   double mySearchAreaRadius;
};
} // namespace makVre