r.Decal.NormalReprojectionThresholdLow

r.Decal.NormalReprojectionThresholdLow

#Overview

name: r.Decal.NormalReprojectionThresholdLow

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.NormalReprojectionThresholdLow is to control the blending of normal maps in decal shaders within Unreal Engine 5’s rendering system. It specifically sets the lower threshold for determining when to use the geometry normal versus the reprojected normal from the previous frame.

This setting variable is primarily used in the Renderer module of Unreal Engine, specifically in the deferred decal rendering subsystem. It’s part of the composition lighting system that handles how decals are applied to surfaces in the game world.

The value of this variable is set through the console variable system, allowing it to be adjusted at runtime. It’s defined with a default value of 0.990f, but can be changed through console commands or configuration files.

The r.Decal.NormalReprojectionThresholdLow variable interacts closely with r.Decal.NormalReprojectionThresholdHigh. 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. Lower values will favor the geometry normal, which can be more accurate but potentially more expensive to compute. Higher values will favor the reprojected normal, which can be faster but may introduce artifacts in some cases.

Best practices when using this variable include:

  1. Fine-tuning it in conjunction with r.Decal.NormalReprojectionThresholdHigh for optimal visual results.
  2. Testing across various scenes and viewing angles to ensure consistent quality.
  3. Considering performance implications, especially on lower-end hardware.

Regarding the associated variable CVarDBufferDecalNormalReprojectionThresholdLow:

This is the actual console variable object that stores and manages the r.Decal.NormalReprojectionThresholdLow setting. It’s used internally by the engine to access the current value of the setting.

The purpose of CVarDBufferDecalNormalReprojectionThresholdLow is to provide a programmatic interface for getting and setting the r.Decal.NormalReprojectionThresholdLow value.

It’s used in the Renderer module, specifically in the creation of deferred decal uniform buffers. The value is retrieved using the GetValueOnRenderThread() method, ensuring thread-safe access in the rendering pipeline.

Developers should be aware that changes to this variable will take effect on the render thread, which may not be immediate depending on the current frame state.

Best practices for using CVarDBufferDecalNormalReprojectionThresholdLow include:

  1. Accessing it only on the render thread or through appropriate thread-safe methods.
  2. Considering caching its value if used frequently, to avoid repeated calls to GetValueOnRenderThread().
  3. Being cautious about modifying it at runtime, as it can affect ongoing rendering operations.

#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:28

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarDBufferDecalNormalReprojectionThresholdLow(
	TEXT("r.Decal.NormalReprojectionThresholdLow"),
	0.990f, 
	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 CVarDBufferDecalNormalReprojectionThresholdLow. They share the same value. See the following C++ source code.

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<float> CVarDBufferDecalNormalReprojectionThresholdLow(
	TEXT("r.Decal.NormalReprojectionThresholdLow"),
	0.990f, 
	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:254

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: