MaterialBaking.UseMaterialProxyCaching

MaterialBaking.UseMaterialProxyCaching

#Overview

name: MaterialBaking.UseMaterialProxyCaching

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 MaterialBaking.UseMaterialProxyCaching is to control whether Material Proxies should be cached to speed up the material baking process in Unreal Engine 5.

This setting variable is primarily used in the Material Baking module of Unreal Engine 5. It affects the performance and behavior of the material baking workflow, which is part of the rendering system.

The value of this variable is set through a console variable (CVar) named CVarUseMaterialProxyCaching. It is initialized with a default value of 1 (enabled) but can be changed at runtime through console commands or project settings.

The main variable that interacts with it is the MaterialProxyPool, which is a TMultiMap that stores cached material proxies when the caching feature is enabled.

Developers should be aware that:

  1. When enabled (set to 1), material proxies are cached, which can significantly speed up material baking processes, especially when working with complex materials or performing multiple baking operations.
  2. The cached proxies remain resident in memory, which could increase memory usage.
  3. Changes to source materials may not be immediately reflected in baked results if caching is enabled, as the system might use cached proxies.

Best practices when using this variable include:

  1. Enable it (set to 1) for improved performance during development and iteration.
  2. Consider disabling it (set to 0) when making frequent changes to materials to ensure the latest changes are always baked.
  3. Be mindful of memory usage when working with a large number of complex materials, as the cache can grow quite large.

Regarding the associated variable CVarUseMaterialProxyCaching:

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Developer/MaterialBaking/Private/MaterialBakingModule.cpp:40

Scope: file

Source code excerpt:

/** Cvars for advanced features */
static TAutoConsoleVariable<int32> CVarUseMaterialProxyCaching(
	TEXT("MaterialBaking.UseMaterialProxyCaching"),
	1,
	TEXT("Determines whether or not Material Proxies should be cached to speed up material baking.\n")
	TEXT("0: Turned Off\n")
	TEXT("1: Turned On"),	
	ECVF_Default);

#Loc: <Workspace>/Engine/Source/Developer/MaterialBaking/Private/MaterialBakingModule.h:61

Scope (from outer to inner):

file
function     class MATERIALBAKING_API FMaterialBakingModule : public IMaterialBakingModule { public: /** IModuleInterface overrides begin */ virtual void StartupModule

Source code excerpt:

	UTextureRenderTarget2D* CreateRenderTarget(FMaterialPropertyEx InProperty, const FIntPoint& InTargetSize, bool bInUsePooledRenderTargets, const FColor& BackgroundColor);

	/* Creates and adds (or reuses a ExportMaterialProxy from the pool if MaterialBaking.UseMaterialProxyCaching is set to 1) */
	FExportMaterialProxy* CreateMaterialProxy(const FMaterialDataEx* MaterialSettings, const FMaterialPropertyEx& Property);

	/** Cleans up all cached material proxies in MaterialProxyPool */
	void CleanupMaterialProxies();

	/** Free up all pooled render targets */

#Loc: <Workspace>/Engine/Source/Developer/MaterialBaking/Private/MaterialBakingModule.h:86

Scope (from outer to inner):

file
function     class MATERIALBAKING_API FMaterialBakingModule : public IMaterialBakingModule { public: /** IModuleInterface overrides begin */ virtual void StartupModule

Source code excerpt:

	TArray<TStrongObjectPtr<UTextureRenderTarget2D>> RenderTargetPool;

	/** Pool of cached material proxies to optimize material baking workflow, stays resident when MaterialBaking.UseMaterialProxyCaching is set to 1 */
	typedef TWeakObjectPtr<UMaterialInterface>				FMaterialPoolKey;
	typedef TPair<FMaterialPropertyEx, FExportMaterialProxy*> FMaterialPoolValue;
	typedef TMultiMap<FMaterialPoolKey, FMaterialPoolValue, FDefaultSetAllocator, TWeakObjectPtrMapKeyFuncs<FMaterialPoolKey, FMaterialPoolValue, true /*bInAllowDuplicateKeys*/>> FMaterialPoolMap;
	FMaterialPoolMap MaterialProxyPool;

	/** Pixel formats to use for baking out specific material properties */

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Developer/MaterialBaking/Private/MaterialBakingModule.cpp:39

Scope: file

Source code excerpt:


/** Cvars for advanced features */
static TAutoConsoleVariable<int32> CVarUseMaterialProxyCaching(
	TEXT("MaterialBaking.UseMaterialProxyCaching"),
	1,
	TEXT("Determines whether or not Material Proxies should be cached to speed up material baking.\n")
	TEXT("0: Turned Off\n")
	TEXT("1: Turned On"),	
	ECVF_Default);

#Loc: <Workspace>/Engine/Source/Developer/MaterialBaking/Private/MaterialBakingModule.cpp:1360

Scope (from outer to inner):

file
function     void FMaterialBakingModule::OnObjectModified

Source code excerpt:

	TRACE_CPUPROFILER_EVENT_SCOPE(FMaterialBakingModule::OnObjectModified)

	if (CVarUseMaterialProxyCaching.GetValueOnAnyThread())
	{
		UMaterialInterface* MaterialToInvalidate = Cast<UMaterialInterface>(Object);
		if (!MaterialToInvalidate)
		{
			// Check to see if the object is a material editor instance constant and if so, retrieve its source instance
			UMaterialEditorInstanceConstant* EditorInstance = Cast<UMaterialEditorInstanceConstant>(Object);