VirtualTexturing.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
#pragma once
 
#include "Async/TaskGraphInterfaces.h"
#include "Containers/EnumAsByte.h"
#include "Containers/HashTable.h"
#include "CoreMinimal.h"
#include "Logging/LogMacros.h"
#include "Math/Color.h"
#include "Math/IntVector.h"
#include "Math/UnrealMathSSE.h"
#include "Misc/AssertionMacros.h"
#include "Misc/EnumClassFlags.h"
#include "PixelFormat.h"
#include "Stats/Stats.h"
#include "Templates/RefCounting.h"
#include "Templates/TypeHash.h"
#include "UObject/NameTypes.h"
 
class FRDGBuilder;
class FRHICommandListBase;
class FRHIShaderResourceView;
class FRHITexture;
class FRHIUnorderedAccessView;
struct IPooledRenderTarget;
class ISceneRenderer;
namespace ERHIFeatureLevel { enum Type : int; }
enum class EVTProducerPriority : uint8;
enum class EVTInvalidatePriority : uint8;
 
union FVirtualTextureProducerHandle
{
    FVirtualTextureProducerHandle() : PackedValue(0u) {}
    explicit FVirtualTextureProducerHandle(uint32 InPackedValue) : PackedValue(InPackedValue) {}
    FVirtualTextureProducerHandle(uint32 InIndex, uint32 InMagic) : Index(InIndex), Magic(InMagic) {}
 
    inline bool IsValid() const { return PackedValue != 0u; }
    inline bool IsNull() const { return PackedValue == 0u; }
 
    uint32 PackedValue;
    struct
    {
        uint32 Index : 22;
        uint32 Magic : 10;
    };
 
    friend inline bool operator==(const FVirtualTextureProducerHandle& Lhs, const FVirtualTextureProducerHandle& Rhs) { return Lhs.PackedValue == Rhs.PackedValue; }
    friend inline bool operator!=(const FVirtualTextureProducerHandle& Lhs, const FVirtualTextureProducerHandle& Rhs) { return Lhs.PackedValue != Rhs.PackedValue; }
};
static_assert(sizeof(FVirtualTextureProducerHandle) == sizeof(uint32), "Bad packing");
 
#define VIRTUALTEXTURE_MAX_FEEDBACK_SPACES 16
 
#define VIRTUALTEXTURE_SPACE_MAXLAYERS 8
 
#define VIRTUALTEXTURE_LOG2_MAX_PAGETABLE_SIZE 12u
#define VIRTUALTEXTURE_MAX_PAGETABLE_SIZE (1u << VIRTUALTEXTURE_LOG2_MAX_PAGETABLE_SIZE)
#define VIRTUALTEXTURE_MIN_PAGETABLE_SIZE 32u
 
struct FAllocatedVTDescription
{
    FName Name;
 
    uint32 TileSize = 0u;
    uint32 TileBorderSize = 0u;
    uint32 MaxSpaceSize = 0u;
    uint32 IndirectionTextureSize = 0u;
    uint8 Dimensions = 0u;
    uint8 NumTextureLayers = 0u;
    uint8 ForceSpaceID = 0xff;
    uint8 AdaptiveLevelBias = 0u;
 
    FVirtualTextureProducerHandle ProducerHandle[VIRTUALTEXTURE_SPACE_MAXLAYERS];
    uint8 ProducerLayerIndex[VIRTUALTEXTURE_SPACE_MAXLAYERS] = { 0u };
 
    union
    {
        uint8 PackedFlags = 0u;
        struct
        {
            uint8 bPrivateSpace : 1;
 
            uint8 bShareDuplicateLayers : 1;
        };
    };
 
    friend inline bool operator==(const FAllocatedVTDescription& Lhs, const FAllocatedVTDescription& Rhs)
    {
        if (Lhs.TileSize != Rhs.TileSize ||
            Lhs.TileBorderSize != Rhs.TileBorderSize ||
            Lhs.Dimensions != Rhs.Dimensions ||
            Lhs.NumTextureLayers != Rhs.NumTextureLayers ||
            Lhs.PackedFlags != Rhs.PackedFlags)
        {
            return false;
        }
        for (uint32 LayerIndex = 0u; LayerIndex < Lhs.NumTextureLayers; ++LayerIndex)
        {
            if (Lhs.ProducerHandle[LayerIndex] != Rhs.ProducerHandle[LayerIndex] ||
                Lhs.ProducerLayerIndex[LayerIndex] != Rhs.ProducerLayerIndex[LayerIndex])
            {
                return false;
            }
        }
        return true;
    }
    friend inline bool operator!=(const FAllocatedVTDescription& Lhs, const FAllocatedVTDescription& Rhs)
    {
        return !operator==(Lhs, Rhs);
    }
 
