r.Streaming.UseBackgroundThreadPool

r.Streaming.UseBackgroundThreadPool

#Overview

name: r.Streaming.UseBackgroundThreadPool

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.Streaming.UseBackgroundThreadPool is to control whether the background thread pool is used for mip calculations in the texture streaming system. This setting variable is part of Unreal Engine’s rendering and asset streaming subsystem.

The Unreal Engine subsystem that relies on this setting variable is the Render Asset Streaming Manager, specifically within the texture streaming module. This can be seen from the file location (StreamingManagerTexture.cpp) and the class name (FRenderAssetStreamingManager) in the provided code snippets.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 1 (true) in the code, but can be changed at runtime through console commands or configuration files.

The associated variable CVarUseBackgroundThreadPool directly interacts with r.Streaming.UseBackgroundThreadPool. They share the same value and purpose.

Developers must be aware that this variable affects the threading behavior of mip calculations in texture streaming. When set to true (1), it uses the background thread pool, which may impact performance and resource utilization.

Best practices when using this variable include:

  1. Consider the target platform’s capabilities and threading model.
  2. Monitor performance metrics to ensure optimal streaming performance.
  3. Test thoroughly with both enabled and disabled states to determine the best setting for your specific game or application.

Regarding the associated variable CVarUseBackgroundThreadPool:

The purpose of CVarUseBackgroundThreadPool is to provide programmatic access to the r.Streaming.UseBackgroundThreadPool setting within the C++ code.

It’s used directly in the FRenderAssetStreamingManager::UpdateResourceStreaming function to determine which thread pool to use for the background task (either GBackgroundPriorityThreadPool or GThreadPool).

The value of CVarUseBackgroundThreadPool is set automatically by the CVar system based on the r.Streaming.UseBackgroundThreadPool setting.

Developers should be aware that changes to r.Streaming.UseBackgroundThreadPool will affect the behavior of code that uses CVarUseBackgroundThreadPool.GetValueOnGameThread().

Best practices for using CVarUseBackgroundThreadPool include:

  1. Use GetValueOnGameThread() to access its current value, as shown in the provided code.
  2. Be aware of potential performance implications when switching between thread pools.
  3. Consider caching the value if it’s accessed frequently, as GetValueOnGameThread() may have some overhead.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Streaming/StreamingManagerTexture.cpp:1701

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarUseBackgroundThreadPool(
	TEXT("r.Streaming.UseBackgroundThreadPool"),
	1,
	TEXT("If true, use the background thread pool for mip calculations."));

class FUpdateStreamingRenderAssetsTask
{
	FRenderAssetStreamingManager* Manager;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Streaming/StreamingManagerTexture.cpp:1700

Scope: file

Source code excerpt:

 */

static TAutoConsoleVariable<int32> CVarUseBackgroundThreadPool(
	TEXT("r.Streaming.UseBackgroundThreadPool"),
	1,
	TEXT("If true, use the background thread pool for mip calculations."));

class FUpdateStreamingRenderAssetsTask
{

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Streaming/StreamingManagerTexture.cpp:1813

Scope (from outer to inner):

file
function     void FRenderAssetStreamingManager::UpdateResourceStreaming

Source code excerpt:

		UpdatePendingStates(false);
		PrepareAsyncTask(bProcessEverything || Settings.bStressTest);
		AsyncWork->StartBackgroundTask(CVarUseBackgroundThreadPool.GetValueOnGameThread() ? GBackgroundPriorityThreadPool : GThreadPool);
		TickFastResponseAssets();
		++ProcessingStage;

		STAT(GatheredStats.SetupAsyncTaskCycles += FPlatformTime::Cycles();)
	}
	else if (ProcessingStage <= NumRenderAssetProcessingStages)