AudioDecompress.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
/*=============================================================================
    AudioDecompress.h: Unreal audio vorbis decompression interface object.
=============================================================================*/
 
#pragma once
 
#include "CoreMinimal.h"
#include "Stats/Stats.h"
#include "Async/AsyncWork.h"
#include "Sound/SoundWave.h"
#include "Misc/ScopeLock.h"
#include "HAL/LowLevelMemTracker.h"
#include "ContentStreaming.h"
 
// 100ms of 48KHz data
// 108ms of 44.1KHz data
// 218ms of 22KHz data
constexpr int32 MONO_PCM_BUFFER_SAMPLES = 4800;
constexpr uint32 MONO_PCM_SAMPLE_SIZE = sizeof(int16);
constexpr uint32 MONO_PCM_BUFFER_SIZE = MONO_PCM_BUFFER_SAMPLES * MONO_PCM_SAMPLE_SIZE;
 
struct FSoundQualityInfo;
class FStreamedAudioChunkSeekTable;
 
class ICompressedAudioInfo
{
public:
    ENGINE_API ICompressedAudioInfo();
 
    ENGINE_API virtual ~ICompressedAudioInfo();
 
    virtual bool ReadCompressedInfo(const uint8* InSrcBufferData, uint32 InSrcBufferDataSize, struct FSoundQualityInfo* QualityInfo) = 0;
 
    virtual bool ReadCompressedData(uint8* Destination, bool bLooping, uint32 BufferSize) = 0;
 
    virtual void SeekToTime(const float SeekTime) = 0;
 
    virtual void SeekToFrame(const uint32 Frame) = 0;
 
    virtual void ExpandFile(uint8* DstBuffer, struct FSoundQualityInfo* QualityInfo) = 0;
 
    virtual void EnableHalfRate(bool HalfRate) = 0;
 
    virtual uint32 GetSourceBufferSize() const = 0;
 
    virtual bool UsesVorbisChannelOrdering() const = 0;
 
    virtual int GetStreamBufferSize() const = 0;
 
    virtual bool IsStreamedCompressedInfo() const { return false; }
 
    // Following functions are optional if streaming is supported //
 
    virtual bool SupportsStreaming() const {return false;}
 
    virtual bool ReleaseStreamChunk(bool bBlockUntilReleased)
    {
        // If we hit this check, ReleaseStreamChunk needs to be implemented for this codec.
        checkNoEntry();
        return false;
    }
 
    ENGINE_API bool StreamCompressedInfo(USoundWave* Wave, struct FSoundQualityInfo* QualityInfo);
    ENGINE_API bool StreamCompressedInfo(const FSoundWaveProxyPtr& Wave, struct FSoundQualityInfo* QualityInfo);
 
    ENGINE_API virtual bool HasError() const;
 
protected:
    virtual bool StreamCompressedInfoInternal(const FSoundWaveProxyPtr& InWaveProxy, struct FSoundQualityInfo* QualityInfo) = 0;
 
public:
 
    virtual bool StreamCompressedData(uint8* Destination, bool bLooping, uint32 BufferSize, int32& OutNumBytesStreamed) { OutNumBytesStreamed = -1; return false; }
 
    virtual int32 GetCurrentChunkIndex() const {return -1;}
 
    virtual int32 GetCurrentChunkOffset() const {return -1;}
 
    virtual const FSoundWaveProxyPtr& GetStreamingSoundWave() const { return StreamingSoundWave; }
 
protected:
    mutable bool bHasError = false;
 
#if !UE_BUILD_SHIPPING
    bool bWantsFilteredLogging = false;
#endif //UE_BUILD_SHIPPING
    bool WantsFilteredLogging() const 
    {
#if UE_BUILD_SHIPPING
        return false;
#else
        return bWantsFilteredLogging;
#endif //UE_BUILD_SHIPPING      
    }
    
    FSoundWaveProxyPtr StreamingSoundWave;
};
 
struct FDecodeResult
{
    // Number of bytes of compressed data consumed
    int32 NumCompressedBytesConsumed;
    // Number of bytes produced
    int32 NumPcmBytesProduced;
    // Number of frames produced.
    int32 NumAudioFramesProduced;
 
    FDecodeResult()
        : NumCompressedBytesConsumed(INDEX_NONE)
        , NumPcmBytesProduced(INDEX_NONE)
        , NumAudioFramesProduced(INDEX_NONE)
    {}
};
 
class IStreamedCompressedInfo : public ICompressedAudioInfo
{
public:
    ENGINE_API IStreamedCompressedInfo();
    ENGINE_API virtual ~IStreamedCompressedInfo();
 
