hudItem.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file hudItem.h
//! \brief Classes for representing and managing HUD (Heads-Up Display) items
//! \ingroup vreCommonComponents
 
#pragma once
 
#include "vreCommonComponents/export.h"
 
#include <string>
 
namespace makVre
{
 
//! \brief Base class for all HUD (Heads-Up Display) items
//!
//! HudItem provides common functionality for all HUD elements, including positioning,
//! alignment, visibility, and color. It also maintains a dirty flag system to track
//! when properties have changed and rendering needs to be updated.
class VRECOMMONCOMPONENTS_DLL HudItem
{
public:
   //! \brief Enumeration of supported HUD item types
   enum Type
   {
      //! \brief Invalid or uninitialized HUD item type
      ILLEGAL_TYPE_UNDEFINED,
 
      //! \brief Text-based HUD item
      TEXT,
 
      //! \brief Image-based HUD item
      IMAGE,
   };
 
   //! \brief Horizontal alignment options for HUD items
   enum AlignHorizontal
   {
      //! \brief Align to the left edge
      LEFT,
 
      //! \brief Align to the horizontal center
      CENTER,
 
      //! \brief Align to the right edge
      RIGHT,
   };
 
   //! \brief Vertical alignment options for HUD items
   enum AlignVertical
   {
      //! \brief Align to the top edge
      TOP,
 
      //! \brief Align to the vertical middle
      MIDDLE,
 
      //! \brief Align to the bottom edge
      BOTTOM,
   };
 
   //! \brief Constructor for HudItem
   //!
   //! Initializes the item with default values: centered position (0.5, 0.5),
   //! white color (1,1,1,1), visibility enabled, and LEFT/TOP alignment
   HudItem();
 
   //! \brief Virtual destructor for HudItem
   virtual ~HudItem();
 
   //! \brief Gets the type of this HUD item
   //! \return The HUD item type (TEXT, IMAGE, etc.)
   virtual Type type() const;
 
   //! \brief Gets the current dirty key value
   //! \return Integer representing the current dirty state
   //!
   //! The dirty key is incremented whenever a property of the item is changed
   virtual int dirtyKey() const;
 
   //! \brief Forces the item to be marked as dirty
   //!
   //! Marks the item as needing a redraw by significantly incrementing the dirty key
   virtual void makeDirty();
 
   //! \brief Gets the current position of the HUD item
   //! \param x Pointer to receive the x-coordinate (0.0 to 1.0)
   //! \param y Pointer to receive the y-coordinate (0.0 to 1.0)
   //!
   //! Coordinates are in normalized screen space (0.0 to 1.0)
   virtual void getPosition(float* x, float* y) const;
 
   //! \brief Sets the position of the HUD item
   //! \param x The x-coordinate in normalized screen space (0.0 to 1.0)
   //! \param y The y-coordinate in normalized screen space (0.0 to 1.0)
   //!
   //! Updates the dirty key if the position changes
   virtual void setPosition(float x, float y);
 
   //! \brief Gets the current horizontal alignment
   //! \return The horizontal alignment value (LEFT, CENTER, or RIGHT)
   virtual AlignHorizontal getHorizontalAlignment() const;
 
   //! \brief Sets the horizontal alignment
   //! \param align The horizontal alignment to use
   //!
   //! Updates the dirty key if the alignment changes
   virtual void setHorizontalAlignment(AlignHorizontal align);
 
   //! \brief Gets the current vertical alignment
   //! \return The vertical alignment value (TOP, MIDDLE, or BOTTOM)
   virtual AlignVertical getVerticalAlignment() const;
 
   //! \brief Sets the vertical alignment
   //! \param align The vertical alignment to use
   //!
   //! Updates the dirty key if the alignment changes
   virtual void setVerticalAlignment(AlignVertical align);
 
   //! \brief Gets the x-coordinate of the item's position
   //! \return The x-coordinate in normalized screen space (0.0 to 1.0)
   virtual float getX() const;
 
   //! \brief Gets the y-coordinate of the item's position
   //! \return The y-coordinate in normalized screen space (0.0 to 1.0)
   virtual float getY() const;
 
   //! \brief Gets whether the HUD item is currently visible
   //! \return True if the item is visible, false otherwise
   virtual bool getVisible() const;
 
   //! \brief Sets the visibility of the HUD item
   //! \param visible True to make the item visible, false to hide it
   //!
   //! Updates the dirty key if the visibility changes
   virtual void setVisible(bool visible);
 
   //! \brief Gets the current color of the HUD item
   //! \param r Pointer to receive the red component (0.0 to 1.0)
   //! \param g Pointer to receive the green component (0.0 to 1.0)
   //! \param b Pointer to receive the blue component (0.0 to 1.0)
   //! \param a Pointer to receive the alpha component (0.0 to 1.0)
   virtual void getColor(float* r, float* g, float* b, float* a) const;
 
