r.TSR.ShadingRejection.Flickering

r.TSR.ShadingRejection.Flickering

#Overview

name: r.TSR.ShadingRejection.Flickering

The value of this variable can be defined or overridden in .ini config files. 5 .ini config files referencing this setting variable.

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.TSR.ShadingRejection.Flickering is to control the anti-flickering mechanism in Unreal Engine 5’s Temporal Super Resolution (TSR) system. This setting is part of the rendering system, specifically targeting the post-processing stage where temporal upscaling is applied.

This variable is primarily used in the Renderer module of Unreal Engine 5. It’s referenced in the TemporalSuperResolution.cpp and VisualizeTemporalUpscaler.cpp files, which are part of the post-processing pipeline.

The value of this variable is set through a console variable (CVarTSRFlickeringEnable) with a default value of 1 (enabled). It can be changed at runtime through console commands or project settings.

This variable interacts closely with CVarTSRFlickeringPeriod, which determines the frame period at which history changes are considered too distracting. Together, they control the behavior of the anti-flickering mechanism in TSR.

Developers should be aware that this variable addresses two main sources of instability in TSR output:

  1. Moire patterns caused by the interaction between structured geometry and the jittered pixel grid.
  2. Instability in cases of extreme geometric complexity due to the temporal history’s “chicken-and-egg” problem.

Best practices when using this variable include:

  1. Keep it enabled (default value of 1) unless you have specific reasons to disable it.
  2. If you’re experiencing flickering issues in your scene, consider adjusting this variable in conjunction with r.TSR.FlickeringPeriod.
  3. Be aware that disabling this (setting to 0) may result in more visible flickering in complex scenes or with certain types of geometry.
  4. For materials that intentionally have pixel animation, use the UMaterial::bHasPixelAnimation flag to disable this anti-flickering heuristic on a per-pixel basis.

Regarding the associated variable CVarTSRFlickeringEnable:

The purpose of CVarTSRFlickeringEnable is to provide a programmable interface to control the r.TSR.ShadingRejection.Flickering setting. It’s an internal representation of the console variable that developers can use in C++ code to read or modify the setting.

This variable is used in the Renderer module, specifically in the Temporal Super Resolution implementation. It’s typically accessed using the GetValueOnRenderThread() method to ensure thread-safe access in the render thread.

The value of CVarTSRFlickeringEnable is set when the r.TSR.ShadingRejection.Flickering console variable is modified, either through console commands or project settings.

Developers should be aware that changes to CVarTSRFlickeringEnable will directly affect the TSR anti-flickering behavior. It’s important to only modify this variable in the appropriate thread context (usually the render thread) to avoid race conditions.

Best practices for using CVarTSRFlickeringEnable include:

  1. Always access its value using GetValueOnRenderThread() when in rendering code.
  2. Consider caching the value if it’s used multiple times in performance-critical sections.
  3. Be cautious when modifying this variable, as it can have a significant impact on visual quality and performance.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseScalability.ini:58, section: [AntiAliasingQuality@0]

Location: <Workspace>/Engine/Config/BaseScalability.ini:68, section: [AntiAliasingQuality@1]

Location: <Workspace>/Engine/Config/BaseScalability.ini:78, section: [AntiAliasingQuality@2]

Location: <Workspace>/Engine/Config/BaseScalability.ini:88, section: [AntiAliasingQuality@3]

Location: <Workspace>/Engine/Config/BaseScalability.ini:98, section: [AntiAliasingQuality@Cine]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/TemporalSuperResolution.cpp:115

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:


TAutoConsoleVariable<int32> CVarTSRFlickeringEnable(
	TEXT("r.TSR.ShadingRejection.Flickering"), 1,
	TEXT("Instability in TSR output 99% of the time coming from instability of the shading rejection, for different reasons:\n")
	TEXT(" - One first source of instability is most famously moire pattern between structured geometry and the rendering pixel grid changing ")
	TEXT("every frame due to the offset of the jittering pixel grid offset;\n")
	TEXT(" - Another source of instability can happen on extrem geometric complexity due to temporal history's chicken-and-egg problem that can ")
	TEXT("not be overcome by other mechanisms in place in TSR's RejectHistory pass: ")
	TEXT("how can the history be identical to rendered frame if the amount of details you have in the rendered frame is not in history? ")

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/VisualizeTemporalUpscaler.cpp:171

Scope (from outer to inner):

file
function     FScreenPassTexture AddVisualizeTemporalUpscalerPass

Source code excerpt:

		}

		// Display UMaterial::bHasPixelAnimation used to disable TSR's anti-flickering heuristic (r.TSR.ShadingRejection.Flickering) on per pixel basis
		if (Inputs.TAAConfig == EMainTAAPassConfig::TSR)
		{
			FVisualizeMotionVectorsInputs PassInputs;
			PassInputs.SceneColor = Inputs.SceneColor;
			PassInputs.SceneDepth = Inputs.Inputs.SceneDepth;
			PassInputs.SceneVelocity = Inputs.Inputs.SceneVelocity;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/TemporalSuperResolution.cpp:114

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

	ECVF_RenderThreadSafe);

TAutoConsoleVariable<int32> CVarTSRFlickeringEnable(
	TEXT("r.TSR.ShadingRejection.Flickering"), 1,
	TEXT("Instability in TSR output 99% of the time coming from instability of the shading rejection, for different reasons:\n")
	TEXT(" - One first source of instability is most famously moire pattern between structured geometry and the rendering pixel grid changing ")
	TEXT("every frame due to the offset of the jittering pixel grid offset;\n")
	TEXT(" - Another source of instability can happen on extrem geometric complexity due to temporal history's chicken-and-egg problem that can ")
	TEXT("not be overcome by other mechanisms in place in TSR's RejectHistory pass: ")

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/TemporalSuperResolution.cpp:1312

Scope (from outer to inner):

file
function     FDefaultTemporalUpscaler::FOutputs AddTemporalSuperResolutionPasses

Source code excerpt:


	// period at which history changes is considered too distracting.
	const float FlickeringFramePeriod = CVarTSRFlickeringEnable.GetValueOnRenderThread() ? (CVarTSRFlickeringPeriod.GetValueOnRenderThread() / FMath::Max(RefreshRateToFrameRateCap, 1.0f)) : 0.0f;

	ETSRHistoryFormatBits HistoryFormatBits = ETSRHistoryFormatBits::None;
	{
		if (FlickeringFramePeriod > 0)
		{
			HistoryFormatBits |= ETSRHistoryFormatBits::Moire;