vortexStateRepository.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file    vortexStateRepository.h
//! \brief   State repository for Vortex physics entities
//! \ingroup vreVrfVortex
 
#pragma once
 
#include <vreVrfVortex/export.h>
 
#include <vlutil/vlMachineTypes.h>
#include <vrfobjcore/groundVehicleStateRepository.h>
#include <vrfobjcore/vrfObjectStateRepository.h>
#include <readerWriter/noArgumentCallbackList.h>
 
#include <matrix/vlVector.h>
 
class DtSpaceEntityParameters;
 
//! \brief Type identifier for the Vortex state repository
const char DtVortexStateRepositoryType[] = "vortex-state-repository";
 
//! \brief Function type for location change callbacks
//!
//! \param location The new location
//! \param userData User data pointer passed to the callback
using DtLocationCallbackFunction = void (*)(const DtVector& location, void* userData);
 
//! \brief Function type for heading change callbacks
//!
//! \param heading The new heading
//! \param userData User data pointer passed to the callback
using DtHeadingCallbackFunction = void (*)(DtReal heading, void* userData);
 
//! \brief Callback list type for location changes
using DtLocationCallbackList = DtCallbackList<const DtVector&>;
 
//! \brief Callback list type for heading changes
using DtHeadingCallbackList = DtCallbackList<DtReal>;
 
//! \brief State repository for Vortex physics entities
//!
//! Extends the ground vehicle state repository to provide specialized
//! state management for entities using the Vortex physics engine.
//! Includes support for location and heading change callbacks.
//!
//! \note Since version 5.0, this class no longer provides a copy constructor
//! or assignment operator. Also, the constructor prototype has changed
//! to remove the object type and parameters.
class VREVRFVORTEX_DLL DtVortexStateRepository : public DtGroundVehicleStateRepository
{
private:
   //! \brief Copy constructor (private, not implemented)
   DtVortexStateRepository(const DtVortexStateRepository& orig);
 
   //! \brief Assignment operator (private, not implemented)
   const DtVortexStateRepository& operator=(const DtVortexStateRepository& orig);
 
public:
   //! \brief Constructor
   //!
   //! Creates a new state repository with the specified parameters.
   //!
   //! \param vrfObject The VR-Forces object to associate with
   //! \param name Name for the repository
   //! \param parentRegistry Optional parent registry
   DtVortexStateRepository(DtLocalObject* vrfObject, const DtString& name, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Destructor
   virtual ~DtVortexStateRepository() override;
 
   //! \brief Gets the type of this repository
   //!
   //! Returns a unique string identifying the type of component,
   //! used as key in the state repository factory.
   //!
   //! \return Type string "vortex-state-repository"
   virtual DtString type() const override;
 
   //! \brief Factory method to create new instances
   //!
   //! Returns a newly created instance of this class. To be registered
   //! with the state repository factory.
   //!
   //! \param name Name for the repository
   //! \param vrfObject The VR-Forces object to associate with
   //! \param parentRegistry Optional parent registry
   //! \return Pointer to the new repository
   static DtVrfObjectStateRepository* creator(
      const DtString& name, DtLocalObject* vrfObject, DtReaderWriterRegistry* parentRegistry);
 
   //! \brief Safe type-checking conversion
   //!
   //! Returns the pointer to the repository if the repository passed
   //! in is of type DtVortexStateRepository, nullptr if not.
   //!
   //! \param repository Repository to cast
   //! \return Typed pointer or nullptr if wrong type
   static DtVortexStateRepository* asVortexStateRepository(const DtVrfObjectStateRepository* repository);
 
   //! \brief Places the entity at a new location and heading
   //!
   //! Positions the entity at the specified location and heading, then
   //! invokes all registered location and heading change callbacks.
   //!
   //! \param location The new position vector
   //! \param heading The new heading in radians
   //! \param clampToGroundFlag Whether to clamp the entity to ground
   //! \param dataAvailable Optional pointer to receive data availability status
   //! \param requireAllData Whether all data must be available
   virtual void place(const DtVector& location, const DtReal heading, bool clampToGroundFlag /* = true */,
      bool* dataAvailable /* = 0 */, bool requireAllData /* = false */) override;
 
   //! \brief Adds a location change callback
   //!
   //! Registers a function to be called when the entity's location changes.
   //! The callback will be invoked whenever the place() method is called.
   //!
   //! \param function Callback function to add
   //! \param userData User data to pass to the callback
   virtual void addLocationChangedCallback(DtLocationCallbackFunction function, void* userData);
 
   //! \brief Removes a location change callback
   //!
   //! Unregisters a previously added location change callback.
   //!
   //! \param function Callback function to remove
   //! \param userData User data associated with the callback
   virtual void removeLocationChangedCallback(DtLocationCallbackFunction function, void* userData);
 
   //! \brief Adds a heading change callback
   //!
   //! Registers a function to be called when the entity's heading changes.
   //! The callback will be invoked whenever the place() method is called.
   //!
   //! \param function Callback function to add
   //! \param userData User data to pass to the callback
   virtual void addHeadingChangedCallback(DtHeadingCallbackFunction function, void* userData);
 
   //! \brief Removes a heading change callback
   //!
   //! Unregisters a previously added heading change callback.
   //!
   //! \param function Callback function to remove
   //! \param userData User data associated with the callback
   virtual void removeHeadingChangedCallback(DtHeadingCallbackFunction function, void* userData);
 
protected:
   DtLocationCallbackList myLocationCallbackList; //!< List of location change callbacks
   DtHeadingCallbackList myHeadingCallbackList;   //!< List of heading change callbacks
};