r.Decal.NormalReprojectionThresholdHigh

r.Decal.NormalReprojectionThresholdHigh

#Overview

name: r.Decal.NormalReprojectionThresholdHigh

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Decal.NormalReprojectionThresholdHigh is to control the blending of normal maps in deferred decal rendering within Unreal Engine 5’s rendering system. Specifically, it sets the upper threshold for determining when to use the reprojected normal from the previous frame instead of the geometry normal extracted from the depth buffer.

This setting variable is primarily used by the Renderer module, particularly in the deferred decal rendering subsystem. It’s part of the post-processing stage that handles decal application in deferred rendering.

The value of this variable is set through the console variable system, with a default value of 0.995f. It can be changed at runtime using console commands or through configuration files.

This variable interacts closely with another variable, r.Decal.NormalReprojectionThresholdLow. Together, these two variables define a range for blending between the geometry normal and the reprojected normal.

Developers should be aware that this variable affects the visual quality and performance of decal rendering. A higher value will favor using the reprojected normal more often, which can improve performance but may lead to less accurate results in some cases.

Best practices when using this variable include:

  1. Adjusting it in tandem with r.Decal.NormalReprojectionThresholdLow to fine-tune the blending behavior.
  2. Testing different values to find the optimal balance between performance and visual quality for your specific use case.
  3. Being cautious about setting it too low, as this could lead to more frequent use of the more expensive geometry normal calculation.

Regarding the associated variable CVarDBufferDecalNormalReprojectionThresholdHigh:

This is the actual console variable object that stores and manages the r.Decal.NormalReprojectionThresholdHigh value. It’s used internally by the engine to access and modify the threshold value.

The purpose of this variable is to provide a programming interface for the r.Decal.NormalReprojectionThresholdHigh setting. It’s used in the creation of the deferred decal uniform buffer, where its value is retrieved using the GetValueOnRenderThread() method.

This variable is part of the rendering system’s internal implementation and is not typically interacted with directly by game developers. Instead, developers would use the r.Decal.NormalReprojectionThresholdHigh console command to modify the value.

When working with this variable, developers should be aware that it’s accessed on the render thread, which is important for maintaining thread safety in the rendering system.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/CompositionLighting/PostProcessDeferredDecals.cpp:38

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarDBufferDecalNormalReprojectionThresholdHigh(
	TEXT("r.Decal.NormalReprojectionThresholdHigh"),
	0.995f, 
	TEXT("When reading the normal from a SceneTexture node in a DBuffer decal shader, ")
	TEXT("the normal is a mix of the geometry normal (extracted from the depth buffer) and the normal from the reprojected ")
	TEXT("previous frame. When the dot product of the geometry and reprojected normal is below the r.Decal.NormalReprojectionThresholdLow, ")
	TEXT("the geometry normal is used. When that value is above r.Decal.NormalReprojectionThresholdHigh, the reprojected ")
	TEXT("normal is used. Otherwise it uses a lerp between them."),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/CompositionLighting/PostProcessDeferredDecals.cpp:37

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarDBufferDecalNormalReprojectionThresholdHigh(
	TEXT("r.Decal.NormalReprojectionThresholdHigh"),
	0.995f, 
	TEXT("When reading the normal from a SceneTexture node in a DBuffer decal shader, ")
	TEXT("the normal is a mix of the geometry normal (extracted from the depth buffer) and the normal from the reprojected ")
	TEXT("previous frame. When the dot product of the geometry and reprojected normal is below the r.Decal.NormalReprojectionThresholdLow, ")
	TEXT("the geometry normal is used. When that value is above r.Decal.NormalReprojectionThresholdHigh, the reprojected ")

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/CompositionLighting/PostProcessDeferredDecals.cpp:255

Scope (from outer to inner):

file
function     TUniformBufferRef<FDeferredDecalUniformParameters> CreateDeferredDecalUniformBuffer

Source code excerpt:

	FDeferredDecalUniformParameters UniformParameters;
	UniformParameters.NormalReprojectionThresholdLow  = CVarDBufferDecalNormalReprojectionThresholdLow .GetValueOnRenderThread();
	UniformParameters.NormalReprojectionThresholdHigh = CVarDBufferDecalNormalReprojectionThresholdHigh.GetValueOnRenderThread();
	UniformParameters.NormalReprojectionEnabled = bIsNormalReprojectionEnabled ? 1 : 0;
	
	// the algorithm is:
	//    value = (dot - low)/(high - low)
	// so calculate the divide in the helper to turn the math into:
	//    helper = 1.0f/(high - low)