SoundConcurrency.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
#pragma once
 
#include "UObject/ObjectMacros.h"
#include "UObject/Object.h"
#include "UObject/PerPlatformProperties.h"
 
#include "SoundConcurrency.generated.h"
 
class FAudioDevice;
class FSoundConcurrencyManager;
 
struct FActiveSound;
 
using FConcurrencyGroupID = uint32;
 
using FConcurrencyObjectID = uint32;
 
using FSoundOwnerObjectID = uint32;
 
using FSoundObjectID = uint32;
 
ENGINE_API DECLARE_LOG_CATEGORY_EXTERN(LogAudioConcurrency, Log, All);
 
UENUM()
namespace EMaxConcurrentResolutionRule
{
    enum Type : int
    {
        PreventNew,
 
        StopOldest,
 
        StopFarthestThenPreventNew,
 
        StopFarthestThenOldest,
 
        StopLowestPriority,
 
        StopQuietest,
 
        StopLowestPriorityThenPreventNew,
 
        Count UMETA(Hidden)
    };
}
 
UENUM()
enum class EConcurrencyVolumeScaleMode
{
    /* Scales volume of older sounds more than newer sounds (default) */
    Default = 0,
 
    /* Scales distant sounds by volume scalar more than closer sounds */
    Distance,
 
    /* Scales lower priority sounds by volume scalar more than closer sounds */
    Priority
};
 
USTRUCT(BlueprintType)
struct FSoundConcurrencySettings
{
    GENERATED_BODY()
 
    
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = Concurrency, meta = (
        DisplayName = "Max Count (Dynamic)",
        DisplayAfter = "bEnableMaxCountPlatformScaling",
        EditCondition = "!bEnableMaxCountPlatformScaling",
        EditConditionHides,
        UIMin = "1", ClampMin = "1"))
    int32 MaxCount;
 
    /* Whether or not to limit the concurrency to per sound owner (i.e. the actor that plays the sound). If the sound doesn't have an owner, it falls back to global concurrency. */
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = Concurrency)
    uint8 bLimitToOwner : 1 = 0;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Volume Scaling", meta = (DisplayName = "Can Recover", DisplayAfter = "VolumeScaleMode", EditCondition = "VolumeScaleMode == EConcurrencyVolumeScaleMode::Default", EditConditionHides))
    uint8 bVolumeScaleCanRelease : 1 = 0;
 
private:
    /* If true, MaxCount supports platform scaling, but cannot be dynamically changed at runtime (ex. from Blueprint or Gameplay Code).  If false, MaxCount is dynamically assignable at runtime, but is not platform scalable. */
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = Concurrency, meta = (AllowPrivateAccess))
    uint8 bEnableMaxCountPlatformScaling : 1 = 0;
 
public:
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = Concurrency)
    TEnumAsByte<EMaxConcurrentResolutionRule::Type> ResolutionRule = EMaxConcurrentResolutionRule::StopFarthestThenOldest;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = Concurrency, meta = (UIMin = "0.0", ClampMin = "0.0"))
    float RetriggerTime = 0.0f;
 
private:
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = Concurrency, meta = (
        DisplayName = "Max Count (Platform Scaled)",
        DisplayAfter = "bEnableMaxCountPlatformScaling",
        EditCondition = "bEnableMaxCountPlatformScaling",
        EditConditionHides,
        AllowPrivateAccess,
        UIMin = "1", ClampMin = "1"))
    FPerPlatformInt PlatformMaxCount;
 
    UPROPERTY(EditAnywhere, Category = "Volume Scaling", meta = (UIMin = "0.0", UIMax = "1.0", ClampMin = "0.0", ClampMax = "1.0"))
    float VolumeScale = 1.0f;
 
