Distributions.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
/*=============================================================================
    Distributions.h: Declaration of distributions.
=============================================================================*/
 
#pragma once
 
#include "CoreMinimal.h"
#include "Math/RandomStream.h"
 
#define checkDistribution check
 
enum ERawDistributionOperation
{
    RDO_Uninitialized,
    RDO_None,
    RDO_Random,
    RDO_Extreme,
};
 
struct FDistributionLookupTable
{
    float TimeScale;
    float TimeBias;
    TArray<float> Values;
    uint8 Op;
    uint8 EntryCount;
    uint8 EntryStride;
    uint8 SubEntryStride;
    uint8 LockFlag;
    
    FDistributionLookupTable()
        : TimeScale(0.0f)
        , TimeBias(0.0f)
        , Op(RDO_Uninitialized)
        , EntryCount(0)
        , EntryStride(0)
        , SubEntryStride(0)
        , LockFlag(0)
    {}
 
    void Empty()
    {
        Op = RDO_Uninitialized;
        EntryCount = 0;
        EntryStride = 0;
        SubEntryStride = 0;
        TimeScale = 0.0f;
        TimeBias = 0.0f;
        LockFlag = 0;
    }
 
    inline bool IsEmpty() const
    {
        return Values.Num() == 0 || EntryCount == 0;
    }
 
    inline float GetValuesPerEntry() const
    {
        return (float)(EntryStride - SubEntryStride);
    }
 
    inline float GetValueCount() const
    {
        return (float)(Values.Num());
    }
 
    inline void GetEntry( float Time, const float*& Entry1, const float*& Entry2, float& LerpAlpha ) const
    {
        // make time relative to start time
        Time -= TimeBias;
        Time *= TimeScale;
        Time = FMath::FloatSelect( Time, Time, 0.0f );
 
        // calculate the alpha to lerp between entry1 and entry2
        LerpAlpha = FMath::Fractional(Time);
 
        // get the entries to lerp between
        const uint32 Index = FMath::TruncToInt(Time);
        const uint32 Index1 = FMath::Min<uint32>( Index + 0, EntryCount - 1 ) * EntryStride;
        const uint32 Index2 = FMath::Min<uint32>( Index + 1, EntryCount - 1 ) * EntryStride;
        Entry1 = &Values[Index1];
        Entry2 = &Values[Index2];
    }
 
    void GetRange( float* OutMinValues, float* OutMaxValues )
    {
        if ( EntryCount > 0 )
        {
            const int32 ValuesPerEntry = (int32)GetValuesPerEntry();
            const float* Entry = Values.GetData();
 
            // Initialize to the first entry in the table.
            for ( int32 ValueIndex = 0; ValueIndex < ValuesPerEntry; ++ValueIndex )
            {
                OutMinValues[ValueIndex] = Entry[ValueIndex];
                OutMaxValues[ValueIndex] = Entry[ValueIndex + SubEntryStride];
            }
 
            // Iterate over each entry updating the minimum and maximum values.
            for ( int32 EntryIndex = 1; EntryIndex < EntryCount; ++EntryIndex )
            {
                Entry += EntryStride;
                for ( int32 ValueIndex = 0; ValueIndex < ValuesPerEntry; ++ValueIndex )
                {
                    OutMinValues[ValueIndex] = FMath::Min( OutMinValues[ValueIndex], Entry[ValueIndex] );
                    OutMaxValues[ValueIndex] = FMath::Max( OutMaxValues[ValueIndex], Entry[ValueIndex + SubEntryStride] );
                }
            }
        }
    }
};
 
// Helper macro for retrieving random value
#define DIST_GET_RANDOM_VALUE(RandStream)       ((RandStream == NULL) ? FMath::SRand() : RandStream->GetFraction())
 
struct FRawDistribution
{
    FRawDistribution()
    {
    }
 
    ENGINE_API bool Serialize( FArchive& Ar );
 
    ENGINE_API void GetValue(float Time, float* Value, int32 NumCoords, int32 Extreme, struct FRandomStream* InRandomStream) const;
 
