SoundAttenuation.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
#pragma once
 
#include "Engine/Attenuation.h"
#include "IAudioParameterInterfaceRegistry.h"
#include "AudioLinkSettingsAbstract.h"
#include "SoundAttenuationEditorSettings.h"
#include "Sound/SoundSubmixSend.h"
 
#include "SoundAttenuation.generated.h"
 
class UOcclusionPluginSourceSettingsBase;
class UReverbPluginSourceSettingsBase;
class USourceDataOverridePluginSourceSettingsBase;
class USoundSubmixBase;
class USpatializationPluginSourceSettingsBase;
 
// This enumeration is deprecated
UENUM()
enum ESoundDistanceCalc : int
{
    SOUNDDISTANCE_Normal,
    SOUNDDISTANCE_InfiniteXYPlane,
    SOUNDDISTANCE_InfiniteXZPlane,
    SOUNDDISTANCE_InfiniteYZPlane,
    SOUNDDISTANCE_MAX,
};
 
UENUM()
enum ESoundSpatializationAlgorithm : int
{
    // Standard panning method for spatialization (linear or equal power method defined in project settings)
    SPATIALIZATION_Default UMETA(DisplayName = "Panning"),
 
    // Spatialization method provided by spatialization plugin currently selected in the project settings
    SPATIALIZATION_HRTF UMETA(DisplayName = "Plugin-Spatialized"),
};
 
UENUM(BlueprintType)
enum class EAirAbsorptionMethod : uint8
{
    // The air absorption conform to a linear distance function
    Linear,
 
    // The air absorption conforms to a custom distance curve.
    CustomCurve,
};
 
 
UENUM(BlueprintType)
enum class EReverbSendMethod : uint8
{
    // A reverb send based on linear interpolation between a distance range and send-level range
    Linear,
 
    // A reverb send based on a supplied curve
    CustomCurve,
 
    // A manual reverb send level (Uses the specified constant send level value. Useful for 2D sounds.)
    Manual,
};
 
UENUM(BlueprintType)
enum class EPriorityAttenuationMethod : uint8
{
    // A priority attenuation based on linear interpolation between a distance range and priority attenuation range
    Linear,
 
    // A priority attenuation based on a supplied curve
    CustomCurve,
 
    // A manual priority attenuation (Uses the specified constant value. Useful for 2D sounds.)
    Manual,
};
 
 
USTRUCT(BlueprintType)
struct FSoundAttenuationPluginSettings
{
    GENERATED_USTRUCT_BODY()
 
    
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationSpatialization, meta = (DisplayName = "Spatialization Plugin Settings"))
    TArray<TObjectPtr<USpatializationPluginSourceSettingsBase>> SpatializationPluginSettingsArray;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationOcclusion, meta = (DisplayName = "Occlusion Plugin Settings"))
    TArray<TObjectPtr<UOcclusionPluginSourceSettingsBase>> OcclusionPluginSettingsArray;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationReverbSend, meta = (DisplayName = "Reverb Plugin Settings"))
    TArray<TObjectPtr<UReverbPluginSourceSettingsBase>> ReverbPluginSettingsArray;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationSourceDataOverride, meta = (DisplayName = "Source Data Override Plugin Settings"))
    TArray<TObjectPtr<USourceDataOverridePluginSourceSettingsBase>> SourceDataOverridePluginSettingsArray;
 
    void AddStructReferencedObjects(FReferenceCollector& Collector);    
};
 
template<>
struct TStructOpsTypeTraits<FSoundAttenuationPluginSettings> : public TStructOpsTypeTraitsBase2<FSoundAttenuationPluginSettings>
{
    enum
    {
        WithAddStructReferencedObjects = true
    };
};
 
 
// Defines how to speaker map the sound when using the non-spatialized radius feature
UENUM(BlueprintType)
enum class ENonSpatializedRadiusSpeakerMapMode : uint8
{
    // Will blend the 3D sound to an omni-directional sound (equal output mapping in all directions)
    OmniDirectional,
 
    // Will blend the 3D source to the same representation speaker map used when playing the asset 2D
    Direct2D,
 
    // Will blend the 3D source to a multichannel 2D version (i.e. upmix stereo to quad) if rendering in surround
    Surround2D,
};
 
USTRUCT(BlueprintType)
struct FAttenuationSubmixSendSettings : public FSoundSubmixSendInfoBase
{
    GENERATED_BODY();
    
    FAttenuationSubmixSendSettings();
};
 
/*
The settings for attenuating.
*/
USTRUCT(BlueprintType)
struct FSoundAttenuationSettings : public FBaseAttenuationSettings
{
    GENERATED_USTRUCT_BODY()
 
