r.TSR.Velocity.WeightClampingSampleCount

r.TSR.Velocity.WeightClampingSampleCount

#Overview

name: r.TSR.Velocity.WeightClampingSampleCount

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.TSR.Velocity.WeightClampingSampleCount is to control the temporal stability and blur in the Temporal Super Resolution (TSR) system, which is part of Unreal Engine’s rendering pipeline.

This setting variable is primarily used in the Temporal Super Resolution subsystem of Unreal Engine’s rendering module. It’s specifically referenced in the TemporalSuperResolution.cpp file, which handles the implementation of the TSR algorithm.

The value of this variable is set through a console variable (CVar) system, allowing it to be adjusted at runtime. It’s initialized with a default value of 4.0f.

This variable interacts closely with other TSR-related variables, such as r.TSR.Velocity.WeightClampingPixelSpeed. It’s used in calculations that determine how the engine handles motion and stability in the TSR process.

Developers should be aware that this variable affects the trade-off between stability and blur in moving scenes. Higher values provide more stability during movement but can introduce additional blur due to the successive convolution of each history reprojection.

Best practices when using this variable include:

  1. Use the “r.TSR.Visualize 0” command to visualize how many samples were accumulated in the TSR history across different areas of the screen.
  2. Adjust the value based on the specific needs of your scene. If you need more stability in moving objects, increase the value, but be prepared for potential increased blur.
  3. Test different values to find the optimal balance between stability and image clarity for your specific use case.

Regarding the associated variable CVarTSRWeightClampingSampleCount:

This is the actual C++ variable that stores and provides access to the r.TSR.Velocity.WeightClampingSampleCount value. It’s defined as a TAutoConsoleVariable, which is part of Unreal’s system for creating adjustable parameters.

The purpose of CVarTSRWeightClampingSampleCount is to provide a programmatic interface to the r.TSR.Velocity.WeightClampingSampleCount setting. It’s used in the code to retrieve the current value of the setting and apply it in the TSR calculations.

This variable is primarily used within the TemporalSuperResolution.cpp file, specifically in the AddTemporalSuperResolutionPasses function, which is a key part of the TSR implementation.

The value of CVarTSRWeightClampingSampleCount is set automatically by the CVar system based on the r.TSR.Velocity.WeightClampingSampleCount setting.

Developers should be aware that changes to r.TSR.Velocity.WeightClampingSampleCount will be reflected in CVarTSRWeightClampingSampleCount, and vice versa. They should use the GetValueOnRenderThread() method to safely access this value in render thread operations.

Best practices include using this variable consistently throughout the TSR implementation to ensure that changes to the setting are properly propagated throughout the system.

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

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:


TAutoConsoleVariable<float> CVarTSRWeightClampingSampleCount(
	TEXT("r.TSR.Velocity.WeightClampingSampleCount"), 4.0f,
	TEXT("Number of sample to count to in history pixel to clamp history to when output pixel velocity reach r.TSR.Velocity.WeightClampingPixelSpeed. ")
	TEXT("Higher value means higher stability on movement, but at the expense of additional blur due to successive convolution of each history reprojection.\n")
	TEXT("\n")
	TEXT("Use \"r.TSR.Visualize 0\" command to see how many samples where accumulated in TSR history on areas of the screen.\n")
	TEXT("\n")
	TEXT("Please note this clamp the sample count in history pixel, not output pixel, and therefore lower values are by designed less ")

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

	ECVF_RenderThreadSafe);

TAutoConsoleVariable<float> CVarTSRWeightClampingSampleCount(
	TEXT("r.TSR.Velocity.WeightClampingSampleCount"), 4.0f,
	TEXT("Number of sample to count to in history pixel to clamp history to when output pixel velocity reach r.TSR.Velocity.WeightClampingPixelSpeed. ")
	TEXT("Higher value means higher stability on movement, but at the expense of additional blur due to successive convolution of each history reprojection.\n")
	TEXT("\n")
	TEXT("Use \"r.TSR.Visualize 0\" command to see how many samples where accumulated in TSR history on areas of the screen.\n")
	TEXT("\n")

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

Scope (from outer to inner):

file
function     FDefaultTemporalUpscaler::FOutputs AddTemporalSuperResolutionPasses

Source code excerpt:

		PassParameters->HistoryHisteresis = 1.0f / PassParameters->HistorySampleCount;
		PassParameters->WeightClampingRejection = 1.0f - (CVarTSRHistoryRejectionSampleCount.GetValueOnRenderThread() / OutputToHistoryResolutionFractionSquare) * PassParameters->HistoryHisteresis;
		PassParameters->WeightClampingPixelSpeedAmplitude = FMath::Clamp(1.0f - CVarTSRWeightClampingSampleCount.GetValueOnRenderThread() * PassParameters->HistoryHisteresis, 0.0f, 1.0f);
		PassParameters->InvWeightClampingPixelSpeed = 1.0f / (CVarTSRWeightClampingPixelSpeed.GetValueOnRenderThread() * OutputToHistoryResolutionFraction);
		
		PassParameters->InputToHistoryFactor = float(HistorySize.X) / float(InputRect.Width());
		PassParameters->InputContributionMultiplier = OutputToHistoryResolutionFractionSquare; 
		PassParameters->bGenerateOutputMip1 = false;
		PassParameters->bGenerateOutputMip2 = false;