    //~ Begin ICompressedInfo Interface
    ENGINE_API virtual bool ReadCompressedInfo(const uint8* InSrcBufferData, uint32 InSrcBufferDataSize, FSoundQualityInfo* QualityInfo) override;
    ENGINE_API virtual bool ReadCompressedData(uint8* Destination, bool bLooping, uint32 BufferSize) override;
    ENGINE_API virtual void SeekToTime(const float SeekTime) override;
    ENGINE_API virtual void SeekToFrame(const uint32 SeekFrame) override;
    ENGINE_API virtual void ExpandFile(uint8* DstBuffer, struct FSoundQualityInfo* QualityInfo) override;
    virtual void EnableHalfRate(bool HalfRate) override {};
    virtual uint32 GetSourceBufferSize() const override { return SrcBufferDataSize; }
    virtual bool UsesVorbisChannelOrdering() const override { return false; }
    virtual int GetStreamBufferSize() const override { return  MONO_PCM_BUFFER_SIZE; }
    virtual bool SupportsStreaming() const override { return true; }
    ENGINE_API virtual bool StreamCompressedInfoInternal(const FSoundWaveProxyPtr& InWaveProxy, FSoundQualityInfo* QualityInfo) override;
    ENGINE_API virtual bool StreamCompressedData(uint8* Destination, bool bLooping, uint32 BufferSize, int32& OutNumBytesStreamed) override;
    virtual int32 GetCurrentChunkIndex() const override { return CurrentChunkIndex; }
    virtual int32 GetCurrentChunkOffset() const override { return SrcBufferOffset; }
    virtual bool IsStreamedCompressedInfo() const override { return true; }
    //~ End ICompressedInfo Interface
 
    virtual bool ParseHeader(const uint8* InSrcBufferData, uint32 InSrcBufferDataSize, FSoundQualityInfo* QualityInfo) = 0;
 
    virtual bool CreateDecoder() = 0;
 
    virtual FDecodeResult Decode(const uint8* CompressedData, const int32 CompressedDataSize, uint8* OutPCMData, const int32 OutputPCMDataSize) = 0;
 
    virtual void PrepareToLoop() {}
 
    virtual int32 GetFrameSize() = 0;
 
    virtual uint32 GetMaxFrameSizeSamples() const = 0;
 
    int32 GetStreamSeekBlockIndex() const { return StreamSeekBlockIndex; }
    int32 GetStreamSeekBlockOffset() const { return StreamSeekBlockOffset; }
protected:
 
    ENGINE_API uint32   Read(void *Outbuffer, uint32 DataSize);
 
    int32 DecompressToPCMBuffer(uint16 FrameSize);
 
    uint32 IncrementCurrentSampleCount(uint32 NewSamples);
 
    uint32  WriteFromDecodedPCM(uint8* Destination, uint32 BufferSize);
 
    uint32  ZeroBuffer(uint8* Destination, uint32 BufferSize);
 
    ENGINE_API const uint8* GetLoadedChunk(const FSoundWaveProxyPtr& InSoundWave, uint32 ChunkIndex, uint32& OutChunkSize);
 
    void RetainNextChunkInSequence(const FSoundWaveProxyPtr& InSoundWave,const uint32 InChunkIndex);
 
    const FStreamedAudioChunkSeekTable& GetCurrentSeekTable() const;
    FStreamedAudioChunkSeekTable& GetCurrentSeekTable();
 
    bool bIsStreaming;
    const uint8* SrcBufferData;
    uint32 SrcBufferDataSize;
    uint32 SrcBufferOffset;
    uint32 AudioDataOffset;
    uint32 AudioDataChunkIndex;
    uint32 TrueSampleCount;
    uint32 CurrentSampleCount;
    uint8 NumChannels;
    uint32 MaxFrameSizeSamples;
    uint32 SampleStride;
    TArray<uint8> LastDecodedPCM;
    uint32 LastPCMByteSize;
    uint32 LastPCMOffset;
    bool bStoringEndOfFile;
    int32 CurrentChunkIndex;
    uint32 SrcBufferPadding;
    FAudioChunkHandle CurCompressedChunkHandle;
    FAudioChunkHandle NextPlayingChunkHandle;
    TPimplPtr<FStreamedAudioChunkSeekTable> CurrentChunkSeekTable;
    std::atomic<int32> StreamSeekBlockIndex;
    int32 StreamSeekBlockOffset;
 
    uint32 StreamSeekToAudioFrames = INDEX_NONE;    
 
private:
    bool SeekToDecodedPCMFrame(uint32 InTargetAudioFrame);
};
 
struct IAudioInfoFactory 
{   
    virtual ~IAudioInfoFactory() = default;
    virtual ICompressedAudioInfo* Create() = 0;
 
