SoundModulationDestination.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
#pragma once
 
#include "Containers/ArrayView.h"
#include "Containers/Set.h"
#include "DSP/BufferVectorOperations.h"
#include "HAL/CriticalSection.h"
#include "IAudioModulation.h"
#include "UObject/NameTypes.h"
#include "UObject/Object.h"
#include "UObject/ObjectPtr.h"
 
#include "SoundModulationDestination.generated.h"
 
 
// Forward Declarations
class USoundModulatorBase;
 
namespace Audio
{
    struct FModulationParameter;
}
 
 
UENUM(BlueprintType)
enum class EModulationRouting : uint8
{
    /* Disables modulation routing */
    Disable,
 
    /* Inherits modulation routing (AudioComponent inherits from Sound, Sound inherits from SoundClass) */
    Inherit,
 
    /* Ignores inherited settings and uses modulation settings on this object */
    Override,
 
    /* Performs set union on local modulation sources with those inherited (AudioComponent inherits from Sound, Sound inherits from SoundClass) */
    Union
};
 
UENUM(BlueprintType)
enum class EModulationDestination : uint8
{
    /* Volume modulation */
    Volume,
 
    /* Pitch modulation */
    Pitch,
 
    /* Cutoff Frequency of a lowpass filter */
    Lowpass,
 
    /* Cutoff Frequency of a highpass filter */
    Highpass,
 
    Count UMETA(Hidden)
};
 
USTRUCT(BlueprintType)
struct FSoundModulationDestinationSettings
{
    GENERATED_USTRUCT_BODY()
 
    
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = Modulation)
    float Value = 1.0f;
 
#if WITH_EDITORONLY_DATA
    UPROPERTY(EditAnywhere, Category = Modulation, meta = (DisplayName = "Modulate"))
    bool bEnableModulation = false;
 
    UE_DEPRECATED(5.3, "Use the Modulators set property instead.")
    UPROPERTY(meta = (DeprecatedProperty))
    TObjectPtr<USoundModulatorBase> Modulator = nullptr;
#endif // WITH_EDITORONLY_DATA
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = Modulation)
    TSet<TObjectPtr<USoundModulatorBase>> Modulators;
 
#if WITH_EDITORONLY_DATA
    ENGINE_API void VersionModulators();
#endif // WITH_EDITORONLY_DATA
 
    // We need to explicitly disable warnings on these constructors/operators for clang to be happy with deprecated variables
    PRAGMA_DISABLE_DEPRECATION_WARNINGS
    FSoundModulationDestinationSettings() = default;
    ~FSoundModulationDestinationSettings() = default;
    FSoundModulationDestinationSettings(const FSoundModulationDestinationSettings&) = default;
    FSoundModulationDestinationSettings(FSoundModulationDestinationSettings&&) = default;
    FSoundModulationDestinationSettings& operator=(const FSoundModulationDestinationSettings&) = default;
    FSoundModulationDestinationSettings& operator=(FSoundModulationDestinationSettings&&) = default;
    PRAGMA_ENABLE_DEPRECATION_WARNINGS
 
};
 
USTRUCT(BlueprintType)
struct FSoundModulationDefaultSettings
{
    GENERATED_USTRUCT_BODY()
 
    ENGINE_API FSoundModulationDefaultSettings();
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Modulation", meta = (DisplayName = "Volume", AudioParam = "Volume", AudioParamClass = "SoundModulationParameterVolume"))
    FSoundModulationDestinationSettings VolumeModulationDestination;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Modulation", meta = (DisplayName = "Pitch", AudioParam = "Pitch", AudioParamClass = "SoundModulationParameterBipolar"))
    FSoundModulationDestinationSettings PitchModulationDestination;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Modulation", meta = (DisplayName = "Highpass", AudioParam = "HPFCutoffFrequency", AudioParamClass = "SoundModulationParameterHPFFrequency"))
    FSoundModulationDestinationSettings HighpassModulationDestination;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Modulation", meta = (DisplayName = "Lowpass", AudioParam = "LPFCutoffFrequency", AudioParamClass = "SoundModulationParameterLPFFrequency"))
    FSoundModulationDestinationSettings LowpassModulationDestination;
 
