r.AutoExposure.IgnoreMaterials.UsePrecalculatedIlluminance

r.AutoExposure.IgnoreMaterials.UsePrecalculatedIlluminance

#Overview

name: r.AutoExposure.IgnoreMaterials.UsePrecalculatedIlluminance

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

• type: Var
• help: ``

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.AutoExposure.IgnoreMaterials.UsePrecalculatedIlluminance is to control whether the auto-exposure system in Unreal Engine 5 uses precalculated illuminance values when ignoring materials for exposure calculations.

This setting variable is primarily used in the rendering system, specifically in the post-processing pipeline for auto-exposure and eye adaptation. It is part of the Renderer module in Unreal Engine 5.

The value of this variable is set as a console variable (CVar) in the engine’s rendering code. It is initialized with a default value of true, meaning that by default, the system will use precalculated illuminance values.

This variable interacts closely with another variable named CVarAutoExposureIgnoreMaterials. When both variables are enabled, the engine uses precalculated illuminance values for auto-exposure calculations, ignoring material-specific lighting information.

Developers should be aware that this variable affects the performance and visual quality of the auto-exposure system. Using precalculated illuminance can be faster but may be less accurate in some scenarios compared to real-time material-based calculations.

Best practices when using this variable include:

1. Testing the visual impact of enabling or disabling this feature in various lighting conditions.
2. Considering the performance implications, especially on lower-end hardware.
3. Balancing the use of precalculated illuminance with the need for material-specific lighting information in your scenes.

Regarding the associated variable CVarAutoExposureIgnoreMaterialsUsePrecalculatedIlluminance:

This is the actual C++ variable that controls the behavior described above. It is defined as a TAutoConsoleVariable, which means it can be changed at runtime through console commands.

The variable is used in several parts of the eye adaptation post-processing code to determine whether to use precalculated illuminance values. It affects shader permutations and the execution of specific compute shaders related to exposure calculation.

Developers should note that changes to this variable will immediately affect the rendering pipeline, potentially causing visual changes in the scene’s overall brightness and contrast. It’s important to test thoroughly when modifying this setting to ensure desired visual results across different lighting scenarios in your game or application.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessEyeAdaptation.cpp:111

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

	TAutoConsoleVariable<bool> CVarAutoExposureIgnoreMaterialsUsePrecalculatedIlluminance(
		TEXT("r.AutoExposure.IgnoreMaterials.UsePrecalculatedIlluminance"),
		true,
		TEXT(""),
		ECVF_Scalability | ECVF_RenderThreadSafe);

	TAutoConsoleVariable<int32> CVarAutoExposureIgnoreMaterialsDownscaleFactor(
		TEXT("r.AutoExposure.IgnoreMaterials.DownscaleFactor"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessEyeAdaptation.cpp:110

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

		ECVF_RenderThreadSafe);

	TAutoConsoleVariable<bool> CVarAutoExposureIgnoreMaterialsUsePrecalculatedIlluminance(
		TEXT("r.AutoExposure.IgnoreMaterials.UsePrecalculatedIlluminance"),
		true,
		TEXT(""),
		ECVF_Scalability | ECVF_RenderThreadSafe);

	TAutoConsoleVariable<int32> CVarAutoExposureIgnoreMaterialsDownscaleFactor(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessEyeAdaptation.cpp:147

Scope (from outer to inner):

file
namespace    AutoExposurePermutation
function     FCommonDomain BuildCommonPermutationDomain

Source code excerpt:

		if (CVarAutoExposureIgnoreMaterials.GetValueOnRenderThread())
		{
			if (CVarAutoExposureIgnoreMaterialsUsePrecalculatedIlluminance.GetValueOnRenderThread())
			{
				PermutationVector.Set<FUsePrecalculatedLuminanceDim>(true);
			}
			else
			{
				PermutationVector.Set<FUseApproxIlluminanceDim>(true);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessEyeAdaptation.cpp:662

Scope (from outer to inner):

file
function     FRDGTextureRef AddSetupExposureIlluminancePass

Source code excerpt:

	for (uint32 ViewIndex = 0; ViewIndex < ViewCount; ++ViewIndex)
	{
		bAnyViewEnabled |= IsAutoExposureUsingIlluminanceEnabled(Views[ViewIndex]) && CVarAutoExposureIgnoreMaterialsUsePrecalculatedIlluminance.GetValueOnRenderThread();
	}

	if (!bAnyViewEnabled)
	{
		return nullptr;
	}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessEyeAdaptation.cpp:679

Scope (from outer to inner):

file
function     FRDGTextureRef AddSetupExposureIlluminancePass

Source code excerpt:

		const FViewInfo& View = Views[ViewIndex];

		if (IsAutoExposureUsingIlluminanceEnabled(View) && CVarAutoExposureIgnoreMaterialsUsePrecalculatedIlluminance.GetValueOnRenderThread())
		{
			const FScreenPassTextureViewport SceneViewport(SceneTextures.Config.Extent, View.ViewRect);
			const FScreenPassTextureViewport OutputViewport(GetDownscaledViewport(SceneViewport, GetAutoExposureIlluminanceDownscaleFactor()));

			auto* PassParameters = GraphBuilder.AllocParameters<FSetupExposureIlluminanceCS::FParameters>();
			PassParameters->View = View.ViewUniformBuffer;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessEyeAdaptation.cpp:758

Scope (from outer to inner):

file
function     FRDGTextureRef AddCalculateExposureIlluminancePass

Source code excerpt:

		if (IsAutoExposureUsingIlluminanceEnabled(View))
		{
			check(CVarAutoExposureIgnoreMaterialsUsePrecalculatedIlluminance.GetValueOnRenderThread());

			const FScreenPassTextureViewport SceneViewport(SceneTextures.Config.Extent, View.ViewRect);
			const FScreenPassTextureViewport OutputViewport(GetDownscaledViewport(SceneViewport, GetAutoExposureIlluminanceDownscaleFactor()));

			auto* PassParameters = GraphBuilder.AllocParameters<FCalculateExposureIlluminanceCS::FParameters>();
			PassParameters->View = View.ViewUniformBuffer;