    /* Allows distance-based volume attenuation. */
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationDistance, meta = (DisplayName = "Enable Volume Attenuation"))
    uint8 bAttenuate : 1;
 
    /* Allows the source to be 3D spatialized. */
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationSpatialization, meta = (DisplayName = "Enable Spatialization"))
    uint8 bSpatialize : 1;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationAirAbsorption, meta = (DisplayName = "Enable Air Absorption"))
    uint8 bAttenuateWithLPF : 1;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationListenerFocus)
    uint8 bEnableListenerFocus : 1;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationListenerFocus)
    uint8 bEnableFocusInterpolation : 1;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationOcclusion)
    uint8 bEnableOcclusion : 1;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationOcclusion)
    uint8 bUseComplexCollisionForOcclusion : 1;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationReverbSend, meta = (DisplayName = "Enable Reverb Send"))
    uint8 bEnableReverbSend : 1;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationPriority, meta = (DisplayName = "Enable Priority Attenuation"))
    uint8 bEnablePriorityAttenuation : 1;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationSpatialization, meta = (DisplayName = "Normalize 3D Stereo Sounds"))
    uint8 bApplyNormalizationToStereoSounds : 1;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationAirAbsorption, meta = (DisplayName = "Enable Log Frequency Scaling"))
    uint8 bEnableLogFrequencyScaling : 1;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationSubmixSend, meta = (DisplayName = "Enable Submix Send"))
    uint8 bEnableSubmixSends : 1;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationSourceDataOverride, meta = (DisplayName = "Enable Source Data Override"))
    uint8 bEnableSourceDataOverride : 1;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationAudioLink, meta = (DisplayName = "Enable Send to AudioLink"))
    uint8 bEnableSendToAudioLink : 1;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationSpatialization, meta = (ClampMin = "0", EditCondition = "bSpatialize", DisplayName = "Spatialization Method"))
    TEnumAsByte<enum ESoundSpatializationAlgorithm> SpatializationAlgorithm;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationAudioLink, meta = (DisplayName = "AudioLink Settings Override", EditCondition = "bEnableSendToAudioLink"))
    TObjectPtr<UAudioLinkSettingsAbstract> AudioLinkSettingsOverride;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationSpatialization, meta = (ClampMin = "0", EditCondition = "bSpatialize"))
    float BinauralRadius;
 
    /* The normalized custom curve to use for the air absorption lowpass frequency values. Does a mapping from defined distance values (x-axis) and defined frequency values (y-axis) */
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationAirAbsorption)
    FRuntimeFloatCurve CustomLowpassAirAbsorptionCurve;
 
    /* The normalized custom curve to use for the air absorption highpass frequency values. Does a mapping from defined distance values (x-axis) and defined frequency values (y-axis) */
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationAirAbsorption)
    FRuntimeFloatCurve CustomHighpassAirAbsorptionCurve;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationAirAbsorption)
    EAirAbsorptionMethod AbsorptionMethod;
 
    /* Which trace channel to use for audio occlusion checks. */
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationOcclusion)
    TEnumAsByte<enum ECollisionChannel> OcclusionTraceChannel;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationReverbSend)
    EReverbSendMethod ReverbSendMethod;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationPriority)
    EPriorityAttenuationMethod PriorityAttenuationMethod;
 
#if WITH_EDITORONLY_DATA
    UPROPERTY()
    TEnumAsByte<enum ESoundDistanceCalc> DistanceType_DEPRECATED;
 
    UPROPERTY()
    float OmniRadius_DEPRECATED;
#endif
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationSpatialization, meta = (ClampMin = "0", EditCondition = "bSpatialize"))
    float NonSpatializedRadiusStart;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationSpatialization, meta = (ClampMin = "0", EditCondition = "bSpatialize"))
    float NonSpatializedRadiusEnd;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationSpatialization, meta = (ClampMin = "0", EditCondition = "bSpatialize"))
    ENonSpatializedRadiusSpeakerMapMode NonSpatializedRadiusMode;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationSpatialization, meta = (ClampMin = "0", EditCondition = "bSpatialize", DisplayName = "3D Stereo Spread"))
    float StereoSpread;
 
#if WITH_EDITORONLY_DATA
    UPROPERTY()
    TObjectPtr<USpatializationPluginSourceSettingsBase> SpatializationPluginSettings_DEPRECATED;
 
    UPROPERTY()
    float RadiusMin_DEPRECATED;
 
    UPROPERTY()
    float RadiusMax_DEPRECATED;