   //! \brief Sets the color of the HUD item
   //! \param r The red component (0.0 to 1.0)
   //! \param g The green component (0.0 to 1.0)
   //! \param b The blue component (0.0 to 1.0)
   //! \param a The alpha component (0.0 to 1.0)
   //!
   //! Updates the dirty key if the color changes
   virtual void setColor(float r, float g, float b, float a);
 
   //! \brief Gets the red component of the item's color
   //! \return The red component value (0.0 to 1.0)
   virtual float getRed() const;
 
   //! \brief Gets the green component of the item's color
   //! \return The green component value (0.0 to 1.0)
   virtual float getGreen() const;
 
   //! \brief Gets the blue component of the item's color
   //! \return The blue component value (0.0 to 1.0)
   virtual float getBlue() const;
 
   //! \brief Gets the alpha component of the item's color
   //! \return The alpha component value (0.0 to 1.0)
   virtual float getAlpha() const;
 
protected:
   //! \brief The type of this HUD item
   Type myType;
 
   //! \brief Key that tracks whether the item needs to be redrawn
   //!
   //! Incremented whenever a property changes that affects rendering
   int myDirtyKey;
 
   //! \brief Position of the item in normalized screen space [x, y]
   float myPosition[2];
 
   //! \brief Horizontal alignment of the item
   AlignHorizontal myHorizontalAlignment;
 
   //! \brief Vertical alignment of the item
   AlignVertical myVerticalAlignment;
 
   //! \brief Visibility flag for the item
   bool myVisible;
 
   //! \brief Color of the item [r, g, b, a] with components in range 0.0 to 1.0
   float myColor[4];
};
 
//! \brief Text-based HUD item
//!
//! HudTextItem extends HudItem with text-specific properties including
//! the text content, font path, and font size.
class VRECOMMONCOMPONENTS_DLL HudTextItem : public HudItem
{
public:
   //! \brief Constructor for HudTextItem
   //!
   //! Initializes the item as a TEXT type with default font size of 0.0
   HudTextItem();
 
   //! \brief Virtual destructor for HudTextItem
   virtual ~HudTextItem() override;
 
   //! \brief Gets the current text content
   //! \return The current text string
   virtual std::string getText() const;
 
   //! \brief Sets the text content
   //! \param text The new text string to display
   //!
   //! Updates the dirty key if the text changes
   virtual void setText(const std::string& text);
 
   //! \brief Gets the current font path
   //! \return Path to the font file
   virtual std::string getFontPath() const;
 
   //! \brief Sets the font path
   //! \param path Path to the font file to use
   //!
   //! Updates the dirty key if the font path changes
   virtual void setFontPath(const std::string& path);
 
   //! \brief Gets the current font size
   //! \return The font size
   virtual float getFontSize() const;
 
   //! \brief Sets the font size
   //! \param size The new font size to use
   //!
   //! Updates the dirty key if the font size changes
   virtual void setFontSize(float size);
 
protected:
   //! \brief The text content to display
   std::string myText;
 
   //! \brief Path to the font file
   std::string myFontPath;
 
   //! \brief Font size for rendering
   float myFontSize;
};
 
//! \brief Image-based HUD item
//!
//! HudImageItem extends HudItem with image-specific properties including
//! the image path and size dimensions.
class VRECOMMONCOMPONENTS_DLL HudImageItem : public HudItem
{
public:
   //! \brief Constructor for HudImageItem
   //!
   //! Initializes the item as an IMAGE type
   HudImageItem();
 
   //! \brief Virtual destructor for HudImageItem
   virtual ~HudImageItem() override;
 
   //! \brief Gets the current image path
   //! \return Path to the image file
   virtual std::string getImagePath() const;
 
   //! \brief Sets the image path
   //! \param path Path to the image file to display
   //!
   //! Updates the dirty key if the image path changes
   virtual void setImagePath(const std::string& path);
 
   //! \brief Gets the current image size
   //! \param w Pointer to receive the width
   //! \param h Pointer to receive the height
   virtual void getSize(float* w, float* h) const;
 
   //! \brief Sets the image size
   //! \param w The width of the image
   //! \param h The height of the image
   //!
   //! Updates the dirty key if the size changes
   virtual void setSize(float w, float h);
 
   //! \brief Gets the width of the image
   //! \return The current width
   virtual float getWidth() const;
 
   //! \brief Gets the height of the image
   //! \return The current height
   virtual float getHeight() const;
 
protected:
   //! \brief Path to the image file
   std::string myImagePath;
 
   //! \brief Size of the image [width, height]
   float mySize[2];
};
 
} // namespace makVre