AudioDeviceManager.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
#pragma once
 
#include "AudioDefines.h"
#include "AudioDeviceHandle.h"
#include "AudioThread.h"
#include "CoreMinimal.h"
#include "UObject/WeakObjectPtr.h"
 
 
#if ENABLE_AUDIO_DEBUG
class FAudioDebugger;
#endif // ENABLE_AUDIO_DEBUG
 
class FReferenceCollector;
class FSoundBuffer;
class IAudioDeviceModule;
class UAudioComponent;
class USoundClass;
class USoundMix;
class USoundSubmixBase;
class USoundWave;
class UWorld;
class FAudioDevice;
struct FSourceEffectChainEntry;
class FSimpleAudioInfoFactory;
 
namespace Audio
{
    class FMixerDevice;
    class FAudioDebugger;
    class FAudioFormatSettings;
}
 
enum class ESoundType : uint8
{
    Class,
    Cue,
    Wave
};
 
// This enum is used in FAudioDeviceManager::RequestAudioDevice to map a given UWorld to an audio device.
enum class EAudioDeviceScope : uint8
{
    // Default to the behavior specified by the editor preferences.
    Default,
    // Use an audio device that can be shared by multiple worlds.
    Shared,
    // Create a new audio device specifically for this handle.
    Unique
};
 
// Parameters passed into FAudioDeviceManager::RequestAudioDevice.
struct FAudioDeviceParams
{
    // Optional world parameter. This allows tools to surface information about which worlds are being rendered through which audio devices.
    UWorld* AssociatedWorld = nullptr;
    // This should be set to EAudioDeviceScope::Unique if you'd like to force a new device to be created from scratch, or use EAudioDeviceScope::Shared to use an existing device if possible.
    EAudioDeviceScope Scope = EAudioDeviceScope::Default;
    // Set this to true to get a handle to a non realtime audio renderer.
    bool bIsNonRealtime = false;
    // Use this to force this audio device to use a specific audio module. If nullptr, uses the default audio module.
    IAudioDeviceModule* AudioModule = nullptr;
    // Buffer size override
    int32 BufferSizeOverride = INDEX_NONE;
    // Num buffers override
    int32 NumBuffersOverride = INDEX_NONE;
};
 
// List of delegates for the audio device manager.
class FAudioDeviceManagerDelegates
{
public:
    // This delegate is called whenever an entirely new audio device is created.
    DECLARE_TS_MULTICAST_DELEGATE_OneParam(FOnAudioDeviceCreated, Audio::FDeviceId /* AudioDeviceId*/);
    static ENGINE_API FOnAudioDeviceCreated OnAudioDeviceCreated;
 
    // This delegate is called whenever an audio device is destroyed.
    DECLARE_TS_MULTICAST_DELEGATE_OneParam(FOnAudioDeviceDestroyed, Audio::FDeviceId /* AudioDeviceId*/);
    static ENGINE_API FOnAudioDeviceDestroyed OnAudioDeviceDestroyed;
};
 
class FAudioDeviceManager
{
public:
 
    ENGINE_API FAudioDeviceManager();
 
    ENGINE_API ~FAudioDeviceManager();
 
    const FAudioDeviceHandle & GetMainAudioDeviceHandle() const { return MainAudioDeviceHandle; }
    FAudioDevice* GetMainAudioDeviceRaw() const { return MainAudioDeviceHandle.GetAudioDevice(); }
    Audio::FDeviceId GetMainAudioDeviceID() const { return MainAudioDeviceHandle.GetDeviceID(); }
 
    static ENGINE_API FAudioDevice* GetAudioDeviceFromWorldContext(const UObject* WorldContextObject);
    static ENGINE_API Audio::FMixerDevice* GetAudioMixerDeviceFromWorldContext(const UObject* WorldContextObject);
 
    ENGINE_API IAudioDeviceModule* GetAudioDeviceModule();
 
    ENGINE_API FAudioDeviceParams GetDefaultParamsForNewWorld();
 
    ENGINE_API FAudioDeviceHandle RequestAudioDevice(const FAudioDeviceParams& InParams);
 
    ENGINE_API bool IsValidAudioDevice(Audio::FDeviceId DeviceID) const;
 
    ENGINE_API FAudioDeviceHandle GetAudioDevice(Audio::FDeviceId InDeviceID);
 
    ENGINE_API FAudioDevice* GetAudioDeviceRaw(Audio::FDeviceId InDeviceID);
    ENGINE_API const FAudioDevice* GetAudioDeviceRaw(Audio::FDeviceId InDeviceID) const;
 
    ENGINE_API void SetAudioDevice(UWorld& InWorld, Audio::FDeviceId InDeviceID);
 
    static ENGINE_API bool PreInitialize();
 
    static ENGINE_API bool Initialize();
 
    static ENGINE_API FAudioDeviceManager* Get();
 
    static ENGINE_API void Shutdown();
 
    ENGINE_API bool CreateMainAudioDevice();
 
    ENGINE_API FAudioDeviceHandle GetActiveAudioDevice();
 