    friend inline uint32 GetTypeHash(const FAllocatedVTDescription& Description)
    {
        uint32 Hash = GetTypeHash(Description.TileSize);
        Hash = HashCombine(Hash, GetTypeHash(Description.TileBorderSize));
        Hash = HashCombine(Hash, GetTypeHash(Description.Dimensions));
        Hash = HashCombine(Hash, GetTypeHash(Description.NumTextureLayers));
        Hash = HashCombine(Hash, GetTypeHash(Description.PackedFlags));
        for (uint32 LayerIndex = 0u; LayerIndex < Description.NumTextureLayers; ++LayerIndex)
        {
            Hash = HashCombine(Hash, GetTypeHash(Description.ProducerHandle[LayerIndex].PackedValue));
            Hash = HashCombine(Hash, GetTypeHash(Description.ProducerLayerIndex[LayerIndex]));
        }
        return Hash;
    }
};
 
struct FVTProducerDescription
{
    RENDERCORE_API FVTProducerDescription();
 
    FName Name; 
    uint32 FullNameHash;
    
    bool bPersistentHighestMip = true;
    bool bContinuousUpdate = false;
    bool bRequiresSinglePhysicalPool = false;
    bool bNotifyCompleted = false; 
    uint32 TileSize = 0u;
    uint32 TileBorderSize = 0u;
 
    uint32 BlockWidthInTiles = 0u;
    uint32 BlockHeightInTiles = 0u;
    uint32 DepthInTiles = 0u;
    uint16 WidthInBlocks = 1u;
    uint16 HeightInBlocks = 1u;
    uint8 Dimensions = 0u;
    uint8 MaxLevel = 0u;
 
    uint8 NumTextureLayers = 0u;
    TEnumAsByte<EPixelFormat> LayerFormat[VIRTUALTEXTURE_SPACE_MAXLAYERS] = { PF_Unknown };
    FLinearColor LayerFallbackColor[VIRTUALTEXTURE_SPACE_MAXLAYERS] = { FLinearColor::Black };
    bool bIsLayerSRGB[VIRTUALTEXTURE_SPACE_MAXLAYERS] = { false };
    
    uint8 NumPhysicalGroups = 0u;
    uint8 PhysicalGroupIndex[VIRTUALTEXTURE_SPACE_MAXLAYERS] = { 0 };
 
    EVTProducerPriority Priority;
};
 
typedef void (FVTProducerDestroyedFunction)(const FVirtualTextureProducerHandle& InHandle, void* Baton);
 
class IVirtualTextureFinalizer
{
public:
    virtual void RenderFinalize(FRDGBuilder& GraphBuilder, ISceneRenderer* SceneRenderingContext) {}
    virtual void Finalize(FRDGBuilder& GraphBuilder) = 0;
};
 
enum class EVTRequestPageStatus
{
    Invalid,
 
    Saturated,
 
    Pending,
 
    Available,
};
 
inline bool VTRequestPageStatus_HasData(EVTRequestPageStatus InStatus) { return InStatus == EVTRequestPageStatus::Pending || InStatus == EVTRequestPageStatus::Available; }
 
enum class EVTRequestPagePriority
{
    Normal,
    High,
};
 
enum class EVTProducePageFlags : uint8
{
    None = 0u,
    SkipPageBorders = (1u << 0),
    ContinuousUpdate = (1u << 1),
};
ENUM_CLASS_FLAGS(EVTProducePageFlags);
 
struct FVTRequestPageResult
{
    FVTRequestPageResult(EVTRequestPageStatus InStatus = EVTRequestPageStatus::Invalid, uint64 InHandle = 0u) : Handle(InHandle), Status(InStatus) {}
 
    uint64 Handle;
 
    EVTRequestPageStatus Status;
};
 
struct FVTProduceTargetLayer
{
    IPooledRenderTarget* PooledRenderTarget = nullptr;
    FIntVector pPageLocation = FIntVector::ZeroValue;
 
    UE_DEPRECATED(5.6, "Use PooledRenderTarget instead.")
    FRHITexture* TextureRHI = nullptr;
 
