overlayComponent.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file overlayComponent.h
//! \brief Component for creating and managing HUD elements in overlay channels
//! \ingroup vreCommonComponents
 
 
#pragma once
 
#include "vreCommonComponents/export.h"
 
#include "vrePlayerStation/playerComponent.h"
#include "vrePlayerStation/vrvOverlay.h"
 
#include <string>
#include <vector>
 
namespace makVre
{
namespace OverlayComponentConfig
{
//! \ingroup RoleConfigParams
//! \defgroup OverlayComponentRoleParams Overlay Component Role Parameters
//! \roleInherits{PlayerComponentRoleParams}
//! Configuration Options for overlay component role.
//! @{
 
//! \vreRoleParam{channelName,string,"Channel 1",overlayComponent,Name of the render channel where the overlay should be displayed.}
constexpr const char* channelName = "channelName";
 
//! \vreRoleParam{elements,table,"",overlayComponent,Table defining the HUD elements to be created and displayed in the overlay.}
constexpr const char* elements = "elements";
 
//! \vreRoleParam{windowName,string,"Window 1",overlayComponent,Name of the window where the overlay should be rendered.}
constexpr const char* windowName = "windowName";
 
//! @}
} // namespace OverlayComponentConfig
 
//! \brief Type identifier for DtOverlayComponent component
constexpr const char* DtOverlayComponentType = "DtOverlayComponent";
 
//! \brief Base component for creating and managing 2D HUD overlays
//!
//! DtOverlayComponent provides functionality for creating and managing 2D HUD elements
//! including text, lines, and textured quads. The component can render these elements
//! on top of the 3D scene and dynamically update text content based on state attributes.
//! Elements are defined in the component's configuration and can be resized or repositioned
//! when the display resolution changes.
class VRECOMMONCOMPONENTS_DLL DtOverlayComponent : public DtPlayerComponent
{
public:
   //! \brief Constructor for DtOverlayComponent
   //!
   //! Initializes the overlay component with the specified class name
   DtOverlayComponent();
 
   //! \brief Virtual destructor for DtOverlayComponent
   virtual ~DtOverlayComponent() override;
 
   //! \brief Initializes the overlay component
   //! \param player Pointer to the player station this component belongs to
   //! \param config Configuration table containing overlay settings and element definitions
   //! \return True if initialization succeeded, false otherwise
   //!
   //! Creates the VRV overlay in the appropriate window/channel and builds the
   //! defined HUD elements from the configuration
   virtual bool initialize(makVre::DtPlayerStation* player, makVre::DtInitTable& config) override;
 
   //! \brief Performs post-initialization after all components are initialized
   //! \return True if post-initialization succeeded, false otherwise
   //!
   //! Resolves initial text values by substituting state attribute values
   virtual bool postInitialize() override;
 
   //! \brief Called every frame to update the overlay
   //! \param dt Delta time since the last frame in seconds
   //!
   //! Updates text elements with current state attribute values
   virtual void tick(double dt) override;
 
   //! \brief Shuts down the overlay component
   //!
   //! Destroys all created elements and the overlay itself
   virtual void shutdown() override;
 
   //! \brief Finds a text element by its name
   //! \param name Name of the text element to find
   //! \return Pointer to the text proxy if found, nullptr otherwise
   //!
   //! Searches through the text elements for one with the specified name
   virtual makVrv::DtTextProxy* findTextByName(const std::string& name);
   
   //! \brief Sets the visibility of a text element
   //! \param name Name of the text element to modify
   //! \param isVisible True to show the text, false to hide it
   //!
   //! Changes the visibility of a named text element by setting its group
   virtual void setTextVisible(const std::string& name, bool isVisible);
 
   //! \brief Sets the group for all overlay elements
   //! \param group Group number to assign to all elements
   //!
   //! Changes the visibility group of all text, line, and quad elements
   //! (group 0 is typically used to hide elements, group 1 to show them)
   virtual void setAllElementGroups(int group);
 
   //! \brief Returns the component type identifier
   //! \return The component type string
   virtual const char* type() const override;
 
protected:
   //! \brief Updates text elements with current state attribute values
   //!
   //! Processes all text strings, replacing state attribute references like $(attributeName)
   //! with their current values from the player attribute store
   virtual void resolveTexts();
   //! \brief Converts a state attribute to a string representation
   //! \param attrName Name of the attribute to retrieve
   //! \param mappings Optional value mappings to translate numeric values to strings
   //! \return String representation of the attribute value
   //!
   //! Retrieves a state attribute and converts it to a string, applying any mappings if provided
   virtual std::string getAttributeAsString(const std::string& attrName, const std::vector<std::string>& mappings);
   //! \brief Handles overlay resize events
   //!
   //! Called when the window or overlay is resized to rebuild all elements
   //! with the new screen dimensions
   virtual void handleOverlayResized();
   //! \brief Destroys all overlay elements
   //!
   //! Removes and deletes all text, line, and quad elements from the overlay
   virtual void destroyElements();
   //! \brief Builds overlay elements from a configuration table
   //! \param elements Configuration table containing element definitions
   //!
   //! Creates text, line, and quad elements based on the provided configuration
   virtual void buildElements(DtInitTable& elements);
 
   //! \brief Pointer to the VRV overlay that contains all HUD elements
   DtVrvOverlay* myOverlay;
 
   //! \brief Structure representing a text element in the overlay
   struct Text
   {
      //! \brief Name identifier for the text element
      std::string myName;
 
      //! \brief Original text string with attribute references
      std::string myTextString;
 
      //! \brief Pointer to the text proxy in the overlay
      makVrv::DtTextProxy* myText;
 
      //! \brief Value mappings for translating numeric values to strings
      std::vector<std::string> myValueMapping;
   };
 
   //! \brief Collection of text elements in the overlay
   std::vector<Text> myTexts;
 
   //! \brief Collection of line elements in the overlay
   std::vector<makVrv::DtLineSegment*> myLines;
 
   //! \brief Collection of quad elements in the overlay
   std::vector<makVrv::DtQuadProxy*> myQuads;
 
   //! \brief Configuration table containing element definitions
   DtInitTable myElementConfig;
};
} // namespace makVre