soundscape.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file soundscape.h
//! \brief Defines a soundscape system for managing ambient and periodic sounds
//!
//! The DtSoundscape class manages ambient background sounds and periodic sound
//! effects for creating immersive audio environments. It supports varying
//! sound volumes, pitches, and positions over time according to configured
//! parameters loaded from an initialization file.
 
#pragma once
 
#include "vrePlayerStation/export.h"
#include <makAudio/abstractAudio.h>
 
#include <matrix/vlVector.h>
 
#include <string>
#include <vector>
 
namespace makAudio
{
//! Forward declaration of DtSound class from makAudio namespace
class DtSound;
} // namespace makAudio
 
namespace makVre
{
//! Forward declaration of initialization table class
class DtInitTable;
 
//! \brief A class for managing ambient and periodic sound effects
//!
//! DtSoundscape loads and manages a collection of background ambient sounds
//! and periodic sound effects from a configuration file. Background sounds
//! play continuously with varying volume and pitch, while periodic sounds
//! play at random intervals from random positions within a specified range.
//! This provides a dynamic audio environment for immersive simulations.
class PLAYERSTATION_DLL DtSoundscape : public makAudio::DtAbstractAudio
{
public:
   //! \brief Constructor that loads a soundscape from a configuration file
   //! \param filename The path to the soundscape configuration file
   //!
   //! Loads background and periodic sound definitions from the specified
   //! configuration file, preparing them for playback when play() is called.
   DtSoundscape(std::string filename);
 
   //! \brief Destructor that cleans up all sound resources
   //!
   //! Stops all sounds and releases allocated resources for
   //! background and periodic sounds.
   virtual ~DtSoundscape() override;
 
   //! \brief Starts playing all background and periodic sounds
   //! \return True if playback started successfully
   //!
   //! Plays all background sounds immediately and begins the timer
   //! for periodic sounds. Also registers this soundscape for updates
   //! with the audio manager.
   virtual bool play() override;
 
   //! \brief Pauses all currently playing sounds
   //! \return True if all sounds were paused successfully
   //!
   //! Pauses all background and periodic sounds and stops updates
   //! from the audio manager.
   virtual bool pause() override;
 
   //! \brief Stops all sounds and resets them
   //! \return True if all sounds were stopped successfully
   //!
   //! Stops all background and periodic sounds and unregisters this
   //! soundscape from the audio manager.
   virtual bool stop() override;
 
   //! \brief Sets the master volume multiplier for all sounds
   //! \param vol The volume multiplier (gain) to apply
   //!
   //! Sets the master volume for all sounds in the soundscape.
   //! Individual sound volumes will be multiplied by this value.
   virtual void setGain(float vol) override;
 
protected:
   //! \brief Updates all sounds in the soundscape
   //! \param dt The time elapsed since the last update in seconds
   //!
   //! Called by the audio manager to update the state of all background
   //! and periodic sounds, applying volume and pitch variations and
   //! triggering periodic sounds as needed.
   virtual void update(double dt) override;
 
   //! \brief Loads a background sound configuration from initialization data
   //! \param data The initialization table containing background sound parameters
   //!
   //! Creates and configures a new background sound that plays continuously
   //! with varying volume and pitch parameters defined in the data table.
   void loadBackground(DtInitTable& data);
 
   //! \brief Loads a periodic sound configuration from initialization data
   //! \param data The initialization table containing periodic sound parameters
   //!
   //! Creates and configures a new periodic sound that plays at random intervals
   //! from random positions within a specified range.
   void loadPeriodic(DtInitTable& data);
 
   //! \brief A structure for managing a value that varies over time
   //!
   //! Handles automatic variation of a floating point value (like volume or pitch)
   //! within a specified range and over varying durations.
   struct Varying
   {
      //! \brief Current value of the parameter
      float currentVal;
 
      //! \brief Time remaining until next value change (seconds)
      float duration;
 
      //! \brief Rate of change per second toward target value
      float rate;
 
      //! \brief Minimum allowed value
      float minVal;
 
      //! \brief Maximum allowed value
      float maxVal;
 
      //! \brief Minimum time between value changes (seconds)
      float minTime;
 
      //! \brief Maximum time between value changes (seconds)
      float maxTime;
 
      //! \brief Resets the variation with a new random target value and duration
      //!
      //! Selects a new random target value between minVal and maxVal and
      //! calculates the rate of change needed to reach that value over a
      //! random duration between minTime and maxTime.
      void reset();
 
      //! \brief Updates the current value based on elapsed time
      //! \param dt Time elapsed since last update in seconds
      //!
      //! Applies the current rate of change to the current value and
      //! resets if the duration has elapsed.
      void update(double dt);
   };
 
   //! \brief A structure for managing a background ambient sound
   //!
   //! Represents a continuously playing ambient sound with varying
   //! volume and pitch characteristics.
   struct Background
   {
      //! \brief Constructor that initializes with parent soundscape reference
      //! \param soundscape Pointer to the parent soundscape
      Background(DtSoundscape* soundscape)
         : mySoundscape(soundscape)
      {
      }
 
      //! \brief The sound resource to play
      makAudio::DtSound* sound;
 
      //! \brief Volume variation controller
      Varying volume;
 
      //! \brief Pitch variation controller
      Varying pitch;
 
      //! \brief Updates the sound's volume and pitch
      //! \param dt Time elapsed since last update in seconds
      //!
      //! Applies current volume and pitch values to the sound and
      //! ensures it continues playing.
      void update(double dt);
 
      //! \brief Reference to the parent soundscape for gain access
      DtSoundscape* mySoundscape;
   };
 
   //! \brief A structure for managing a periodic sound effect
   //!
   //! Represents a sound that plays at random intervals from random
   //! positions within a configurable range.
   struct Periodic
   {
      //! \brief Constructor that initializes with parent soundscape reference
      //! \param soundscape Pointer to the parent soundscape
      Periodic(DtSoundscape* soundscape)
         : mySoundscape(soundscape)
      {
      }
 
      //! \brief The sound resource to play periodically
      makAudio::DtSound* sound;
 
      //! \brief Minimum position coordinates for random placement
      DtVector minRange;
 
      //! \brief Maximum position coordinates for random placement
      DtVector maxRange;
 
      //! \brief Time remaining until next sound trigger (seconds)
      float nextTime;
 
      //! \brief Minimum delay between sound triggers (seconds)
      float minDelay;
 
      //! \brief Maximum delay between sound triggers (seconds)
      float maxDelay;
 
      //! \brief Minimum pitch for random pitch selection
      float minPitch;
 
      //! \brief Maximum pitch for random pitch selection
      float maxPitch;
 
      //! \brief Updates the timer and triggers the sound when appropriate
      //! \param dt Time elapsed since last update in seconds
      //!
      //! Decrements the timer and when it reaches zero, plays the sound
      //! at a random position with random pitch, then resets the timer.
      void update(double dt);
 
      //! \brief Reference to the parent soundscape for gain access
      DtSoundscape* mySoundscape;
   };
 
   //! \brief Collection of all background sounds in this soundscape
   std::vector<Background*> myBackgrounds;
 
   //! \brief Collection of all periodic sounds in this soundscape
   std::vector<Periodic*> myPeriodics;
 
   //! \brief Path to the directory containing sound files
   std::string mySoundscapePath;
};
 
} // namespace makVre