public:
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Volume Scaling")
    EConcurrencyVolumeScaleMode VolumeScaleMode = EConcurrencyVolumeScaleMode::Default;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Volume Scaling", meta = (DisplayName = "Duck Time", UIMin = "0.0", ClampMin = "0.0", UIMax = "10.0", ClampMax = "1000000.0"))
    float VolumeScaleAttackTime = 0.01f;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Volume Scaling", meta = (
        DisplayName = "Recover Time",
        DisplayAfter = "bVolumeScaleCanRelease",
        EditCondition = "bVolumeScaleCanRelease && VolumeScaleMode == EConcurrencyVolumeScaleMode::Default",
        EditConditionHides,
        UIMin = "0.0",
        ClampMin = "0.0",
        UIMax = "10.0",
        ClampMax = "1000000.0"))
    float VolumeScaleReleaseTime = 0.5f;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Voice Stealing", meta = (UIMin = "0.0", ClampMin = "0.0", UIMax = "1.0", ClampMax="1000000.0"))
    float VoiceStealReleaseTime = 0.0f;
 
    FSoundConcurrencySettings();
 
    ENGINE_API int32 GetMaxCount() const;
 
    ENGINE_API bool SetMaxCount(int32 InMaxCount);
 
#if WITH_EDITOR
    ENGINE_API void SetEnableMaxCountPlatformScaling(bool bEnabled);
 
    ENGINE_API bool IsMaxCountPlatformScalingEnabled() const;
 
    ENGINE_API bool SetPlatformMaxCount(FPerPlatformInt InMaxCount);
#endif // WITH_EDITOR
 
    ENGINE_API float GetVolumeScale() const;
 
    ENGINE_API bool IsEvictionSupported() const;
};
 
 
UCLASS(BlueprintType, hidecategories=Object, editinlinenew, MinimalAPI)
class USoundConcurrency : public UObject
{
    GENERATED_UCLASS_BODY()
 
public:
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = Settings, meta = (ShowOnlyInnerProperties))
    FSoundConcurrencySettings Concurrency;
 
    UFUNCTION(BlueprintCallable, Category = Concurrency)
    UPARAM(DisplayName = "Success") bool SetMaxCount(UPARAM(DisplayName = "MaxCount") int32 InMaxCount);
};
 
enum class EConcurrencyMode : uint8
{
    Group,
    Owner,
    OwnerPerSound,
    Sound,
};
 
struct FConcurrencyHandle
{
    const FSoundConcurrencySettings& Settings;
    const FConcurrencyObjectID ObjectID;
    const bool bIsOverride;
 
    FConcurrencyHandle(const FSoundConcurrencySettings& InSettings);
 
    FConcurrencyHandle(const USoundConcurrency& Concurrency);
 
    EConcurrencyMode GetMode(const FActiveSound& ActiveSound) const;
};
 
 
struct FConcurrencySoundData
{
    int32 Generation;
    float LerpTime;
 
private:
    float Elapsed;
    float DbTargetVolume;
    float DbStartVolume;
 
public:
    FConcurrencySoundData()
        : Generation(0)
        , LerpTime(0.0f)
        , Elapsed(0.0f)
        , DbTargetVolume(0.0f)
        , DbStartVolume(0.0f)
    {
    }
 
    void Update(float InElapsed);
 
    float GetLerpTime() const;
    float GetVolume(bool bInDecibels = false) const;
    float GetTargetVolume(bool bInDecibels = false) const;
 
    void SetTarget(float InTargetVolume, float InLerpTime);
};
 
 
class FConcurrencyGroup
{
    TArray<FActiveSound*> ActiveSounds;
 
    FConcurrencyGroupID GroupID;
    FConcurrencyObjectID ObjectID;
    FSoundConcurrencySettings Settings;
 
    float LastTimePlayed = 0.0f;
 
public:
    FConcurrencyGroup(FConcurrencyGroupID GroupID, const FConcurrencyHandle& ConcurrencyHandle);
 
    static FConcurrencyGroupID GenerateNewID();
 
    const TArray<FActiveSound*>& GetActiveSounds() const;
 
    FConcurrencyGroupID GetGroupID() const;
 
    const int32 GetNextGeneration() const;
 
    const FSoundConcurrencySettings& GetSettings() const;
 
    FConcurrencyObjectID GetObjectID() const;
 
    bool IsEmpty() const;
 
    bool IsFull() const;
 
    void AddActiveSound(FActiveSound& ActiveSound);
 
    void RemoveActiveSound(FActiveSound& ActiveSound);
 
    void UpdateGeneration(FActiveSound* NewActiveSound = nullptr);
 
    void CullSoundsDueToMaxConcurrency();
 
