r.Nanite.PrimaryRaster.PixelsPerEdgeScaling

r.Nanite.PrimaryRaster.PixelsPerEdgeScaling

#Overview

name: r.Nanite.PrimaryRaster.PixelsPerEdgeScaling

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Nanite.PrimaryRaster.PixelsPerEdgeScaling is to control the scaling of the Nanite primary raster’s MaxPixelsPerEdge value when the rendering system is over budget. This setting is part of Unreal Engine 5’s Nanite virtualized geometry system, specifically focusing on the primary raster performance optimization.

This setting variable is primarily used by the Nanite rendering subsystem within Unreal Engine 5. It is referenced in the NaniteCullRaster.cpp file, which is part of the Renderer module.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 30.0f, which represents a 30% lower limit for scaling. Developers can modify this value at runtime using console commands or through project settings.

The r.Nanite.PrimaryRaster.PixelsPerEdgeScaling variable interacts closely with r.Nanite.MaxPixelsPerEdge. When the system is over budget, the MaxPixelsPerEdge value is scaled based on the percentage defined by this variable. For example, if MaxPixelsPerEdge is 1.0 and PixelsPerEdgeScaling is set to 20%, the effective MaxPixelsPerEdge could be scaled up to 5.0 when heavily over budget.

Developers should be aware that this variable affects the balance between performance and visual quality in Nanite-rendered geometry. Lower values will allow for more aggressive scaling, potentially improving performance at the cost of visual fidelity.

Best practices when using this variable include:

  1. Carefully balancing it with other Nanite settings to achieve optimal performance and visual quality.
  2. Testing different values in various scenarios to find the best setting for your specific project.
  3. Considering the target hardware capabilities when adjusting this value.

Regarding the associated variable CVarNanitePrimaryPixelsPerEdgeScalingPercentage:

This is the actual console variable that stores and manages the r.Nanite.PrimaryRaster.PixelsPerEdgeScaling value. It’s defined as a TAutoConsoleVariable, which allows for runtime modification.

The purpose of this variable is the same as r.Nanite.PrimaryRaster.PixelsPerEdgeScaling, as they represent the same setting.

It’s used in the GetDynamicNaniteScalingPrimarySettings() function to retrieve the current value and calculate the minimum resolution fraction for dynamic Nanite scaling.

When working with this variable, developers should:

  1. Ensure values are clamped between 1.0f and 100.0f for stability.
  2. Be aware that changes to this variable will immediately affect the Nanite rendering system’s behavior.
  3. Consider exposing this setting in user-facing graphics options if fine-tuning of Nanite performance is desired.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Nanite/NaniteCullRaster.cpp:252

Scope: file

Source code excerpt:

// i.e. if r.Nanite.MaxPixelsPerEdge is 1.0 and r.Nanite.PrimaryRaster.PixelsPerEdgeScaling is 20%, when heavily over budget r.Nanite.MaxPixelsPerEdge will be scaled to to 5.0
static TAutoConsoleVariable<float> CVarNanitePrimaryPixelsPerEdgeScalingPercentage(
	TEXT("r.Nanite.PrimaryRaster.PixelsPerEdgeScaling"),
	30.0f, // 100% - no scaling - set to < 100% to scale pixel error when over budget
	TEXT("Lower limit percentage to scale the Nanite primary raster MaxPixelsPerEdge value when over budget."),
	ECVF_RenderThreadSafe | ECVF_Default);

// i.e. if r.Nanite.MaxPixelsPerEdge is 1.0 and r.Nanite.ShadowRaster.PixelsPerEdgeScaling is 20%, when heavily over budget r.Nanite.MaxPixelsPerEdge will be scaled to to 5.0
static TAutoConsoleVariable<float> CVarNaniteShadowPixelsPerEdgeScalingPercentage(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Nanite/NaniteCullRaster.cpp:250

Scope: file

Source code excerpt:

);

// i.e. if r.Nanite.MaxPixelsPerEdge is 1.0 and r.Nanite.PrimaryRaster.PixelsPerEdgeScaling is 20%, when heavily over budget r.Nanite.MaxPixelsPerEdge will be scaled to to 5.0
static TAutoConsoleVariable<float> CVarNanitePrimaryPixelsPerEdgeScalingPercentage(
	TEXT("r.Nanite.PrimaryRaster.PixelsPerEdgeScaling"),
	30.0f, // 100% - no scaling - set to < 100% to scale pixel error when over budget
	TEXT("Lower limit percentage to scale the Nanite primary raster MaxPixelsPerEdge value when over budget."),
	ECVF_RenderThreadSafe | ECVF_Default);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Nanite/NaniteCullRaster.cpp:251

Scope: file

Source code excerpt:


// i.e. if r.Nanite.MaxPixelsPerEdge is 1.0 and r.Nanite.PrimaryRaster.PixelsPerEdgeScaling is 20%, when heavily over budget r.Nanite.MaxPixelsPerEdge will be scaled to to 5.0
static TAutoConsoleVariable<float> CVarNanitePrimaryPixelsPerEdgeScalingPercentage(
	TEXT("r.Nanite.PrimaryRaster.PixelsPerEdgeScaling"),
	30.0f, // 100% - no scaling - set to < 100% to scale pixel error when over budget
	TEXT("Lower limit percentage to scale the Nanite primary raster MaxPixelsPerEdge value when over budget."),
	ECVF_RenderThreadSafe | ECVF_Default);

// i.e. if r.Nanite.MaxPixelsPerEdge is 1.0 and r.Nanite.ShadowRaster.PixelsPerEdgeScaling is 20%, when heavily over budget r.Nanite.MaxPixelsPerEdge will be scaled to to 5.0

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Nanite/NaniteCullRaster.cpp:284

Scope (from outer to inner):

file
function     static DynamicRenderScaling::FHeuristicSettings GetDynamicNaniteScalingPrimarySettings

Source code excerpt:

static DynamicRenderScaling::FHeuristicSettings GetDynamicNaniteScalingPrimarySettings()
{
	const float PixelsPerEdgeScalingPercentage = FMath::Clamp(CVarNanitePrimaryPixelsPerEdgeScalingPercentage.GetValueOnAnyThread(), 1.0f, 100.0f);

	DynamicRenderScaling::FHeuristicSettings BucketSetting;
	BucketSetting.Model = DynamicRenderScaling::EHeuristicModel::Linear;
	BucketSetting.bModelScalesWithPrimaryScreenPercentage = false; // r.Nanite.MaxPixelsPerEdge is not scaled by dynamic resolution of the primary view
	BucketSetting.MinResolutionFraction = DynamicRenderScaling::PercentageToFraction(PixelsPerEdgeScalingPercentage);
	BucketSetting.MaxResolutionFraction = DynamicRenderScaling::PercentageToFraction(100.0f);