    // Disable some TextureRHI deprecation warnings here.
    PRAGMA_DISABLE_DEPRECATION_WARNINGS
    FVTProduceTargetLayer() = default;
    FVTProduceTargetLayer(const FVTProduceTargetLayer&) = default;
    FVTProduceTargetLayer& operator=(const FVTProduceTargetLayer&) = default;
    PRAGMA_ENABLE_DEPRECATION_WARNINGS
};
 
class IVirtualTexture
{
public:
    inline IVirtualTexture() {}
    virtual ~IVirtualTexture() {}
 
    virtual uint32 GetLocalMipBias(uint8 vLevel, uint32 vAddress) const { return 0u; }
 
    virtual bool IsPageStreamed(uint8 vLevel, uint32 vAddress) const = 0;
 
    virtual FVTRequestPageResult RequestPageData(FRHICommandListBase& RHICmdList, const FVirtualTextureProducerHandle& ProducerHandle, uint8 LayerMask, uint8 vLevel, uint64 vAddress, EVTRequestPagePriority Priority) = 0;
 
    virtual IVirtualTextureFinalizer* ProducePageData(
        FRHICommandListBase& RHICmdList,
        ERHIFeatureLevel::Type FeatureLevel,
        EVTProducePageFlags Flags,
        const FVirtualTextureProducerHandle& ProducerHandle, uint8 LayerMask, uint8 vLevel, uint64 vAddress,
        uint64 RequestHandle,
        const FVTProduceTargetLayer* TargetLayers) = 0;
 
    virtual void GatherProducePageDataTasks(FVirtualTextureProducerHandle const& ProducerHandle, FGraphEventArray& InOutTasks) const {}
 
    virtual void GatherProducePageDataTasks(uint64 RequestHandle, FGraphEventArray& InOutTasks) const {};
 
    virtual void DumpToConsole(bool verbose) {}
 
    virtual void OnRequestsCompleted() {}
};
 
enum class EVTPageTableFormat : uint8
{
    UInt16,
    UInt32,
};
 
class IAllocatedVirtualTexture
{
public:
    static const uint32 LayersPerPageTableTexture = 4u;
 
    inline IAllocatedVirtualTexture(const FAllocatedVTDescription& InDesc,
        uint32 InBlockWidthInTiles,
        uint32 InBlockHeightInTiles,
        uint32 InWidthInBlocks,
        uint32 InHeightInBlocks,
        uint32 InDepthInTiles)
        : Description(InDesc)
        , BlockWidthInTiles(InBlockWidthInTiles)
        , BlockHeightInTiles(InBlockHeightInTiles)
        , WidthInBlocks(InWidthInBlocks)
        , HeightInBlocks(InHeightInBlocks)
        , DepthInTiles(InDepthInTiles)
        , FrameDeleted(0u)
        , NumRefs(0)
        , bIsWaitingToMap(false)
        , PageTableFormat(EVTPageTableFormat::UInt32)
        , SpaceID(~0u)
        , MaxLevel(0u)
        , VirtualAddress(~0u)
        , VirtualPageX(~0u)
        , VirtualPageY(~0u)
    {}
 
    virtual uint32 GetPersistentHash() const = 0;
    virtual uint32 GetNumPageTableTextures() const = 0;
    virtual FRHITexture* GetPageTableTexture(uint32 InPageTableIndex) const = 0;
    virtual FRHITexture* GetPageTableIndirectionTexture() const = 0;
    virtual uint32 GetPhysicalTextureSize(uint32 InLayerIndex) const = 0;
    virtual FRHITexture* GetPhysicalTexture(uint32 InLayerIndex) const = 0;
    virtual FRHIShaderResourceView* GetPhysicalTextureSRV(uint32 InLayerIndex, bool bSRGB) const = 0;
 
    virtual void GetPackedPageTableUniform(FUintVector4* OutUniform) const = 0;
    virtual void GetPackedUniform(FUintVector4* OutUniform, uint32 LayerIndex) const = 0;
 
    virtual void DumpToConsole(bool bVerbose) const {}
 
    inline const FAllocatedVTDescription& GetDescription() const { return Description; }
    inline const FVirtualTextureProducerHandle& GetProducerHandle(uint32 InLayerIndex) const { check(InLayerIndex < Description.NumTextureLayers); return Description.ProducerHandle[InLayerIndex]; }
    
