vrvOverlay.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file vrvOverlay.h
//! \brief Provides a 2D overlay rendering system for VRV-based applications
//!
//! The DtVrvOverlay class provides an interface for creating and managing 2D
//! overlay graphics (text, lines, quads, textures) that are rendered on top of
//! a 3D scene using the VRV rendering engine. This is commonly used for HUDs,
//! UI elements, and debugging visualizations.
 
#pragma once
 
#include "vrePlayerStation/export.h"
 
#include <vreUtil/delegate.h>
 
#include <vrvGraphics/DtFont.h>
 
#include <osg/Geode>
#include <osg/Texture2D>
#include <osg/ref_ptr>
 
namespace makVrv
{
//! Forward declaration of display engine class
class DtDe;
 
//! Forward declaration of overlay renderer interface
class DtOverlayRendererInterface;
 
//! Forward declaration of overlay renderer implementation
class DtOverlayRenderer;
 
//! Forward declaration of OSG channel class
class DtOsgChannel;
 
//! Forward declaration of font class
class DtFont;
 
//! Forward declaration of text proxy class
class DtTextProxy;
 
//! Forward declaration of line segment class
class DtLineSegment;
 
//! Forward declaration of quad proxy class
class DtQuadProxy;
 
//! Forward declaration of texture wrapper class
class DtOsgTextureWrapper;
} // namespace makVrv
 
 
namespace makVre
{
//! \brief Simple structure to hold a reference to a font
//!
//! This structure holds a pointer to a font interface to prevent it
//! from being deleted while still in use by the overlay system.
struct DtFontHolder
{
   //! \brief Pointer to the font interface
   makVrv::DtFontInterface* myFont;
};
 
//! \brief Delegate type for overlay resize events
using DtOverlayResizedDelegate = DtDelegate<void>;
 
//! \brief Class for creating and managing 2D overlays on a 3D scene
//!
//! DtVrvOverlay provides functionality for creating and managing 2D overlay
//! elements (text, lines, quads, and textures) that are rendered on top of
//! a 3D scene within a specific window and channel. It handles viewport
//! transformations, resource management, and cleanup.
class PLAYERSTATION_DLL DtVrvOverlay
{
public:
   //! \brief Constructor that creates an overlay for a specific window and channel
   //! \param windowName The name of the window to create the overlay on
   //! \param channelName The name of the channel within the window
   //!
   //! Creates a new overlay on the specified window and channel. Throws an
   //! exception if the window or channel cannot be found, or if the overlay
   //! cannot be created.
   DtVrvOverlay(const std::string& windowName, const std::string& channelName);
 
   //! \brief Constructor that creates an overlay for a specific channel
   //! \param channel Pointer to the OSG channel to create the overlay on
   //!
   //! Creates a new overlay on the specified channel. Throws an exception
   //! if the channel is invalid or if the overlay cannot be created.
   DtVrvOverlay(makVrv::DtOsgChannel* channel);
 
   //! \brief Virtual destructor that cleans up resources
   //!
   //! Destroys the overlay and cleans up associated resources.
   virtual ~DtVrvOverlay();
 
   //! \brief Gets the overlay renderer object
   //! \return Pointer to the overlay renderer, or nullptr if not initialized
   //!
   //! Returns the underlying overlay renderer that can be used for direct
   //! rendering operations.
   virtual makVrv::DtOverlayRenderer* overlay();
 
   //! \brief Gets the geode node used for the overlay
   //! \return Pointer to the OSG geode node
   //!
   //! Returns the OSG geode node that contains the overlay drawable.
   virtual osg::Geode* geode();
 
   //! \brief Gets the channel associated with this overlay
   //! \return Pointer to the OSG channel
   //!
   //! Returns the OSG channel that this overlay is attached to.
   virtual makVrv::DtOsgChannel* channel();
 
   //! \brief Creates a font for use with overlay text
   //! \param filename The font file path (will be resolved through path configuration)
   //! \param size The font size in points
   //! \return A font holder containing the created font
   //!
   //! Creates and caches a font that can be used for rendering text in the overlay.
   //! Throws an exception if the font cannot be loaded.
   virtual DtFontHolder* createFont(const std::string& filename, float size);
 
   //! \brief Creates a text element for the overlay
   //! \return A new text proxy object
   //!
   //! Creates a new text element that can be configured and added to the overlay.
   virtual makVrv::DtTextProxy* createText();
 
   //! \brief Creates a line element for the overlay
   //! \return A new line segment object
   //!
   //! Creates a new line segment that can be configured and added to the overlay.
   virtual makVrv::DtLineSegment* createLine();
 
   //! \brief Creates a quad element for the overlay
   //! \return A new quad proxy object
   //!
   //! Creates a new quad that can be textured and added to the overlay.
   //! By default, creates textured quads.
   virtual makVrv::DtQuadProxy* createQuad();
 
