r.TSR.Velocity.WeightClampingPixelSpeed

r.TSR.Velocity.WeightClampingPixelSpeed

#Overview

name: r.TSR.Velocity.WeightClampingPixelSpeed

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.WeightClampingPixelSpeed is to control the weight clamping of high-frequency history contributions in the Temporal Super Resolution (TSR) system based on pixel velocity.

This setting variable is primarily used in the rendering system, specifically within the Temporal Super Resolution module of Unreal Engine 5. It is part of the post-processing pipeline and is utilized in the TemporalSuperResolution.cpp file.

The value of this variable is set through a console variable (CVarTSRWeightClampingPixelSpeed) with a default value of 1.0f. It can be modified at runtime using console commands or through engine configuration files.

This variable interacts closely with r.TSR.Velocity.WeightClampingSampleCount. Together, they control how the weight of high-frequency history contributions is adjusted based on pixel velocity.

Developers should be aware that this variable affects the quality and performance of temporal upscaling. It defines the output pixel velocity at which the high frequencies of the history get their contributing weight clamped. Essentially, it helps to interpolate the effect of r.TSR.Velocity.WeightClampingSampleCount when the pixel velocity becomes smaller than the value set by this variable.

Best practices when using this variable include:

  1. Carefully adjusting its value in conjunction with r.TSR.Velocity.WeightClampingSampleCount to achieve the desired balance between image quality and performance.
  2. Testing the effects of different values in various scenarios, especially those with different levels of motion in the scene.
  3. Considering the target hardware capabilities when fine-tuning this value, as it can affect performance.

Regarding the associated variable CVarTSRWeightClampingPixelSpeed:

This is the actual console variable that controls the r.TSR.Velocity.WeightClampingPixelSpeed setting. It is defined in the TemporalSuperResolution.cpp file and is used to store and retrieve the current value of the setting.

The purpose of CVarTSRWeightClampingPixelSpeed is to provide a runtime-configurable interface for the r.TSR.Velocity.WeightClampingPixelSpeed setting. It allows developers and users to modify the setting without recompiling the engine.

This variable is used in the AddTemporalSuperResolutionPasses function to calculate the InvWeightClampingPixelSpeed parameter, which is then passed to the TSR shader.

When working with CVarTSRWeightClampingPixelSpeed, developers should:

  1. Use GetValueOnRenderThread() to safely access its value in render thread code.
  2. Be aware that changes to this variable will affect the TSR system in real-time, which can be useful for debugging and fine-tuning but should be used carefully in production builds.
  3. Consider exposing this setting in user-facing graphics options if allowing end-users to fine-tune TSR behavior is desirable for your project.

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

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:


TAutoConsoleVariable<float> CVarTSRWeightClampingPixelSpeed(
	TEXT("r.TSR.Velocity.WeightClampingPixelSpeed"), 1.0f,
	TEXT("Defines the output pixel velocity at which the the high frequencies of the history get's their contributing weight clamped. ")
	TEXT("It's basically to lerp the effect of r.TSR.Velocity.WeightClampingSampleCount when the pixel velocity get smaller than r.TSR.Velocity.WeightClampingPixelSpeed. ")
	TEXT("(Default = 1.0f)."),
	ECVF_RenderThreadSafe);

// TODO: improve CONFIG_VELOCITY_EXTRAPOLATION in TSRDilateVelcity.usf that is disabled at the moment.

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

	ECVF_RenderThreadSafe);

TAutoConsoleVariable<float> CVarTSRWeightClampingPixelSpeed(
	TEXT("r.TSR.Velocity.WeightClampingPixelSpeed"), 1.0f,
	TEXT("Defines the output pixel velocity at which the the high frequencies of the history get's their contributing weight clamped. ")
	TEXT("It's basically to lerp the effect of r.TSR.Velocity.WeightClampingSampleCount when the pixel velocity get smaller than r.TSR.Velocity.WeightClampingPixelSpeed. ")
	TEXT("(Default = 1.0f)."),
	ECVF_RenderThreadSafe);

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

Scope (from outer to inner):

file
function     FDefaultTemporalUpscaler::FOutputs AddTemporalSuperResolutionPasses

Source code excerpt:

		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;
		PassParameters->bGenerateOutputMip3 = false;