UDocumentation UE5.7 10.02.2026 (Source)
API documentation for Unreal Engine 5.7
ShadowSetup.cpp File Reference

Classes

struct  FBoxEdge
 
struct  FDrawDebugShadowFrustumOp
 
struct  FFilteredShadowArrays
 
class  FShadowMeshCollector
 
struct  FDynamicShadowsTaskData
 
struct  FAddSubjectPrimitiveOverflowedIndices
 
struct  FFinalizeAddSubjectPrimitiveContext
 
struct  FAddSubjectPrimitiveResult
 
struct  FAddSubjectPrimitiveOp
 
struct  FAddSubjectPrimitiveStats
 
struct  FComparePreshadows
 
struct  FGatherShadowPrimitivesPacket
 
struct  FGatherShadowPrimitivesPrepareTask
 
struct  FLayoutAndAssignedShadows
 
class  RenderTargetNameSet
 

Typedefs

typedef TArray< FVector, TInlineAllocator< 8 > > FBoundingBoxVertexArray
 
typedef TArray< FBoxEdge, TInlineAllocator< 12 > > FBoundingBoxEdgeArray
 
typedef TArray< FAddSubjectPrimitiveOpFShadowSubjectPrimitives
 
typedef TArray< FAddSubjectPrimitiveStatsFPerShadowGatherStats
 
using FProjectedShadowInfoList = TArray< FProjectedShadowInfo *, SceneRenderingAllocator >
 
typedef TArray< FConvexVolume, TInlineAllocator< 8 > > FLightViewFrustumConvexHulls
 

Functions

FAutoConsoleVariableRef CVarCacheWholeSceneShadows (TEXT("r.Shadow.CacheWholeSceneShadows"), GCacheWholeSceneShadows, TEXT("When enabled, movable point and spot light whole scene shadow depths from static primitives will be cached as an optimization."), ECVF_Scalability|ECVF_RenderThreadSafe)
 
FAutoConsoleVariableRef CVarMaxNumPointShadowCacheUpdatePerFrame (TEXT("r.Shadow.MaxNumPointShadowCacheUpdatesPerFrame"), GMaxNumPointShadowCacheUpdatesPerFrame, TEXT("Maximum number of point light shadow cache updates allowed per frame." "Only affect updates caused by resolution change. -1 means no limit."), ECVF_Scalability|ECVF_RenderThreadSafe)
 
FAutoConsoleVariableRef CVarMaxNumSpotShadowCacheUpdatePerFrame (TEXT("r.Shadow.MaxNumSpotShadowCacheUpdatesPerFrame"), GMaxNumSpotShadowCacheUpdatesPerFrame, TEXT("Maximum number of spot light shadow cache updates allowed per frame." "Only affect updates caused by resolution change. -1 means no limit."), ECVF_Scalability|ECVF_RenderThreadSafe)
 
FAutoConsoleVariableRef CVarWholeSceneShadowCacheMb (TEXT("r.Shadow.WholeSceneShadowCacheMb"), GWholeSceneShadowCacheMb, TEXT("Amount of memory that can be spent caching whole scene shadows. ShadowMap allocations in a single frame can cause this to be exceeded."), ECVF_Scalability|ECVF_RenderThreadSafe)
 
FAutoConsoleVariableRef CVarCachedWholeSceneShadowsCastFromMovablePrimitives (TEXT("r.Shadow.CachedShadowsCastFromMovablePrimitives"), GCachedShadowsCastFromMovablePrimitives, TEXT("Disabling this can be used to remove the copy of the cached shadowmap."), ECVF_Scalability|ECVF_RenderThreadSafe)
 
FAutoConsoleVariableRef CVarSkipCullingNaniteMeshes (TEXT("r.Shadow.SkipCullingNaniteMeshes"), GSkipCullingNaniteMeshes, TEXT("When enabled, CPU culling will ignore nanite meshes."), ECVF_Scalability|ECVF_RenderThreadSafe)
 
bool ShouldUseCachePreshadows ()
 