    inline uint32 GetVirtualTileSize() const { return Description.TileSize; }
    inline uint32 GetTileBorderSize() const { return Description.TileBorderSize; }
    inline uint32 GetPhysicalTileSize() const { return Description.TileSize + Description.TileBorderSize * 2u; }
    inline uint32 GetNumTextureLayers() const { return Description.NumTextureLayers; }
    inline uint8 GetDimensions() const { return Description.Dimensions; }
    inline uint32 GetWidthInBlocks() const { return WidthInBlocks; }
    inline uint32 GetHeightInBlocks() const { return HeightInBlocks; }
    inline uint32 GetBlockWidthInTiles() const { return BlockWidthInTiles; }
    inline uint32 GetBlockHeightInTiles() const { return BlockHeightInTiles; }
    inline uint32 GetWidthInTiles() const { return BlockWidthInTiles * WidthInBlocks; }
    inline uint32 GetHeightInTiles() const { return BlockHeightInTiles * HeightInBlocks; }
    inline uint32 GetDepthInTiles() const { return DepthInTiles; }
    inline uint32 GetWidthInPixels() const { return GetWidthInTiles() * Description.TileSize; }
    inline uint32 GetHeightInPixels() const { return GetHeightInTiles() * Description.TileSize; }
    inline uint32 GetDepthInPixels() const { return DepthInTiles * Description.TileSize; }
    inline uint32 GetSpaceID() const { return SpaceID; }
    inline uint32 GetVirtualAddress() const { return VirtualAddress; }
    inline uint32 GetVirtualPageX() const { return VirtualPageX; }
    inline uint32 GetVirtualPageY() const { return VirtualPageY; }
    inline uint32 GetMaxLevel() const { return MaxLevel; }
    inline EVTPageTableFormat GetPageTableFormat() const { return PageTableFormat; }
 
protected:
    friend class FVirtualTextureSystem;
    virtual void Destroy(class FVirtualTextureSystem* InSystem) = 0;
    virtual bool TryMapLockedTiles(class FVirtualTextureSystem* InSystem) const = 0;
    virtual ~IAllocatedVirtualTexture() {}
 
    FAllocatedVTDescription Description;
    uint32 BlockWidthInTiles;
    uint32 BlockHeightInTiles;
    uint32 WidthInBlocks;
    uint32 HeightInBlocks;
    uint32 DepthInTiles;
    uint32 FrameDeleted;
    int32 NumRefs;
    bool bIsWaitingToMap;
 
    // should be set explicitly by derived class constructor
    EVTPageTableFormat PageTableFormat;
    uint32 SpaceID;
    uint32 MaxLevel;
    uint32 VirtualAddress;
    uint32 VirtualPageX;
    uint32 VirtualPageY;
};
 
class IAdaptiveVirtualTexture
{
public:
    virtual IAllocatedVirtualTexture* GetAllocatedVirtualTexture() = 0;
 
protected:
    friend class FVirtualTextureSystem;
    virtual ~IAdaptiveVirtualTexture() {}
    virtual int32 GetSpaceID() const = 0;
    virtual void Destroy(class FVirtualTextureSystem* InSystem) = 0;
};
 
struct FAdaptiveVTDescription
{
    uint32 TileCountX;
    uint32 TileCountY;
    uint32 MaxAdaptiveLevel;
};
 
union FVirtualTextureLocalTile
{
    inline FVirtualTextureLocalTile() {}
    explicit inline FVirtualTextureLocalTile(const FVirtualTextureProducerHandle& InProducerHandle, uint32 InLocal_vAddress, uint8 InLocal_vLevel)
        : PackedProducerHandle(InProducerHandle.PackedValue)
        , Local_vAddress(InLocal_vAddress)
        , Local_vLevel(InLocal_vLevel)
        , Pad(0)
    {
    }
    explicit inline FVirtualTextureLocalTile(uint64 InPackedValue)
        : PackedValue(InPackedValue)
    {
        Pad = 0;
    }
 
    inline FVirtualTextureProducerHandle GetProducerHandle() const { return FVirtualTextureProducerHandle(PackedProducerHandle); }
 
    uint64 PackedValue = 0;
    struct
    {
        // Core "identity" data that identify a given tile
        uint32 PackedProducerHandle;
        uint32 Local_vAddress : 24;
        uint32 Local_vLevel : 4;
        uint32 Pad : 4;  // Important : this has to be kept in sync with FVirtualTextureLocalTileRequest : both are packed in a uint64 and the latter stores additional info in these bits
    };
 
