DtSceneObjectMimicUpdater.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file DtSceneObjectMimicUpdater.h
//! \brief Defines the DtSceneObjectMimicUpdater class that allows one scene object to mimic another's position.
//!
//! This updater allows a scene object to follow the position and orientation of another scene object
//! with an optional offset. This is particularly useful for implementing first-person views,
//! attached equipment, or any other entity that needs to follow another entity's movements.
//!
//! \ingroup vreCommonComponents
 
#pragma once
 
#include "vreCommonComponents/export.h"
 
#include <vrvCore/DtSceneObjectUpdater.h>
 
namespace makVrv
{
//! \brief Forward declaration of the model instance class
class DtModelInstance;
 
//! \brief Forward declaration of the OSG model instance class
class DtOsgModelInstance;
} // namespace makVrv
 
namespace osg
{
//! \brief Forward declaration of the OSG node class
class Node;
} // namespace osg
 
using namespace makVrv;
 
namespace makVre
{
//! \brief Scene object updater that mimics the position and orientation of another scene object
//!
//! The DtSceneObjectMimicUpdater allows one scene object to follow another's position and orientation
//! with an optional offset. This updater is responsible for connecting to the parent scene object,
//! tracking its position, and updating the child scene object accordingly. It also handles special
//! cases like DiGuy character models and configures the child object's rendering properties.
//!
//! Common use cases include:
//! - First-person view models (cockpit interiors, weapon models)
//! - Attached equipment (backpacks, tools, accessories)
//! - Character models that need to follow another entity
class VRECOMMONCOMPONENTS_DLL DtSceneObjectMimicUpdater : public DtSceneObjectUpdater
{
public:
   //! \brief Constructor for DtSceneObjectMimicUpdater
   //!
   //! Initializes the updater with default values (no parent object, null model instance,
   //! and zero speeds).
   //!
   //! \param de Reference to the dynamic environment
   //! \param id Unique identifier for this updater
   DtSceneObjectMimicUpdater(DtDe& de, DtUniqueID id);
 
   //! \brief Virtual destructor for DtSceneObjectMimicUpdater
   //!
   //! Clears the parent scene object reference to avoid dangling pointers.
   virtual ~DtSceneObjectMimicUpdater() override;
 
   //! \brief Updates the scene object's position and orientation
   //!
   //! Called each frame to update the scene object's position and orientation based on
   //! the parent scene object. Performs model checking and position updating.
   //!
   //! \param tNow Current simulation time
   virtual void update(DtTime tNow) override;
 
   //! \brief Sets the parent scene object to copy position from
   //!
   //! Establishes a connection to the specified scene object and sets up a signal/slot
   //! to handle parent object deletion. If a previous parent was set, disconnects from it.
   //!
   //! \param id Unique identifier of the parent scene object
   virtual void setParentSceneObject(DtUniqueID id);
 
   //! \brief Sets the offset from the parent object
   //!
   //! Defines a local offset vector to apply when positioning this object relative to
   //! the parent. The offset is applied in the parent's local coordinate system.
   //!
   //! \param offset Vector offset to apply (typically in meters)
   virtual void setModelOffset(const DtVector& offset);
 
protected:
   //! \brief Checks if the model instance has changed
   //!
   //! Verifies if the current scene object's model instance has changed since the last update.
   //! If it has, initializes the new model instance by calling initModel().
   virtual void checkModel();
 
   //! \brief Initializes a new model instance
   //!
   //! Sets up a new model instance, detecting if it's an OSG model instance and configuring it accordingly.
   //!
   //! \param modelInstance Pointer to the model instance to initialize
   virtual void initModel(DtModelInstance* modelInstance);
 
   //! \brief Sets up OSG nodes for an OSG model instance
   //!
   //! Retrieves the root node from the OSG model instance and sets it up.
   //!
   //! \param osgModelInstance Pointer to the OSG model instance to configure
   virtual void setupOsgNodes(DtOsgModelInstance* osgModelInstance);
 
   //! \brief Configures an OSG node
   //!
   //! Sets up rendering properties for the node, including:
   //! - Disabling intersection testing (making the model not selectable)
   //! - Disabling shadow casting
   //! - Setting the render bin to ensure proper rendering order
   //!
   //! \param node Pointer to the OSG node to configure
   virtual void setupOsgNode(osg::Node* node);
 
   //! \brief Updates the position and orientation
   //!
   //! Calculates and applies the position and orientation based on the parent object.
   //! Handles special cases like DiGuy character models.
   //!
   //! \param tNow Current simulation time
   virtual void updatePosition(DtTime tNow);
 
   //! \brief Signal handler for parent scene object deletion
   //!
   //! Called when the parent scene object is about to be deleted.
   //! Clears the reference to avoid dangling pointers.
   //!
   //! \param id The unique ID of the scene object being deleted
   virtual void slot_parentSceneObjectToBeDeleted(const DtUniqueID& id);
 
   //! \brief Pointer to the parent scene object being mimicked
   //!
   //! This is the scene object whose position and orientation are being copied.
   DtSceneObject* myParentSceneObject;
 
   //! \brief Pointer to the current model instance
   //!
   //! The model instance for the scene object being updated.
   DtModelInstance* myModelInstance;
 
   //! \brief Offset vector to apply when positioning
   //!
   //! Local offset to apply from the parent object's position.
   DtVector myModelOffset;
 
   //! \brief Smoothed linear speed
   //!
   //! Cached and smoothed linear speed value for animation purposes.
   double myLinearSpeed;
 
   //! \brief Smoothed yaw rotation speed
   //!
   //! Cached and smoothed yaw rotation speed value for animation purposes.
   double myYawSpeed;
};
} // namespace makVre