r.DynamicRes.ThrottlingMaxScreenPercentage

r.DynamicRes.ThrottlingMaxScreenPercentage

#Overview

name: r.DynamicRes.ThrottlingMaxScreenPercentage

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.DynamicRes.ThrottlingMaxScreenPercentage is to control the maximum screen percentage allowed by the dynamic resolution heuristic when throttling is enabled. It is part of Unreal Engine’s dynamic resolution system, which is used to adjust rendering resolution dynamically to maintain performance.

This setting variable is primarily used in the Engine module, specifically within the dynamic resolution subsystem. It’s referenced in the DynamicResolution.cpp file, which is part of the core engine’s rendering system.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value derived from DynamicRenderScaling::FHeuristicSettings::kDefaultThrottlingMaxResolutionFraction, but can be modified at runtime through console commands or game code.

This variable interacts closely with other dynamic resolution settings, such as minimum and maximum screen percentages. It’s specifically used to limit the maximum resolution when the system is in a throttled state, which can be useful for managing power consumption or performance in certain scenarios.

Developers must be aware that this setting does not affect preallocated video memory. It’s primarily used to control the resolution scaling without resizing the renderer’s internal render targets, which helps avoid visual popping effects.

Best practices when using this variable include:

  1. Carefully balancing it with other dynamic resolution settings to achieve optimal performance and visual quality.
  2. Considering its impact on power consumption, especially on mobile or console platforms.
  3. Testing thoroughly to ensure it doesn’t negatively impact visual quality in critical game scenarios.

The associated variable CVarDynamicResThrottlingMaxSP is the actual console variable that stores and provides access to the r.DynamicRes.ThrottlingMaxScreenPercentage value. It’s used internally by the engine to retrieve the current throttling max screen percentage value when needed, such as in the GetPrimaryDynamicResolutionSettings function.

When working with CVarDynamicResThrottlingMaxSP, developers should:

  1. Use it to read the current throttling max screen percentage value in C++ code.
  2. Be aware that changes to this variable will directly affect the dynamic resolution system’s behavior.
  3. Consider exposing it through game settings if dynamic resolution throttling needs to be adjustable by end-users.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/DynamicResolution.cpp:30

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarDynamicResThrottlingMaxSP(
	TEXT("r.DynamicRes.ThrottlingMaxScreenPercentage"),
	DynamicRenderScaling::FractionToPercentage(DynamicRenderScaling::FHeuristicSettings::kDefaultThrottlingMaxResolutionFraction),
	TEXT("Throttle the primary screen percentage allowed by the heuristic to this max value when enabled. This has no effect on preallocated video memory.\n")
	TEXT("This is for instance useful when the video game wants to trottle power consumption when inactive without resizing internal renderer's render targets\n")
	TEXT("(which can result in popping)"),
	ECVF_Default);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/DynamicResolution.cpp:29

Scope: file

Source code excerpt:

	ECVF_Default);

static TAutoConsoleVariable<float> CVarDynamicResThrottlingMaxSP(
	TEXT("r.DynamicRes.ThrottlingMaxScreenPercentage"),
	DynamicRenderScaling::FractionToPercentage(DynamicRenderScaling::FHeuristicSettings::kDefaultThrottlingMaxResolutionFraction),
	TEXT("Throttle the primary screen percentage allowed by the heuristic to this max value when enabled. This has no effect on preallocated video memory.\n")
	TEXT("This is for instance useful when the video game wants to trottle power consumption when inactive without resizing internal renderer's render targets\n")
	TEXT("(which can result in popping)"),
	ECVF_Default);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/DynamicResolution.cpp:150

Scope (from outer to inner):

file
function     DynamicRenderScaling::FHeuristicSettings GetPrimaryDynamicResolutionSettings

Source code excerpt:

	BudgetSetting.MinResolutionFraction      = DynamicRenderScaling::GetPercentageCVarToFraction(CVarDynamicResMinSP);
	BudgetSetting.MaxResolutionFraction      = DynamicRenderScaling::GetPercentageCVarToFraction(CVarDynamicResMaxSP);
	BudgetSetting.ThrottlingMaxResolutionFraction = DynamicRenderScaling::GetPercentageCVarToFraction(CVarDynamicResThrottlingMaxSP);
	BudgetSetting.UpperBoundQuantization     = CVarUpperBoundQuantization.GetValueOnAnyThread();
	BudgetSetting.BudgetMs                   = CVarFrameTimeBudget.GetValueOnAnyThread() * (1.0f - DynamicRenderScaling::GetPercentageCVarToFraction(CVarOverBudgetGPUHeadRoomPercentage));
	BudgetSetting.ChangeThreshold            = DynamicRenderScaling::GetPercentageCVarToFraction(CVarChangeThreshold);
	BudgetSetting.TargetedHeadRoom           = DynamicRenderScaling::GetPercentageCVarToFraction(CVarTargetedGPUHeadRoomPercentage);
	BudgetSetting.IncreaseAmortizationFactor = CVarIncreaseAmortizationFactor.GetValueOnAnyThread();
	return BudgetSetting;