vortexPagedTerrain.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2024 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file    vortexPagedTerrain.h
//! \brief   Class that manages all the translation from the VR-Forces terrain to the Vortex Terrain system.
//!          This class also manages dynamic terrain events that come from DtVortexDynamicTerrainHandler.
//!          This class acts as an interface between the paged terrain producer and the terrain database in regions
//!          where parts and collision geometries are required for collision with other entities.
//!          The responsibility of the paged terrain interface is to answer these queries and to create the requested
//!          parts and collision geometries from the terrain information in the terrain database.
//!
//! \ingroup vreVrfVortex
 
#pragma once
 
#include <vreVrfVortex/export.h>
#include "vreVrfVortex/pagedTerrainRequest.h"
#include "vreVrfVortex/surfaceToVxMaterialMapper.h"
 
#include <vrfobjcore/simObjectReference.h>
 
#include "vreMessageManager/vreMessage.h"
 
#include <VxTerrain/VxPagedTerrainInterface.h>
 
#include <VxMath/VxMath.h>
#include <VxMath/BoundingBox.h>
 
#include <tbb/concurrent_vector.h>
#include <tbb/task_arena.h>
#include <tbb/spin_mutex.h>
 
#include <future>
 
// Forward declares
class DtTerrainImplementation;
 
namespace VxTerrain
{
class VxPagedTerrainProducer;
}
 
namespace Vx
{
class VxCollisionGeometry;
class VxPart;
class VxTriangleMeshUVGrid;
class VxTriangleMeshBVTree;
} // namespace Vx
 
namespace makVre
{
class DtVortexPhysicalWorld;
class DtVortexPagedTerrainProducer;
class DtVortexTriangleOutputInterface;
class DtVortexDynamicTerrainHandler;
 
//! \brief Main class that manages terrain translation between VR-Forces and Vortex
//!
//! This class facilitates the communication between VR-Forces terrain system and the Vortex physics engine.
//! It handles the conversion of terrain data, processes terrain generation requests, creates collision
//! geometries, and manages dynamic terrain modifications. The class implements the VxPagedTerrainInterface
//! to interact with the Vortex paged terrain system.
class VREVRFVORTEX_DLL DtVortexPagedTerrainInterface : public VxTerrain::VxPagedTerrainInterface
{
public:
   //! \brief Data structure for managing new terrain requests from the Vortex Forecaster
   //!
   //! Holds information about asynchronous terrain generation requests including priority,
   //! unique identifier, and future object for tracking completion.
   struct VortexNewTerrainRequest
   {
      std::shared_future<void> future; //!< Future object for asynchronous processing
      int priority;                    //!< Priority level of the request
      int requestId;                   //!< Unique identifier for the request
   };
   using NewTerrainRequestQueue = std::list<VortexNewTerrainRequest>;
 
   //! \brief Structure for queueing vortex requests to be inserted on the next update()
   //!
   //! Contains all necessary data for creating and inserting a new terrain cell,
   //! including the bounding box, triangle mesh, and triangle interface.
   struct VortexCellToInsert
   {
      //! \brief Default constructor
      //!
      //! Initializes the structure with null pointers for the triangle interface and mesh.
      VortexCellToInsert();
 
      //! \brief Destructor
      //!
      //! Cleans up by setting pointers to nullptr to prevent dangling references.
      ~VortexCellToInsert();
 
      VxMath::BoundingBox requestBounds;                                     //!< The bounding box of this request
      std::shared_ptr<DtVortexTriangleOutputInterface> newTriangleInterface; //!< Triangle Interface
      Vx::VxTriangleMeshBVTree* newTriangleMesh;                             //!< The triangle mesh
   };
 
   //! \brief Structure for queueing vortex requests to be modified on the next step()
   //!
   //! Contains the data needed to modify an existing terrain cell, including
   //! source ID, collision geometry, and new triangle data.
   struct VortexCellToModify
   {
      //! \brief Default constructor
      //!
      //! Initializes the structure with null pointers for collision geometry and triangle data.
      VortexCellToModify();
 
