r.DistanceFields.Debug.ForceNumMips

r.DistanceFields.Debug.ForceNumMips

#Overview

name: r.DistanceFields.Debug.ForceNumMips

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.DistanceFields.Debug.ForceNumMips is to override the requested number of mips for distance field streaming in Unreal Engine’s rendering system. This variable is primarily used for debugging and testing purposes within the distance field rendering subsystem.

This setting variable is utilized by the Renderer module of Unreal Engine, specifically within the distance field streaming functionality. It’s part of the rendering system that handles distance fields, which are used for various graphical effects and optimizations.

The value of this variable is set through the console variable system in Unreal Engine. It’s defined as a TAutoConsoleVariable with an initial value of 0, which means by default, it doesn’t override the normal mip selection behavior.

The associated variable CVarDebugForceNumMips interacts directly with r.DistanceFields.Debug.ForceNumMips, as they share the same value. This console variable is used to access and modify the setting within the C++ code.

Developers must be aware of several things when using this variable:

  1. It’s intended for debugging purposes and should not be used in production builds.
  2. When set to a value greater than 0, it overrides the normal mip selection logic for distance field streaming.
  3. The value is clamped between 0 and 3, where 1 means only the lowest resolution mip is loaded, and 3 means all mips are loaded.
  4. Even when forcing mip levels, the actual loaded mips may still be limited by the available space in the distance field atlas.

Best practices when using this variable include:

  1. Use it only during development and debugging phases.
  2. Be cautious when setting it to higher values, as it may impact performance by loading more mip levels than necessary.
  3. Remember to reset it to 0 when finished debugging to restore normal distance field streaming behavior.
  4. Use in conjunction with other distance field debugging tools for comprehensive analysis.

Regarding the associated variable CVarDebugForceNumMips:

The purpose of CVarDebugForceNumMips is to provide a programmatic interface to access and modify the r.DistanceFields.Debug.ForceNumMips setting within the C++ code of the Unreal Engine.

This variable is used within the Renderer module, specifically in the distance field streaming system. It allows the engine to read the current value of the debug setting and apply it to the distance field streaming logic.

The value of CVarDebugForceNumMips is set automatically by the console variable system when r.DistanceFields.Debug.ForceNumMips is modified. It reflects the same value as the console variable.

CVarDebugForceNumMips interacts directly with the distance field streaming code. For example, in the GenerateStreamingRequests function, its value is read and clamped to ensure it’s within the valid range for the number of mips.

Developers should be aware that modifying CVarDebugForceNumMips directly in code will not persist the change across engine restarts, as it’s tied to the console variable system.

Best practices for using CVarDebugForceNumMips include:

  1. Use GetValueOnRenderThread() to safely access its value from the render thread.
  2. Always clamp the value to ensure it’s within the valid range for the number of mips.
  3. Consider the performance implications when forcing higher numbers of mips.
  4. Use it in conjunction with other distance field debugging tools and variables for comprehensive analysis.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldStreaming.cpp:79

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarDebugForceNumMips(
	TEXT("r.DistanceFields.Debug.ForceNumMips"),
	0,	
	TEXT("When set to > 0, overrides the requested number of mips for streaming.  1 = only lowest resolution mip loaded, 3 = all mips loaded.  Mips will still be clamped by available space in the atlas."),
	ECVF_RenderThreadSafe);

static int32 GDistanceFieldAtlasLogStats = 0;
static FAutoConsoleVariableRef CVarDistanceFieldAtlasLogStats(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldStreaming.cpp:78

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarDebugForceNumMips(
	TEXT("r.DistanceFields.Debug.ForceNumMips"),
	0,	
	TEXT("When set to > 0, overrides the requested number of mips for streaming.  1 = only lowest resolution mip loaded, 3 = all mips loaded.  Mips will still be clamped by available space in the atlas."),
	ECVF_RenderThreadSafe);

static int32 GDistanceFieldAtlasLogStats = 0;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DistanceFieldStreaming.cpp:1238

Scope (from outer to inner):

file
function     void FDistanceFieldSceneData::GenerateStreamingRequests

Source code excerpt:

			PassParameters->RWDistanceFieldAssetStreamingRequests = GraphBuilder.CreateUAV(StreamingRequestsBuffer);
			PassParameters->DistanceFieldObjectBuffers = DistanceField::SetupObjectBufferParameters(GraphBuilder, *this);
			PassParameters->DebugForceNumMips = FMath::Clamp(CVarDebugForceNumMips.GetValueOnRenderThread(), 0, DistanceField::NumMips);
			extern int32 GAOGlobalDistanceFieldNumClipmaps;
			// Request Mesh SDF mips based off of the Global SDF clipmaps
			PassParameters->Mip1WorldTranslatedCenter = FVector3f(View.ViewMatrices.GetViewOrigin() + View.ViewMatrices.GetPreViewTranslation());
			PassParameters->Mip1WorldExtent = FVector3f(GlobalDistanceField::GetClipmapExtent(GAOGlobalDistanceFieldNumClipmaps - 1, Scene, bLumenEnabled));
			PassParameters->Mip2WorldTranslatedCenter = FVector3f(View.ViewMatrices.GetViewOrigin() + View.ViewMatrices.GetPreViewTranslation());
			PassParameters->Mip2WorldExtent = FVector3f(GlobalDistanceField::GetClipmapExtent(FMath::Max<int32>(GAOGlobalDistanceFieldNumClipmaps / 2 - 1, 0), Scene, bLumenEnabled));