r.Shading.EnergyConservation

r.Shading.EnergyConservation

#Overview

name: r.Shading.EnergyConservation

This variable is created as a Console Variable (cvar).

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Shading.EnergyConservation is to control energy conservation on shading models in Unreal Engine 5’s rendering system. It is a boolean flag that enables or disables energy conservation in the shading process.

This setting variable is primarily used in the Renderer module of Unreal Engine 5, specifically within the shading and energy conservation subsystem. The code references are found in the ShadingEnergyConservation.cpp file, which suggests that this variable is crucial for managing energy conservation in the rendering pipeline.

The value of this variable is set through a console variable (CVarShadingEnergyConservation) with a default value of 1 (enabled). It can be changed at runtime using console commands or through engine configuration files.

The associated variable CVarShadingEnergyConservation directly interacts with r.Shading.EnergyConservation. They share the same value and purpose, with CVarShadingEnergyConservation being the actual TAutoConsoleVariable used in the C++ code to access and modify the setting.

Developers must be aware that this variable affects the rendering quality and performance. Enabling energy conservation (value > 0) ensures more physically accurate shading but may have a performance impact. Disabling it (value = 0) might improve performance at the cost of less realistic lighting.

Best practices when using this variable include:

  1. Keep it enabled (default value of 1) for most scenarios to maintain physically accurate lighting.
  2. Consider disabling it only when performance is critical and the loss in lighting accuracy is acceptable.
  3. Test thoroughly when changing this setting, as it can significantly impact the visual quality of your game.
  4. Be aware of its interaction with other rendering settings, such as material energy conservation and Substrate rendering.

Regarding the associated variable CVarShadingEnergyConservation:

The purpose of CVarShadingEnergyConservation is to provide a programmatic way to access and modify the r.Shading.EnergyConservation setting within the C++ code of Unreal Engine 5.

This console variable is used in the Renderer module, specifically in the shading energy conservation system. It allows the engine to check the current state of energy conservation and make rendering decisions based on its value.

The value of CVarShadingEnergyConservation is set when the console variable is initialized, but it can be modified at runtime through console commands or engine configuration changes.

CVarShadingEnergyConservation interacts directly with r.Shading.EnergyConservation, effectively serving as its representation within the C++ code.

Developers should be aware that this variable is used in conditional statements to determine whether energy conservation should be applied in various rendering scenarios. It’s important to understand that changing its value will have immediate effects on the rendering pipeline.

Best practices for using CVarShadingEnergyConservation include:

  1. Use the provided IsEnable() function to check the current state of energy conservation.
  2. Be cautious when directly accessing or modifying this variable, as it can affect the entire rendering system.
  3. Consider the performance implications when enabling or disabling energy conservation through this variable.
  4. Ensure that any code depending on this variable handles both enabled and disabled states correctly.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarShadingEnergyConservation(
	TEXT("r.Shading.EnergyConservation"),
	1,
	TEXT("0 to disable energy conservation on shading models.\n")
	TEXT(" 0: off\n")
	TEXT(" 1: on"),
	ECVF_RenderThreadSafe);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

#include "Substrate/Substrate.h"

static TAutoConsoleVariable<int32> CVarShadingEnergyConservation(
	TEXT("r.Shading.EnergyConservation"),
	1,
	TEXT("0 to disable energy conservation on shading models.\n")
	TEXT(" 0: off\n")
	TEXT(" 1: on"),
	ECVF_RenderThreadSafe);

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

Scope (from outer to inner):

file
function     namespace ShadingEnergyConservation { bool IsEnable
function     bool IsEnable

Source code excerpt:

bool IsEnable()
{
	return CVarShadingEnergyConservation.GetValueOnAnyThread() > 0;
}

void Init(FRDGBuilder& GraphBuilder, FViewInfo& View)
{
	FRDGTextureRef GGXSpecEnergyTexture = nullptr;
	FRDGTextureRef GGXGlassEnergyTexture = nullptr;

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

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