vreModelSetEntry.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreModelSetEntry.h
//! \ingroup vreUtil
//! \brief Extends model set entries with VR-Engage specific role data
//!
//! This file defines the DtVreModelSetEntry class which extends VR-Forces' DtModelSetEntry
//! with the ability to read and write VR-Engage-specific role data in entity files.
//! It manages role descriptors, parameters, and display configurations for entities.
 
#pragma once
 
#include "vreUtil/export.h"
#include "vreUtil/entityRoleDescriptorStructs.h"
#include "vreUtil/vreModelSetEntry.h"
 
#include <vrfobjparam/modelSetEntry.h>
 
namespace vreXml
{
//! \brief XML tag for VR-Engage roles container
static const char* EngageRolesTag = "vrEngageRoles";
//! \brief XML tag for individual VR-Engage role
static const char* EngageRoleTag = "role";
//! \brief XML tag for role slot name attribute
static const char* EngageRoleSlotNameTag = "slotName";
//! \brief XML tag for unlisted role attribute
static const char* EngageRoleUnlistedTag = "unlisted";
//! \brief XML tag for default display layout attribute
static const char* EngageRoleDefaultDisplayConfigTag = "defaultDisplayLayout";
//! \brief XML tag for parameter override element
static const char* EngageParameterOverrideTag = "parameterOverride";
//! \brief XML tag for display configuration element
static const char* EngageDisplayConfigurationTag = "displayConfiguration";
} // namespace vreXml
 
namespace makVre
{
//! \brief Default display layout name for entity roles
//!
//! It is expected that there will always be a default display layout available
//! for all entity roles. This is the name of that expected display layout.
static const char* DtDefaultDisplayLayout = "1 Screen Horizontal";
 
//! \brief Default value for the unlisted attribute of roles
//!
//! By default, role configurations should be listed in the Choose Role panel.
//! Setting this to true would hide the role from the panel.
static bool DtDefaultUnlistedValue = false;
 
//! \brief VR-Engage specific model set entry with role information
//!
//! This class extends the base VR-Forces model set entry to provide VR-Engage
//! specific functionality for managing entity roles, role parameters, and display
//! configurations. It handles reading and writing role data to/from entity files.
class UTIL_DLL DtVreModelSetEntry : public DtModelSetEntry
{
public:
   //! \brief Default constructor
   //!
   //! Creates an empty model set entry with no name or registry
   DtVreModelSetEntry();
 
   //! \brief Named constructor with optional registry
   //! \param name The name of the model set entry
   //! \param parentRegistry Optional parent registry for resource loading
   DtVreModelSetEntry(const DtString& name, DtReaderWriterRegistry* const parentRegistry = NULL);
 
   //! \brief Copy constructor
   //! \param orig The model set entry to copy
   //! \param parentRegistry Optional parent registry for resource loading
   DtVreModelSetEntry(const DtVreModelSetEntry& orig, DtReaderWriterRegistry* const parentRegistry = NULL);
 
   //! \brief Assignment operator for VR-Engage model set entries
   //! \param orig The model set entry to copy from
   //! \return Reference to this object
   //!
   //! Performs a deep copy of the VR-Engage specific data
   virtual DtVreModelSetEntry& operator=(const DtVreModelSetEntry& orig);
 
   //! \brief Assignment operator for base model set entries
   //! \param orig The base model set entry to copy from
   //! \return Reference to this object
   //!
   //! The override allows us to eventually call the derived assignment operator
   virtual DtVreModelSetEntry& operator=(const DtModelSetEntry& orig) override;
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources owned by the model set entry
   virtual ~DtVreModelSetEntry() override;
 
   //! \brief Creates a copy of this model set entry
   //! \return Pointer to the newly created copy
   virtual DtModelSetEntry* clone() override;
 
   //! \brief Checks if this entity can be controlled in VR-Engage
   //! \return True if the entity is controllable in VR-Engage, false otherwise
   virtual bool engageControllable() const;
 
   //! \brief Gets the list of available roles for this entity
   //! \return Vector of role names
   virtual std::vector<std::string> roles();
 
