RenderGraphDefinitions.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
#pragma once
 
#include "ProfilingDebugging/RealtimeGPUProfiler.h"
#include "RenderGraphAllocator.h"
#include "RenderGraphFwd.h"
#include "RHIBreadcrumbs.h"
 
#define RDG_ENABLE_DEBUG (!UE_BUILD_SHIPPING && !UE_BUILD_TEST)
 
#if RDG_ENABLE_DEBUG
    #define IF_RDG_ENABLE_DEBUG(Op) Op
#else
    #define IF_RDG_ENABLE_DEBUG(Op)
#endif
 
#define RDG_ENABLE_DEBUG_WITH_ENGINE (RDG_ENABLE_DEBUG && WITH_ENGINE)
 
#define RDG_ENABLE_TRACE UE_TRACE_ENABLED && !IS_PROGRAM && !UE_BUILD_SHIPPING
 
#if RDG_ENABLE_TRACE
    #define IF_RDG_ENABLE_TRACE(Op) Op
#else
    #define IF_RDG_ENABLE_TRACE(Op)
#endif
 
#define RDG_DUMP_RESOURCES (WITH_DUMPGPU)
 
#define RDG_EVENTS_NONE 0
#define RDG_EVENTS_STRING_REF 1
#define RDG_EVENTS_STRING_COPY 2
 
#if WITH_PROFILEGPU
    #if UE_BUILD_TEST || UE_BUILD_SHIPPING
        #define RDG_EVENTS RDG_EVENTS_STRING_REF
    #else
        #define RDG_EVENTS RDG_EVENTS_STRING_COPY
    #endif
#elif WITH_RHI_BREADCRUMBS
    #define RDG_EVENTS RDG_EVENTS_STRING_REF
#else
    #define RDG_EVENTS RDG_EVENTS_NONE
#endif
 
#define SUPPORTS_VISUALIZE_TEXTURE (WITH_ENGINE && (!UE_BUILD_SHIPPING || WITH_EDITOR))
 
struct FRDGAsyncTask {};
 
enum class ERDGBuilderFlags
{
    None = 0,
 
    ParallelSetup = 1 << 0,
    
    ParallelCompile = 1 << 1,
 
    ParallelExecute = 1 << 2,
 
    Parallel = ParallelSetup | ParallelCompile | ParallelExecute,
 
    AllowParallelExecute UE_DEPRECATED(5.5, "Use ERDDGBuilderFlags::Parallel instead.") = Parallel,
};
ENUM_CLASS_FLAGS(ERDGBuilderFlags);
 
enum class ERDGPassFlags : uint16
{
    None = 0,
 
    Raster = 1 << 0,
 
    Compute = 1 << 1,
 
    AsyncCompute = 1 << 2,
 
    Copy = 1 << 3,
 
    NeverCull = 1 << 4,
 
    SkipRenderPass = 1 << 5,
 
    NeverMerge = 1 << 6,
 
    NeverParallel = 1 << 7,
 
    Readback = Copy | NeverCull
};
ENUM_CLASS_FLAGS(ERDGPassFlags);
 
enum class ERDGBufferFlags : uint8
{
    None = 0,
 
    MultiFrame = 1 << 0,
 
    SkipTracking = 1 << 1,
 
    ForceImmediateFirstBarrier = 1 << 2,
};
ENUM_CLASS_FLAGS(ERDGBufferFlags);
 
enum class ERDGTextureFlags : uint8
{
    None = 0,
 
    MultiFrame = 1 << 0,
 
    SkipTracking = 1 << 1,
    
    ForceImmediateFirstBarrier = 1 << 2,
 
    MaintainCompression = 1 << 3,
};
ENUM_CLASS_FLAGS(ERDGTextureFlags);
 
enum class ERDGSetupTaskWaitPoint : uint8
{
    Compile = 0,
 
    Execute = 1,
 
    MAX
};
 
enum class ERDGUnorderedAccessViewFlags : uint8
{
    None = 0,
 
