qtQuickOverlay.h

Go to the documentation of this file.

 
/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file qtQuickOverlay.h
//! \brief Contains DtQtQuickOverlay class which provides a Qt Quick overlay component for rendering 2D UI over 3D
//! graphics
//! \ingroup vreCommonComponents
 
 
#pragma once
 
#include "vreCommonComponents/export.h"
 
#include "vrePlayerStation/playerComponent.h"
 
#include "vreMessageManager/vreMessage.h"
 
#include "vreUtil/attribute.h"
 
#include <string>
#include <vector>
 
#include <QObject>
 
class QQuickItem;
 
namespace makVrv
{
class DtOsgChannel;
class DtObserverObject;
} // namespace makVrv
 
namespace QtQuickOverlayConfig
{
//! \ingroup RoleConfigParams
//! \defgroup QtQuickOverlayRoleParams Qt Quick Overlay Role Parameters
//! \roleInherits{PlayerComponentRoleParams}
//! Configuration Options for qt quick overlay role.
//! @{
 
//! \vreRoleParamRequired{bindQmlPropertyToAttribute,DtInitTable,qtQuickOverlay,"Table",Table of bindings from state attributes to QML properties.}
constexpr const char* bindQmlPropertyToAttribute = "bindQmlPropertyToAttribute";
 
//! \vreRoleParamRequired{qmlDataItemObjectName,string,qtQuickOverlay,"dataItem",Name of the QML object to bind data to.}
constexpr const char* qmlDataItemObjectName = "qmlDataItemObjectName";
 
//! \vreRoleParamRequired{qmlFilename,string,qtQuickOverlay,"overlay.qml",Path to the QML file to load.}
constexpr const char* qmlFilename = "qmlFilename";
 
//! \vreRoleParam{qmlTargetWindow,string,"",qtQuickOverlay,Window to display the overlay on.}
constexpr const char* qmlTargetWindow = "qmlTargetWindow";
 
//! \vreRoleParam{renderOverlayOnly,bool,false,qtQuickOverlay,If true hides the 3D scene when the overlay is visible.}
constexpr const char* renderOverlayOnly = "renderOverlayOnly";
 
//! \vreRoleParam{visibilityAttribute,string,"",qtQuickOverlay,Attribute name to control overlay visibility.}
constexpr const char* visibilityAttribute = "visibilityAttribute";
 
//! @}
} // namespace QtQuickOverlayConfig
 
namespace makVre
{
//! \brief Type identifier for DtQtQuickOverlay component
constexpr const char* DtQtQuickOverlayType = "DtQtQuickOverlay";
 
//! \brief A component that manages Qt Quick overlays for rendering 2D UI elements on top of 3D graphics
//!
//! DtQtQuickOverlay loads and manages QML files as overlays for the 3D scene. It can bind state attributes
//! to QML properties, control overlay visibility based on player state, and optionally hide the 3D scene when
//! only the overlay should be visible.
class VRECOMMONCOMPONENTS_DLL DtQtQuickOverlay : public DtPlayerComponent
{
public:
   //! \brief Constructor for DtQtQuickOverlay
   DtQtQuickOverlay();
 
   //! \brief Alternative constructor with target window parameter (commented out)
   //! \param target_window The target window to display the overlay on
   // DtQtQuickOverlay(const std::string& target_window = "" );
 
   //! \brief Destructor that cleans up message handlers and attribute callbacks
   virtual ~DtQtQuickOverlay() override;
 
   //! \brief Initializes the overlay component with configuration options
   //! \param player Pointer to the player station this component belongs to
   //! \param config Configuration table containing overlay settings
   //! \return True if initialization succeeded, false otherwise
   //!
   //! Required configuration parameters:
   //! - qmlFilename: Path to the QML file to load
   //! - qmlDataItemObjectName: Name of the QML object to bind data to
   //! - qmlDataItemBindings: Table of bindings from state attributes to QML properties
   //!
   //! Optional configuration parameters:
   //! - qmlTargetWindow: Window to display the overlay on
   //! - visibilityAttribute: Attribute name to control visibility
   //! - renderOverlayOnly: If true, hides the 3D scene when the overlay is visible
   virtual bool initialize(makVre::DtPlayerStation* player, makVre::DtInitTable& config) override;
 
   //! \brief Performs post-initialization steps after all components are initialized
   //! \return True if post-initialization succeeded, false otherwise
   //!
   //! Builds connections between state attributes and QML properties,
   //! then loads the QML file using the appropriate renderer method based on VR status
   virtual bool postInitialize() override;
 
   //! \brief Called every frame to update the overlay
   //! \param dt Delta time since the last frame in seconds
   //!
   //! Updates QML property values from state attributes and handles scene visibility
   virtual void tick(double dt) override;
 
   //! \brief Shuts down the overlay component
   //!
   //! Closes the UI, restores 3D scene visibility if needed, and disconnects property bindings
   virtual void shutdown() override;
 
   //! \brief Returns the type identifier for this component
   //! \return The type string for DtQtQuickOverlay
   virtual const char* type() const override;
 
