Root Directory > Code > Engine > Audio
The Audio module provides a comprehensive FMOD-based 3D audio system enabling immersive sound experiences with spatial audio, dynamic sound loading, real-time audio parameter control, and multi-listener support for complex audio scenarios.
AudioSystem.hpp
- Main audio system interface and management
sAudioSystemConfig config;
AudioSystem* audioSystem = new AudioSystem(config);
audioSystem->Startup();
// Basic audio usage
SoundID soundId = audioSystem->CreateOrGetSound("Data/Audio/music.wav", eAudioSystemSoundDimension::Sound2D);
SoundPlaybackID playbackId = audioSystem->StartSound(soundId, false, 1.0f, 0.0f, 1.0f, false);
// 3D positioned sound
SoundID sound3D = audioSystem->CreateOrGetSound("Data/Audio/effect.wav", eAudioSystemSoundDimension::Sound3D);
Vec3 soundPosition(10.0f, 0.0f, 5.0f);
SoundPlaybackID playback3D = audioSystem->StartSoundAt(sound3D, soundPosition, false, 10.0f);
class AudioSystem {
// System lifecycle
void Startup();
void Shutdown();
void BeginFrame();
void EndFrame();
// Sound loading and management
SoundID CreateOrGetSound(String const& soundFilePath, eAudioSystemSoundDimension dimension);
// 2D sound playback
SoundPlaybackID StartSound(SoundID soundID, bool isLooped = false, float volume = 1.f,
float balance = 0.f, float speed = 1.f, bool isPaused = false);
// 3D spatial sound playback
SoundPlaybackID StartSoundAt(SoundID soundID, Vec3 const& soundPosition,
bool isLooped = false, float volume = 10.0f,
float balance = 0.0f, float speed = 1.0f, bool isPaused = false);
// Playback control
void StopSound(SoundPlaybackID soundPlaybackID);
void SetSoundPlaybackVolume(SoundPlaybackID soundPlaybackID, float volume);
void SetSoundPlaybackBalance(SoundPlaybackID soundPlaybackID, float balance);
void SetSoundPlaybackSpeed(SoundPlaybackID soundPlaybackID, float speed);
void SetSoundPosition(SoundPlaybackID soundPlaybackID, const Vec3& soundPosition);
bool IsPlaying(SoundPlaybackID soundPlaybackID);
};
// Multi-listener support for complex audio scenarios
void SetNumListeners(int numListeners) const;
void UpdateListener(int listenerIndex, Vec3 const& listenerPosition,
Vec3 const& listenerForward, Vec3 const& listenerUp) const;
enum class eAudioSystemSoundDimension : int8_t {
Sound2D, // Traditional stereo/mono sounds
Sound3D // Spatially positioned sounds with distance attenuation
};
- FMOD Studio API: Professional audio middleware (
fmod.lib
, fmodstudio.lib
)
- FMOD Core: Low-level audio processing engine
- FMOD headers from
ThirdParty/fmod/fmod.hpp
- Math module for 3D vector operations (
Vec3
)
- Core module for string utilities and basic types
- Platform module for file system access
struct sAudioSystemConfig {
// Currently minimal configuration
// Future expansion: sample rates, buffer sizes, channel counts
};
typedef size_t SoundID;
typedef size_t SoundPlaybackID;
size_t constexpr MISSING_SOUND_ID = static_cast<size_t>(-1);
// Internal sound registry
std::map<String, SoundID> m_registeredSoundIDs;
std::vector<FMOD::Sound*> m_registeredSounds;
class AudioSystem {
protected:
FMOD::System* m_fmodSystem; // FMOD system instance
std::map<String, SoundID> m_registeredSoundIDs; // Sound path to ID mapping
std::vector<FMOD::Sound*> m_registeredSounds; // Loaded sound assets
};
// Conversion between engine Vec3 and FMOD_VECTOR
FMOD_VECTOR CastVec3ToFmodVec(Vec3 const& vectorToCast) const;
FMOD_VECTOR CreateZeroVector() const;
// FMOD result validation with comprehensive error reporting
void ValidateResult(FMOD_RESULT result);
- FMOD Error Checking: Automatic validation of all FMOD API calls
- Sound Asset Validation: File existence and format checking
- Memory Management: Automatic cleanup of FMOD resources
- Performance Monitoring: Built-in FMOD performance profiling
- Manual audio testing through developer console commands
- 3D spatial audio verification through listener movement
- Volume and pitch parameter validation
- Memory usage tracking for loaded audio assets
- Automatic sound format support detection
- Robust error handling for missing audio files
- Thread-safe audio operations
- Graceful degradation when audio hardware is unavailable
- Automated audio unit tests for API functions
- 3D spatial audio accuracy testing
- Performance benchmarks for large-scale audio scenarios
- Cross-platform audio compatibility testing
A: FMOD supports a wide range of formats including WAV, MP3, OGG, FLAC, AIFF, and many others. Compressed formats are automatically decoded.
A: 3D sounds use FMOD's built-in spatial processing with distance attenuation, doppler effects, and listener orientation for realistic positional audio.
A: Yes, each
StartSound()
call returns a unique
SoundPlaybackID
for independent control of multiple playback instances.
A: Use
StartSound()
with
isLooped = true
. FMOD handles seamless looping for properly prepared audio files.
A: FMOD operations are internally thread-safe, but it's recommended to call audio functions from the main thread for consistency.
A: Future enhancements will include master volume controls and audio category management through FMOD Studio integration.
AudioSystem.cpp
- Main audio system implementation with FMOD integration
AudioSystem.hpp
- Public API declarations and type definitions
The Audio module integrates with:
- Math Module: Vec3 for 3D positioning and listener orientation
- Core Module: String utilities for file path management
- Event System: For audio-triggered events and callbacks
- Resource System: For efficient audio asset loading and caching
- FMOD Studio integration for advanced audio features
- Audio streaming for large music files
- Real-time audio effects and filters
- Audio occlusion and obstruction simulation
- Dynamic music system with interactive transitions
- 2025-11-24: Audio module documentation updated for Assignment 7
- Confirmed AudioSystem ready for A7 sound effects integration (FR-7)
- Will be used for Minecraft-style mining, placing, and crafting sounds
- Existing API supports
.wav
and .mp3
loading from Run/Data/Audio/
- No changes needed - system already production-ready for A7 requirements
- 2025-09-06 21:17:11: Initial Audio module documentation created
- Recent developments: 3D spatial audio system, multi-listener support, comprehensive FMOD integration