    ENGINE_API uint8 GetNumActiveAudioDevices() const;
 
    ENGINE_API uint8 GetNumMainAudioDeviceWorlds() const;
 
    ENGINE_API void UpdateActiveAudioDevices(bool bGameTicking);
 
    ENGINE_API void IterateOverAllDevices(TUniqueFunction<void(Audio::FDeviceId, FAudioDevice*)> ForEachDevice);
    ENGINE_API void IterateOverAllDevices(TUniqueFunction<void(Audio::FDeviceId, const FAudioDevice*)> ForEachDevice) const;
 
    ENGINE_API void AddReferencedObjects(FReferenceCollector& Collector);
 
    ENGINE_API void StopSoundsUsingResource(class USoundWave* InSoundWave, TArray<UAudioComponent*>* StoppedComponents = nullptr);
 
    ENGINE_API void RegisterSoundClass(USoundClass* SoundClass);
 
    ENGINE_API void UnregisterSoundClass(USoundClass* SoundClass);
 
    ENGINE_API void RegisterWorld(UWorld* InWorld, Audio::FDeviceId DeviceId);
 
    ENGINE_API void UnregisterWorld(UWorld* InWorld, Audio::FDeviceId DeviceId);
 
    ENGINE_API void InitSoundClasses();
 
    ENGINE_API void RegisterSoundSubmix(USoundSubmixBase* SoundSubmix);
 
    ENGINE_API void UnregisterSoundSubmix(const USoundSubmixBase* SoundSubmix);
 
    ENGINE_API void InitSoundSubmixes();
 
    UE_DEPRECATED(5.4, "Will be removed in upcoming versions of this code")
    ENGINE_API void InitSoundEffectPresets();
 
    ENGINE_API void UpdateSourceEffectChain(const uint32 SourceEffectChainId, const TArray<FSourceEffectChainEntry>& SourceEffectChain, const bool bPlayEffectChainTails);
 
    ENGINE_API void UpdateSubmix(USoundSubmixBase* SoundSubmix);
 
    ENGINE_API void SetActiveDevice(uint32 InAudioDeviceHandle);
 
    ENGINE_API void SetSoloDevice(Audio::FDeviceId InAudioDeviceHandle);
 
    UE_DEPRECATED(5.5, "This is no longer used.  Existing calls may be deleted")
    ENGINE_API void TrackResource(USoundWave* SoundWave, FSoundBuffer* Buffer);
    ENGINE_API void FreeResource(USoundWave* SoundWave);
 
    UE_DEPRECATED(5.5, "This is no longer used.  Existing calls may be deleted")
    ENGINE_API void FreeBufferResource(FSoundBuffer* SoundBuffer);
 
    UE_DEPRECATED(5.5, "This is no longer used.  Existing calls may be deleted")
    ENGINE_API void StopSourcesUsingBuffer(FSoundBuffer* Buffer);
 
    UE_DEPRECATED(5.5, "This is no longer used.  Existing calls may be deleted")
    ENGINE_API FSoundBuffer* GetSoundBufferForResourceID(uint32 ResourceID);
 
    UE_DEPRECATED(5.5, "This is no longer used.  Existing calls may be deleted")
    ENGINE_API void RemoveSoundBufferForResourceID(uint32 ResourceID);
 
    ENGINE_API void RemoveSoundMix(USoundMix* SoundMix);
 
    ENGINE_API void TogglePlayAllDeviceAudio();
 
    bool IsPlayAllDeviceAudio() const { return bPlayAllDeviceAudio; }
 
    ENGINE_API bool IsAlwaysPlayNonRealtimeDeviceAudio() const;
 
    ENGINE_API bool IsVisualizeDebug3dEnabled() const;
 
    ENGINE_API void ToggleVisualize3dDebug();
 
    ENGINE_API void ResetAllDynamicSoundVolumes();
 
    ENGINE_API float GetDynamicSoundVolume(ESoundType SoundType,  const FName& SoundName) const;
    ENGINE_API void ResetDynamicSoundVolume(ESoundType SoundType, const FName& SoundName);
    ENGINE_API void SetDynamicSoundVolume(ESoundType SoundType, const FName& SoundName, float Volume);
 
#if ENABLE_AUDIO_DEBUG
    ENGINE_API Audio::FAudioDebugger& GetDebugger();
    ENGINE_API const Audio::FAudioDebugger& GetDebugger() const;
#endif // ENABLE_AUDIO_DEBUG
 
public:
 
    UE_DEPRECATED(5.5, "This is no longer used and should not be accessed directly.")
    TArray<FSoundBuffer*>           Buffers;
    
    UE_DEPRECATED(5.5, "This is no longer used and should not be accessed directly.")
    TMap<int32, FSoundBuffer*>  WaveBufferMap;
 
    ENGINE_API TArray<FAudioDevice*> GetAudioDevices() const;
 
