driverQmlHudComponent.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/
 
//! \file driverQmlHudComponent.h
//! \brief Component demonstrating QML HUD overlay integration with vehicle damage state.
 
 
#pragma once
 
#include "vrePlayerStation/playerComponent.h"
 
#include "vreUtil/attribute.h"
 
#include "vreMessageManager/vreMessage.h"
 
//! Component type identifier for factory registration and role configuration.
//!
//! This string must match the componentGroup name used in role configuration XML files
//! to instantiate this component as part of a player station role.
constexpr auto DtDriverQmlHudComponentType = "DtDriverQmlHudComponent";
 
//! \brief Example component demonstrating QML overlay integration with vehicle damage state.
//!
//! This component shows how to:
//! - Create and manage player attribute store entries for QML data binding
//! - Subscribe to simulation state messages to track entity appearance changes
//! - Extract DIS appearance bits and interpret damage states (mobility-kill, firepower-kill)
//! - Publish data to QML overlays through the VR-Engage attribute store system
//!
//! The component inherits from DtPlayerComponent and is registered with the player station's
//! component factory for role-based instantiation. It works in conjunction with a QML overlay
//! (configured separately) that displays the vehicle damage information.
//!
//! **Integration Pattern**: This component creates attribute store entries that QML files
//! can bind to using the VR-Engage QML bridge. The QML overlay reads these attributes
//! reactively and updates the UI when values change.
//!
//! **Message Handling**: Uses the legacy delegate-based message handling pattern. For new
//! code, consider using the lambda-based subscription pattern shown in other examples.
//!
//! \see DtPlayerComponent for base class lifecycle methods
//! \see DtPlayerAttributeStore for reactive data binding with QML
class DtDriverQmlHudComponent : public makVre::DtPlayerComponent
{
public:
   //! \brief Constructs the driver QML HUD component.
   //!
   //! Default constructor. Actual initialization is deferred to the initialize() method
   //! following the VR-Engage component lifecycle pattern.
   DtDriverQmlHudComponent();
 
   //! \brief Destructor (compiler-generated).
   virtual ~DtDriverQmlHudComponent() override = default;
 
   //! \brief Initializes the component with player station and configuration.
   //!
   //! This method demonstrates the standard VR-Engage component initialization pattern:
   //! - Calls base class initialize() first (required)
   //! - Registers message handlers for simulation state updates
   //! - Does NOT access attribute store yet (deferred to postInitialize)
   //!
   //! **Pattern Note**: Attribute store access should be done in postInitialize() to ensure
   //! all components have been constructed and basic initialization is complete.
   //!
   //! \param player The player station instance this component belongs to
   //! \param config Configuration table containing role parameters (unused in this example)
   //! \return true if initialization succeeds, false otherwise
   virtual bool initialize(makVre::DtPlayerStation* player, makVre::DtInitTable& config) override;
 
   //! \brief Completes initialization after all components are initialized.
   //!
   //! This method demonstrates the proper phase for attribute store setup:
   //! - Creates the "vehicle-status" attribute hierarchy
   //! - Initializes "mobility-kill" and "firepower-kill" boolean attributes
   //! - Sets initial values (both false, indicating no damage)
   //!
   //! **Design Pattern**: Use postInitialize() for cross-component dependencies and
   //! attribute store manipulation, as all components are guaranteed to exist at this point.
   //!
   //! \return true if post-initialization succeeds, false otherwise
   virtual bool postInitialize() override;
 
   //! \brief Per-frame update callback.
   //!
   //! Empty implementation - this component is purely message-driven and does not require
   //! per-frame updates. All state changes happen in response to SimulationStateMessage.
   //!
   //! \param dt Elapsed time since last tick in seconds (unused)
   virtual void tick(double dt) override {};
 
   //! \brief Cleanup and resource release.
   //!
   //! Unregisters message handlers to prevent callbacks after component destruction.
   //! This is critical for avoiding dangling pointers when the component is destroyed.
   virtual void shutdown() override;
 
   //! \brief Returns the component type identifier string.
   //!
   //! Used by the VR-Engage framework for component identification and factory registration.
   //!
   //! \return The component type string matching DtDriverQmlHudComponentType
   virtual const char* type() const override;
 
   //! \brief Handles simulation state messages to update vehicle damage status.
   //!
   //! This message handler demonstrates:
   //! - Filtering messages by entity ID to process only relevant entities
   //! - Extracting DIS appearance bits from simulation state
   //! - Using DtAppearance helper to interpret damage states
   //! - Updating attribute store values for QML consumption
   //!
   //! **Message Pattern**: Uses the legacy delegate-based handler pattern. The handler
   //! is registered in initialize() and unregistered in shutdown().
   //!
   //! \param msg The simulation state message containing entity appearance data
   //! \return HANDLED to indicate successful processing
   virtual makVre::DtVreMessageResult handleSimState(makVre::DtVreMessage* msg);
 
protected:
   //! Handle to the vehicle damage state attribute hierarchy.
   //!
   //! This attribute contains two boolean child attributes:
   //! - "mobility-kill": true when vehicle is immobilized
   //! - "firepower-kill": true when vehicle weapons are disabled
   //!
   //! QML overlays bind to these attributes to reactively display damage state in the UI.
   //! The handle is obtained in postInitialize() and updated in handleSimState().
   makVre::DtAttributeHandle myVehicleDamageState;
};