r.Shadow.TexelsPerPixel

r.Shadow.TexelsPerPixel

#Overview

name: r.Shadow.TexelsPerPixel

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

• type: Var
• help: The ratio of subject pixels to shadow texels for per-object shadows

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shadow.TexelsPerPixel is to control the ratio of subject pixels to shadow texels for per-object shadows in Unreal Engine 5’s rendering system. This setting variable is primarily used in the shadow rendering and light function rendering subsystems of the engine.

The Unreal Engine subsystems that rely on this setting variable are primarily the Renderer module, as evidenced by the references in ShadowSetup.cpp and LightFunctionRendering.cpp. It’s also referenced in the Engine module’s SystemSettings.cpp, indicating its importance in the overall rendering pipeline.

The value of this variable is initially set to 1.27324f in the ShadowSetup.cpp file. However, it can be overridden in SystemSettings.cpp, where it’s set to 4.0f in the ApplyOverrides function.

This variable interacts closely with its associated variable CVarShadowTexelsPerPixel. They share the same value and are used interchangeably in the code. The CVarShadowTexelsPerPixel is used to retrieve the value of r.Shadow.TexelsPerPixel at runtime.

Developers must be aware that this variable directly affects the quality and performance of shadow rendering. A higher value will result in higher quality shadows but at the cost of increased performance overhead. Conversely, a lower value will improve performance but may result in lower quality shadows.

Best practices when using this variable include:

1. Carefully balancing shadow quality and performance based on the target hardware.
2. Testing different values to find the optimal balance for your specific game or application.
3. Considering dynamic adjustment of this value based on the scene complexity or distance from the camera.
4. Being aware that changes to this value may require adjustments to other shadow-related settings for optimal results.

Regarding the associated variable CVarShadowTexelsPerPixel, it serves as the runtime accessor for r.Shadow.TexelsPerPixel. It’s used in various parts of the rendering code to retrieve the current value of the setting. Developers should use this variable when they need to access the r.Shadow.TexelsPerPixel value in C++ code, particularly within the render thread.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:205

Scope: file

Source code excerpt:

static TAutoConsoleVariable<float> CVarShadowTexelsPerPixel(
	TEXT("r.Shadow.TexelsPerPixel"),
	1.27324f,
	TEXT("The ratio of subject pixels to shadow texels for per-object shadows"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarShadowTexelsPerPixelPointlight(
	TEXT("r.Shadow.TexelsPerPixelPointlight"),

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SystemSettings.cpp:305

Scope (from outer to inner):

file
function     void FSystemSettings::ApplyOverrides

Source code excerpt:

		// Increase shadow texel density
		{
			static auto CVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.Shadow.TexelsPerPixel"));
			CVar->Set(4.0f, SetBy);
		}

		// Don't downsample preshadows
		{
			static auto CVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.Shadow.PreShadowResolutionFactor"));

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightFunctionRendering.cpp:207

Scope (from outer to inner):

file
function     float GetLightFunctionFadeFraction

Source code excerpt:

		FMath::Max(ScreenPosition.W, 1.0f);

	static auto CVarShadowTexelsPerPixel = IConsoleManager::Get().FindTConsoleVariableDataFloat(TEXT("r.Shadow.TexelsPerPixel"));
	const float UnclampedResolution = ScreenRadius * CVarShadowTexelsPerPixel->GetValueOnRenderThread();
	const float ResolutionFadeAlpha = CalculateShadowFadeAlpha(UnclampedResolution, ShadowFadeResolution, MinShadowResolution);
	return ResolutionFadeAlpha;
}

/**

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightFunctionRendering.cpp:207

Scope (from outer to inner):

file
function     float GetLightFunctionFadeFraction

Source code excerpt:

		FMath::Max(ScreenPosition.W, 1.0f);

	static auto CVarShadowTexelsPerPixel = IConsoleManager::Get().FindTConsoleVariableDataFloat(TEXT("r.Shadow.TexelsPerPixel"));
	const float UnclampedResolution = ScreenRadius * CVarShadowTexelsPerPixel->GetValueOnRenderThread();
	const float ResolutionFadeAlpha = CalculateShadowFadeAlpha(UnclampedResolution, ShadowFadeResolution, MinShadowResolution);
	return ResolutionFadeAlpha;
}

/**
* Used by RenderLights to figure out if light functions need to be rendered to the attenuation buffer.

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:204

Scope: file

Source code excerpt:

	ECVF_Scalability | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarShadowTexelsPerPixel(
	TEXT("r.Shadow.TexelsPerPixel"),
	1.27324f,
	TEXT("The ratio of subject pixels to shadow texels for per-object shadows"),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarShadowTexelsPerPixelPointlight(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadowSetup.cpp:3351

Scope (from outer to inner):

file
function     void FSceneRenderer::CreatePerObjectProjectedShadow

Source code excerpt:

		// Determine the amount of shadow buffer resolution needed for this view.
		const float UnclampedResolution = ScreenRadius * CVarShadowTexelsPerPixel.GetValueOnRenderThread();

		// Calculate fading based on resolution
		// Compute FadeAlpha before ShadowResolutionScale contribution (artists want to modify the softness of the shadow, not change the fade ranges)
		const float ViewSpecificAlpha = CalculateShadowFadeAlpha(UnclampedResolution, ShadowFadeResolution, MinShadowResolution) * LightSceneInfo->Proxy->GetShadowAmount();
		MaxResolutionFadeAlpha = FMath::Max(MaxResolutionFadeAlpha, ViewSpecificAlpha);
		ResolutionFadeAlphas.Add(ViewSpecificAlpha);