    struct FCapabilities
    {
        bool bSupportsSeeking = true;
        bool bSupportsSeekableStreaming = true;
    };
    virtual bool IsSeekingSupported(const bool bIsStreaming) const = 0;
};
struct IAudioInfoFactoryRegistry
{
    static ENGINE_API IAudioInfoFactoryRegistry& Get();
    virtual ~IAudioInfoFactoryRegistry() = default;
    virtual void Register(IAudioInfoFactory*, FName) = 0;
    virtual void Unregister(IAudioInfoFactory*, FName) = 0;
    virtual IAudioInfoFactory* Find(FName InName) const = 0;
    
    // Convenience helper.
    ICompressedAudioInfo* Create(FName InName) const
    {
        if (IAudioInfoFactory* Factory = Find(InName))
        {
            return Factory->Create();
        }
        return nullptr;
    }
};
 
class FSimpleAudioInfoFactory : public IAudioInfoFactory
{
public:
    FSimpleAudioInfoFactory(const TFunction<ICompressedAudioInfo*()>& InLambda, const FName& InFormatName, const FCapabilities InCaps = {})
    :  CreateLambda(InLambda), FormatName(InFormatName), Capabilities(InCaps)
    {
        IAudioInfoFactoryRegistry::Get().Register(this, FormatName);
    }
    virtual ~FSimpleAudioInfoFactory() override 
    {
        IAudioInfoFactoryRegistry::Get().Unregister(this, FormatName);
    }
    virtual ICompressedAudioInfo* Create() override { return CreateLambda(); }
 
    virtual bool IsSeekingSupported(const bool bIsStreaming) const override
    {
        return bIsStreaming ?
            Capabilities.bSupportsSeekableStreaming :
            Capabilities.bSupportsSeeking;
    }
    
private:
    TFunction<ICompressedAudioInfo* ()> CreateLambda;
    FName FormatName;
    FCapabilities Capabilities;
};
 
class FAsyncAudioDecompressWorker : public FNonAbandonableTask
{
protected:
    USoundWave* Wave;
    ICompressedAudioInfo* AudioInfo;
    int32 NumPrecacheFrames;
 
public:
    ENGINE_API FAsyncAudioDecompressWorker(USoundWave* InWave, int32 InNumPrecacheFrames, FAudioDevice* InAudioDevice = nullptr);
 
    ENGINE_API void DoWork();
 
    inline TStatId GetStatId() const
    {
        RETURN_QUICK_DECLARE_CYCLE_STAT(FAsyncAudioDecompressWorker, STATGROUP_ThreadPoolAsyncTasks);
    }
};
 
typedef FAsyncTask<FAsyncAudioDecompressWorker> FAsyncAudioDecompress;
 
enum class ERealtimeAudioTaskType : uint8
{
    CompressedInfo,
 
    Decompress,
 
    Procedural
};
 
template<class T>
class FAsyncRealtimeAudioTaskWorker : public FNonAbandonableTask
{
protected:
    T* AudioBuffer;
    USoundWave* WaveData;
    uint8* AudioData;
    int32 NumPrecacheFrames;
    int32 MaxSamples;
    int32 BytesWritten;
    ERealtimeAudioTaskType TaskType;
    uint32 bSkipFirstBuffer:1;
    uint32 bLoopingMode:1;
    uint32 bLooped:1;
 
public:
    FAsyncRealtimeAudioTaskWorker(T* InAudioBuffer, USoundWave* InWaveData)
        : AudioBuffer(InAudioBuffer)
        , WaveData(InWaveData)
        , AudioData(nullptr)
        , NumPrecacheFrames(0)
        , MaxSamples(0)
        , BytesWritten(0)
        , TaskType(ERealtimeAudioTaskType::CompressedInfo)
        , bSkipFirstBuffer(false)
        , bLoopingMode(false)
        , bLooped(false)
    {
        check(AudioBuffer);
        check(WaveData);
    }
 
    FAsyncRealtimeAudioTaskWorker(T* InAudioBuffer, uint8* InAudioData, int32 InNumPrecacheFrames, bool bInLoopingMode, bool bInSkipFirstBuffer)
        : AudioBuffer(InAudioBuffer)
        , AudioData(InAudioData)
        , NumPrecacheFrames(InNumPrecacheFrames)
        , TaskType(ERealtimeAudioTaskType::Decompress)
        , bSkipFirstBuffer(bInSkipFirstBuffer)
        , bLoopingMode(bInLoopingMode)
        , bLooped(false)
    {
        check(AudioBuffer);
        check(AudioData);
    }
 
    FAsyncRealtimeAudioTaskWorker(USoundWave* InWaveData, uint8* InAudioData, int32 InMaxSamples)
        : WaveData(InWaveData)
        , AudioData(InAudioData)
        , NumPrecacheFrames(0)
        , MaxSamples(InMaxSamples)
        , BytesWritten(0)
        , TaskType(ERealtimeAudioTaskType::Procedural)
    {
        check(WaveData);
        check(AudioData);
    }
 