FAutoConsoleVariableRef CVarPreshadowsForceLowestLOD (TEXT("r.Shadow.PreshadowsForceLowestDetailLevel"), GPreshadowsForceLowestLOD, TEXT("When enabled, static meshes render their lowest detail level into preshadow depth maps. Disabled by default as it causes artifacts with poor quality LODs (tree billboard)."), ECVF_Scalability|ECVF_RenderThreadSafe)
 
uint32 GetNumShadowDynamicMeshElementTasks ()
 
FAutoConsoleVariableRef CVarUseOctreeForShadowCulling (TEXT("r.Shadow.UseOctreeForCulling"), GUseOctreeForShadowCulling, TEXT("Whether to use the primitive octree for shadow subject culling. The octree culls large groups of primitives at a time, but introduces cache misses walking the data structure."), ECVF_Scalability|ECVF_RenderThreadSafe)
 
 CSV_DECLARE_CATEGORY_EXTERN (LightCount)
 
void DumpShadowDumpSetup ()
 
template<typename CacheLambdaType , typename UnCacheLambdaType >
void TryToCacheShadowMap (const FScene *Scene, int64 CachedShadowMapsSize, int32 &OutNumShadowMaps, EShadowDepthCacheMode *OutCacheModes, uint32 &NumCachesUpdatedThisFrame, CacheLambdaType &&CacheLambda, UnCacheLambdaType &&UnCacheLambda)
 
float CalculateShadowFadeAlpha (const float MaxUnclampedResolution, const uint32 ShadowFadeResolution, const uint32 MinShadowResolution)
 
int32 GetMaxShadowResolution (ERHIFeatureLevel::Type FeatureLevel)
 
bool AreAnyViewsStaticSceneOnly (TArrayView< FViewInfo > Views)
 
UE::Tasks::FTask GetGatherAndSortLightsPrerequisiteTask (const FDynamicShadowsTaskData *TaskData)
 
void BeginShadowGatherDynamicMeshElements (FDynamicShadowsTaskData *TaskData)
 
TConstArrayView< FProjectedShadowInfo * > GetProjectedDistanceFieldShadows (const FDynamicShadowsTaskData *TaskData)
 
bool ShouldCreateObjectShadowForStationaryLight (const FLightSceneInfo *LightSceneInfo, const FPrimitiveSceneProxy *PrimitiveSceneProxy, bool bInteractionShadowMapped)
 
void ComputeWholeSceneShadowCacheModes (const FLightSceneInfo *LightSceneInfo, bool bCubeShadowMap, float RealTime, float ActualDesiredResolution, const FIntPoint &MaxShadowResolution, FScene *Scene, bool bNeedsVirtualShadowMap, FWholeSceneProjectedShadowInitializer &InOutProjectedShadowInitializer, const int64 CachedShadowMapsSize, FIntPoint &InOutShadowMapSize, uint32 &InOutNumPointShadowCachesUpdatedThisFrame, uint32 &InOutNumSpotShadowCachesUpdatedThisFrame, int32 &OutNumShadowMaps, EShadowDepthCacheMode *OutCacheModes)
 
void ComputeViewDependentWholeSceneShadowCacheModes (const FLightSceneInfo *LightSceneInfo, float RealTime, FScene *Scene, const FWholeSceneProjectedShadowInitializer &ProjectedShadowInitializer, const int64 CachedShadowMapsSize, const FIntPoint &ShadowMapSize, uint32 &InOutNumCSMCachesUpdatedThisFrame, int32 &OutNumShadowMaps, EShadowDepthCacheMode *OutCacheModes)
 
void BuildLightViewFrustumConvexHull (const FVector &LightOrigin, const FConvexVolume &Frustum, FConvexVolume &ConvexHull)
 
void BuildLightViewFrustumConvexHulls (const FVector &LightOrigin, const TArray< FViewInfo > &Views, FLightViewFrustumConvexHulls &ConvexHulls)
 
