r.Test.FreezeTemporalHistories

r.Test.FreezeTemporalHistories

#Overview

name: r.Test.FreezeTemporalHistories

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

• type: Var
• help: Freezes all temporal histories as well as the temporal sequence.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Test.FreezeTemporalHistories is to freeze all temporal histories and the temporal sequence in Unreal Engine’s rendering system. This is primarily used for testing and debugging purposes.

This setting variable is relied upon by Unreal Engine’s rendering subsystem, specifically in the scene visibility and rendering components. It is referenced in the SceneVisibility.cpp and ScenePrivate.h files, which are part of the Renderer module.

The value of this variable is set through a console variable (CVarFreezeTemporalHistories) in the engine’s configuration system. It is initialized with a default value of 0, meaning the freezing is disabled by default.

This variable interacts closely with another variable called CVarFreezeTemporalHistoriesProgress. While r.Test.FreezeTemporalHistories controls whether the histories are frozen, CVarFreezeTemporalHistoriesProgress allows for advancing the frozen state by one frame when modified.

Developers must be aware that using this variable will affect the rendering pipeline, particularly temporal effects. It’s important to note that this is a testing feature and should not be used in production builds or gameplay scenarios. It’s designed for debugging and analyzing temporal effects in isolation.

Best practices when using this variable include:

1. Only enable it during debugging sessions.
2. Be aware that it may impact performance and visual quality when enabled.
3. Use it in conjunction with CVarFreezeTemporalHistoriesProgress for step-by-step analysis of temporal effects.
4. Remember to disable it after testing to restore normal rendering behavior.

Regarding the associated variable CVarFreezeTemporalHistories:

The purpose of CVarFreezeTemporalHistories is to provide a programmatic way to control the r.Test.FreezeTemporalHistories setting. It’s an implementation detail of how the engine exposes the setting to both the console and the C++ code.

This variable is used directly in the rendering subsystem to determine whether temporal histories should be frozen. It’s typically checked in the render thread to ensure thread-safe access to the value.

The value of CVarFreezeTemporalHistories is set through the console variable system, which allows it to be changed at runtime through console commands or configuration files.

Developers should be aware that changes to CVarFreezeTemporalHistories will immediately affect the rendering pipeline. It’s important to use this variable carefully and only in appropriate development and testing scenarios.

Best practices for using CVarFreezeTemporalHistories include:

1. Access its value using the GetValueOnRenderThread() method to ensure thread-safe operations.
2. Consider the performance implications of frequently checking this value in performance-critical code paths.
3. Use it in conjunction with other debugging tools and variables for comprehensive analysis of temporal rendering effects.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneVisibility.cpp:356

Scope: file

Source code excerpt:

static TAutoConsoleVariable<float> CVarFreezeTemporalHistories(
	TEXT("r.Test.FreezeTemporalHistories"), 0,
	TEXT("Freezes all temporal histories as well as the temporal sequence."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarFreezeTemporalHistoriesProgress(
	TEXT("r.Test.FreezeTemporalHistories.Progress"), 0,
	TEXT("Progress the temporal histories by one frame when modified."),

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ScenePrivate.h:1003

Scope: file

Source code excerpt:

	 * after being copied to FViewInfo::PrevViewInfo. New temporal histories get directly written to it.
	 *
	 * When temporal histories are frozen (pause command, or r.Test.FreezeTemporalHistories), this keeps it's values, and the currently
	 * rendering FViewInfo should not update it. Refer to FViewInfo::bStatePrevViewInfoIsReadOnly.
	 */
	FPreviousViewInfo PrevFrameViewInfo;

	// Temporal AA result for light shafts of last frame
	FTemporalAAHistory LightShaftOcclusionHistory;
	// Temporal AA result for light shafts of last frame
	TMap<const ULightComponent*, TUniquePtr<FTemporalAAHistory> > LightShaftBloomHistoryRTs;

	FIntRect DistanceFieldAOHistoryViewRect;
	TRefCountPtr<IPooledRenderTarget> DistanceFieldAOHistoryRT;
	TRefCountPtr<IPooledRenderTarget> DistanceFieldIrradianceHistoryRT;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneVisibility.cpp:355

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarFreezeTemporalHistories(
	TEXT("r.Test.FreezeTemporalHistories"), 0,
	TEXT("Freezes all temporal histories as well as the temporal sequence."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarFreezeTemporalHistoriesProgress(
	TEXT("r.Test.FreezeTemporalHistories.Progress"), 0,

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneVisibility.cpp:4731

Scope (from outer to inner):

file
function     void FSceneRenderer::PrepareViewStateForVisibility

Source code excerpt:

	const bool bFreezeTemporalSequences = false;
#else
	bool bFreezeTemporalHistories = CVarFreezeTemporalHistories.GetValueOnRenderThread() != 0;

	static int32 CurrentFreezeTemporalHistoriesProgress = 0;
	if (CurrentFreezeTemporalHistoriesProgress != CVarFreezeTemporalHistoriesProgress.GetValueOnRenderThread())
	{
		bFreezeTemporalHistories = false;
		CurrentFreezeTemporalHistoriesProgress = CVarFreezeTemporalHistoriesProgress.GetValueOnRenderThread();