r.Shadow.Virtual.CoarsePagePixelThresholdStatic

r.Shadow.Virtual.CoarsePagePixelThresholdStatic

#Overview

name: r.Shadow.Virtual.CoarsePagePixelThresholdStatic

This variable is created as a Console Variable (cvar).

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.Virtual.CoarsePagePixelThresholdStatic is to control the culling of static (non-Nanite) instances in virtual shadow maps based on their estimated pixel footprint. This setting is part of Unreal Engine 5’s virtual shadow mapping system, which is a component of the rendering subsystem.

This setting variable is primarily used in the Renderer module, specifically within the virtual shadow map implementation. It’s referenced in the VirtualShadowMapArray.cpp file, which suggests it’s an integral part of the virtual shadow mapping system.

The value of this variable is set as a console variable with a default value of 1.0f. It can be adjusted at runtime through the console or project settings.

This variable interacts closely with other related variables such as CoarsePagePixelThresholdDynamic and CoarsePagePixelThresholdDynamicNanite. Together, these variables control the culling behavior for different types of objects (static, dynamic, and Nanite) in virtual shadow maps.

Developers should be aware that:

  1. Higher values of this variable will result in more aggressive culling of static instances from coarse shadow map pages.
  2. This threshold is typically set lower than the dynamic threshold because static pages have better caching.
  3. Adjusting this value can impact performance and shadow quality, especially for static objects in the scene.

Best practices when using this variable include:

  1. Carefully balance between performance and shadow quality when adjusting this value.
  2. Test the impact of changes across various scenes and lighting conditions.
  3. Consider the relationship between this variable and other shadow-related settings for optimal results.

Regarding the associated variable CVarCoarsePagePixelThresholdStatic:

This is the actual console variable object that stores and manages the r.Shadow.Virtual.CoarsePagePixelThresholdStatic setting. It’s defined using TAutoConsoleVariable, which allows it to be adjusted at runtime.

The purpose of CVarCoarsePagePixelThresholdStatic is to provide a programmatic interface to access and modify the r.Shadow.Virtual.CoarsePagePixelThresholdStatic setting within the engine’s C++ code.

This variable is used in the Renderer module, specifically in the VirtualShadowMapArray class. It’s accessed in the Initialize and BuildPageAllocations functions to set up the uniform parameters for virtual shadow mapping.

The value of this variable is typically set through the console or project settings, but it can also be modified programmatically if needed.

Developers should be aware that:

  1. Changes to this variable will take effect on the render thread, as indicated by the ECVF_RenderThreadSafe flag.
  2. The variable is marked with ECVF_Scalability, suggesting it’s part of the engine’s scalability system and may be automatically adjusted based on performance settings.

Best practices when using this variable include:

  1. Access the value using GetValueOnRenderThread() when in render thread context.
  2. Consider the performance implications when modifying this value, especially in performance-critical sections of code.
  3. Coordinate changes to this variable with other related shadow mapping parameters for consistent behavior.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.cpp:217

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarCoarsePagePixelThresholdStatic(
	TEXT("r.Shadow.Virtual.CoarsePagePixelThresholdStatic"),
	1.0f,
	TEXT("If a static (non-nanite) instance has a smaller estimated pixel footprint than this value, it should not be drawn into a coarse page. Higher values cull away more instances.\n")
	TEXT("This value is typically lower than the non-static one because the static pages have better caching."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

This variable is associated with another variable named CVarCoarsePagePixelThresholdStatic. They share the same value. See the following C++ source code.

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.cpp:216

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<float> CVarCoarsePagePixelThresholdStatic(
	TEXT("r.Shadow.Virtual.CoarsePagePixelThresholdStatic"),
	1.0f,
	TEXT("If a static (non-nanite) instance has a smaller estimated pixel footprint than this value, it should not be drawn into a coarse page. Higher values cull away more instances.\n")
	TEXT("This value is typically lower than the non-static one because the static pages have better caching."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.cpp:435

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::Initialize

Source code excerpt:

	UniformParameters.bExcludeNonNaniteFromCoarsePages = !CVarCoarsePagesIncludeNonNanite.GetValueOnRenderThread();
	UniformParameters.CoarsePagePixelThresholdDynamic = CVarCoarsePagePixelThresholdDynamic.GetValueOnRenderThread();
	UniformParameters.CoarsePagePixelThresholdStatic = CVarCoarsePagePixelThresholdStatic.GetValueOnRenderThread();
	UniformParameters.CoarsePagePixelThresholdDynamicNanite = CVarCoarsePagePixelThresholdDynamicNanite.GetValueOnRenderThread();
	UniformParameters.bClipmapGreedyLevelSelection = CVarClipmapGreedyLevelSelection.GetValueOnRenderThread();

	UniformParameters.SceneFrameNumber = Scene.GetFrameNumberRenderThread();

	// Reference dummy data in the UB initially

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.cpp:1315

Scope (from outer to inner):

file
function     void FVirtualShadowMapArray::BuildPageAllocations

Source code excerpt:

	UniformParameters.bExcludeNonNaniteFromCoarsePages = !CVarCoarsePagesIncludeNonNanite.GetValueOnRenderThread();
	UniformParameters.CoarsePagePixelThresholdDynamic = CVarCoarsePagePixelThresholdDynamic.GetValueOnRenderThread();
	UniformParameters.CoarsePagePixelThresholdStatic = CVarCoarsePagePixelThresholdStatic.GetValueOnRenderThread();
	UniformParameters.CoarsePagePixelThresholdDynamicNanite = CVarCoarsePagePixelThresholdDynamicNanite.GetValueOnRenderThread();

	bool bCsvLogEnabled = false;
#if !UE_BUILD_SHIPPING
	const bool bRunPageAreaDiagnostics = CVarNumPageAreaDiagSlots.GetValueOnRenderThread() != 0;
#if CSV_PROFILER