    // prebaked versions of these
    ENGINE_API void GetValue1(float Time, float* Value, int32 Extreme, struct FRandomStream* InRandomStream) const;
    ENGINE_API void GetValue3(float Time, float* Value, int32 Extreme, struct FRandomStream* InRandomStream) const;
    inline void GetValue1None(float Time, float* InValue) const
    {
        float* Value = InValue;
        const float* Entry1;
        const float* Entry2;
        float LerpAlpha = 0.0f;
        LookupTable.GetEntry(Time, Entry1, Entry2, LerpAlpha);
        const float* NewEntry1 = Entry1;
        const float* NewEntry2 = Entry2;
        Value[0] = FMath::Lerp(NewEntry1[0], NewEntry2[0], LerpAlpha);
    }
    inline void GetValue3None(float Time, float* InValue) const
    {
        float* Value = InValue;
        const float* Entry1;
        const float* Entry2;
        float LerpAlpha = 0.0f;
        LookupTable.GetEntry(Time, Entry1, Entry2, LerpAlpha);
        const float* NewEntry1 = Entry1;
        const float* NewEntry2 = Entry2;
        float T0 = FMath::Lerp(NewEntry1[0], NewEntry2[0], LerpAlpha);
        float T1 = FMath::Lerp(NewEntry1[1], NewEntry2[1], LerpAlpha);
        float T2 = FMath::Lerp(NewEntry1[2], NewEntry2[2], LerpAlpha);
        Value[0] = T0;
        Value[1] = T1;
        Value[2] = T2;
    }
    ENGINE_API void GetValue1Extreme(float Time, float* Value, int32 Extreme, struct FRandomStream* InRandomStream) const;
    ENGINE_API void GetValue3Extreme(float Time, float* Value, int32 Extreme, struct FRandomStream* InRandomStream) const;
    ENGINE_API void GetValue1Random(float Time, float* Value, struct FRandomStream* InRandomStream) const;
    ENGINE_API void GetValue3Random(float Time, float* Value, struct FRandomStream* InRandomStream) const;
 
    inline bool IsSimple() 
    {
        return LookupTable.Op == RDO_None;
    }
 
    static ENGINE_API UObject* TryGetDistributionObjectFromRawDistributionProperty(FStructProperty* Property, uint8* Data);
 
protected:
 
    FDistributionLookupTable LookupTable;
};
 
/*-----------------------------------------------------------------------------
    Type safe distributions.
 
    Like FRawDistribution but typesafe and not tied directly to UObjects.
-----------------------------------------------------------------------------*/
 
class FFloatDistribution
{
public:
    FFloatDistribution();
 
    inline void GetValue( float Time, float* RESTRICT OutValue ) const
    {
        checkDistribution( LookupTable.GetValuesPerEntry() == 1 );
 
        const float* Entry1;
        const float* Entry2;
        float Alpha;
 
        LookupTable.GetEntry( Time, Entry1, Entry2, Alpha );
        OutValue[0] = FMath::Lerp( Entry1[0], Entry2[0], Alpha );
    }
 
    inline void GetRandomValue( float Time, float* RESTRICT OutValue, FRandomStream& RandomStream ) const
    {
        checkDistribution( LookupTable.GetValuesPerEntry() == 1 );
 
        const float* Entry1;
        const float* Entry2;
        float Alpha;
        float RandomAlpha;
        float MinValue, MaxValue;
        const int32 SubEntryStride = LookupTable.SubEntryStride;
 
        LookupTable.GetEntry( Time, Entry1, Entry2, Alpha );
        MinValue = FMath::Lerp( Entry1[0], Entry2[0], Alpha );
        MaxValue = FMath::Lerp( Entry1[SubEntryStride], Entry2[SubEntryStride], Alpha );
        RandomAlpha = RandomStream.GetFraction();
        OutValue[0] = FMath::Lerp( MinValue, MaxValue, RandomAlpha );
    }
 
    void GetRange( float* OutMin, float* OutMax )
    {
        LookupTable.GetRange( OutMin, OutMax );
    }
 
private:
    FDistributionLookupTable LookupTable;
 
    //@todo.CONSOLE: These are needed until we have a cooker/package in place!
    friend class FComposableDistribution;
};
 
class FVectorDistribution
{
public:
    FVectorDistribution();
 
    inline void GetValue( float Time, float* RESTRICT OutValue ) const
    {
        checkDistribution( LookupTable.GetValuesPerEntry() == 3 );
 
        const float* Entry1;
        const float* Entry2;
        float Alpha;
 
        LookupTable.GetEntry( Time, Entry1, Entry2, Alpha );
        OutValue[0] = FMath::Lerp( Entry1[0], Entry2[0], Alpha );
        OutValue[1] = FMath::Lerp( Entry1[1], Entry2[1], Alpha );
        OutValue[2] = FMath::Lerp( Entry1[2], Entry2[2], Alpha );
    }
 
