r.Material.EnergyConservation

r.Material.EnergyConservation

#Overview

name: r.Material.EnergyConservation

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 r.Material.EnergyConservation is to enable energy conservation for legacy materials in Unreal Engine’s rendering system. This setting is primarily used in the context of material shading and lighting calculations.

This setting variable is primarily relied upon by the Renderer module of Unreal Engine, as evidenced by its usage in the ShadingEnergyConservation.cpp file. It also affects shader compilation, as seen in the ShaderCompiler.cpp and Shader.cpp files.

The value of this variable is set through a console variable (CVar) system, which allows it to be modified at runtime or through configuration files. It’s defined as a read-only variable, meaning its value is typically set at project startup and not meant to be changed during runtime.

The associated variable CVarMaterialEnergyConservation directly interacts with r.Material.EnergyConservation, as they share the same value and purpose.

Developers must be aware of several important points when using this variable:

  1. It’s a read-only variable, so it should not be modified during runtime.
  2. When Substrate (a newer material system in UE5) is enabled, energy conservation is forced on regardless of this setting.
  3. This setting affects shader compilation and may require shader recompilation when changed.
  4. It’s specifically for legacy materials, implying it may not affect newer material systems.

Best practices when using this variable include:

  1. Set it appropriately in project settings rather than trying to modify it at runtime.
  2. Be aware of its impact on rendering performance and visual fidelity.
  3. Consider its interaction with other rendering settings, especially those related to lighting and materials.
  4. When transitioning to newer material systems like Substrate, be prepared to phase out reliance on this variable.

Regarding the associated variable CVarMaterialEnergyConservation:

The purpose of CVarMaterialEnergyConservation is to serve as the actual console variable that controls the r.Material.EnergyConservation setting. It’s defined in the Renderer module and is used to store and retrieve the current value of the energy conservation setting.

This variable is used directly in the rendering code to determine whether energy conservation should be applied. It’s checked in the ShadingEnergyConservation::Init function to enable or disable energy conservation features.

The value of CVarMaterialEnergyConservation is set when the console variable is initialized, defaulting to 0 (disabled). It can be changed through console commands or configuration files, but its ECVF_ReadOnly flag suggests that it’s not intended to be modified during runtime.

Developers should be aware that this is the actual variable being queried when the energy conservation setting is checked in various parts of the engine. Changes to this variable will directly affect the behavior of the energy conservation system.

Best practices for CVarMaterialEnergyConservation align with those of r.Material.EnergyConservation, as they are effectively the same setting. Developers should treat it as a project-level setting and be cautious about changing it, especially in shipping builds.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadingEnergyConservation.cpp:49

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarMaterialEnergyConservation(
	TEXT("r.Material.EnergyConservation"),
	0,
	TEXT("Enable energy conservation for legacy materials (project settings, read only). Please note that when Substrate is enabled, energy conservation is forced to enabled."),
	ECVF_ReadOnly | ECVF_RenderThreadSafe);

#define SHADING_ENERGY_CONSERVATION_TABLE_RESOLUTION 32

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp:8572

Scope (from outer to inner):

file
function     void GlobalBeginCompileShader

Source code excerpt:


	{
		static IConsoleVariable* CVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.Material.EnergyConservation"));
		const bool bMaterialEnergyConservation = CVar && CVar->GetInt() != 0;
		SET_SHADER_DEFINE(Input.Environment, LEGACY_MATERIAL_ENERGYCONSERVATION, bMaterialEnergyConservation ? 1 : 0);
	}

	{
		static IConsoleVariable* CVar = IConsoleManager::Get().FindConsoleVariable(TEXT("r.SupportSkyAtmosphereAffectsHeightFog"));

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/Shader.cpp:2128

Scope (from outer to inner):

file
function     void ShaderMapAppendKeyString

Source code excerpt:


	{
		static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.Material.EnergyConservation"));
		if (CVar && CVar->GetValueOnAnyThread() > 0)
		{
			KeyString += FString::Printf(TEXT("_MATENERGY"));
		}
	}

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadingEnergyConservation.cpp:48

Scope: file

Source code excerpt:

// Transition render settings that will disapear when Substrate gets enabled

static TAutoConsoleVariable<int32> CVarMaterialEnergyConservation(
	TEXT("r.Material.EnergyConservation"),
	0,
	TEXT("Enable energy conservation for legacy materials (project settings, read only). Please note that when Substrate is enabled, energy conservation is forced to enabled."),
	ECVF_ReadOnly | ECVF_RenderThreadSafe);

#define SHADING_ENERGY_CONSERVATION_TABLE_RESOLUTION 32

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShadingEnergyConservation.cpp:220

Scope (from outer to inner):

file
function     namespace ShadingEnergyConservation { bool IsEnable
function     void Init

Source code excerpt:


	// Enabled based on settings
	const bool bMaterialEnergyConservationEnabled = CVarMaterialEnergyConservation.GetValueOnRenderThread() > 0;
	const bool bIsEnergyConservationEnabled = CVarShadingEnergyConservation.GetValueOnRenderThread() > 0;
	const bool bIsEnergyPreservationEnabled = CVarShadingEnergyConservation_Preservation.GetValueOnRenderThread() > 0;	

	// Build/bind table if energy conservation is enabled or if Substrate is enabled in order to have 
	// the correct tables built & bound. Even if we are not using energy conservation, we want to 
	// have access to directional albedo information for env. lighting for instance)