   //! \brief Finds a role descriptor by name
   //! \param role The name of the role to find
   //! \return Pointer to the role descriptor if found, nullptr otherwise
   virtual const DtEntityRoleDescriptor* findRoleDescriptor(const std::string& role);
 
   //! \brief Adds a new role to the entity
   //! \param role The name of the role to add
   //! \param rolePath Path to the role configuration file
   //! \param unlisted Whether the role should be hidden from role selection panels
   virtual void addRole(const std::string& role, const std::string& rolePath, bool unlisted = false);
 
   //! \brief Adds a parameter to an existing role
   //! \param role The name of the role to add the parameter to
   //! \param roleParameter The name of the parameter to add
   //! \param paramValue The value of the parameter
   virtual void addRoleParameter(
      const std::string& role, const std::string& roleParameter, const std::string& paramValue);
 
   //! \brief Loads model set entry information from the specified environment
   //! \param e The environment to read from
   //! \param objectNode The object node to read from
   //! \param keepCurrentData Whether to retain existing data when reading
   //!
   //! Looks for a variable in the environment called guiInformation and extracts
   //! attributes and role information from that node. VR-Engage specific data is
   //! read from the vrEngageRoles section if present.
   virtual void readFromEnvironment(DtEnvironmentSP e, DtEnvValueSP objectNode, bool keepCurrentData = false) override;
 
   //! \brief Writes entry contents to the specified environment
   //! \param e The environment to write to
   //! \param objectNode The object node to write to
   //! \param vec Optional vector to track modified attributes
   //! \param mse Optional model set entry for reference
   //!
   //! Writes the model set entry information to the guiInformation section of the
   //! environment. VR-Engage specific role data is written to the vrEngageRoles section.
   virtual void writeToEnvironment(DtEnvironmentSP e,
      DtEnvValueSP objectNode,
      std::vector<DtString>* vec = nullptr,
      DtModelSetEntry* mse = nullptr) const override;
 
   //! \brief Gets the filename associated with this entry
   //! \return The filename of the entity file that created this entry
   virtual std::string filename() const;
 
   //! \brief Factory method for creating model set entry instances
   //! \param name The name of the model set entry to create
   //! \param parentRegistry Optional parent registry for resource loading
   //! \return Pointer to the newly created model set entry
   //!
   //! This static method creates a new instance of DtVreModelSetEntry. Used by the factory system.
   static DtModelSetEntry* Create(
      const DtString& name = "model-set-entry", DtReaderWriterRegistry* const parentRegistry = nullptr);
 
protected:
   //! \brief Gets parameter overrides from an environment node
   //! \param e The environment to read from
   //! \param node The node to read parameters from
   //! \param parameterOverrides Output map to store parameter name/value pairs
   //!
   //! Extracts parameter overrides from the given node, only including parameters
   //! that are immediate children of that node.
   virtual void getParameterOverrides(
      DtEnvironmentSP e, DtEnvValueSP node, std::map<std::string, std::string>& parameterOverrides);
 
   //! \brief Resolves path variables in a string
   //! \param path The path string to resolve
   //! \return The resolved path with variables expanded
   //!
   //! Replaces instances of '@' with '$' (as '@' is used instead of '$' in XML files)
   //! and then resolves any $DATA_DIR or $SHARED_DATA_DIR variables in the path.
   virtual std::string resolvePath(const std::string& path) const;
 
   //! \brief Marks up a path with variables for XML storage
   //! \param path The path string to mark up
   //! \return The marked up path with variables and XML-safe characters
   //!
   //! Substitutes in $DATA_DIR or $SHARED_DATA_DIR variables for specific path prefixes,
   //! and replaces '$' with '@' (needed for XML files which cannot tolerate '$').
   virtual std::string markupPath(const std::string& path) const;
 
protected:
   //! \brief Map of role names to role descriptors
   //!
   //! Contains all the roles supported by this entity and their associated configuration
   std::map<std::string, DtEntityRoleDescriptor> myRoleDescriptors;
 
   //! \brief Cache of the filename used to create this entry
   //!
   //! Stores the path to the entity file that was loaded to create this entry
   std::string myFilename;
};
} // namespace makVre