aglUpdater.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file aglUpdater.h
//! \ingroup vreVrfmodel
//! \brief Component for updating the above-ground-level altitude for entities
//!
//! This file defines the DtAglUpdater class, which calculates and maintains the
//! above-ground-level (AGL) altitude for entities. It provides accurate terrain
//! intersection calculations for HUD displays and other systems that need AGL data.
 
#pragma once
 
#include "vreVrfmodel/export.h"
#include "vreVrfmodel/vreSimComponent.h"
#include <vrfobjcore/simComponent.h>
#include <vreMessageManager/vreMessage.h>
 
namespace makVre
{
//! \brief Type identifier for the AGL updater component
constexpr char DtAglUpdaterType[] = "agl-updater";
 
//! \brief Component that updates the above-ground-level altitude for entities
//!
//! The DtAglUpdater exists to set the altitude-agl extended data, which is used by
//! the aircraft HUD and other systems. It performs terrain intersections in the simulation
//! which are more precise than those performed in the GUI, as GUI intersections
//! depend on the level of detail (LOD) of the terrain that is currently loaded.
class VREVRFMODEL_DLL DtAglUpdater : public DtVreSimComponent<DtSimComponent>
{
public:
   //! \brief Constructor
   //! \param name The name of this component
   //! \param owner The local object that owns this component
   //! \param simManager The simulation services manager
   //! \param desc Optional component descriptor
   //! \param parentRegistry Optional parent registry for reader/writer functionality
   //!
   //! Creates a new AGL updater component with the specified parameters.
   DtAglUpdater(const DtString& name,
      DtLocalObject* owner,
      DtSimulationServices* simManager,
      DtComponentDescriptor* desc = nullptr,
      DtReaderWriterRegistry* parentRegistry = nullptr);
 
   //! \brief Default constructor (not implemented)
   //!
   //! Default constructor is private and not implemented to prevent
   //! creation of instances without proper initialization.
   DtAglUpdater() = delete;
 
   //! \brief Copy constructor (not implemented)
   //!
   //! Copy constructor is private and not implemented to prevent
   //! copy construction.
   DtAglUpdater(const DtAglUpdater& orig) = delete;
 
   //! \brief Assignment operator (not implemented)
   //! \return Reference to this object
   //!
   //! Assignment operator is private and not implemented to prevent
   //! assignment.
   const DtAglUpdater& operator=(const DtAglUpdater& orig) = delete;
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the AGL updater component.
   virtual ~DtAglUpdater() override;
 
   //! \brief Update method called each simulation frame
   //!
   //! If the entity is player-controlled and myRequireAgl is true,
   //! this method will update the AGL altitude by calling updateAglAltitude().
   //! This ensures the AGL data is refreshed only when needed, to optimize performance.
   virtual void tick() override;
 
   //! \brief Gets the type identifier for this component
   //! \return String identifying the component type (DtAglUpdaterType)
   //!
   //! Implements the DtSimComponent::type() method to return the
   //! type identifier for this component.
   virtual const char* type() const override;
 
   //! \brief Updates the AGL altitude value for the entity
   //!
   //! Calculates and sets the "altitude-agl" extended data value to be
   //! the difference between the entity's altitude and the terrain height
   //! at the entity's current location. This provides an accurate above-ground-level
   //! altitude value that can be used by HUDs and other systems.
   virtual void updateAglAltitude();
 
   //! \brief Handles AGL subscription messages
   //! \param msg The subscription message to process
   //! \return The message processing result
   //!
   //! Processes messages that request subscription to AGL updates.
   //! When a system subscribes, the myRequireAgl flag is set to true,
   //! indicating that AGL updates should be performed each frame.
   virtual DtVreMessageResult handleAglSubscription(DtVreMessage* msg);
 
   //! \brief Handles AGL unsubscription messages
   //! \param msg The unsubscription message to process
   //! \return The message processing result
   //!
   //! Processes messages that request unsubscription from AGL updates.
   //! When the last system unsubscribes, the myRequireAgl flag may be
   //! set to false to stop performing AGL updates each frame.
   virtual DtVreMessageResult handleAglUnsubscription(DtVreMessage* msg);
 
   //! \brief Factory method to create a new instance of this component
   //! \param name The name for the new component
   //! \param owner The local object that will own this component
   //! \param simManager The simulation services manager
   //! \param desc Optional component descriptor
   //! \param parentRegistry Optional parent registry for reader/writer functionality
   //! \return Pointer to the newly created component
   //!
   //! Static factory method used by the component creation system to instantiate
   //! new instances of this component type.
   static DtSimComponent* creator(const DtString& name,
      DtLocalObject* owner,
      DtSimulationServices* simManager,
      DtComponentDescriptor* desc,
      DtReaderWriterRegistry* parentRegistry);
 
   void initializeMessageHandlers();
 
protected:
   //! \brief Flag indicating whether AGL updates are required
   //!
   //! When true, AGL altitude is updated every tick. This flag is set
   //! when systems subscribe to AGL updates and cleared when all subscribers
   //! have unsubscribed.
   bool myRequireAgl = false;
};
} // namespace makVre