vreRtdTerrainQueryHighFidelity.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreRtdTerrainQueryHighFidelity.h
//! \ingroup vreVrfRtd
//! \brief High-fidelity terrain query implementation for VREngage
//!
//! This file defines the DtVreRtdTerrainQueryHighFidelity class, which provides
//! high-fidelity terrain and object intersection queries for the VREngage
//! Real-Time Dynamics system, supporting ground contact and collision detection.
 
#pragma once
 
#include <vreVrfRtd/vreRtdBackendLibCommon.h>
#include <vreVrfRtd/vreRtdTraitTerrainQuery.h>
#include <RTD/TraitGroundContact.h>
 
namespace vreRtd
{
//! \brief High-fidelity terrain query implementation for VREngage
//!
//! This class provides high-fidelity terrain and object intersection queries
//! for the VREngage Real-Time Dynamics system. It detects collisions with terrain
//! and simulation objects, and provides detailed information about hits including
//! position, normal vectors, velocity, and surface properties like friction.
//! This is used primarily for ground contact detection in flight models.
class RTD_VRF_BACKEND_PLUGIN_EXPORT DtVreRtdTerrainQueryHighFidelity : public RTD::TerrainQueryCallback,
                                                                       public DtVreRtdTraitTerrainQuery
{
public:
   //! \brief Macro for common RTD type definitions
   RTD_BASE_COMMON(vreRtd, DtVreRtdTerrainQueryHighFidelity);
 
   //! \brief Constructor
   //! \param pw Pointer to the physical world instance to query against
   //! \param blocking Whether terrain queries should block until completed
   //!
   //! Initializes a new high-fidelity terrain query handler with the specified
   //! physical world and blocking behavior.
   DtVreRtdTerrainQueryHighFidelity(DtPhysicalWorld* pw, bool blocking);
 
   //! \brief Destructor
   //!
   //! Cleans up resources used by the terrain query handler.
   virtual ~DtVreRtdTerrainQueryHighFidelity() override;
   //! \brief Performs a terrain query between two points
   //! \param context The query context (ground contact, sensor, etc.)
   //! \param contextData Additional context-specific data
   //! \param userData User-provided terrain query data
   //! \param start The start point of the query in world coordinates
   //! \param end The end point of the query in world coordinates
   //! \param hitXYZ Output parameter for the hit position
   //! \param hitNormal Output parameter for the surface normal at the hit position
   //! \param hitVelocity Output parameter for the velocity of the hit object (if moving)
   //! \param frictionFactor Output parameter for the surface friction factor
   //! \param isLiquid Output parameter indicating whether the hit surface is liquid
   //! \param entity Output parameter for the entity that was hit (if any)
   //! \return True if an intersection was found, false otherwise
   //!
   //! Performs a high-fidelity terrain query between the specified start and end points,
   //! checking for intersections with both terrain and simulation objects. If an
   //! intersection is found, the output parameters are populated with the hit details.
   virtual bool query(QueryContext context, const void* contextData, const RTD::TerrainQueryUserData* userData,
      const smVec3d& start, const smVec3d& end, smVec3d& hitXYZ, smVec3d& hitNormal, smVec3d& hitVelocity,
      smReal& frictionFactor, bool& isLiquid, const RTD::EntityBase*& entity) override;
 
protected:
   //! \brief Updates and checks the position cache for queries
   //! \param isectRecord Intersection record to populate
   //! \param vehicleUuid UUID of the vehicle performing the query
   //! \param contextData Additional context-specific data
   //! \param coordSys Coordinate system for the query
   //! \param startPoint Start point of the query in world coordinates
   //! \param endPoint End point of the query in world coordinates
   //! \return True if the cache was updated, false otherwise
   //!
   //! Updates the internal position cache and checks if it contains valid data
   //! for the current query, which can be used to optimize repeated queries in similar locations.
   bool updateAndCheckPositionCache(DtVrfChordIntersectionRecord& isectRecord, DtUUID& vehicleUuid,
      const void* contextData, Coordinate_System* coordSys, DtPoint startPoint, DtPoint endPoint);
 
   //! \brief Performs a terrain-only intersection test
   //! \param isectRecord Intersection record to populate
   //! \param startPoint Start point of the query in world coordinates
   //! \param endPoint End point of the query in world coordinates
   //! \return True if a terrain intersection was found, false otherwise
   //!
   //! Checks for intersections with the terrain database between the specified points.
   bool terrainIntersect(DtVrfChordIntersectionRecord& isectRecord, DtPoint startPoint, DtPoint endPoint);
 
   //! \brief Performs a simulation object intersection test
   //! \param isectRecord Intersection record to populate
   //! \param vehicleUuid UUID of the vehicle performing the query
   //! \param contextData Additional context-specific data
   //! \param startPoint Start point of the query in world coordinates
   //! \param endPoint End point of the query in world coordinates
   //! \return True if a simulation object intersection was found, false otherwise
   //!
   //! Checks for intersections with simulation objects between the specified points.
   bool simObjectIntersect(DtVrfChordIntersectionRecord& isectRecord, DtUUID& vehicleUuid, const void* contextData,
      DtPoint startPoint, DtPoint endPoint);
 
   //! \brief Calculates hit details from an intersection record
   //! \param isectRecord Intersection record containing raw intersection data
   //! \param coordSys Coordinate system for the query
   //! \param hitXYZ Output parameter for the hit position
   //! \param hitNormal Output parameter for the surface normal at the hit position
   //! \param hitVelocity Output parameter for the velocity of the hit object
   //! \return True if hit details were successfully calculated, false otherwise
   //!
   //! Processes an intersection record to extract detailed hit information.
   bool calculateHit(DtVrfChordIntersectionRecord& isectRecord, Coordinate_System* coordSys, smVec3d& hitXYZ,
      smVec3d& hitNormal, smVec3d& hitVelocity);
 
   //! \brief Handles the case where no terrain database is available
   //! \param isectRecord Intersection record to populate
   //! \param coordSys Coordinate system for the query
   //! \param startLocal Start point of the query in local coordinates
   //! \param endLocal End point of the query in local coordinates
   //! \param hitXYZ Output parameter for the hit position
   //! \param hitNormal Output parameter for the surface normal at the hit position
   //! \param hitVelocity Output parameter for the velocity of the hit object
   //! \return True if a fallback intersection was calculated, false otherwise
   //!
   //! Provides a fallback intersection calculation when no terrain database is available,
   //! typically returning a flat ground plane intersection if appropriate.
   bool noTerrainDBIntersect(DtVrfChordIntersectionRecord& isectRecord, Coordinate_System* coordSys,
      DtVector startLocal, DtVector endLocal, smVec3d& hitXYZ, smVec3d& hitNormal, smVec3d& hitVelocity);
 
   //! \brief Flag indicating whether terrain queries are blocking
   //!
   //! When true, terrain queries will block until completed. When false,
   //! they will return immediately, potentially with cached or approximate results.
   bool myIsBlocking;
};
} // namespace vreRtd