    friend inline bool operator==(const FVirtualTextureLocalTile& Lhs, const FVirtualTextureLocalTile& Rhs) { return Lhs.PackedValue == Rhs.PackedValue; }
    friend inline bool operator!=(const FVirtualTextureLocalTile& Lhs, const FVirtualTextureLocalTile& Rhs) { return Lhs.PackedValue != Rhs.PackedValue; }
    friend inline uint32 GetTypeHash(const FVirtualTextureLocalTile& T) { return GetTypeHash(T.PackedValue); } 
    inline uint16 GetMurmurHash() const { return static_cast<uint16>(MurmurFinalize64(PackedValue)); }
};
static_assert(sizeof(FVirtualTextureLocalTile) == sizeof(uint64), "Bad packing");
 
union FVirtualTextureLocalTileRequest
{
    explicit inline FVirtualTextureLocalTileRequest() {}
    explicit inline FVirtualTextureLocalTileRequest(const FVirtualTextureLocalTile& InTile, EVTProducerPriority InProducerPriority, EVTInvalidatePriority InInvalidatePriority)
        : TilePackedValue(InTile.PackedValue)
        , ProducerPriority(static_cast<uint64>(InProducerPriority))
        , InvalidatePriority(static_cast<uint64>(InInvalidatePriority))
    {
        checkSlow(InTile == GetTile());
        ValidatePriorities();
    }
 
    inline FVirtualTextureLocalTile GetTile() const { return FVirtualTextureLocalTile(TilePackedValue); }
    inline EVTProducerPriority GetProducerPriority() const { return static_cast<EVTProducerPriority>(ProducerPriority); }
    inline EVTInvalidatePriority GetInvalidatePriority() const { return static_cast<EVTInvalidatePriority>(InvalidatePriority); }
 
    inline FVirtualTextureLocalTileRequest& MergeWith(const FVirtualTextureLocalTileRequest& InOther) 
    {   
        // Keep the highest priorities of the 2 :
        ProducerPriority = FMath::Max(ProducerPriority, InOther.ProducerPriority);
        InvalidatePriority = FMath::Max(InvalidatePriority, InOther.InvalidatePriority);
 
        checkSlow(*this == InOther);
        checkSlow(GetTile() == InOther.GetTile());
        ValidatePriorities();
        return *this;
    }
 
    uint64 PackedValue;
    struct
    {
        // Core "identity" data that identifies a given tile : 
        uint64 TilePackedValue : 60;
        // Additional data about the request :
        uint64 ProducerPriority : 3; // See EVTProducerPriority 
        uint64 InvalidatePriority : 1; // Indicates whether the tile should get prioritized over others
    };
 
    friend inline bool operator==(const FVirtualTextureLocalTileRequest& Lhs, const FVirtualTextureLocalTileRequest& Rhs) { return Lhs.GetIdentity() == Rhs.GetIdentity(); }
    friend inline bool operator!=(const FVirtualTextureLocalTileRequest& Lhs, const FVirtualTextureLocalTileRequest& Rhs) { return Lhs.GetIdentity() != Rhs.GetIdentity(); }
    friend inline uint32 GetTypeHash(const FVirtualTextureLocalTileRequest& T) { return GetTypeHash(T.GetIdentity()); }
    inline uint64 GetIdentity() const { return TilePackedValue; }  // 2 requests from the same tile are considered identical (it's up to the user to "merge" them if necessary)
    inline uint16 GetMurmurHash() const { return static_cast<uint16>(MurmurFinalize64(GetIdentity())); } 
 
private:
    RENDERCORE_API void ValidatePriorities() const;
};
static_assert(sizeof(FVirtualTextureLocalTileRequest) == sizeof(uint64), "Bad packing");
 
inline FVirtualTextureLocalTileRequest& AddOrMergeTileRequest(const FVirtualTextureLocalTileRequest& InTileRequest, TSet<FVirtualTextureLocalTileRequest>& TileRequests)
{
    bool bAlreadyInSet = false;
    FVirtualTextureLocalTileRequest& Result = TileRequests.FindOrAdd(InTileRequest, &bAlreadyInSet);
    if (bAlreadyInSet)
    {
        // If the request already exists, merge with this new request, to keep the highest priority :
        Result.MergeWith(InTileRequest);
    }
    return Result;
}
 
RENDERCORE_API DECLARE_LOG_CATEGORY_EXTERN(LogVirtualTexturing, Log, All);
 
DECLARE_STATS_GROUP(TEXT("Virtual Texturing"), STATGROUP_VirtualTexturing, STATCAT_Advanced);
DECLARE_STATS_GROUP(TEXT("Virtual Texture Memory"), STATGROUP_VirtualTextureMemory, STATCAT_Advanced);