    void DoWork()
    {
        LLM_SCOPE(ELLMTag::AudioMisc);
 
        switch(TaskType)
        {
        case ERealtimeAudioTaskType::CompressedInfo:
            AudioBuffer->ReadCompressedInfo(WaveData);
            break;
 
        case ERealtimeAudioTaskType::Decompress:
            if (bSkipFirstBuffer)
            {
#if PLATFORM_ANDROID
                // Only skip one buffer on Android
                AudioBuffer->ReadCompressedData((uint8*)AudioData, NumPrecacheFrames, bLoopingMode );
#else
                // If we're using cached data we need to skip the first two reads from the data
                AudioBuffer->ReadCompressedData((uint8*)AudioData, NumPrecacheFrames, bLoopingMode);
                AudioBuffer->ReadCompressedData((uint8*)AudioData, NumPrecacheFrames, bLoopingMode);
#endif
            }
            bLooped = AudioBuffer->ReadCompressedData((uint8*)AudioData, MONO_PCM_BUFFER_SAMPLES, bLoopingMode);
            break;
 
        case ERealtimeAudioTaskType::Procedural:
            BytesWritten = WaveData->GeneratePCMData((uint8*)AudioData, MaxSamples);
            break;
 
        default:
            check(false);
        }
    }
 
    inline TStatId GetStatId() const
    {
        if (TaskType == ERealtimeAudioTaskType::Procedural)
        {
            RETURN_QUICK_DECLARE_CYCLE_STAT(FAsyncRealtimeAudioProceduralWorker, STATGROUP_ThreadPoolAsyncTasks);
        }
        else
        { //-V523
            RETURN_QUICK_DECLARE_CYCLE_STAT(FAsyncRealtimeAudioDecompressWorker, STATGROUP_ThreadPoolAsyncTasks);
        }
    }
 
    ERealtimeAudioTaskType GetTaskType() const
    {
        return TaskType;
    }
 
    bool GetBufferLooped() const
    { 
        check(TaskType == ERealtimeAudioTaskType::Decompress);
        return bLooped;
    }
 
    int32 GetBytesWritten() const
    { 
        check(TaskType == ERealtimeAudioTaskType::Procedural);
        return BytesWritten;
    }
};
 
ENGINE_API bool ShouldUseBackgroundPoolFor_FAsyncRealtimeAudioTask();
 
template<class T>
class FAsyncRealtimeAudioTaskProxy
{
public:
    FAsyncRealtimeAudioTaskProxy(T* InAudioBuffer, USoundWave* InWaveData)
    {
        Task = new FAsyncTask<FAsyncRealtimeAudioTaskWorker<T>>(InAudioBuffer, InWaveData);
    }
 
    FAsyncRealtimeAudioTaskProxy(T* InAudioBuffer, uint8* InAudioData, int32 InNumFramesToDecode, bool bInLoopingMode, bool bInSkipFirstBuffer)
    {
        Task = new FAsyncTask<FAsyncRealtimeAudioTaskWorker<T>>(InAudioBuffer, InAudioData, InNumFramesToDecode, bInLoopingMode, bInSkipFirstBuffer);
    }
    FAsyncRealtimeAudioTaskProxy(USoundWave* InWaveData, uint8* InAudioData, int32 InMaxSamples)
    {
        Task = new FAsyncTask<FAsyncRealtimeAudioTaskWorker<T>>(InWaveData, InAudioData, InMaxSamples);
    }
 
    ~FAsyncRealtimeAudioTaskProxy()
    {
        check(IsDone());
        delete Task;
    }
 
    bool IsDone()
    {
        FScopeLock Lock(&CritSect);
        return Task->IsDone();
    }
 
    void EnsureCompletion(bool bDoWorkOnThisThreadIfNotStarted = true)
    {
        FScopeLock Lock(&CritSect);
 
        if (!bDoWorkOnThisThreadIfNotStarted)
        {
            Task->Cancel();
        }
        Task->EnsureCompletion(bDoWorkOnThisThreadIfNotStarted);
    }
 
    void StartBackgroundTask()
    {
        FScopeLock Lock(&CritSect);
        const bool bUseBackground = ShouldUseBackgroundPoolFor_FAsyncRealtimeAudioTask() && (Task->GetTask().GetTaskType() != ERealtimeAudioTaskType::Procedural);
        Task->StartBackgroundTask(bUseBackground ? GBackgroundPriorityThreadPool : GThreadPool);
    }
 
    FAsyncRealtimeAudioTaskWorker<T>& GetTask()
    {
        FScopeLock Lock(&CritSect);
        return Task->GetTask();
    }
 
private:
    FCriticalSection CritSect;
    FAsyncTask<FAsyncRealtimeAudioTaskWorker<T>>* Task;
};