    void SetLastTimePlayed(float InLastTimePlayed) { LastTimePlayed = InLastTimePlayed; }
 
    bool CanPlaySoundNow(float InCurrentTime) const;
 
};
 
typedef TMap<FConcurrencyGroupID, FConcurrencyGroup*> FConcurrencyGroups;
 
struct FSoundInstanceEntry
{
    TMap<FSoundObjectID, FConcurrencyGroupID> SoundInstanceToConcurrencyGroup;
 
    FSoundInstanceEntry(FSoundObjectID SoundObjectID, FConcurrencyGroupID GroupID)
    {
        SoundInstanceToConcurrencyGroup.Add(SoundObjectID, GroupID);
    }
};
 
typedef TMap<FConcurrencyObjectID, FConcurrencyGroupID> FConcurrencyMap;
 
struct FOwnerConcurrencyMapEntry
{
    FConcurrencyMap ConcurrencyObjectToConcurrencyGroup;
 
    FOwnerConcurrencyMapEntry(FConcurrencyObjectID ConcurrencyObjectID, FConcurrencyGroupID GroupID)
    {
        ConcurrencyObjectToConcurrencyGroup.Add(ConcurrencyObjectID, GroupID);
    }
};
 
typedef TMap<FSoundOwnerObjectID, FOwnerConcurrencyMapEntry> FOwnerConcurrencyMap;
 
typedef TMap<FSoundOwnerObjectID, FSoundInstanceEntry> FOwnerPerSoundConcurrencyMap;
 
typedef TMap<FSoundObjectID, FConcurrencyGroupID> FPerSoundToActiveSoundsMap;
 
 
class FSoundConcurrencyManager
{
public:
    FSoundConcurrencyManager(FAudioDevice* InAudioDevice);
    ENGINE_API ~FSoundConcurrencyManager();
 
    FActiveSound* CreateNewActiveSound(const FActiveSound& NewActiveSound, bool bIsRetriggering);
 
    void RemoveActiveSound(FActiveSound& ActiveSound);
 
    void StopDueToVoiceStealing(FActiveSound& ActiveSound);
 
    void UpdateVolumeScaleGenerations();
 
    void UpdateSoundsToCull();
 
private: // Methods
 
    FConcurrencyGroup* CanPlaySound(const FActiveSound& NewActiveSound, const FConcurrencyGroupID GroupID, TArray<FActiveSound*>& OutSoundsToEvict, bool bIsRetriggering);
 
    FConcurrencyGroup& CreateNewConcurrencyGroup(const FConcurrencyHandle& ConcurrencyHandle);
 
    void CreateNewGroupsFromHandles(
        const FActiveSound& NewActiveSound,
        const TArray<FConcurrencyHandle>& ConcurrencyHandles,
        TArray<FConcurrencyGroup*>& OutGroupsToApply
    );
 
    FActiveSound* CreateAndEvictActiveSounds(const FActiveSound& NewActiveSound, const TArray<FConcurrencyGroup*>& GroupsToApply, const TArray<FActiveSound*>& SoundsToEvict);
 
    FActiveSound* GetEvictableSound(const FActiveSound& NewActiveSound, const FConcurrencyGroup& ConcurrencyGroup, bool bIsRetriggering);
 
    FActiveSound* GetEvictableSoundStopFarthest(const FActiveSound& NewActiveSound, const FConcurrencyGroup& ConcurrencyGroup, bool bIsRetriggering) const;
    FActiveSound* GetEvictableSoundStopOldest(const FActiveSound& NewActiveSound, const FConcurrencyGroup& ConcurrencyGroup, bool bIsRetriggering) const;
 
    FActiveSound* EvaluateConcurrency(const FActiveSound& NewActiveSound, TArray<FConcurrencyHandle>& ConcurrencyHandles, bool bIsRetriggering);
 
private: // Data
    FAudioDevice* AudioDevice;
 
    FConcurrencyMap ConcurrencyMap;
 
    FOwnerConcurrencyMap OwnerConcurrencyMap;
 
    FOwnerPerSoundConcurrencyMap OwnerPerSoundConcurrencyMap;
 
    FPerSoundToActiveSoundsMap SoundObjectToConcurrencyGroup;
 
    FConcurrencyGroups ConcurrencyGroups;
};