      int sourceId;                               //!< The source ID this cell collision geometry links to
      Vx::VxCollisionGeometry* collisionGeometry; //!< Collision Geometry
      Vx::VxTriangleMeshBVTree* newTriangleData;  //!< This is the new triangleData
      std::vector<DtSimObjectReference>
         objects; //!< List of objects that will need to be dropped if this is a dynamic terrain event
   };
 
public:
   //! \brief Default constructor
   //!
   //! Initializes the paged terrain interface with default settings, sets up the material mapper,
   //! and retrieves configuration parameters from the Vortex physical world. Also initializes
   //! the terrain implementation and coordinate conversion system.
   DtVortexPagedTerrainInterface();
 
   //! \brief Destructor
   //!
   //! Performs cleanup of resources owned by this interface.
   virtual ~DtVortexPagedTerrainInterface() override;
 
   //! \brief Called every frame from within the vortex application while running
   //!
   //! Reorganizes requests based on priority, processes queued collision geometries,
   //! and manages the terrain regeneration queue. Also handles the completion of
   //! asynchronous terrain generation tasks.
   //!
   //! \param producer The current terrain producer
   virtual void step(VxTerrain::VxPagedTerrainProducer* producer) override;
 
   //! \brief Called when new requests for terrain arise
   //!
   //! Processes and queues new terrain generation requests by calling queueNewTerrainRequests.
   //! These requests are then processed asynchronously by the terrain system.
   //!
   //! \param request A list of requests to queue up for terrain generation
   //! \param producer The current terrain producer
   virtual void produce(
      const std::vector<VxTerrain::VxTerrainRequest>& request, VxTerrain::VxPagedTerrainProducer* producer) override;
 
   //! \brief Called when pending requests for terrain get higher priority
   //!
   //! Updates the priority of existing terrain requests to ensure that urgent
   //! requests are processed first during the next update cycle.
   //!
   //! \param request A list of requests to update priority for
   //! \param producer The current terrain producer
   virtual void update(
      const std::vector<VxTerrain::VxTerrainRequest>& request, VxTerrain::VxPagedTerrainProducer* producer) override;
 
   //! \brief Gets the material mapper
   //!
   //! Returns the current material mapper used for translating terrain surface types
   //! to Vortex material properties.
   //!
   //! \return The current material mapper
   virtual std::shared_ptr<DtSurfaceToVxMaterialMapper> materialMapper() const;
 
   //! \brief Sets the material mapper
   //!
   //! Updates the material mapper used for translating terrain surface types
   //! to Vortex material properties.
   //!
   //! \param val The new material mapper to use
   virtual void setMaterialMapper(std::shared_ptr<DtSurfaceToVxMaterialMapper> val);
 
   //! \brief Sort the incoming requests to have the highest priority ones first
   //!
   //! Prioritizes terrain requests based on their priority level and submits them
   //! as asynchronous jobs to the thread pool. This ensures that more important
   //! terrain cells are generated first.
   //!
   //! \param requests List of requests to queue up
   virtual void queueNewTerrainRequests(const std::vector<VxTerrain::VxTerrainRequest>& requests);
 
   //! \brief Queues up and manages any new dynamic terrain or terrain regeneration requests
   //!
   //! Processes terrain modification requests from the dynamic terrain handler.
   //! This includes creating new triangle meshes for modified terrain areas
   //! and queuing them for integration in the next update cycle.
   virtual void queueTerrainRegenerationRequests();
 
   //! \brief Gets the maximum terrain height tolerance check value
   //!
   //! Returns the tolerance value used to determine how far above/below
   //! the terrain to check for collisions.
   //!
   //! \return The current terrain height tolerance check value in meters
   virtual double terrainHeightToleranceCheck() const;
 