   //! \brief Creates a texture from an image file
   //! \param filename The image file path (will be resolved through path configuration)
   //! \return A texture wrapper containing the loaded texture, or nullptr if loading failed
   //!
   //! Loads an image from the specified file and creates a texture that can be
   //! used with quads in the overlay. The texture is cached to prevent it from
   //! being garbage collected.
   virtual makVrv::DtOsgTextureWrapper* createTexture(const std::string& filename);
 
   //! \brief Converts a normalized X coordinate to pixel coordinates
   //! \param normalizedX The normalized X coordinate (0.0 to 1.0, left to right)
   //! \return The pixel X coordinate relative to the channel viewport
   virtual float pixelX(float normalizedX);
 
   //! \brief Converts a normalized Y coordinate to pixel coordinates
   //! \param normalizedY The normalized Y coordinate (0.0 to 1.0, top to bottom)
   //! \return The pixel Y coordinate relative to the channel viewport
   virtual float pixelY(float normalizedY);
 
   //! \brief Converts a normalized height to pixel height
   //! \param normalizedH The normalized height (0.0 to 1.0)
   //! \return The height in pixels
   virtual float pixelH(float normalizedH);
 
   //! \brief Converts a normalized width to pixel width
   //! \param normalizedW The normalized width (0.0 to 1.0)
   //! \return The width in pixels
   virtual float pixelW(float normalizedW);
 
   //! \brief Adds a handler for overlay resize events
   //! \param del The delegate to call when the overlay is resized
   //!
   //! Registers a callback function that will be called whenever the overlay's
   //! viewport changes size. Multiple callbacks can be registered, and each will
   //! be called in the order they were added.
   virtual void addOverlayResizedHandler(const DtOverlayResizedDelegate& del);
 
   //! \brief Removes a previously added resize handler
   //! \param del The delegate to remove
   //!
   //! Unregisters a callback function that was previously added with
   //! addOverlayResizedHandler. If the delegate is not found, a warning
   //! is logged.
   virtual void removeOverlayResizedHandler(const DtOverlayResizedDelegate& del);
 
protected:
   //! \brief Finds a channel by name and sets it as the current channel
   //! \param windowName The name of the window containing the channel
   //! \param channelName The name of the channel to find
   //! \return True if the channel was found, false otherwise
   //!
   //! Searches for a channel with the specified name in the specified window
   //! and sets it as the current channel for this overlay.
   virtual bool findChannel(const std::string& windowName, const std::string& channelName);
 
   //! \brief Sets the channel for this overlay
   //! \param channel Pointer to the channel to use
   //! \return True if the channel was set successfully, false otherwise
   //!
   //! Sets the specified channel as the current channel for this overlay
   //! and registers for viewport change notifications.
   virtual bool setChannel(makVrv::DtOsgChannel* channel);
 
   //! \brief Creates the overlay rendering system
   //! \return True if the overlay was created successfully, false otherwise
   //!
   //! Creates the overlay renderer and adds it to the channel's scene graph.
   virtual bool createOverlay();
 
   //! \brief Destroys the overlay and cleans up resources
   //!
   //! Removes the overlay from the channel's scene graph and releases
   //! allocated resources.
   virtual void destroyOverlay();
 
   //! \brief Called when the viewport of the channel changes
   //!
   //! Updates the cached viewport dimensions and notifies registered
   //! resize handlers of the change.
   virtual void onViewportChanged();
 
   //! \brief Called when a channel is about to be destroyed
   //! \param displayName The name of the display containing the channel
   //! \param windowName The name of the window containing the channel
   //! \param channelName The name of the channel being destroyed
   //!
   //! Checks if the channel being destroyed is the one used by this overlay,
   //! and if so, cleans up the overlay resources.
   virtual void onChannelDestroyed(
      const std::string& displayName, const std::string& windowName, const std::string& channelName);
 
   //! \brief Pointer to the display engine
   makVrv::DtDe* myDe;
 
   //! \brief Pointer to the overlay renderer
   makVrv::DtOverlayRenderer* myOverlayRenderer;
 
   //! \brief Pointer to the channel this overlay is attached to
   makVrv::DtOsgChannel* myChannel;
 
   //! \brief The OSG geode node containing the overlay drawable
   osg::ref_ptr<osg::Geode> myGeode;
 
   //! \brief The X position of the channel viewport
   int myX;
 
   //! \brief The Y position of the channel viewport
   int myY;
 
   //! \brief The width of the channel viewport
   int myW;
 
   //! \brief The height of the channel viewport
   int myH;
 
   //! \brief Collection of cached fonts to prevent garbage collection
   std::vector<DtFontHolder*> myCachedFonts;
 
   //! \brief Collection of cached textures to prevent garbage collection
   std::vector<osg::ref_ptr<osg::Texture2D>> myCachedTextures;
 
   //! \brief Type definition for a list of resize handlers
   using OverlayResizedList = std::vector<DtOverlayResizedDelegate>;
 
   //! \brief List of callbacks to notify when the overlay is resized
   OverlayResizedList myOverlayResizedCallbacks;
};
} // namespace makVre