    // The view will not perform UAV barriers between consecutive usage.
    SkipBarrier = 1 << 0
};
ENUM_CLASS_FLAGS(ERDGUnorderedAccessViewFlags);
 
enum class ERDGViewableResourceType : uint8
{
    Texture,
    Buffer,
    MAX
};
 
enum class ERDGViewType : uint8
{
    TextureUAV,
    TextureSRV,
    BufferUAV,
    BufferSRV,
    MAX
};
 
inline ERDGViewableResourceType GetParentType(ERDGViewType ViewType)
{
    switch (ViewType)
    {
    case ERDGViewType::TextureUAV:
    case ERDGViewType::TextureSRV:
        return ERDGViewableResourceType::Texture;
    case ERDGViewType::BufferUAV:
    case ERDGViewType::BufferSRV:
        return ERDGViewableResourceType::Buffer;
    }
    checkNoEntry();
    return ERDGViewableResourceType::MAX;
}
 
enum class ERDGResourceExtractionFlags : uint8
{
    None = 0,
 
    // Allows the resource to remain transient. Only use this flag if you intend to register the resource back
    // into the graph and release the reference. This should not be used if the resource is cached for a long
    // period of time.
    AllowTransient = 1,
};
ENUM_CLASS_FLAGS(ERDGResourceExtractionFlags);
 
enum class ERDGInitialDataFlags : uint8
{
    None = 0,
 
     NoCopy = 1 << 0
};
ENUM_CLASS_FLAGS(ERDGInitialDataFlags)
 
enum class ERDGPooledBufferAlignment : uint8
{
    // The buffer size is not aligned.
    None,
 
    // The buffer size is aligned up to the next page size.
    Page,
 
    // The buffer size is aligned up to the next power of two.
    PowerOfTwo
};
 
inline ERDGViewableResourceType GetViewableResourceType(ERDGViewType ViewType)
{
    switch (ViewType)
    {
    case ERDGViewType::TextureUAV:
    case ERDGViewType::TextureSRV:
        return ERDGViewableResourceType::Texture;
    case ERDGViewType::BufferUAV:
    case ERDGViewType::BufferSRV:
        return ERDGViewableResourceType::Buffer;
    default:
        checkNoEntry();
        return ERDGViewableResourceType::MAX;
    }
}
 
using ERDGTextureMetaDataAccess = ERHITextureMetaDataAccess;
 
inline int32 GetResourceTransitionPlaneForMetadataAccess(ERDGTextureMetaDataAccess Metadata)
{
    switch (Metadata)
    {
    case ERDGTextureMetaDataAccess::CompressedSurface:
    case ERDGTextureMetaDataAccess::HTile:
    case ERDGTextureMetaDataAccess::Depth:
        return FRHITransitionInfo::kDepthPlaneSlice;
    case ERDGTextureMetaDataAccess::Stencil:
        return FRHITransitionInfo::kStencilPlaneSlice;
    default:
        return 0;
    }
}
 
// Disable false positive buffer overrun warning during pgo linking step
PGO_LINK_DISABLE_WARNINGS
template <typename LocalObjectType, typename LocalIndexType>
class TRDGHandle
{
public:
    using ObjectType = LocalObjectType;
    using IndexType = LocalIndexType;
 
    static const TRDGHandle Null;
 
    TRDGHandle() = default;
 
    explicit inline TRDGHandle(uint32 InIndex)
    {
        check(InIndex >= 0 && InIndex <= kNullIndex);
        Index = (IndexType)InIndex;
    }
 