bool IntersectsConvexHulls (FLightViewFrustumConvexHulls const &ConvexHulls, FBoxSphereBounds const &Bounds)
 
TCHAR *const GetTranslucencyShadowTransmissionName (uint32 Id)
 

Variables

float GMinScreenRadiusForShadowCaster = 0.01f
 
int GEnableNonNaniteVSM
 
int32 GCacheWholeSceneShadows = 1
 
int32 GMaxNumPointShadowCacheUpdatesPerFrame = -1
 
int32 GMaxNumSpotShadowCacheUpdatesPerFrame = -1
 
int32 GWholeSceneShadowCacheMb = 150
 
int32 GCachedShadowsCastFromMovablePrimitives = 1
 
int32 GSkipCullingNaniteMeshes = 1
 
int32 GPreshadowsForceLowestLOD = 0
 
int32 GParallelInitDynamicShadows = 1
 
int32 GNumShadowDynamicMeshElementTasks = 4
 
int32 GUseOctreeForShadowCulling = 1
 
TAutoConsoleVariable< int32CVarVsmUseFarShadowRules (TEXT("r.Shadow.Virtual.UseFarShadowCulling"), 1, TEXT("Switch between implementing the far shadow culling logic for VSMs."), ECVF_RenderThreadSafe)
 
bool GDumpShadowSetup = false
 
FAutoConsoleCommand CmdDumpShadowDumpSetup (TEXT("r.DumpShadows"), TEXT("Dump shadow setup (for developer only, only for non shiping build)"), FConsoleCommandDelegate::CreateStatic(DumpShadowDumpSetup))
 
FAutoConsoleVariableRef CVarComputeShadowFadeUsingResolutionScale (TEXT("r.Shadow.DoesFadeUseResolutionScale"), GDoesShadowFadeUseResolutionScale, TEXT("When enabled (default), the shadow resolution scale for the individual light feeds into the fade out calculation, increasing the control of shadow fade out.\n" " Setting the cvar to 0 restores the behavior to pre UE 5.6."), ECVF_RenderThreadSafe)
 
FAutoConsoleTaskPriority CPrio_GatherShadowPrimitives (TEXT("TaskGraph.TaskPriorities.GatherShadowPrimitives"), TEXT("Task and thread priority for GatherShadowPrimitives tasks."), ENamedThreads::HighThreadPriority, ENamedThreads::NormalTaskPriority, ENamedThreads::HighTaskPriority)
 

Typedef Documentation

◆ FBoundingBoxEdgeArray

◆ FBoundingBoxVertexArray

◆ FLightViewFrustumConvexHulls

◆ FPerShadowGatherStats

◆ FProjectedShadowInfoList

◆ FShadowSubjectPrimitives

Function Documentation

◆ AreAnyViewsStaticSceneOnly()

bool AreAnyViewsStaticSceneOnly ( TArrayView< FViewInfo Views)
inline

◆ BeginShadowGatherDynamicMeshElements()

void BeginShadowGatherDynamicMeshElements ( FDynamicShadowsTaskData TaskData)

Triggers shadow gather dynamic mesh elements task graph to start processing.

◆ BuildLightViewFrustumConvexHull()

void BuildLightViewFrustumConvexHull ( const FVector LightOrigin,
const FConvexVolume Frustum,
FConvexVolume ConvexHull 
)

◆ BuildLightViewFrustumConvexHulls()

void BuildLightViewFrustumConvexHulls ( const FVector LightOrigin,
const TArray< FViewInfo > &  Views,
FLightViewFrustumConvexHulls ConvexHulls 
)

◆ CalculateShadowFadeAlpha()

float CalculateShadowFadeAlpha ( const float  MaxUnclampedResolution,
const uint32  ShadowFadeResolution,
const uint32  MinShadowResolution 
)

Helper function to determine fade alpha value for shadows based on resolution. In the below ASCII art (1) is the MinShadowResolution and (2) is the ShadowFadeResolution. Alpha will be 0 below the min resolution and 1 above the fade resolution. In between it is going to be an exponential curve with the values between (1) and (2) being normalized in the 0..1 range.

