r.Nanite.ShadowRaster.PixelsPerEdgeScaling

r.Nanite.ShadowRaster.PixelsPerEdgeScaling

#Overview

name: r.Nanite.ShadowRaster.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.ShadowRaster.PixelsPerEdgeScaling is to control the scaling of the Nanite shadow 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 for shadow rendering optimization.

This setting variable is primarily used in the Nanite subsystem of Unreal Engine’s rendering module. It’s 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 100.0f, representing 100% scaling (no scaling). Developers can modify this value at runtime through console commands or programming interfaces.

The r.Nanite.ShadowRaster.PixelsPerEdgeScaling variable interacts closely with r.Nanite.MaxPixelsPerEdge. When the rendering system is over budget, r.Nanite.MaxPixelsPerEdge is scaled based on the percentage set in r.Nanite.ShadowRaster.PixelsPerEdgeScaling.

Developers must be aware that:

  1. This variable affects shadow rendering performance and quality.
  2. Lower values will reduce shadow quality but improve performance when the system is over budget.
  3. The value is clamped between 1.0f and 100.0f for safety.

Best practices when using this variable include:

  1. Only modify it if you’re experiencing performance issues with shadow rendering.
  2. Test thoroughly after changes, as it can significantly impact visual quality.
  3. Consider using it in conjunction with other Nanite and shadow-related settings for optimal results.

Regarding the associated variable CVarNaniteShadowPixelsPerEdgeScalingPercentage:

This is the actual console variable that stores and manages the r.Nanite.ShadowRaster.PixelsPerEdgeScaling value. It’s defined as a TAutoConsoleVariable, which allows it to be easily accessed and modified at runtime.

The purpose of CVarNaniteShadowPixelsPerEdgeScalingPercentage is to provide a programmatic interface for the r.Nanite.ShadowRaster.PixelsPerEdgeScaling setting. It’s used internally by the engine to read and apply the scaling value.

This variable is used in the GetDynamicNaniteScalingShadowSettings() function to determine the minimum resolution fraction for dynamic Nanite scaling in shadow rendering. The value is clamped between 1.0f and 100.0f for safety before being used.

Developers should be aware that modifying CVarNaniteShadowPixelsPerEdgeScalingPercentage directly in code will have the same effect as changing r.Nanite.ShadowRaster.PixelsPerEdgeScaling through console commands.

Best practices for using CVarNaniteShadowPixelsPerEdgeScalingPercentage include:

  1. Use it when you need programmatic control over the Nanite shadow raster scaling.
  2. Remember to use GetValueOnAnyThread() when accessing its value, as shown in the provided code.
  3. Consider exposing it through game settings if you want to give users control over this aspect of shadow quality vs. performance.

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

Scope: file

Source code excerpt:

// 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(
	TEXT("r.Nanite.ShadowRaster.PixelsPerEdgeScaling"),
	100.0f, // 100% - no scaling - set to < 100% to scale pixel error when over budget
	TEXT("Lower limit percentage to scale the Nanite shadow raster MaxPixelsPerEdge value when over budget."),
	ECVF_RenderThreadSafe | ECVF_Default);

static TAutoConsoleVariable<float> CVarNanitePrimaryTimeBudgetMs(
	TEXT("r.Nanite.PrimaryRaster.TimeBudgetMs"),

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

Scope: file

Source code excerpt:

	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(
	TEXT("r.Nanite.ShadowRaster.PixelsPerEdgeScaling"),
	100.0f, // 100% - no scaling - set to < 100% to scale pixel error when over budget
	TEXT("Lower limit percentage to scale the Nanite shadow raster MaxPixelsPerEdge value when over budget."),
	ECVF_RenderThreadSafe | ECVF_Default);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:


// 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(
	TEXT("r.Nanite.ShadowRaster.PixelsPerEdgeScaling"),
	100.0f, // 100% - no scaling - set to < 100% to scale pixel error when over budget
	TEXT("Lower limit percentage to scale the Nanite shadow raster MaxPixelsPerEdge value when over budget."),
	ECVF_RenderThreadSafe | ECVF_Default);

static TAutoConsoleVariable<float> CVarNanitePrimaryTimeBudgetMs(

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

Scope (from outer to inner):

file
function     static DynamicRenderScaling::FHeuristicSettings GetDynamicNaniteScalingShadowSettings

Source code excerpt:

static DynamicRenderScaling::FHeuristicSettings GetDynamicNaniteScalingShadowSettings()
{
	const float PixelsPerEdgeScalingPercentage = FMath::Clamp(CVarNaniteShadowPixelsPerEdgeScalingPercentage.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);