ISoundfieldFormat.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
#pragma once
 
#include "AudioMixer.h"
#include "Containers/Array.h"
#include "CoreMinimal.h"
#include "CoreTypes.h"
#include "Features/IModularFeature.h"
#include "Features/IModularFeatures.h"
#include "Math/Quat.h"
#include "Misc/AssertionMacros.h"
#include "Templates/TypeHash.h"
#include "Templates/UniquePtr.h"
#include "UObject/NameTypes.h"
#include "UObject/Object.h"
#include "UObject/ObjectMacros.h"
#include "UObject/ObjectPtr.h"
#include "UObject/UObjectGlobals.h"
 
#include "ISoundfieldFormat.generated.h"
 
class FArchive;
class UClass;
 
 
// List of classes that that interface with Soundfield objects:
namespace Audio
{
    class FMixerDevice;
    class FMixerSourceManager;
    class FMixerSubmix;
 
    struct FChannelPositionInfo
    {
        EAudioMixerChannel::Type Channel = EAudioMixerChannel::DefaultChannel;
 
        // Horizontal angle of the position of this channel, in radians.
        // Increases as the channel moves clockwise about the listener.
        // Goes from -PI to PI.
        float Azimuth = 0.0f;
        // Vertical angle of the position of this channel, in radians.
        // Increases as the height of the channel increases proportional to the channel's distance from the listener.
        // Goes from -PI to PI.
        float Elevation = 0.0f;
 
        // distance from the listener. By default, channels are typically on the unit sphere and have a radius of 1.0f.
        // For spatialized inputs, this radius will be expressed in Unreal Units.
        float Radius = 1.0f;
    };
}
 
template<typename ToType, typename FromType>
ToType& DowncastSoundfieldRef(FromType& InRef)
{
#if PLATFORM_WINDOWS
    constexpr bool bIsToTypeChildClass = std::is_base_of<FromType, ToType>::value;
    static_assert(bIsToTypeChildClass, "Tried to cast a reference to an unrelated type.");
#endif
 
    check(&InRef != nullptr);
 
    return *static_cast<ToType*>(&InRef);
}
 
 
class ISoundfieldEncodingSettingsProxy
{
public:
    virtual ~ISoundfieldEncodingSettingsProxy() {};
 
    virtual uint32 GetUniqueId() const = 0;
 
    virtual TUniquePtr<ISoundfieldEncodingSettingsProxy> Duplicate() const = 0;
};
 
UCLASS(config = Engine, abstract, editinlinenew, BlueprintType, MinimalAPI)
class USoundfieldEncodingSettingsBase : public UObject
{
    GENERATED_BODY()
 
public:
    virtual TUniquePtr<ISoundfieldEncodingSettingsProxy> GetProxy() const PURE_VIRTUAL(USoundfieldEncodingSettingsBase::GetProxy, return nullptr;);
};
 
struct FAudioPluginInitializationParams;
 
class ISoundfieldAudioPacket
{
public:
    virtual ~ISoundfieldAudioPacket() {};
 
    virtual void Serialize(FArchive& Ar) = 0;
 
    virtual TUniquePtr<ISoundfieldAudioPacket> Duplicate() const = 0;
 
    virtual void Reset() = 0;
};
 
struct FSoundfieldSpeakerPositionalData
{
    int32 NumChannels = 0;
 
    const TArray<Audio::FChannelPositionInfo>* ChannelPositions = nullptr;
 
    // For encoding, this is the rotation of the emitter source relative to the world.
    // For decoding, this is the rotation of the listener relative to the output speaker bed.
    FQuat Rotation = FQuat::Identity;
};
 
struct FSoundfieldEncoderInputData
{
    /*
     * Input buffer of interleaved floats. Each channel of the interleaved AudioBuffer corresponds to a channel index in PositionalData.
     */
    Audio::FAlignedFloatBuffer& AudioBuffer;
 
    // Number of channels of the source audio buffer.
    int32 NumChannels;
 
    // if the input audio was already encoded to ambisonics,
    // this will point to the settings the audio was encoded with.
    // Otherwise, this will be a null pointer.
    ISoundfieldEncodingSettingsProxy& InputSettings;
 
    FSoundfieldSpeakerPositionalData& PositionalData;
};
 
class ISoundfieldEncoderStream
{
public:
    virtual ~ISoundfieldEncoderStream() {};
 
    virtual void Encode(const FSoundfieldEncoderInputData& InputData, ISoundfieldAudioPacket& OutputData) = 0;
    virtual void EncodeAndMixIn(const FSoundfieldEncoderInputData& InputData, ISoundfieldAudioPacket& OutputData) = 0;
};
 
struct FSoundfieldDecoderInputData
{
    ISoundfieldAudioPacket& SoundfieldBuffer;
 
    // The positions of the channels we will output FSoundfieldDecoderOutputData::AudioBuffer to.
    FSoundfieldSpeakerPositionalData& PositionalData;
 