| /----— | / |/ 1--—2----—

Parameters
MaxUnclampedResolutionRequested resolution, unclamped so it can be below min
ShadowFadeResolutionResolution at which fade begins
MinShadowResolutionMinimum resolution of shadow
Returns
fade value between 0 and 1

◆ ComputeViewDependentWholeSceneShadowCacheModes()

void ComputeViewDependentWholeSceneShadowCacheModes ( const FLightSceneInfo LightSceneInfo,
float  RealTime,
FScene Scene,
const FWholeSceneProjectedShadowInitializer ProjectedShadowInitializer,
const int64  CachedShadowMapsSize,
const FIntPoint ShadowMapSize,
uint32 InOutNumCSMCachesUpdatedThisFrame,
int32 OutNumShadowMaps,
EShadowDepthCacheMode OutCacheModes 
)

◆ ComputeWholeSceneShadowCacheModes()

void ComputeWholeSceneShadowCacheModes ( const FLightSceneInfo LightSceneInfo,
bool  bCubeShadowMap,
float  RealTime,
float  ActualDesiredResolution,
const FIntPoint MaxShadowResolution,
FScene Scene,
bool  bNeedsVirtualShadowMap,
FWholeSceneProjectedShadowInitializer InOutProjectedShadowInitializer,
const int64  CachedShadowMapsSize,
FIntPoint InOutShadowMapSize,
uint32 InOutNumPointShadowCachesUpdatedThisFrame,
uint32 InOutNumSpotShadowCachesUpdatedThisFrame,
int32 OutNumShadowMaps,
EShadowDepthCacheMode OutCacheModes 
)

◆ CSV_DECLARE_CATEGORY_EXTERN()

CSV_DECLARE_CATEGORY_EXTERN ( LightCount  )

◆ CVarCachedWholeSceneShadowsCastFromMovablePrimitives()

