wp.Runtime.HLOD.WarmupNumFrames

wp.Runtime.HLOD.WarmupNumFrames

#Overview

name: wp.Runtime.HLOD.WarmupNumFrames

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of wp.Runtime.HLOD.WarmupNumFrames is to control the delay in unloading a cell to ensure HLOD (Hierarchical Level of Detail) assets are ready to be shown at the proper resolution. This setting is part of the HLOD system in Unreal Engine 5, which is used for optimizing rendering performance in large, open-world environments.

This setting variable is primarily used by the World Partition HLOD Runtime Subsystem, which is part of the Engine module. It’s specifically utilized in the management and preparation of HLOD assets for rendering.

The value of this variable is set as a console variable (CVar) with a default value of 5 frames. It can be modified at runtime through the console or programmatically.

The associated variable CVarHLODWarmupNumFrames directly interacts with wp.Runtime.HLOD.WarmupNumFrames. They share the same value and are used interchangeably in the code.

Developers should be aware that:

  1. Setting this value to 0 will force disable the warmup feature.
  2. The value affects the performance and visual quality trade-off. A higher value ensures smoother transitions but may impact performance.
  3. It’s used in conjunction with other HLOD-related settings, such as wp.Runtime.HLOD.WarmupEnabled.

Best practices when using this variable include:

  1. Adjusting the value based on the specific needs of the project and target hardware capabilities.
  2. Testing different values to find the optimal balance between visual quality and performance.
  3. Considering the interaction with other HLOD settings for a comprehensive optimization strategy.

Regarding the associated variable CVarHLODWarmupNumFrames:

The purpose of CVarHLODWarmupNumFrames is identical to wp.Runtime.HLOD.WarmupNumFrames, as they share the same value and functionality.

It’s used directly in the HLOD Runtime Subsystem to control the warmup behavior of HLOD assets. The variable is accessed in various functions within the HLODRuntimeSubsystem.cpp file, including PrepareToWarmup, ShouldPerformWarmup, and OnBeginRenderViews.

The value is typically retrieved using GetValueOnGameThread() method, indicating that it can be accessed and potentially modified during runtime.

Developers should be aware that this variable directly affects the HLOD system’s behavior and performance. It’s crucial for determining how many frames an HLOD asset will be prepared before it’s needed for rendering.

Best practices include using this variable in conjunction with other HLOD-related settings for comprehensive HLOD system tuning, and potentially exposing it as a configurable setting for different performance profiles in the game.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/WorldPartition/HLOD/HLODRuntimeSubsystem.cpp:52

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarHLODWarmupNumFrames(
	TEXT("wp.Runtime.HLOD.WarmupNumFrames"),
	5,
	TEXT("Delay unloading of a cell for this amount of frames to ensure HLOD assets are ready to be shown at the proper resolution. Set to 0 to force disable warmup."));

static TAutoConsoleVariable<int32> CVarHLODWarmupDebugDraw(
	TEXT("wp.Runtime.HLOD.WarmupDebugDraw"),
	0,

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/WorldPartition/HLOD/HLODRuntimeSubsystem.cpp:51

Scope: file

Source code excerpt:

	TEXT("Enable Nanite warmup for HLOD assets. Requires wp.Runtime.HLOD.WarmupEnabled to be 1."));

static TAutoConsoleVariable<int32> CVarHLODWarmupNumFrames(
	TEXT("wp.Runtime.HLOD.WarmupNumFrames"),
	5,
	TEXT("Delay unloading of a cell for this amount of frames to ensure HLOD assets are ready to be shown at the proper resolution. Set to 0 to force disable warmup."));

static TAutoConsoleVariable<int32> CVarHLODWarmupDebugDraw(
	TEXT("wp.Runtime.HLOD.WarmupDebugDraw"),

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/WorldPartition/HLOD/HLODRuntimeSubsystem.cpp:449

Scope (from outer to inner):

file
function     bool UWorldPartitionHLODRuntimeSubsystem::PrepareToWarmup

Source code excerpt:

		FWorldPartitionHLODWarmupState& WarmupState = HLODActorsToWarmup.FindOrAdd(InHLODActor);

		// Trigger warmup for CVarHLODWarmupNumFrames frames on the first request, or if a warmup wasn't requested in the last frame
		const bool bResetWarmup =  WarmupState.WarmupLastRequestedFrame == INDEX_NONE ||
								  (WarmupState.WarmupLastRequestedFrame + 1) < GFrameNumber;
				
		if (bResetWarmup)
		{
			WarmupState.WarmupCallsUntilReady = CVarHLODWarmupNumFrames.GetValueOnGameThread();
			WarmupState.WarmupBounds = InCell->GetContentBounds();

			// If we're dealing with an instanced world partition, take the instance transform into account
			const UWorldPartition* WorldPartition = InCell->GetOuterWorld()->GetWorldPartition();
			if (ensure(WorldPartition) && !WorldPartition->IsMainWorldPartition())
			{

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/WorldPartition/HLOD/HLODRuntimeSubsystem.cpp:493

Scope (from outer to inner):

file
function     bool UWorldPartitionHLODRuntimeSubsystem::ShouldPerformWarmup

Source code excerpt:


	// If warmup num of frames is invalid, no warmup needed
	if (CVarHLODWarmupNumFrames.GetValueOnGameThread() <= 0)
	{
		return false;
	}

	// If warmup num of frames is invalid, no warmup needed
	const EShaderPlatform ShaderPlatform = GShaderPlatformForFeatureLevel[GMaxRHIFeatureLevel];

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/WorldPartition/HLOD/HLODRuntimeSubsystem.cpp:693

Scope (from outer to inner):

file
function     void UWorldPartitionHLODRuntimeSubsystem::OnBeginRenderViews
lambda-function

Source code excerpt:

					if (bWarmupNanite)
					{
						if (HLODWarmupState.WarmupCallsUntilReady == CVarHLODWarmupNumFrames.GetValueOnGameThread())
						{
							// Send a nanite request to prepare for visibility in CVarHLODWarmupNumFrames frames
							PrepareNaniteRequests(NaniteRequests, SMC, CVarHLODWarmupNumFrames.GetValueOnGameThread());
						}
						else if (HLODWarmupState.WarmupCallsUntilReady == 0)
						{
							// We expect HLOD to be visible at any moment (likely waiting for server visibility ack)
							PrepareNaniteRequests(NaniteRequests, SMC, 1);
						}