    inline IndexType GetIndex() const { check(IsValid()); return Index; }
    inline IndexType GetIndexUnchecked() const { return Index; }
    inline bool IsNull()  const { return Index == kNullIndex; }
    inline bool IsValid() const { return Index != kNullIndex; }
    inline bool operator==(TRDGHandle Other) const { return Index == Other.Index; }
    inline bool operator!=(TRDGHandle Other) const { return Index != Other.Index; }
    inline bool operator<=(TRDGHandle Other) const { check(IsValid() && Other.IsValid()); return Index <= Other.Index; }
    inline bool operator>=(TRDGHandle Other) const { check(IsValid() && Other.IsValid()); return Index >= Other.Index; }
    inline bool operator< (TRDGHandle Other) const { check(IsValid() && Other.IsValid()); return Index <  Other.Index; }
    inline bool operator> (TRDGHandle Other) const { check(IsValid() && Other.IsValid()); return Index >  Other.Index; }
 
    inline TRDGHandle& operator+=(int32 Increment)
    {
        check(int64(Index + Increment) <= int64(kNullIndex));
        Index += (IndexType)Increment;
        return *this;
    }
 
    inline TRDGHandle& operator-=(int32 Decrement)
    {
        check(int64(Index - Decrement) > 0);
        Index -= (IndexType)Decrement;
        return *this;
    }
 
    inline TRDGHandle operator-(int32 Subtract) const
    {
        TRDGHandle Handle = *this;
        Handle -= Subtract;
        return Handle;
    }
 
    inline TRDGHandle operator+(int32 Add) const
    {
        TRDGHandle Handle = *this;
        Handle += Add;
        return Handle;
    }
 
    inline TRDGHandle& operator++()
    {
        check(IsValid());
        ++Index;
        return *this;
    }
 
    inline TRDGHandle& operator--()
    {
        check(IsValid());
        --Index;
        return *this;
    }
 
    // Returns the min of two pass handles. Returns null if both are null; returns the valid handle if one is null.
    inline static TRDGHandle Min(TRDGHandle A, TRDGHandle B)
    {
        // If either index is null is will fail the comparison.
        return A.Index < B.Index ? A : B;
    }
 
    // Returns the max of two pass handles. Returns null if both are null; returns the valid handle if one is null.
    inline static TRDGHandle Max(TRDGHandle A, TRDGHandle B)
    {
        // If either index is null, it will wrap around to 0 and fail the comparison.
        return (IndexType)(A.Index + 1) > (IndexType)(B.Index + 1) ? A : B;
    }
 
private:
    static const IndexType kNullIndex = TNumericLimits<IndexType>::Max();
    IndexType Index = kNullIndex;
 
    friend inline uint32 GetTypeHash(TRDGHandle Handle)
    {
        return Handle.GetIndex();
    }
};
PGO_LINK_ENABLE_WARNINGS
 
enum class ERDGHandleRegistryDestructPolicy
{
    Registry,
    Allocator,
    Never
};
 
template <typename LocalHandleType, ERDGHandleRegistryDestructPolicy DestructPolicy = ERDGHandleRegistryDestructPolicy::Registry>
class TRDGHandleRegistry
{
public:
    using HandleType = LocalHandleType;
    using ObjectType = typename HandleType::ObjectType;
    using IndexType = typename HandleType::IndexType;
 
    TRDGHandleRegistry() = default;
    TRDGHandleRegistry(const TRDGHandleRegistry&) = delete;
    TRDGHandleRegistry(TRDGHandleRegistry&&) = default;
    TRDGHandleRegistry& operator=(TRDGHandleRegistry&&) = default;
    TRDGHandleRegistry& operator=(const TRDGHandleRegistry&) = delete;
 
    ~TRDGHandleRegistry()
    {
        Clear();
    }
 
    void Insert(ObjectType* Object)
    {
        Array.Emplace(Object);
        Object->Handle = Last();
    }
 
    template<typename DerivedType = ObjectType, class ...TArgs>
    DerivedType* Allocate(FRDGAllocator& Allocator, TArgs&&... Args)
    {
        static_assert(TIsDerivedFrom<DerivedType, ObjectType>::Value, "You must specify a type that derives from ObjectType");
        DerivedType* Object;
        if (DestructPolicy == ERDGHandleRegistryDestructPolicy::Allocator)
        {
            Object = Allocator.Alloc<DerivedType>(Forward<TArgs>(Args)...);
        }
        else
        {
            Object = Allocator.AllocNoDestruct<DerivedType>(Forward<TArgs>(Args)...);
        }
        Insert(Object);
        return Object;
    }
 