   //! \brief Sets the root QQuickItem for this overlay
   //! \param root Pointer to the root QQuickItem
   virtual void setRoot(QQuickItem* root) { myRoot = root; }
 
   //! \brief Initialize document with the root QQuickItem
   //! \param root Pointer to the root QQuickItem
   //!
   //! Stores the root item and sets initial visibility based on the visibility attribute
   virtual void initdoc(QQuickItem* root);
 
   //! \brief Handles messages for entering player states
   //! \param msg The message containing the state transition information
   //! \return Message handling result indicating if the message was handled
   //!
   //! Special handling for MENU_STATE and ENGAGED states to control overlay visibility
   //! and scene visibility when renderOverlayOnly is true
   virtual DtVreMessageResult handleEnterPlayerState(DtVreMessage* msg);
 
   //! \brief Handles messages for exiting player states
   //! \param msg The message containing the state transition information
   //! \return Message handling result indicating if the message was handled
   //!
   //! Special handling for MENU_STATE to restore previous overlay visibility
   //! and control scene visibility when renderOverlayOnly is true
   virtual DtVreMessageResult handleExitPlayerState(DtVreMessage* msg);
 
   //! \brief Sets the visibility of the overlay
   //! \param visible True to show the overlay, false to hide it
   //!
   //! Sets the "visible" property on the root QML item
   virtual void setVisibility(bool visible);
 
   //! \brief Checks if the overlay is currently visible
   //! \return True if the overlay is visible, false otherwise
   //!
   //! Reads the "visible" property from the root QML item
   virtual bool isVisible();
 
   //! \brief Updates the menu state and toggles visibility accordingly
   //! \param on True if entering menu state, false if exiting
   //!
   //! When entering menu state, caches and hides the overlay
   //! When exiting menu state, restores the previous visibility
   virtual void setMenuState(bool on);
 
protected:
   //! \brief Updates QML property values from state attributes
   //! \param dt Delta time since the last frame in seconds
   //!
   //! Finds the QML value source object and updates properties based on
   //! current state attribute values, then calls the tick method on the source
   virtual void updateVals(double dt);
 
   //! \brief Disconnects all property bindings
   //!
   //! Clears the connections list to remove all bindings
   virtual void disconnect();
 
   //! \brief Builds connections between state attributes and QML properties
   //! \param connections Configuration table defining the connections
   //! \return True if connections were successfully built, false otherwise
   //!
   //! Each connection maps a state attribute to a QML property
   virtual bool buildConnections(DtInitTable& connections);
 
   //! \brief Called when the visibility attribute changes
   //! \param on New visibility value
   //!
   //! Sets the overlay visibility based on the new attribute value
   virtual void onVisibilityAttributeChanged(bool on);
 
   //! \brief Removes the model set and sky from the channel
   //!
   //! Used when renderOverlayOnly is true to hide the 3D scene
   //! and only show the overlay
   virtual void removeModelSetAndSkyFromChannel();
 
   //! \brief Restores the model set and sky to the channel
   //!
   //! Used to restore the 3D scene visibility after it was hidden
   virtual void restoreModelSetAndSkyToChannel();
 
protected:
   //! \brief Configuration table containing QML data item bindings
   DtInitTable myBindQmlPropertyToAttribute;
 
   //! \brief Pointer to the root QQuickItem for this overlay
   QQuickItem* myRoot;
 
   //! \brief Name of the target window to display the overlay on
   std::string myTargetWindow;
 
   //! \brief Structure defining a connection between a state attribute and QML property
   struct Connection
   {
      //! \brief Name of the QML property to bind to
      std::string myQmlProperty;
 
      //! \brief Handle to the state attribute to bind from
      DtAttributeHandle myStateAttribute;
   };
 
   //! \brief List of connections between state attributes and QML properties
   std::vector<Connection> myConnections;
 
   //! \brief Path to the QML file to load
   std::string myQmlFile;
 
   //! \brief Name of the QML object to bind data to
   std::string myQmlDataItemName;
 
   //! \brief Flag indicating if the PlayerStation is in the "MENU_STATE"
   //! Used to determine whether the overlays should be visible
   bool myIsInMenuState;
 
   //! \brief Cached visibility value to restore when exiting menu state
   bool myCachedVisibility;
 
   //! \brief Handle to attribute that controls overlay visibility
   DtAttributeHandleType<bool> myVisibilityAttribute;
 
   //! \brief Flag indicating if only the overlay should be rendered without the 3D scene
   bool myRenderOverlayOnly;
 
   //! \brief Flag indicating if the 3D scene should be hidden
   bool myWantSceneHidden;
 
   //! \brief Pointer to the OSG channel used for rendering
   makVrv::DtOsgChannel* myChannel;
 
   //! \brief Pointer to the observer object for the channel
   makVrv::DtObserverObject* myObserver;
 
   //! \brief QObject used as the owner for the QML UI
   QObject myQObject;
 
   //! \brief Flag indicating whether the QML data item has a tick(double) function
   bool myHasTickFunction;
};
} // namespace makVre