    int32 NumFrames;
    float SampleRate;
};
 
struct FSoundfieldDecoderOutputData
{
    Audio::FAlignedFloatBuffer& AudioBuffer;
};
 
class ISoundfieldDecoderStream
{
public:
    virtual ~ISoundfieldDecoderStream() {};
 
    virtual void Decode(const FSoundfieldDecoderInputData& InputData, FSoundfieldDecoderOutputData& OutputData) = 0;
    virtual void DecodeAndMixIn(const FSoundfieldDecoderInputData& InputData, FSoundfieldDecoderOutputData& OutputData) = 0;
};
 
class ISoundfieldTranscodeStream
{
public:
    virtual ~ISoundfieldTranscodeStream() {};
 
    virtual void Transcode(const ISoundfieldAudioPacket& InputData, const ISoundfieldEncodingSettingsProxy& InputSettings, ISoundfieldAudioPacket& OutputData, const ISoundfieldEncodingSettingsProxy& OutputSettings) = 0;
    virtual void TranscodeAndMixIn(const ISoundfieldAudioPacket& InputData, const ISoundfieldEncodingSettingsProxy& InputSettings, ISoundfieldAudioPacket& PacketToMixTo, const ISoundfieldEncodingSettingsProxy& OutputSettings) = 0;
};
 
struct FSoundfieldMixerInputData
{
    // Packet that should be mixed into the output.
    const ISoundfieldAudioPacket& InputPacket;
    // settings used to encode both the input packet than the packet we are mixing to.
    const ISoundfieldEncodingSettingsProxy& EncodingSettings;
    // The amount, in linear gain, to
    float SendLevel;
};
 
class ISoundfieldMixerStream
{
public:
    virtual ~ISoundfieldMixerStream() {};
 
    virtual void MixTogether(const FSoundfieldMixerInputData& InputData, ISoundfieldAudioPacket& PacketToMixInto) = 0;
};
 
class ISoundfieldFactory : public IModularFeature
{
public:
    virtual ~ISoundfieldFactory()
    {
    }
 
    static AUDIOEXTENSIONS_API FName GetFormatNameForNoEncoding();
 
    static AUDIOEXTENSIONS_API FName GetFormatNameForInheritedEncoding();
 
    static AUDIOEXTENSIONS_API FName GetModularFeatureName();
 
    static AUDIOEXTENSIONS_API void RegisterSoundfieldFormat(ISoundfieldFactory* InFactory);
 
    static AUDIOEXTENSIONS_API void UnregisterSoundfieldFormat(ISoundfieldFactory* InFactory);
 
    static AUDIOEXTENSIONS_API ISoundfieldFactory* Get(const FName& InName);
 
    static AUDIOEXTENSIONS_API TArray<FName> GetAvailableSoundfieldFormats();
 
    virtual FName GetSoundfieldFormatName() = 0;
 
    virtual TUniquePtr<ISoundfieldEncoderStream> CreateEncoderStream(const FAudioPluginInitializationParams& InitInfo, const ISoundfieldEncodingSettingsProxy& InitialSettings) = 0;
    virtual TUniquePtr<ISoundfieldDecoderStream> CreateDecoderStream(const FAudioPluginInitializationParams& InitInfo, const ISoundfieldEncodingSettingsProxy& InitialSettings) = 0;
 
    // Transcoder streams are fed a soundfield audio packet with either a different format entirely, or the same format and different settings.
    // Specifying and returns a Transcoder Stream is not necessary if CanTranscodeSoundfieldFormat and ShouldReencodeBetween always returns false.
    virtual TUniquePtr<ISoundfieldTranscodeStream> CreateTranscoderStream(const FName SourceFormat, const ISoundfieldEncodingSettingsProxy& InitialSourceSettings, const FName DestinationFormat, const ISoundfieldEncodingSettingsProxy& InitialDestinationSettings, const FAudioPluginInitializationParams& InitInfo) = 0;
    virtual TUniquePtr<ISoundfieldMixerStream> CreateMixerStream(const ISoundfieldEncodingSettingsProxy& InitialSettings) = 0;
    virtual TUniquePtr<ISoundfieldAudioPacket> CreateEmptyPacket() = 0;
 
    /*
    * Override this function to determine whether an incoming ISoundfieldPacket would need to be explicitly operated on between two submixes with the same format, but potentially different encoding settings.
    * If this returns true, a new transcoder will be created.
    * if this returns false, then the source submix's ISoundfieldPacket will be passed down directly.
    */
    virtual bool IsTranscodeRequiredBetweenSettings(const ISoundfieldEncodingSettingsProxy& SourceSettings, const ISoundfieldEncodingSettingsProxy& DestinationSettings)
    {
        return true;
    }
 
    virtual bool CanTranscodeFromSoundfieldFormat(FName SourceFormat, const ISoundfieldEncodingSettingsProxy& SourceEncodingSettings) = 0;
    virtual bool CanTranscodeToSoundfieldFormat(FName DestinationFormat, const ISoundfieldEncodingSettingsProxy& DestinationEncodingSettings) = 0;
 