#endif
 
    /* The distance min range at which to apply an absorption LPF filter. */
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationAirAbsorption, meta = (DisplayName = "Min Distance Range"))
    float LPFRadiusMin;
 
    /* The max distance range at which to apply an absorption LPF filter. Absorption freq cutoff interpolates between filter frequency ranges between these distance values. */
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationAirAbsorption, meta = (DisplayName = "Max Distance Range"))
    float LPFRadiusMax;
 
    /* The range of the cutoff frequency (in Hz) of the lowpass absorption filter. */
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationAirAbsorption, meta = (DisplayName = "Low Pass Cutoff Frequency Min"))
    float LPFFrequencyAtMin;
 
    /* The range of the cutoff frequency (in Hz) of the lowpass absorption filter. */
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationAirAbsorption, meta = (DisplayName = "Low Pass Cutoff Frequency Max"))
    float LPFFrequencyAtMax;
 
    /* The range of the cutoff frequency (in Hz) of the highpass absorption filter. */
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationAirAbsorption, meta = (DisplayName = "High Pass Cutoff Frequency Min"))
    float HPFFrequencyAtMin;
 
    /* The range of the cutoff frequency (in Hz) of the highpass absorption filter. */
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationAirAbsorption, meta = (DisplayName = "High Pass Cutoff Frequency Max"))
    float HPFFrequencyAtMax;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationListenerFocus)
    float FocusAzimuth;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationListenerFocus)
    float NonFocusAzimuth;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationListenerFocus, meta = (ClampMin = "0.0", UIMin = "0.0", EditCondition = "bEnableListenerFocus"))
    float FocusDistanceScale;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationListenerFocus, meta = (ClampMin = "0.0", UIMin = "0.0", EditCondition = "bEnableListenerFocus"))
    float NonFocusDistanceScale;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationListenerFocus, meta = (ClampMin = "0.0", UIMin = "0.0", UIMax = "1.0", EditCondition = "bEnableListenerFocus"))
    float FocusPriorityScale;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationListenerFocus, meta = (ClampMin = "0.0", UIMin = "0.0", UIMax = "1.0", EditCondition = "bEnableListenerFocus"))
    float NonFocusPriorityScale;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationListenerFocus, meta = (ClampMin = "0.0", UIMin = "0.0", EditCondition = "bEnableListenerFocus"))
    float FocusVolumeAttenuation;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationListenerFocus, meta = (ClampMin = "0.0", UIMin = "0.0", EditCondition = "bEnableListenerFocus"))
    float NonFocusVolumeAttenuation;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationListenerFocus, meta = (ClampMin = "0.0", UIMin = "0.0", EditCondition = "bEnableFocusInterpolation"))
    float FocusAttackInterpSpeed;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationListenerFocus, meta = (ClampMin = "0.0", UIMin = "0.0", EditCondition = "bEnableFocusInterpolation"))
    float FocusReleaseInterpSpeed;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationOcclusion, meta = (ClampMin = "0.0", UIMin = "0.0", EditCondition = "bEnableOcclusion"))
    float OcclusionLowPassFilterFrequency;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationOcclusion, meta = (ClampMin = "0.0", UIMin = "0.0", EditCondition = "bEnableOcclusion"))
    float OcclusionVolumeAttenuation;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationOcclusion, meta = (ClampMin = "0", UIMin = "0.0", EditCondition = "bEnableOcclusion"))
    float OcclusionInterpolationTime;
 
#if WITH_EDITORONLY_DATA
    UPROPERTY()
    TObjectPtr<UOcclusionPluginSourceSettingsBase> OcclusionPluginSettings_DEPRECATED;
 
    UPROPERTY()
    TObjectPtr<UReverbPluginSourceSettingsBase> ReverbPluginSettings_DEPRECATED;