    void Clear()
    {
        if (DestructPolicy == ERDGHandleRegistryDestructPolicy::Registry)
        {
            for (int32 Index = Array.Num() - 1; Index >= 0; --Index)
            {
                Array[Index]->~ObjectType();
            }
        }
        Array.Empty();
    }
 
    template <typename FunctionType>
    void Enumerate(FunctionType Function)
    {
        for (ObjectType* Object : Array)
        {
            Function(Object);
        }
    }
 
    template <typename FunctionType>
    void Enumerate(FunctionType Function) const
    {
        for (const ObjectType* Object : Array)
        {
            Function(Object);
        }
    }
 
    inline const ObjectType* Get(HandleType Handle) const
    {
        return Array[Handle.GetIndex()];
    }
 
    inline ObjectType* Get(HandleType Handle)
    {
        return Array[Handle.GetIndex()];
    }
 
    inline const ObjectType* operator[] (HandleType Handle) const
    {
        return Get(Handle);
    }
 
    inline ObjectType* operator[] (HandleType Handle)
    {
        return Get(Handle);
    }
 
    inline HandleType Begin() const
    {
        return HandleType(0);
    }
 
    inline HandleType End() const
    {
        return HandleType(Array.Num());
    }
 
    inline HandleType Last() const
    {
        return HandleType(Array.Num() - 1);
    }
 
    inline int32 Num() const
    {
        return Array.Num();
    }
 
private:
    TArray<ObjectType*, FRDGArrayAllocator> Array;
};
 
template <typename HandleType>
class TRDGHandleBitArray : public TBitArray<FRDGBitArrayAllocator>
{
    using Base = TBitArray<FRDGBitArrayAllocator>;
public:
    using Base::Base;
 
    inline FBitReference operator[](HandleType Handle)
    {
        return Base::operator[](Handle.GetIndex());
    }
 
    inline const FConstBitReference operator[](HandleType Handle) const
    {
        return Base::operator[](Handle.GetIndex());
    }
};
 
template <typename HandleType>
class TRDGHandleUniqueFilter
{
public:
    TRDGHandleUniqueFilter() = default;
 
    TRDGHandleUniqueFilter(HandleType InHandle)
    {
        AddHandle(InHandle);
    }
 
    void Reset()
    {
        Handle = HandleType::Null;
    }
 
    void AddHandle(HandleType InHandle)
    {
        checkf(InHandle != NotUniqueHandle, TEXT("Overflowed TRDGHandleUniqueFilter"));
 
        if (Handle != InHandle && InHandle.IsValid())
        {
            Handle = Handle.IsNull() ? InHandle : NotUniqueHandle;
        }
    }
 
    HandleType GetUniqueHandle() const
    {
        return Handle != NotUniqueHandle ? Handle : HandleType::Null;
    }
 
private:
    static const HandleType NotUniqueHandle;
    HandleType Handle;
};
 
template <typename ObjectType, typename IndexType>
const TRDGHandle<ObjectType, IndexType> TRDGHandle<ObjectType, IndexType>::Null;
 
template <typename HandleType>
const HandleType TRDGHandleUniqueFilter<HandleType>::NotUniqueHandle(TNumericLimits<typename HandleType::IndexType>::Max() - 1);
 
struct FRDGTextureDesc : public FRHITextureDesc
{
    static FRDGTextureDesc Create2D(
        FIntPoint           Size
        , EPixelFormat        Format
        , FClearValueBinding  ClearValue
        , ETextureCreateFlags Flags
        , uint8               NumMips = 1
        , uint8               NumSamples = 1
        , uint32              ExtData = 0
    )
    {
        const uint16 Depth = 1;
        const uint16 ArraySize = 1;
        return FRDGTextureDesc(ETextureDimension::Texture2D, Flags, Format, ClearValue, { Size.X, Size.Y }, Depth, ArraySize, NumMips, NumSamples, ExtData);
    }
 