    ENGINE_API TArray<UWorld*> GetWorldsUsingAudioDevice(const Audio::FDeviceId& InID) const;
 
#if INSTRUMENT_AUDIODEVICE_HANDLES
    ENGINE_API void AddStackWalkForContainer(Audio::FDeviceId InId, uint32 StackWalkID, FString&& InStackWalk);
    ENGINE_API void RemoveStackWalkForContainer(Audio::FDeviceId InId, uint32 StackWalkID);
#endif
 
    ENGINE_API void LogListOfAudioDevices();
 
    ENGINE_API Audio::FAudioFormatSettings& GetAudioFormatSettings() const;
 
    ENGINE_API static void EnableAggregateDeviceSupport(const bool bInEnableAggregateDevice);
    ENGINE_API static bool IsAggregateDeviceSupportEnabled();
 
private:
 
#if ENABLE_AUDIO_DEBUG
    TUniquePtr<Audio::FAudioDebugger> AudioDebugger;
#endif // ENABLE_AUDIO_DEBUG
 
    TPimplPtr<Audio::FAudioFormatSettings> AudioFormatSettings;
    TArray<TPimplPtr<FSimpleAudioInfoFactory>> EngineFormats;
 
    static bool bEnableAggregateDeviceSupport;
 
    static FAudioDeviceManager* GetOrCreate();
 
    ENGINE_API uint32 GetNewDeviceID();
 
    ENGINE_API bool LoadDefaultAudioDeviceModule();
 
    ENGINE_API FAudioDeviceHandle CreateNewDevice(const FAudioDeviceParams& InParams);
 
    // Called exclusively by the FAudioDeviceHandle copy constructor and assignment operators:
    ENGINE_API void IncrementDevice(Audio::FDeviceId DeviceID);
 
    // Called exclusively by the FAudioDeviceHandle dtor.
    ENGINE_API void DecrementDevice(Audio::FDeviceId DeviceID, UWorld* InWorld);
 
    ENGINE_API void AppWillEnterBackground();
    
    ENGINE_API void RegisterAudioInfoFactories();
 
    bool IsInitialized() const { return InitPhase == EInitPhase::Initialized; } 
 
    ENGINE_API bool PreInitializeManager();
 
    ENGINE_API bool InitializeManager();
 
    IAudioDeviceModule* AudioDeviceModule;
 
    FString AudioMixerModuleName;
 
    FAudioDeviceHandle MainAudioDeviceHandle;
 
    struct FAudioDeviceContainer
    {
        // Singularly owned device.
        // Could be a TUniquePtr if FAudioDevice was not an incomplete type here.
        FAudioDevice* Device;
 
        // Ref count of FAudioDeviceHandles referencing this device.
        int32 NumberOfHandlesToThisDevice;
 
        TArray<UWorld*> WorldsUsingThisDevice;
 
        EAudioDeviceScope Scope;
 
        bool bIsNonRealtime;
 
        IAudioDeviceModule* SpecifiedModule;
 
        FAudioDeviceContainer(const FAudioDeviceParams& InParams, Audio::FDeviceId InDeviceID, FAudioDeviceManager* DeviceManager);
        ~FAudioDeviceContainer();
 
        FAudioDeviceContainer(const FAudioDeviceContainer& Other)
        {
            // We explicitly enforce that we invoke the move instructor.
            // If this was hit, you likely need to call either Devices.Emplace(args) or Devices.Add(DeviceID, MoveTemp(Container));
            checkNoEntry();
        }
 
        FAudioDeviceContainer(FAudioDeviceContainer&& Other);
 
#if INSTRUMENT_AUDIODEVICE_HANDLES
        TMap<uint32, FString> HandleCreationStackWalks;
#endif
 
    private:
        FAudioDeviceContainer();
    };
 
    ENGINE_API FAudioDeviceHandle BuildNewHandle(FAudioDeviceContainer&Container, Audio::FDeviceId DeviceID, const FAudioDeviceParams &InParams);
 
    static ENGINE_API bool CanUseAudioDevice(const FAudioDeviceParams& InParams, const FAudioDeviceContainer& InContainer);
 
#if INSTRUMENT_AUDIODEVICE_HANDLES
    static ENGINE_API uint32 CreateUniqueStackWalkID();
#endif
 
    TMap<Audio::FDeviceId, FAudioDeviceContainer> Devices;
    mutable FCriticalSection DeviceMapCriticalSection;
 
    /* Counter used by GetNewDeviceID() to generate a unique ID for a given audio device. */
    uint32 DeviceIDCounter;
 
    int32 NextResourceID;
 
    Audio::FDeviceId SoloDeviceHandle;
 
    Audio::FDeviceId ActiveAudioDeviceID;
 
    TMap<TTuple<ESoundType, FName>, float> DynamicSoundVolumes;
 
    bool bPlayAllDeviceAudio;
 
    FAudioCommandFence SyncFence;
 
    enum class EInitPhase : uint32
    {
        Constructed,
        PreInitialized,
        Initialized
    };
    EInitPhase InitPhase = EInitPhase::Constructed;
    
    friend class FAudioDeviceHandle;
    static ENGINE_API FAudioDeviceManager* Singleton;
};