MaterialUtilities.WarmupFrames

MaterialUtilities.WarmupFrames

#Overview

name: MaterialUtilities.WarmupFrames

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 MaterialUtilities.WarmupFrames is to control the number of frames rendered before each capture in order to warm up various rendering systems such as Virtual Texturing (VT) and Nanite.

This setting variable is primarily used in the MaterialUtilities module, which is part of the Unreal Engine’s rendering and material system. Based on the callsites, it’s clear that this variable is utilized in the process of rendering scenes, particularly when capturing or generating material-related content.

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

The associated variable CVarMaterialUtilitiesWarmupFrames interacts directly with MaterialUtilities.WarmupFrames. It’s an instance of TAutoConsoleVariable that wraps the console variable and provides an interface for accessing its value.

Developers must be aware that this variable affects the performance and quality of material-related captures. Increasing the number of warmup frames may improve the quality of the final capture but will also increase the time required for the operation.

Best practices when using this variable include:

  1. Adjusting the value based on the complexity of the scene and the specific rendering systems in use.
  2. Monitoring performance impact when modifying this value, especially in performance-sensitive scenarios.
  3. Considering project-specific needs when setting this value, as different projects may require different warmup periods.

Regarding the associated variable CVarMaterialUtilitiesWarmupFrames:

The purpose of CVarMaterialUtilitiesWarmupFrames is to provide programmatic access to the MaterialUtilities.WarmupFrames console variable within the C++ code.

This variable is used directly in the MaterialUtilities module, specifically in the PerformSceneRender function. It determines how many times the scene is rendered before the final capture.

The value of this variable is set when the console variable is initialized, but it can be changed at runtime using console commands or through C++ code using the SetValueOnGameThread method.

CVarMaterialUtilitiesWarmupFrames interacts directly with the MaterialUtilities.WarmupFrames console variable, essentially serving as its C++ representation.

Developers should be aware that changes to this variable will immediately affect the rendering process, potentially impacting performance and quality.

Best practices for using CVarMaterialUtilitiesWarmupFrames include:

  1. Using GetValueOnGameThread() to retrieve the current value when needed in C++ code.
  2. Considering thread safety when accessing or modifying this value in multi-threaded contexts.
  3. Using this variable in conjunction with other rendering settings to achieve the desired balance between quality and performance.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Developer/MaterialUtilities/Private/MaterialUtilities.cpp:65

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarMaterialUtilitiesWarmupFrames(
	TEXT("MaterialUtilities.WarmupFrames"),
	10,
	TEXT("Number of frames to render before each capture in order to warmup various rendering systems (VT/Nanite/etc)."));


bool FMaterialUtilities::CurrentlyRendering = false;
TArray<UTextureRenderTarget2D*> FMaterialUtilities::RenderTargetPool;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Developer/MaterialUtilities/Private/MaterialUtilities.cpp:64

Scope: file

Source code excerpt:

DEFINE_LOG_CATEGORY_STATIC(LogMaterialUtilities, Log, All);

static TAutoConsoleVariable<int32> CVarMaterialUtilitiesWarmupFrames(
	TEXT("MaterialUtilities.WarmupFrames"),
	10,
	TEXT("Number of frames to render before each capture in order to warmup various rendering systems (VT/Nanite/etc)."));


bool FMaterialUtilities::CurrentlyRendering = false;

#Loc: <Workspace>/Engine/Source/Developer/MaterialUtilities/Private/MaterialUtilities.cpp:786

Scope: file

Source code excerpt:

/**
 * Render the scene to the provided canvas. Will potentially perform the render multiple times, depending on the value of
 * the CVarMaterialUtilitiesWarmupFrames CVar. This is needed to ensure various rendering systems are primed properly before capturing
 * the scene.
 */
static void PerformSceneRender(FCanvas& Canvas, FSceneViewFamily& ViewFamily, bool bWithWarmup)
{
	if (bWithWarmup)
	{
		for (int32 i = 0; i < CVarMaterialUtilitiesWarmupFrames.GetValueOnGameThread(); i++)
		{
			GetRendererModule().BeginRenderingViewFamily(&Canvas, &ViewFamily);
		}
	}

	GetRendererModule().BeginRenderingViewFamily(&Canvas, &ViewFamily);