r.Translucency.DynamicRes.TargetedHeadRoomPercentage

r.Translucency.DynamicRes.TargetedHeadRoomPercentage

#Overview

name: r.Translucency.DynamicRes.TargetedHeadRoomPercentage

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.Translucency.DynamicRes.TargetedHeadRoomPercentage is to control the targeted GPU headroom for translucency in Unreal Engine’s dynamic resolution scaling system. This setting is part of the rendering system, specifically the dynamic resolution feature for translucent objects.

This variable is primarily used in the Renderer module of Unreal Engine, as evidenced by its location in the TranslucentRendering.cpp file.

The value of this variable is set through a console variable (CVar) system, which allows it to be changed at runtime. It’s initialized with a default value derived from DynamicRenderScaling::FHeuristicSettings::kDefaultTargetedHeadRoom, converted to a percentage.

This variable interacts closely with other dynamic resolution settings, particularly those related to translucency. It’s used in conjunction with CVarTranslucencyTimeBudget and CVarTranslucencyChangeThreshold to determine the dynamic resolution settings for translucent objects.

Developers should be aware that this variable represents a percentage of the overall dynamic resolution time budget (set by r.DynamicRes.DynamicRes.TimeBudget). It affects how aggressively the engine will adjust the resolution of translucent objects to maintain performance.

Best practices when using this variable include:

  1. Adjusting it in conjunction with other dynamic resolution settings for a balanced approach.
  2. Testing thoroughly across various scenes and performance scenarios to ensure it provides the desired balance between visual quality and performance.
  3. Being cautious about setting it too high, as it might lead to unnecessary resolution reductions.

Regarding the associated variable CVarTranslucencyTargetedHeadRoomPercentage:

This is the actual CVar object that holds the value for r.Translucency.DynamicRes.TargetedHeadRoomPercentage. It’s defined using TAutoConsoleVariable, which is Unreal Engine’s way of creating console variables.

The purpose of this variable is the same as r.Translucency.DynamicRes.TargetedHeadRoomPercentage - to store and provide access to the targeted GPU headroom for translucency.

This variable is used in the GetDynamicTranslucencyResolutionSettings function to populate a DynamicRenderScaling::FHeuristicSettings struct, which is then used to configure the dynamic resolution system for translucent objects.

Developers should be aware that changes to this CVar will take effect on the render thread, as indicated by the ECVF_RenderThreadSafe flag.

Best practices for using this variable include:

  1. Accessing its value using the GetValueOnAnyThread() method when needed in code.
  2. Using it in conjunction with other CVars related to dynamic resolution for a cohesive configuration.
  3. Considering its impact on both performance and visual quality when adjusting its value.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/TranslucentRendering.cpp:68

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarTranslucencyTargetedHeadRoomPercentage(
	TEXT("r.Translucency.DynamicRes.TargetedHeadRoomPercentage"),
	DynamicRenderScaling::FractionToPercentage(DynamicRenderScaling::FHeuristicSettings::kDefaultTargetedHeadRoom),
	TEXT("Targeted GPU headroom for translucency (in percent from r.DynamicRes.DynamicRes.TimeBudget)."),
	ECVF_RenderThreadSafe | ECVF_Default);

static TAutoConsoleVariable<float> CVarTranslucencyChangeThreshold(
	TEXT("r.Translucency.DynamicRes.ChangePercentageThreshold"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/TranslucentRendering.cpp:67

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe | ECVF_Default);

static TAutoConsoleVariable<float> CVarTranslucencyTargetedHeadRoomPercentage(
	TEXT("r.Translucency.DynamicRes.TargetedHeadRoomPercentage"),
	DynamicRenderScaling::FractionToPercentage(DynamicRenderScaling::FHeuristicSettings::kDefaultTargetedHeadRoom),
	TEXT("Targeted GPU headroom for translucency (in percent from r.DynamicRes.DynamicRes.TimeBudget)."),
	ECVF_RenderThreadSafe | ECVF_Default);

static TAutoConsoleVariable<float> CVarTranslucencyChangeThreshold(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/TranslucentRendering.cpp:120

Scope (from outer to inner):

file
function     DynamicRenderScaling::FHeuristicSettings GetDynamicTranslucencyResolutionSettings

Source code excerpt:

	BucketSetting.BudgetMs              = CVarTranslucencyTimeBudget.GetValueOnAnyThread();
	BucketSetting.ChangeThreshold       = DynamicRenderScaling::GetPercentageCVarToFraction(CVarTranslucencyChangeThreshold);
	BucketSetting.TargetedHeadRoom      = DynamicRenderScaling::GetPercentageCVarToFraction(CVarTranslucencyTargetedHeadRoomPercentage);
	BucketSetting.UpperBoundQuantization = CVarTranslucencyUpperBoundQuantization.GetValueOnAnyThread();
	return BucketSetting;
}

DynamicRenderScaling::FBudget GDynamicTranslucencyResolution(TEXT("DynamicTranslucencyResolution"), &GetDynamicTranslucencyResolutionSettings);