audioUpdater.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file audioUpdater.h
//! \brief Defines the DtAudioUpdater component that plays audio sounds based on state attributes.
//!
//! This component manages audio playback for entities, allowing sounds to be triggered
//! by boolean state attributes in the VR environment.
//!
//! \ingroup vreCommonComponents
 
#pragma once
 
#include "vreCommonComponents/export.h"
 
#include "vrePlayerStation/playerComponent.h"
 
namespace makAudio
{
class DtSound;
}
 
namespace AudioUpdaterConfig
{
//! \ingroup RoleConfigParams
//! \defgroup AudioUpdaterRoleParams Audio Updater Role Parameters
//! \roleInherits{PlayerComponentRoleParams}
//! Configuration Options for audio updater role.
//! @{
 
//! \vreRoleParamRequired{audio,string,audioUpdater,"example.wav",Filename of the audio clip for a single source entry inside the sources table (resolved relative to audioPath).}
constexpr const char* audio = "audio";
 
//! \vreRoleParam{audioPath,string,"$(SHARED_DATA_DIR)/Audio/",audioUpdater,Base path for locating audio files used by configured sources.}
constexpr const char* audioPath = "audioPath";
 
//! \vreRoleParam{decibels,float,80.0,audioUpdater,Default decibel level applied to an audio source if not explicitly specified in its entry.}
constexpr const char* decibels = "decibels";
 
//! \vreRoleParam{gain,float,1.0,audioUpdater,Default gain multiplier applied to an audio source if not explicitly specified in its entry.}
constexpr const char* gain = "gain";
 
//! \vreRoleParam{is3d,bool,true,audioUpdater,Whether an audio source is spatialized in 3D (position follows the entity) by default.}
constexpr const char* is3d = "is3d";
 
//! \vreRoleParam{looping,bool,true,audioUpdater,Whether an audio source should loop continuously when enabled by default.}
constexpr const char* looping = "looping";
 
//! \vreRoleParam{sources,table,"",audioUpdater,Table (list) of per-sound source configuration entries defining audio playback behavior.}
constexpr const char* sources = "sources";
 
//! \vreRoleParam{stateAttribute,string,"",audioUpdater,Name of the boolean state attribute that enables playback for a source entry (empty string means always enabled).}
constexpr const char* stateAttribute = "stateAttribute";
 
//! @}
} // namespace AudioUpdaterConfig
 
namespace makVre
{
//! \brief Type identifier for DtAudioUpdater component
constexpr const char* DtAudioUpdaterType = "DtAudioUpdater";
 
//! \brief Component for playing audio sounds based on entity state attributes
//!
//! The DtAudioUpdater plays audio sounds for the engaged entity based on the value
//! of boolean state attributes. Each configured sound is associated with a state attribute
//! and will play when that attribute is true. Sounds can be configured to loop, play at
//! specific loudness levels, and be positioned in 3D space at the entity's location.
//!
//! Note that entities that are destroyed will not play sounds, regardless of state attributes.
//!
//! Example Lua configuration:
//! \code
//! ["sirenAudioUpdater"] = {
//!       componentType = "DtAudioUpdater";
//!       priority = 10;
//!       audioPath = "$(SHARED_DATA_DIR)\\Audio\\sirens\\";
//!       sources = {
//!          {  audio = "siren-1-fast-loop.wav";  stateAttribute = "siren-fast"; -- [[ default values:looping = true;
//!          gain = 1.0; decibels = 80.0; is3d = true; ]] }; {  audio = "siren-1-slow-loop.wav";  stateAttribute =
//!          "siren-slow"; -- [[ default values:looping = true; gain = 1.0; decibels = 80.0;  is3d = true; ]] }; { audio
//!          = "siren-airhorn-single.wav";  stateAttribute = "siren-horn"; looping = false; -- [[ default values:gain
//!          = 1.0; decibels = 80.0; is3d = true;]] }; {  audio = "siren-piercer-loop.wav";  stateAttribute =
//!          "siren-piercer"; -- [[ default values:looping = true; gain = 1.0; decibels = 80.0; is3d = true;]] };
//!       };
//! };
//! \endcode
class VRECOMMONCOMPONENTS_DLL DtAudioUpdater : public DtPlayerComponent
{
public:
   //! \brief Constructor for DtAudioUpdater
   //!
   //! Initializes the component with the name "DtAudioUpdater".
   DtAudioUpdater();
 
   //! \brief Virtual destructor for DtAudioUpdater
   //!
   //! Ensures proper cleanup of audio resources when the component is destroyed.
   virtual ~DtAudioUpdater() override;
 
   //! \brief Initializes the component with configuration from Lua
   //!
   //! Sets up audio sources based on the provided configuration. Each source is configured
   //! with its associated state attribute, looping behavior, gain, decibel level, and 3D positioning.
   //!
   //! \param player Pointer to the player station this component belongs to
   //! \param config Configuration table containing initialization parameters, especially the sources table
   //! \return True if initialization succeeds, false otherwise
   virtual bool initialize(DtPlayerStation* player, DtInitTable& config) override;
 
   //! \brief Updates the audio playback based on state attributes
   //!
   //! Called each frame to manage audio playback. For each configured sound, checks its
   //! associated state attribute and plays/stops the sound accordingly. For 3D sounds,
   //! updates their position to match the entity's current location.
   //!
   //! For non-looping sounds, the component will automatically set the state attribute
   //! to false when the sound finishes playing.
   //!
   //! \param dt Delta time in seconds since the last tick
   virtual void tick(double dt) override;
 
   //! \brief Shuts down the component
   //!
   //! Cleans up all audio resources by stopping and deleting sounds.
   virtual void shutdown() override;
 
   //! \brief Returns the component type identifier
   //! \return The component type string
   virtual const char* type() const override;
 
protected:
   //! \brief Structure for managing sound resources and their associated state attributes
   struct Sound
   {
      //! \brief Name of the state attribute that controls this sound
      //!
      //! When this attribute is true, the sound will play. If empty, the sound is always enabled.
      std::string myStateVar;
 
      //! \brief Pointer to the audio source for this sound
      makAudio::DtSound* mySource;
 
      //! \brief Flag to track if a non-looping sound has been triggered
      //!
      //! Used to prevent repeatedly triggering non-looping sounds that are still playing.
      bool myTriggered;
 
      //! \brief Default constructor initializing member variables
      Sound()
         : myStateVar("")
         , mySource(0)
         , myTriggered(false)
      {
      }
   };
 
   //! \brief Collection of sounds managed by this component
   std::vector<Sound> mySounds;
};
} // namespace makVre