    virtual bool ShouldEncodeAllStreamsIndependently(const ISoundfieldEncodingSettingsProxy& EncodingSettings)
    {
        return false;
    }
 
    virtual UClass* GetCustomEncodingSettingsClass() const
    {
        return nullptr;
    }
 
    virtual const USoundfieldEncodingSettingsBase* GetDefaultEncodingSettings() = 0;
 
    virtual bool IsEndpointFormat() { return false; }
};
 
class ISoundfieldEffectSettingsProxy
{
public:
    virtual ~ISoundfieldEffectSettingsProxy() {};
};
 
UCLASS(config = Engine, abstract, editinlinenew, BlueprintType, MinimalAPI)
class USoundfieldEffectSettingsBase : public UObject
{
    GENERATED_BODY()
 
protected:
    virtual TUniquePtr<ISoundfieldEffectSettingsProxy> GetNewProxy() const PURE_VIRTUAL(USoundfieldEffectSettingsBase::GetProxy, return nullptr;);
 
private:
    // This is called by any engine system that is explicitly marked as a friend.
    TUniquePtr<ISoundfieldEffectSettingsProxy> PrivateGetProxy() const { return GetNewProxy(); }
 
    // List of classes that use USoundfieldEffectSettingsBase:
    friend Audio::FMixerSubmix;
    friend Audio::FMixerSourceManager;
};
 
class ISoundfieldEffectInstance
{
public:
    virtual ~ISoundfieldEffectInstance() {};
 
    virtual void ProcessAudio(ISoundfieldAudioPacket& InOutPacket, const ISoundfieldEncodingSettingsProxy& EncodingSettings, const ISoundfieldEffectSettingsProxy& ProcessorSettings) = 0;
};
 
UCLASS(config = Engine, abstract, editinlinenew, BlueprintType, MinimalAPI)
class USoundfieldEffectBase : public UObject
{
    GENERATED_BODY()
 
public:
 
    UPROPERTY(EditAnywhere, Category = EffectPreset)
    TObjectPtr<USoundfieldEffectSettingsBase> Settings;
 
protected:
    /*
     * Get the implementation of USoundfieldProcessorSettingsBase that is used for this processor's settings. Will always be called on the CDO.
     */
    virtual bool SupportsFormat(const FName& InFormat) const PURE_VIRTUAL(USoundfieldEncodingSettingsBase::SupportsFormat, return false;);
 
    /*
     * Get the implementation of USoundfieldProcessorSettingsBase that is used for this processor's settings. Will always be called on the CDO.
     */
    virtual const UClass* GetSettingsClass() const PURE_VIRTUAL(USoundfieldEncodingSettingsBase::GetSettingsClass, return nullptr;);
    
    virtual const USoundfieldEffectSettingsBase* GetDefaultSettings() const PURE_VIRTUAL(USoundfieldEncodingSettingsBase::GetDefaultSettings, return nullptr;);
 
    virtual TUniquePtr<ISoundfieldEffectInstance> GetNewProcessor(const ISoundfieldEncodingSettingsProxy& EncodingSettings) const PURE_VIRTUAL(USoundfieldEncodingSettingsBase::GetProxy, return nullptr;);
 
private:
 
    const USoundfieldEffectSettingsBase* PrivateGetDefaultSettings() const { return GetDefaultSettings(); };
    TUniquePtr<ISoundfieldEffectInstance> PrivateGetNewProcessor(const ISoundfieldEncodingSettingsProxy& EncodingSettings) const { return GetNewProcessor(EncodingSettings); }
 
    // List of classes that use USoundfieldEffectBase:
    friend Audio::FMixerSourceManager;
    friend Audio::FMixerSubmix;
 
};
 
struct FSoundfieldEncodingKey
{
    FName SoundfieldFormat;
    int32 EncodingSettingsID;
 
    FSoundfieldEncodingKey()
        : SoundfieldFormat(ISoundfieldFactory::GetFormatNameForNoEncoding())
        , EncodingSettingsID(0)
    {
    }
 
    FSoundfieldEncodingKey(ISoundfieldFactory* Factory, ISoundfieldEncodingSettingsProxy& InSettings)
        : SoundfieldFormat(Factory ? Factory->GetSoundfieldFormatName() : ISoundfieldFactory::GetFormatNameForNoEncoding())
        , EncodingSettingsID(InSettings.GetUniqueId())
    {
    }
 
    inline bool operator==(const FSoundfieldEncodingKey& Other) const
    {
        return (SoundfieldFormat == Other.SoundfieldFormat) && (EncodingSettingsID == Other.EncodingSettingsID);
    } 
 
    friend inline uint32 GetTypeHash(const FSoundfieldEncodingKey& Value)
    {
        return HashCombine(Value.EncodingSettingsID, Value.SoundfieldFormat.GetNumber());
    }
};