    FSoundModulationDestinationSettings GetSettingsForDestination(EModulationDestination Destination) const;
    
#if WITH_EDITORONLY_DATA
    ENGINE_API void VersionModulators();
#endif // WITH_EDITORONLY_DATA
};
 
USTRUCT(BlueprintType)
struct FSoundModulationDefaultRoutingSettings : public FSoundModulationDefaultSettings
{
    GENERATED_USTRUCT_BODY()
 
    ENGINE_API FSoundModulationDefaultRoutingSettings();
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Modulation")
    EModulationRouting VolumeRouting = EModulationRouting::Inherit;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Modulation")
    EModulationRouting PitchRouting = EModulationRouting::Inherit;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Modulation")
    EModulationRouting HighpassRouting = EModulationRouting::Inherit;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Modulation")
    EModulationRouting LowpassRouting = EModulationRouting::Inherit;
    
    EModulationRouting GetRoutingForDestination(EModulationDestination Destination) const;
};
 
namespace Audio
{
    struct FModulationDestination
    {
        public:
            FModulationDestination() = default;
 
            ENGINE_API FModulationDestination(const FModulationDestination& InModulationDestination);
            ENGINE_API FModulationDestination(FModulationDestination&& InModulationDestination);
 
            ENGINE_API FModulationDestination& operator=(const FModulationDestination& InModulationDestination);
            ENGINE_API FModulationDestination& operator=(FModulationDestination&& InModulationDestination);
 
            ENGINE_API void Init(FDeviceId InDeviceId, bool bInIsBuffered = false, bool bInValueNormalized = false);
 
            ENGINE_API void Init(FDeviceId InDeviceId, FName InParameterName, bool bInIsBuffered = false, bool bInValueNormalized = false);
 
            ENGINE_API bool IsActive() const;
 
            /* Updates internal value (or buffer if set to bIsBuffered) to current modulated result using the provided value as the base carrier value to modulate.
             * Returns true if value was updated.
             */
            ENGINE_API bool ProcessControl(float InValueUnitBase, int32 InNumSamples = 0);
 
 
            UE_DEPRECATED(5.1, "Deprecated in favor of supporting multiple modulators per destination. Use 'UpdateModulators' instead.")
            ENGINE_API void UpdateModulator(const USoundModulatorBase* InModulator);
 
            ENGINE_API void UpdateModulators(const TSet<TObjectPtr<USoundModulatorBase>>& InModulators);
            ENGINE_API void UpdateModulators(const TSet<USoundModulatorBase*>& InModulators);
            ENGINE_API void UpdateModulators(const TSet<const USoundModulatorBase*>& InModulators);
        
            ENGINE_API void ClearModulators();
 
    private:
            ENGINE_API void UpdateModulatorsInternal(TArray<TUniquePtr<Audio::IModulatorSettings>>&& ProxySettings);
 
            struct FModulationDestinationData
            {
                FDeviceId DeviceId = FDeviceId(INDEX_NONE);
 
                float ValueTarget = 1.0f;
 
                bool bIsBuffered = false;
                bool bValueNormalized = false;
                bool bHasProcessed = false;
 
                FAlignedFloatBuffer OutputBuffer;
 
                TSet<FModulatorHandle> Handles;
 
                FModulationParameter Parameter;
 
                mutable FCriticalSection HandleCritSection;
 
                FModulationDestinationData& operator=(const FModulationDestinationData& InDestInfo);
                FModulationDestinationData& operator=(FModulationDestinationData&& InDestInfo);
                const FDeviceId& GetDeviceId() const;
                const FModulationParameter& GetParameter() const;
                void SetHandles(TSet<FModulatorHandle>&& Handles);
                void ResetHandles();
            };
 
            TSharedRef<FModulationDestinationData> DestinationData{ MakeShared<FModulationDestinationData>() };
 
        public:
            inline const FAlignedFloatBuffer& GetBuffer() const
            {
                return DestinationData->OutputBuffer;
            }
 
            inline bool GetHasProcessed() const
            {
                return DestinationData->bHasProcessed;
            }
 
            inline float GetValue() const
            {
                return DestinationData->ValueTarget;
            }
    };
} // namespace Audio