r.Upscale.Softness

r.Upscale.Softness

#Overview

name: r.Upscale.Softness

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

• type: Var
• help: Amount of sharpening for Gaussian Unsharp filter (r.UpscaleQuality=5). Reduce if ringing is visible\n 1: Normal sharpening (default)\n 0: No sharpening (pure Gaussian).

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Upscale.Softness is to control the amount of sharpening applied during the upscaling process in Unreal Engine’s rendering system. Specifically, it affects the Gaussian Unsharp filter when the upscale quality is set to 5.

This setting variable is primarily used by the Renderer module of Unreal Engine, particularly in the post-processing stage for upscaling. It’s part of the spatial upscaling system, which is responsible for increasing the resolution of rendered images.

The value of this variable is set through the console variable system. It’s defined with a default value of 1.0f, which represents normal sharpening. The value can be changed at runtime through console commands or programmatically.

The associated variable CVarUpscaleSoftness directly interacts with r.Upscale.Softness. It’s a TAutoConsoleVariable that encapsulates the console variable functionality for this setting.

Developers should be aware that:

1. The valid range for this variable is between 0.0 and 1.0.
2. Lower values reduce sharpening, with 0.0 resulting in no sharpening (pure Gaussian).
3. Higher values increase sharpening, which may introduce visible ringing artifacts.
4. This setting only affects upscaling when r.UpscaleQuality is set to 5.

Best practices when using this variable include:

1. Use it in conjunction with r.UpscaleQuality=5 for fine-tuning the upscaling results.
2. Adjust the value if ringing artifacts are visible, reducing it to mitigate these artifacts.
3. Consider the target platform and performance implications when adjusting this value, as increased sharpening may have a slight performance cost.

Regarding the associated variable CVarUpscaleSoftness:

• It’s a console variable wrapper for r.Upscale.Softness.
• It’s defined with the ECVF_Scalability and ECVF_RenderThreadSafe flags, indicating it’s safe to modify on the render thread and can be adjusted for different scalability settings.
• The value is retrieved in the render thread using GetValueOnRenderThread() and clamped between 0.0 and 1.0 before being used in the upscale pass.
• It’s used directly in the FScreenPassTexture ISpatialUpscaler::AddDefaultUpscalePass function to set the UpscaleSoftness parameter for the upscale pixel shader.

Developers should use CVarUpscaleSoftness.GetValueOnRenderThread() when accessing this value in render thread code, and be aware of the clamping applied to ensure the value stays within the valid range.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessUpscale.cpp:8

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

{
TAutoConsoleVariable<float> CVarUpscaleSoftness(
	TEXT("r.Upscale.Softness"),
	1.0f,
	TEXT("Amount of sharpening for Gaussian Unsharp filter (r.UpscaleQuality=5). Reduce if ringing is visible\n")
	TEXT("  1: Normal sharpening (default)\n")
	TEXT("  0: No sharpening (pure Gaussian)."),
	ECVF_Scalability | ECVF_RenderThreadSafe);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessUpscale.cpp:7

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

namespace
{
TAutoConsoleVariable<float> CVarUpscaleSoftness(
	TEXT("r.Upscale.Softness"),
	1.0f,
	TEXT("Amount of sharpening for Gaussian Unsharp filter (r.UpscaleQuality=5). Reduce if ringing is visible\n")
	TEXT("  1: Normal sharpening (default)\n")
	TEXT("  0: No sharpening (pure Gaussian)."),
	ECVF_Scalability | ECVF_RenderThreadSafe);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessUpscale.cpp:224

Scope (from outer to inner):

file
function     FScreenPassTexture ISpatialUpscaler::AddDefaultUpscalePass

Source code excerpt:

	PassParameters->PointSceneColorSampler = TStaticSamplerState<SF_Point, AM_Border, AM_Border, AM_Border>::GetRHI();
	PassParameters->Panini = GetPaniniProjectionParameters(PaniniConfig, View);
	PassParameters->UpscaleSoftness = FMath::Clamp(CVarUpscaleSoftness.GetValueOnRenderThread(), 0.0f, 1.0f);
	PassParameters->View = View.ViewUniformBuffer;

	FUpscalePS::FPermutationDomain PixelPermutationVector;
	PixelPermutationVector.Set<FUpscalePS::FMethodDimension>(Method);
	TShaderMapRef<FUpscalePS> PixelShader(View.ShaderMap, PixelPermutationVector);