   //! \brief Sets the maximum terrain height tolerance check value
   //!
   //! Updates the tolerance value used to determine how far above/below
   //! the terrain to check for collisions. This value can be configured
   //! through vortexConfig.lua.
   //!
   //! \param val The new terrain height tolerance check value in meters
   virtual void setTerrainHeightToleranceCheck(double val);
 
protected:
   //! \brief Generates a source ID given the minimum x and y coordinate of a request
   //!
   //! Creates a unique identifier for a terrain cell based on its position.
   //! The ID is calculated using the cell's row and column in the terrain grid,
   //! and is guaranteed to be positive and within a valid range.
   //!
   //! \param minXCoordinate The minimum X coordinate of the request
   //! \param minYCoordinate The minimum Y coordinate of the request
   //! \return A unique source ID for the terrain cell
   virtual int generateSourceID(double minXCoordinate, double minYCoordinate);
 
   //! \brief Helper function for processing queued collision geometries
   //!
   //! Processes collision geometries contained in myCellsToInsert and myCellsToModify.
   //! This includes creating new collision geometries, integrating them into the
   //! Vortex system, and handling dynamic terrain modifications.
   virtual void processQueuedCollisionGeometries();
 
   //! \brief Processes all dynamic terrain events that have been queued up for regeneration
   //!
   //! Handles the regeneration of terrain cells that have been modified by dynamic terrain events.
   //! This includes modifying existing triangle meshes, updating collision geometries,
   //! and managing affected simulation objects.
   //!
   //! \param regenerationData Pair containing the source ID and new triangle mesh
   //! \return True if the regeneration was successful, false otherwise
   virtual bool processTerrainRegenerationRequest(const std::pair<int, Vx::VxTriangleMeshBVTree*>& regenerationData);
 
   //! \brief Processes a terrain request and builds a collision geometry for Vortex
   //!
   //! Creates a new terrain cell from a terrain request, extracting triangles from the
   //! terrain implementation and building a collision geometry for use in Vortex.
   //! The resulting cell is then queued for insertion in the next update cycle.
   //!
   //! \param req The VxTerrainRequest that has been queued for generation
   //! \param triMesh Optional pre-created triangle mesh to use
   virtual void processNewTerrainRequest(VxTerrain::VxTerrainRequest req, Vx::VxTriangleMeshBVTree* triMesh = nullptr);
 
   //! \brief Creates a collision geometry based on the vertices and the surface
   //!
   //! Generates a Vortex collision geometry from a triangle output interface,
   //! either using a provided triangle mesh or creating a new one. The collision
   //! geometry is configured with appropriate material properties and settings.
   //!
   //! \param outputInterface The information of the terrain cell that has been generated
   //! \param triMeshParam Optional triangle mesh to use for the collision geometry
   //! \return The created collision geometry
   virtual Vx::VxCollisionGeometry* createVortexCollisionGeometry(
      DtVortexTriangleOutputInterface& outputInterface, Vx::VxTriangleMeshBVTree* triMeshParam = nullptr);
 
   //! \brief Fills out a triangle mesh based on all the triangles from the output interface
   //!
   //! Populates a Vortex triangle mesh with vertices, triangles, and material properties
   //! from a triangle output interface. Handles coordinate conversion between VR-Forces
   //! and Vortex coordinate systems.
   //!
   //! \param outputInterface The information of the terrain cell that has been generated
   //! \param triMesh The triangle mesh to input all the triangles in
   virtual void buildTriangleMesh(
      const std::shared_ptr<DtVortexTriangleOutputInterface> outputInterface, Vx::VxTriangleMeshBVTree* triMesh);
 
   //! \brief Creates a triangle mesh based on the output interface
   //!
   //! Creates and initializes a new Vortex triangle mesh from a triangle output interface.
   //! The mesh is configured with appropriate settings and then populated with triangles
   //! by calling buildTriangleMesh.
   //!
   //! \param outputInterface The information of the terrain cell that has been generated
   //! \return A triangle mesh created based on the information
   virtual Vx::VxTriangleMeshBVTree* createVortexTriangleMesh(DtVortexTriangleOutputInterface& outputInterface);
 
   //! \brief Gets the terrain process box in terms of geocentric/local terrain
   //!
   //! Converts a Vortex bounding box to a terrain process box that can be used
   //! with the terrain implementation to extract triangles. Handles the conversion
   //! between Vortex and VR-Forces coordinate systems.
   //!
   //! \param bb Vortex request bounds
   //! \return A terrain process box translated for use in getting triangles
   virtual DtTerrainProcessPolygonsBox getTerrainProcessBox(const Vx::VxBoundingBox& bb);
 