FAutoConsoleVariableRef CVarCachedWholeSceneShadowsCastFromMovablePrimitives ( TEXT("r.Shadow.CachedShadowsCastFromMovablePrimitives")  ,
GCachedShadowsCastFromMovablePrimitives  ,
TEXT("Disabling this can be used to remove the copy of the cached shadowmap." ,
ECVF_Scalability ECVF_RenderThreadSafe 
)

◆ CVarCacheWholeSceneShadows()

FAutoConsoleVariableRef CVarCacheWholeSceneShadows ( TEXT("r.Shadow.CacheWholeSceneShadows")  ,
GCacheWholeSceneShadows  ,
TEXT("When enabled, movable point and spot light whole scene shadow depths from static primitives will be cached as an optimization." ,
ECVF_Scalability ECVF_RenderThreadSafe 
)

◆ CVarMaxNumPointShadowCacheUpdatePerFrame()

FAutoConsoleVariableRef CVarMaxNumPointShadowCacheUpdatePerFrame ( TEXT("r.Shadow.MaxNumPointShadowCacheUpdatesPerFrame")  ,
GMaxNumPointShadowCacheUpdatesPerFrame  ,
TEXT("Maximum number of point light shadow cache updates allowed per frame." "Only affect updates caused by resolution change. -1 means no limit." ,
ECVF_Scalability ECVF_RenderThreadSafe 
)

◆ CVarMaxNumSpotShadowCacheUpdatePerFrame()

FAutoConsoleVariableRef CVarMaxNumSpotShadowCacheUpdatePerFrame ( TEXT("r.Shadow.MaxNumSpotShadowCacheUpdatesPerFrame")  ,
GMaxNumSpotShadowCacheUpdatesPerFrame  ,
TEXT("Maximum number of spot light shadow cache updates allowed per frame." "Only affect updates caused by resolution change. -1 means no limit." ,
ECVF_Scalability ECVF_RenderThreadSafe 
)

◆ CVarPreshadowsForceLowestLOD()

FAutoConsoleVariableRef CVarPreshadowsForceLowestLOD ( TEXT("r.Shadow.PreshadowsForceLowestDetailLevel")  ,
GPreshadowsForceLowestLOD  ,
TEXT("When enabled, static meshes render their lowest detail level into preshadow depth maps. Disabled by default as it causes artifacts with poor quality LODs (tree billboard).")  ,
ECVF_Scalability ECVF_RenderThreadSafe 
)

◆ CVarSkipCullingNaniteMeshes()

FAutoConsoleVariableRef CVarSkipCullingNaniteMeshes ( TEXT("r.Shadow.SkipCullingNaniteMeshes")  ,
GSkipCullingNaniteMeshes  ,
TEXT("When enabled, CPU culling will ignore nanite meshes." ,
ECVF_Scalability ECVF_RenderThreadSafe 
)

◆ CVarUseOctreeForShadowCulling()

FAutoConsoleVariableRef CVarUseOctreeForShadowCulling ( TEXT("r.Shadow.UseOctreeForCulling")  ,
GUseOctreeForShadowCulling  ,
TEXT("Whether to use the primitive octree for shadow subject culling. The octree culls large groups of primitives at a time, but introduces cache misses walking the data structure." ,
ECVF_Scalability ECVF_RenderThreadSafe 
)

◆ CVarWholeSceneShadowCacheMb()

FAutoConsoleVariableRef CVarWholeSceneShadowCacheMb ( TEXT("r.Shadow.WholeSceneShadowCacheMb")  ,
GWholeSceneShadowCacheMb  ,
TEXT("Amount of memory that can be spent caching whole scene shadows. ShadowMap allocations in a single frame can cause this to be exceeded." ,
ECVF_Scalability ECVF_RenderThreadSafe 
)

◆ DumpShadowDumpSetup()

void DumpShadowDumpSetup ( )

◆ GetGatherAndSortLightsPrerequisiteTask()

UE::Tasks::FTask GetGatherAndSortLightsPrerequisiteTask ( const FDynamicShadowsTaskData TaskData)

◆ GetMaxShadowResolution()

int32 GetMaxShadowResolution ( ERHIFeatureLevel::Type  FeatureLevel)

◆ GetNumShadowDynamicMeshElementTasks()

uint32 GetNumShadowDynamicMeshElementTasks ( )

◆ GetProjectedDistanceFieldShadows()

TConstArrayView< FProjectedShadowInfo * > GetProjectedDistanceFieldShadows ( const FDynamicShadowsTaskData TaskData)

Returns the array of shadows with distance fields. Call only after finishing shadow initialization.

◆ GetTranslucencyShadowTransmissionName()

TCHAR *const GetTranslucencyShadowTransmissionName ( uint32  Id)

◆ IntersectsConvexHulls()

bool IntersectsConvexHulls ( FLightViewFrustumConvexHulls const &  ConvexHulls,
FBoxSphereBounds const &  Bounds 
)

◆ ShouldCreateObjectShadowForStationaryLight()

bool ShouldCreateObjectShadowForStationaryLight ( const FLightSceneInfo LightSceneInfo,
const FPrimitiveSceneProxy PrimitiveSceneProxy,
bool  bInteractionShadowMapped 
)

◆ ShouldUseCachePreshadows()

bool ShouldUseCachePreshadows ( )

◆ TryToCacheShadowMap()

void TryToCacheShadowMap ( const FScene Scene,
int64  CachedShadowMapsSize,
int32 OutNumShadowMaps,
EShadowDepthCacheMode OutCacheModes,
uint32 NumCachesUpdatedThisFrame,
CacheLambdaType &&  CacheLambda,
UnCacheLambdaType &&  UnCacheLambda 
)

Helper function to maintain the common login of caching the whole scene shadow and be able to handle the specific-purpose through the CacheLambda and UnCacheLambda

Variable Documentation

◆ CmdDumpShadowDumpSetup

FAutoConsoleCommand CmdDumpShadowDumpSetup(TEXT("r.DumpShadows"), TEXT("Dump shadow setup (for developer only, only for non shiping build)"), FConsoleCommandDelegate::CreateStatic(DumpShadowDumpSetup)) ( TEXT("r.DumpShadows")  ,
TEXT("Dump shadow setup (for developer only, only for non shiping build)")  ,
FConsoleCommandDelegate::CreateStatic(DumpShadowDumpSetup  
)

◆ CPrio_GatherShadowPrimitives

FAutoConsoleTaskPriority CPrio_GatherShadowPrimitives(TEXT("TaskGraph.TaskPriorities.GatherShadowPrimitives"), TEXT("Task and thread priority for GatherShadowPrimitives tasks."), ENamedThreads::HighThreadPriority, ENamedThreads::NormalTaskPriority, ENamedThreads::HighTaskPriority) ( TEXT("TaskGraph.TaskPriorities.GatherShadowPrimitives")  ,
TEXT("Task and thread priority for GatherShadowPrimitives tasks." ,
ENamedThreads::HighThreadPriority  ,
ENamedThreads::NormalTaskPriority  ,
ENamedThreads::HighTaskPriority   
)

◆ CVarComputeShadowFadeUsingResolutionScale

FAutoConsoleVariableRef CVarComputeShadowFadeUsingResolutionScale(TEXT("r.Shadow.DoesFadeUseResolutionScale"), GDoesShadowFadeUseResolutionScale, TEXT("When enabled (default), the shadow resolution scale for the individual light feeds into the fade out calculation, increasing the control of shadow fade out.\n" " Setting the cvar to 0 restores the behavior to pre UE 5.6."), ECVF_RenderThreadSafe) ( TEXT("r.Shadow.DoesFadeUseResolutionScale")  ,
GDoesShadowFadeUseResolutionScale  ,
TEXT("When enabled (default), the shadow resolution scale for the individual light feeds into the fade out calculation, increasing the control of shadow fade out.\n" " Setting the cvar to 0 restores the behavior to pre UE 5.6.")  ,
ECVF_RenderThreadSafe   
)

◆ CVarVsmUseFarShadowRules

TAutoConsoleVariable< int32 > CVarVsmUseFarShadowRules(TEXT("r.Shadow.Virtual.UseFarShadowCulling"), 1, TEXT("Switch between implementing the far shadow culling logic for VSMs."), ECVF_RenderThreadSafe) ( TEXT("r.Shadow.Virtual.UseFarShadowCulling")  ,
,
TEXT("Switch between implementing the far shadow culling logic for VSMs." ,
ECVF_RenderThreadSafe   
)

◆ GCachedShadowsCastFromMovablePrimitives

int32 GCachedShadowsCastFromMovablePrimitives = 1

◆ GCacheWholeSceneShadows

int32 GCacheWholeSceneShadows = 1

◆ GDumpShadowSetup

bool GDumpShadowSetup = false

◆ GEnableNonNaniteVSM

int GEnableNonNaniteVSM
extern

◆ GMaxNumPointShadowCacheUpdatesPerFrame

int32 GMaxNumPointShadowCacheUpdatesPerFrame = -1

◆ GMaxNumSpotShadowCacheUpdatesPerFrame

int32 GMaxNumSpotShadowCacheUpdatesPerFrame = -1

◆ GMinScreenRadiusForShadowCaster

float GMinScreenRadiusForShadowCaster = 0.01f

◆ GNumShadowDynamicMeshElementTasks

int32 GNumShadowDynamicMeshElementTasks = 4

◆ GParallelInitDynamicShadows

int32 GParallelInitDynamicShadows = 1

◆ GPreshadowsForceLowestLOD

int32 GPreshadowsForceLowestLOD = 0

◆ GSkipCullingNaniteMeshes

int32 GSkipCullingNaniteMeshes = 1

◆ GUseOctreeForShadowCulling

int32 GUseOctreeForShadowCulling = 1

◆ GWholeSceneShadowCacheMb

int32 GWholeSceneShadowCacheMb = 150