#endif
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationReverbSend, meta = (DisplayName = "Reverb Min Send Level"))
    float ReverbWetLevelMin;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationReverbSend, meta = (DisplayName = "Reverb Max Send Level"))
    float ReverbWetLevelMax;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationReverbSend, meta = (DisplayName = "Reverb Min Send Distance"))
    float ReverbDistanceMin;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationReverbSend, meta = (DisplayName = "Reverb Max Send Distance"))
    float ReverbDistanceMax;
 
    /* The manual master reverb send level to use. Doesn't change as a function of distance. */
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationReverbSend)
    float ManualReverbSendLevel;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationPriority, meta = (ClampMin = "0.0", UIMin = "0.0", UIMax = "1.0", DisplayName = "Priority Attenuation At Min Distance"))
    float PriorityAttenuationMin;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationPriority, meta = (ClampMin = "0.0", UIMin = "0.0", UIMax = "1.0", DisplayName = "Priority Attenuation At Max Distance"))
    float PriorityAttenuationMax;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationPriority, meta = (ClampMin = "0.0", DisplayName = "Priority Attenuation Min Distance"))
    float PriorityAttenuationDistanceMin;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationPriority, meta = (ClampMin = "0.0", DisplayName = "Priority Attenuation Max Distance"))
    float PriorityAttenuationDistanceMax;
 
    /* Static priority scalar to use (doesn't change as a function of distance). */
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationPriority, meta = (ClampMin = "0.0", UIMin = "0.0", UIMax = "1.0", DisplayName = "Attenuation Priority"))
    float ManualPriorityAttenuation;
 
    /* The custom reverb send curve to use for distance-based send level. Values clamped between 0.0 and 1.0. */
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationReverbSend)
    FRuntimeFloatCurve CustomReverbSendCurve;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationSubmixSend)
    TArray<FAttenuationSubmixSendSettings> SubmixSendSettings;
 
    /* The custom curve to use for distance-based priority attenuation. */
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationPriority)
    FRuntimeFloatCurve CustomPriorityAttenuationCurve;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = AttenuationPluginSettings, meta = (ShowOnlyInnerProperties))
    FSoundAttenuationPluginSettings PluginSettings;
 
    ENGINE_API FSoundAttenuationSettings();
    ENGINE_API ~FSoundAttenuationSettings();
    ENGINE_API FSoundAttenuationSettings(const FSoundAttenuationSettings&);
 
    ENGINE_API bool operator==(const FSoundAttenuationSettings& Other) const;
#if WITH_EDITORONLY_DATA
    ENGINE_API void PostSerialize(const FArchive& Ar);
#endif
 
    ENGINE_API virtual void CollectAttenuationShapesForVisualization(TMultiMap<EAttenuationShape::Type, FBaseAttenuationSettings::AttenuationShapeDetails>& ShapeDetailsMap) const override;
    ENGINE_API float GetFocusPriorityScale(const struct FGlobalFocusSettings& FocusSettings, float FocusFactor) const;
    ENGINE_API float GetFocusAttenuation(const struct FGlobalFocusSettings& FocusSettings, float FocusFactor) const;
    ENGINE_API float GetFocusDistanceScale(const struct FGlobalFocusSettings& FocusSettings, float FocusFactor) const;
 
    ENGINE_API void AddStructReferencedObjects(FReferenceCollector& Collector);
};
 
template<>
struct TStructOpsTypeTraits<FSoundAttenuationSettings> : public TStructOpsTypeTraitsBase2<FSoundAttenuationSettings>
{
    enum 
    {
#if WITH_EDITORONLY_DATA
        WithPostSerialize = true,
#endif
        WithAddStructReferencedObjects = true
    };
};
 
 
UCLASS(BlueprintType, hidecategories=Object, editinlinenew, MinimalAPI)
class USoundAttenuation : public UObject
{
    GENERATED_UCLASS_BODY()
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category=Settings, meta = (CustomizeProperty))
    FSoundAttenuationSettings Attenuation;
};
 
namespace Audio
{
    namespace AttenuationInterface
    {
        ENGINE_API const extern FName Name;
 
        namespace Inputs
        {
            ENGINE_API const extern FName Distance;
        } // namespace Inputs
 
        ENGINE_API Audio::FParameterInterfacePtr GetInterface();
    } // namespace AttenuationInterface
 
    namespace SpatializationInterface
    {
        ENGINE_API const extern FName Name;
 
        namespace Inputs
        {
            ENGINE_API const extern FName Azimuth;
            ENGINE_API const extern FName Elevation;
        } // namespace Inputs
 
        ENGINE_API Audio::FParameterInterfacePtr GetInterface();
    } // namespace SpatializationInterface
 
    namespace SourceOrientationInterface
    {
        ENGINE_API const extern FName Name;
 
        namespace Inputs
        {
            ENGINE_API const extern FName Azimuth;
            ENGINE_API const extern FName Elevation;
        } // namespace Inputs
 
        ENGINE_API Audio::FParameterInterfacePtr GetInterface();
    } // namespace EmitterInterface
 
    namespace ListenerOrientationInterface
    {
        ENGINE_API const extern FName Name;
 
        namespace Inputs
        {
            ENGINE_API const extern FName Azimuth;
            ENGINE_API const extern FName Elevation;
        } // namespace Inputs
 
        ENGINE_API Audio::FParameterInterfacePtr GetInterface();
    } // namespace EmitterInterface
} // namespace Audio