   //! \brief Modifies a triangle mesh with z values from a new mesh
   //!
   //! Updates the heights (z-values) of vertices in an existing triangle mesh
   //! based on a new mesh. Only applies changes if the difference exceeds the
   //! specified tolerance.
   //!
   //! \param currentMesh The existing mesh to be modified with updated height values
   //! \param newMesh The new mesh to get the updated triangles
   //! \param upAxis The axis representing the up direction
   //! \param tolerance The tolerance for z-value differences
   //! \return True if there were deformations, false otherwise
   virtual bool modifyTriangleMesh(Vx::VxTriangleMeshBVTree* currentMesh, const Vx::VxTriangleMeshBVTree* newMesh,
      const int upAxis, double tolerance = 0.1);
 
   //! \brief Compares each triangle from both meshes and checks if they are equal
   //!
   //! Determines if two triangle meshes are different by comparing their vertices.
   //! Vertices are considered equal if their positions differ by less than the
   //! specified tolerance.
   //!
   //! \param meshOne First triangle mesh to compare
   //! \param meshTwo Second triangle mesh to compare
   //! \param tolerance The tolerance for considering vertices equal
   //! \return True if the meshes are different, false if they are the same
   virtual bool areTriangleMeshesDifferent(
      Vx::VxTriangleMeshBVTree* meshOne, Vx::VxTriangleMeshBVTree* meshTwo, double tolerance = 0.1);
 
   //! \brief Sets the orphan edges of the triangle mesh to not have an invalid angle between meshes
   //!
   //! Fixes orphan edges in a triangle mesh to ensure valid angles between connected triangles.
   //! This addresses an issue in the Vortex code that can cause incorrect edge handling.
   //!
   //! \param triMesh The triangle mesh to fix orphan edges for
   void fixTriangleMeshOrphanEdges(Vx::VxTriangleMeshBVTree* triMesh);
 
protected:
   DtVortexPhysicalWorld* myPhysicalWorld;                               //!< Pointer to the physical world
   DtTerrainImplementation* myTerrainImplementation;                     //!< Pointer to the terrain implementation
   DtVortexPagedTerrainProducer* myTerrainProducer;                      //!< Pointer to the terrain producer
   std::weak_ptr<DtVortexDynamicTerrainHandler> myDynamicTerrainHandler; //!< Pointer to the dynamic terrain handler
 
   std::shared_ptr<DtSurfaceToVxMaterialMapper>
      myMaterialMapper; //!< Material mapper for surface to Vortex material conversion
 
   std::unique_ptr<tbb::task_arena> myDynamicTerrainTaskArena; //!< Task arena for dynamic terrain processing
 
   double myTerrainHeightToleranceCheck;                       //!< Height tolerance for terrain checks
   double myDynamicTerrainRegenerationRetryInterval;           //!< Interval for retrying dynamic terrain regeneration
   int myDynamicTerrainRegenerationFailureCount; //!< Maximum number of failures before giving up on regeneration
   unsigned int myInitialTriangleVectorSize;     //!< Initial size for triangle vectors
 
   bool myWaitForFutureRequests;                 //!< Whether to wait for future requests to complete
 
   // Containers for terrain requests and cells
   NewTerrainRequestQueue myNewTerrainRequests;                //!< Queue of new terrain requests
   tbb::concurrent_vector<VortexCellToInsert> myCellsToInsert; //!< Cells to insert on the next update
   tbb::concurrent_vector<VortexCellToModify> myCellsToModify; //!< Cells to modify on the next step
 
   tbb::spin_mutex myCellsToInsertSwapMutex; //!< Protects swap operation on myCellsToInsert (push_back is thread-safe)
   tbb::spin_mutex myCellsToModifySwapMutex; //!< Protects swap operation on myCellsToModify (push_back is thread-safe)
};
} // namespace makVre