    inline void GetRandomValue( float Time, float* RESTRICT OutValue, FRandomStream& RandomStream ) const
    {
        checkDistribution( LookupTable.GetValuesPerEntry() == 3 );
 
        const float* Entry1;
        const float* Entry2;
        float Alpha;
        float RandomAlpha[3];
        float MinValue[3], MaxValue[3];
        const int32 SubEntryStride = LookupTable.SubEntryStride;
 
        LookupTable.GetEntry( Time, Entry1, Entry2, Alpha );
 
        MinValue[0] = FMath::Lerp( Entry1[0], Entry2[0], Alpha );
        MinValue[1] = FMath::Lerp( Entry1[1], Entry2[1], Alpha );
        MinValue[2] = FMath::Lerp( Entry1[2], Entry2[2], Alpha );
 
        MaxValue[0] = FMath::Lerp( Entry1[SubEntryStride + 0], Entry2[SubEntryStride + 0], Alpha );
        MaxValue[1] = FMath::Lerp( Entry1[SubEntryStride + 1], Entry2[SubEntryStride + 1], Alpha );
        MaxValue[2] = FMath::Lerp( Entry1[SubEntryStride + 2], Entry2[SubEntryStride + 2], Alpha );
 
        RandomAlpha[0] = RandomStream.GetFraction();
        RandomAlpha[1] = RandomStream.GetFraction();
        RandomAlpha[2] = RandomStream.GetFraction();
 
        OutValue[0] = FMath::Lerp( MinValue[0], MaxValue[0], RandomAlpha[0] );
        OutValue[1] = FMath::Lerp( MinValue[1], MaxValue[1], RandomAlpha[1] );
        OutValue[2] = FMath::Lerp( MinValue[2], MaxValue[2], RandomAlpha[2] );
    }
 
    void GetRange(FVector3f* OutMin, FVector3f* OutMax)
    {
        LookupTable.GetRange((float*)OutMin, (float*)OutMax);
    }
 
    // LWC_TODO: Precision loss
    void GetRange(FVector3d* OutMin, FVector3d* OutMax)
    {
        FVector3f OutMinFloat, OutMaxFloat;
        GetRange(&OutMinFloat, &OutMaxFloat);
        *OutMin = FVector3d(OutMinFloat);
        *OutMax = FVector3d(OutMaxFloat);
    }
 
private:
    FDistributionLookupTable LookupTable;
 
    friend class FComposableDistribution;
};
 
class FVector4Distribution
{
public:
    FVector4Distribution();
 
    inline void GetValue( float Time, float* RESTRICT OutValue ) const
    {
        checkDistribution( LookupTable.GetValuesPerEntry() == 4 );
 
        const float* Entry1;
        const float* Entry2;
        float Alpha;
 
        LookupTable.GetEntry( Time, Entry1, Entry2, Alpha );
        OutValue[0] = FMath::Lerp( Entry1[0], Entry2[0], Alpha );
        OutValue[1] = FMath::Lerp( Entry1[1], Entry2[1], Alpha );
        OutValue[2] = FMath::Lerp( Entry1[2], Entry2[2], Alpha );
        OutValue[3] = FMath::Lerp( Entry1[3], Entry2[3], Alpha );
    }
 
    inline void GetRandomValue( float Time, float* RESTRICT OutValue, FRandomStream& RandomStream ) const
    {
        checkDistribution( LookupTable.GetValuesPerEntry() == 4 );
 
        const float* Entry1;
        const float* Entry2;
        float Alpha;
        float RandomAlpha[4];
        float MinValue[4], MaxValue[4];
        const int32 SubEntryStride = LookupTable.SubEntryStride;
 
        LookupTable.GetEntry( Time, Entry1, Entry2, Alpha );
 
        MinValue[0] = FMath::Lerp( Entry1[0], Entry2[0], Alpha );
        MinValue[1] = FMath::Lerp( Entry1[1], Entry2[1], Alpha );
        MinValue[2] = FMath::Lerp( Entry1[2], Entry2[2], Alpha );
        MinValue[3] = FMath::Lerp( Entry1[3], Entry2[3], Alpha );
 
        MaxValue[0] = FMath::Lerp( Entry1[SubEntryStride + 0], Entry2[SubEntryStride + 0], Alpha );
        MaxValue[1] = FMath::Lerp( Entry1[SubEntryStride + 1], Entry2[SubEntryStride + 1], Alpha );
        MaxValue[2] = FMath::Lerp( Entry1[SubEntryStride + 2], Entry2[SubEntryStride + 2], Alpha );
        MaxValue[3] = FMath::Lerp( Entry1[SubEntryStride + 3], Entry2[SubEntryStride + 3], Alpha );
 
        RandomAlpha[0] = RandomStream.GetFraction();
        RandomAlpha[1] = RandomStream.GetFraction();
        RandomAlpha[2] = RandomStream.GetFraction();
        RandomAlpha[3] = RandomStream.GetFraction();
 
        OutValue[0] = FMath::Lerp( MinValue[0], MaxValue[0], RandomAlpha[0] );
        OutValue[1] = FMath::Lerp( MinValue[1], MaxValue[1], RandomAlpha[1] );
        OutValue[2] = FMath::Lerp( MinValue[2], MaxValue[2], RandomAlpha[2] );
        OutValue[3] = FMath::Lerp( MinValue[3], MaxValue[3], RandomAlpha[3] );
    }
 