    static FRDGTextureDesc Create2DArray(
        FIntPoint           Size
        , EPixelFormat        Format
        , FClearValueBinding  ClearValue
        , ETextureCreateFlags Flags
        , uint16              ArraySize
        , uint8               NumMips = 1
        , uint8               NumSamples = 1
        , uint32              ExtData = 0
    )
    {
        const uint16 Depth = 1;
        return FRDGTextureDesc(ETextureDimension::Texture2DArray, Flags, Format, ClearValue, { Size.X, Size.Y }, Depth, ArraySize, NumMips, NumSamples, ExtData);
    }
 
    static FRDGTextureDesc Create3D(
        FIntVector          Size
        , EPixelFormat        Format
        , FClearValueBinding  ClearValue
        , ETextureCreateFlags Flags
        , uint8               NumMips = 1
        , uint32              ExtData = 0
    )
    {
        const uint16 ArraySize = 1;
        const uint8 LocalNumSamples = 1;
 
        checkf(Size.Z <= TNumericLimits<decltype(FRDGTextureDesc::Depth)>::Max(), TEXT("Depth parameter (Size.Z) exceeds valid range"));
 
        return FRDGTextureDesc(ETextureDimension::Texture3D, Flags, Format, ClearValue, { Size.X, Size.Y }, (uint16)Size.Z, ArraySize, NumMips, LocalNumSamples, ExtData);
    }
 
    static FRDGTextureDesc CreateCube(
        uint32              Size
        , EPixelFormat        Format
        , FClearValueBinding  ClearValue
        , ETextureCreateFlags Flags
        , uint8               NumMips = 1
        , uint8               NumSamples = 1
        , uint32              ExtData = 0
    )
    {
        checkf(Size <= (uint32)TNumericLimits<int32>::Max(), TEXT("Size parameter exceeds valid range"));
 
        const uint16 Depth = 1;
        const uint16 ArraySize = 1;
        return FRDGTextureDesc(ETextureDimension::TextureCube, Flags, Format, ClearValue, { (int32)Size, (int32)Size }, Depth, ArraySize, NumMips, NumSamples, ExtData);
    }
 
    static FRDGTextureDesc CreateCubeArray(
        uint32              Size
        , EPixelFormat        Format
        , FClearValueBinding  ClearValue
        , ETextureCreateFlags Flags
        , uint16              ArraySize
        , uint8               NumMips = 1
        , uint8               NumSamples = 1
        , uint32              ExtData = 0
    )
    {
        checkf(Size <= (uint32)TNumericLimits<int32>::Max(), TEXT("Size parameter exceeds valid range"));
 
        const uint16 Depth = 1;
        return FRDGTextureDesc(ETextureDimension::TextureCubeArray, Flags, Format, ClearValue, { (int32)Size, (int32)Size }, Depth, ArraySize, NumMips, NumSamples, ExtData);
    }
 
    static FRDGTextureDesc CreateRenderTargetTextureDesc(
        FIntPoint Size, EPixelFormat Format
        , FClearValueBinding ClearValue
        , ETextureCreateFlags Flags
        , const bool bRequireMultiView
        , uint16 MobileMultiViewRenderTargetNumLayers = 2)
    {
        if (bRequireMultiView)
        {
            return FRDGTextureDesc::Create2DArray(Size, Format, ClearValue, Flags, MobileMultiViewRenderTargetNumLayers);
        }
 
        return FRDGTextureDesc::Create2D(Size, Format, ClearValue, Flags);
    }
 
