r.Shading.EnergyPreservation

r.Shading.EnergyPreservation

#Overview

name: r.Shading.EnergyPreservation

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.Shading.EnergyPreservation is to control energy preservation in shading models within Unreal Engine 5’s rendering system. Specifically, it manages the energy attenuation on diffuse lighting caused by specular reflection.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, particularly in the shading and lighting subsystems. It’s closely tied to the engine’s energy conservation features for realistic lighting calculations.

The value of this variable is set through a console variable (CVarShadingEnergyConservation_Preservation) in the ShadingEnergyConservation.cpp file. It’s initialized with a default value of 1, meaning it’s enabled by default.

This variable interacts with other energy conservation-related variables, such as CVarMaterialEnergyConservation and CVarShadingEnergyConservation. Together, these variables determine how the engine handles energy conservation and preservation in the rendering process.

Developers must be aware that this variable requires energy conservation to be enabled to have an effect. When disabled (set to 0), it turns off energy preservation on shading models, which might result in less physically accurate lighting but could potentially improve performance.

Best practices when using this variable include:

  1. Keep it enabled (default value of 1) for more physically accurate lighting.
  2. Only disable it if you’re experiencing performance issues and are willing to sacrifice some lighting accuracy.
  3. Consider its interaction with other energy conservation settings when fine-tuning rendering quality and performance.

Regarding the associated variable CVarShadingEnergyConservation_Preservation:

This is the actual console variable that controls the r.Shading.EnergyPreservation setting. It’s defined in the same file (ShadingEnergyConservation.cpp) and serves as the programmatic interface for the r.Shading.EnergyPreservation setting.

The purpose of CVarShadingEnergyConservation_Preservation is to provide a way to access and modify the energy preservation setting at runtime through the console or game code.

This variable is used in the Renderer module, specifically in the ShadingEnergyConservation namespace. It’s typically queried during the rendering process to determine whether energy preservation should be applied.

The value of this variable can be set through the console or programmatically in C++ code. It’s initialized with the same default value (1) as r.Shading.EnergyPreservation.

CVarShadingEnergyConservation_Preservation interacts closely with other energy conservation variables like CVarMaterialEnergyConservation and CVarShadingEnergyConservation. Its value is often checked alongside these other variables to determine the overall energy conservation behavior.

Developers should be aware that changes to this variable will take effect on the render thread, as indicated by the ECVF_RenderThreadSafe flag.

Best practices for using CVarShadingEnergyConservation_Preservation include:

  1. Use it when you need to programmatically control energy preservation in your game code.
  2. Be cautious when modifying it at runtime, as it can affect rendering performance and visual quality.
  3. Consider caching its value if querying it frequently, to avoid potential performance overhead from repeated console variable lookups.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarShadingEnergyConservation_Preservation(
	TEXT("r.Shading.EnergyPreservation"),
	1,
	TEXT("0 to disable energy preservation on shading models, i.e. the energy attenuation on diffuse lighting caused by the specular reflection. Require energy conservation to be enabled\n")
	TEXT(" 0: off\n")
	TEXT(" 1: on"),
	ECVF_RenderThreadSafe);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarShadingEnergyConservation_Preservation(
	TEXT("r.Shading.EnergyPreservation"),
	1,
	TEXT("0 to disable energy preservation on shading models, i.e. the energy attenuation on diffuse lighting caused by the specular reflection. Require energy conservation to be enabled\n")
	TEXT(" 0: off\n")
	TEXT(" 1: on"),
	ECVF_RenderThreadSafe);

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

Scope (from outer to inner):

file
function     namespace ShadingEnergyConservation { bool IsEnable
function     void Init

Source code excerpt:

	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)
	const bool bBindEnergyData = (View.ViewState != nullptr) && (bMaterialEnergyConservationEnabled || Substrate::IsSubstrateEnabled() || (View.Family->EngineShowFlags.PathTracing && RHI_RAYTRACING)) && (bIsEnergyPreservationEnabled || bIsEnergyConservationEnabled);
	if (bBindEnergyData)