    void GetRange( FVector4f* OutMin, FVector4f* OutMax )
    {
        LookupTable.GetRange( (float*)OutMin, (float*)OutMax );
    }
 
    // LWC_TODO: Precision loss
    void GetRange(FVector4d* OutMin, FVector4d* OutMax)
    {
        FVector4f OutMinFloat, OutMaxFloat;
        GetRange(&OutMinFloat, &OutMaxFloat);
        *OutMin = (FVector4d)OutMinFloat;
        *OutMax = (FVector4d)OutMaxFloat;
    }
 
private:
    FDistributionLookupTable LookupTable;
 
    friend class FComposableDistribution;
};
 
/*-----------------------------------------------------------------------------
    Composable distributions.
 
    These classes allow code to compose multiple distributions and produce a
    final, optimized raw distribution.
-----------------------------------------------------------------------------*/
 
//#if WITH_EDITORONLY_DATA
 
class FComposableDistribution
{
public:
    static void BuildFloat( class FFloatDistribution& OutDistribution, const class FComposableFloatDistribution& X );
 
    static void BuildVector( class FVectorDistribution& OutDistribution, const class FComposableVectorDistribution& XYZ );
 
    static void BuildVector4( class FVector4Distribution& OutDistribution, const class FComposableVectorDistribution& XYZ, const class FComposableFloatDistribution& W );
 
    static void BuildVector4( 
        class FVector4Distribution& OutDistribution,
        const class FComposableVectorDistribution& XY,
        const class FComposableFloatDistribution& Z,
        const class FComposableFloatDistribution& W );
 
    static void BuildVector4(
        class FVector4Distribution& OutDistribution,
        const class FComposableFloatDistribution& X,
        const class FComposableFloatDistribution& Y,
        const class FComposableFloatDistribution& Z,
        const class FComposableFloatDistribution& W );
 
    static void QuantizeVector4(
        TArray<FColor>& OutQuantizedSamples,
        FVector4& OutScale,
        FVector4& OutBias,
        const class FVector4Distribution& Distribution );
 
protected:
    FDistributionLookupTable LookupTable;
 
    FComposableDistribution() {}
 
    ~FComposableDistribution() {}
 
    FComposableDistribution( const FComposableDistribution& Other )
        : LookupTable( Other.LookupTable )
    {
    }
 
    const FComposableDistribution& operator=( const FComposableDistribution& Other )
    {
        LookupTable = Other.LookupTable;
        return *this;
    }
};
 
class FComposableFloatDistribution : public FComposableDistribution
{
public:
    FComposableFloatDistribution();
 
    FComposableFloatDistribution( const FComposableFloatDistribution& Other )
        : FComposableDistribution( Other )
    {
    }
 
    const FComposableFloatDistribution& operator=( const FComposableFloatDistribution& Other )
    {
        FComposableDistribution::operator=( Other );
        return *this;
    }
 
    void Initialize( const class UDistributionFloat* FloatDistribution );
 
    void InitializeWithConstant( float Value );
 
    void ScaleByConstant( float Scale );
 
    void ScaleByDistribution( const class UDistributionFloat* FloatDistribution );
 
    void AddDistribution( const class UDistributionFloat* FloatDistribution );
 
    void Normalize( float* OutScale, float* OutBias );
 
    void Resample( float MinIn, float MaxIn );
};
 
class FComposableVectorDistribution : public FComposableDistribution
{
public:
    FComposableVectorDistribution();
 
    FComposableVectorDistribution( const FComposableVectorDistribution& Other )
        : FComposableDistribution( Other )
    {
    }
 
    const FComposableVectorDistribution& operator=( const FComposableVectorDistribution& Other )
    {
        FComposableDistribution::operator=( Other );
        return *this;
    }
 
    void Initialize( const class UDistributionVector* VectorDistribution );
 
    void InitializeWithConstant( const FVector& Value );
 
    void ScaleByConstant( float Scale );
 
    void ScaleByConstantVector( const FVector& Scale );
 
    void AddConstantVector( const FVector& Value );
 
    void ScaleByDistribution( const class UDistributionFloat* FloatDistribution );
 
    void ScaleByVectorDistribution( const class UDistributionVector* VectorDistribution );
 
    void AddDistribution( const class UDistributionVector* VectorDistribution );
 
    void Splat( int32 ChannelIndex );
 
    void Resample( float MinIn, float MaxIn );
};
//#endif // #if WITH_EDITORONLY_DATA