    FRDGTextureDesc() = default;
    FRDGTextureDesc(
        ETextureDimension   InDimension
        , ETextureCreateFlags InFlags
        , EPixelFormat        InFormat
        , FClearValueBinding  InClearValue
        , FIntPoint           InExtent
        , uint16              InDepth
        , uint16              InArraySize
        , uint8               InNumMips
        , uint8               InNumSamples
        , uint32              InExtData
    )
        : FRHITextureDesc(InDimension, InFlags, InFormat, InClearValue, InExtent, InDepth, InArraySize, InNumMips, InNumSamples, InExtData)
    {
    }
};
 
class FRDGBlackboard;
 
class FRDGAsyncComputeBudgetScopeGuard;
class FRDGScopedCsvStatExclusive;
class FRDGScopedCsvStatExclusiveConditional;
 
class FRDGBarrierBatch;
class FRDGBarrierBatchBegin;
class FRDGBarrierBatchEnd;
class FRDGBarrierValidation;
class FRDGEventName;
class FRDGUserValidation;
 
class FRDGViewableResource;
 
using FRDGPassHandle = TRDGHandle<FRDGPass, uint32>;
using FRDGPassRegistry = TRDGHandleRegistry<FRDGPassHandle>;
using FRDGPassHandleArray = TArray<FRDGPassHandle, TInlineAllocator<4, FRDGArrayAllocator>>;
using FRDGPassBitArray = TRDGHandleBitArray<FRDGPassHandle>;
 
using FRDGUniformBufferHandle = TRDGHandle<FRDGUniformBuffer, uint32>;
using FRDGUniformBufferRegistry = TRDGHandleRegistry<FRDGUniformBufferHandle>;
using FRDGUniformBufferBitArray = TRDGHandleBitArray<FRDGUniformBufferHandle>;
 
using FRDGViewHandle = TRDGHandle<FRDGView, uint32>;
using FRDGViewRegistry = TRDGHandleRegistry<FRDGViewHandle, ERDGHandleRegistryDestructPolicy::Never>;
using FRDGViewUniqueFilter = TRDGHandleUniqueFilter<FRDGViewHandle>;
using FRDGViewBitArray = TRDGHandleBitArray<FRDGViewHandle>;
 
using FRDGTextureHandle = TRDGHandle<FRDGTexture, uint32>;
using FRDGTextureRegistry = TRDGHandleRegistry<FRDGTextureHandle, ERDGHandleRegistryDestructPolicy::Never>;
using FRDGTextureBitArray = TRDGHandleBitArray<FRDGTextureHandle>;
 
using FRDGBufferHandle = TRDGHandle<FRDGBuffer, uint32>;
using FRDGBufferReservedCommitHandle = TRDGHandle<FRDGBuffer, uint16>;
using FRDGBufferRegistry = TRDGHandleRegistry<FRDGBufferHandle, ERDGHandleRegistryDestructPolicy::Never>;
using FRDGBufferBitArray = TRDGHandleBitArray<FRDGBufferHandle>;
 
class FRDGBufferPool;
class FRDGTransientRenderTarget;
 
using FRDGPassHandlesByPipeline = TRHIPipelineArray<FRDGPassHandle>;
using FRDGPassesByPipeline = TRHIPipelineArray<FRDGPass*>;
 
class FRDGTrace;
class FRDGResourceDumpContext;
 
using FRDGBufferNumElementsCallback = TFunction<uint32()>;
using FRDGBufferInitialDataCallback = TFunction<const void*()>;
using FRDGBufferInitialDataSizeCallback = TFunction<uint64()>;
template <typename ArrayType, 
    typename ArrayTypeNoRef = std::remove_reference_t<ArrayType>,
    typename = typename TEnableIf<TIsTArray_V<ArrayTypeNoRef>>::Type> using TRDGBufferArrayCallback = TFunction<const ArrayType&()>;
using FRDGBufferInitialDataFreeCallback = TFunction<void(const void* InData)>;
using FRDGBufferInitialDataFillCallback = TFunction<void(void* InData, uint32 InDataSize)>;
using FRDGDispatchGroupCountCallback = TFunction<FIntVector()>;