r.EyeAdaptation.BlackHistogramBucketInfluence

r.EyeAdaptation.BlackHistogramBucketInfluence

#Overview

name: r.EyeAdaptation.BlackHistogramBucketInfluence

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.EyeAdaptation.BlackHistogramBucketInfluence is to control the weight applied to completely dark (0.0) values in the exposure histogram for eye adaptation in the rendering system. This setting variable is part of Unreal Engine 5’s post-processing and rendering subsystem, specifically related to the eye adaptation (auto-exposure) feature.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, particularly the post-processing component responsible for eye adaptation. This can be seen from the file location: “Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessEyeAdaptation.cpp”.

The value of this variable is set through the console variable system. It’s defined as a TAutoConsoleVariable with a default value of 0.0, which means by default, fully dark pixels have no influence on the exposure histogram.

This variable interacts with the exposure histogram calculation in the eye adaptation process. It’s used in conjunction with other eye adaptation parameters to determine the final exposure value for the scene.

Developers must be aware that:

  1. The value ranges from 0.0 to 1.0, where 0.0 means fully dark pixels have no influence, and 1.0 means they accumulate normally in the histogram.
  2. Changing this value can significantly affect the overall brightness and contrast of the scene, especially in scenes with large dark areas.

Best practices when using this variable include:

  1. Use it in conjunction with other eye adaptation settings for fine-tuning the exposure of your scenes.
  2. Test the effects in various lighting conditions to ensure consistent results across different environments in your game.
  3. Consider exposing this setting to artists or technical artists for easier adjustment during the development process.

Regarding the associated variable CVarEyeAdaptationBlackHistogramBucketInfluence:

This is the actual console variable object that stores and manages the r.EyeAdaptation.BlackHistogramBucketInfluence setting. It’s defined as a TAutoConsoleVariable, which means it’s a float value that can be changed at runtime through the console.

The value of this variable is retrieved in the GetEyeAdaptationParameters function, which suggests it’s used in calculating the final eye adaptation parameters for the rendering process.

When working with this variable, developers should:

  1. Use GetValueOnRenderThread() to safely access its value from the render thread.
  2. Be aware that changes to this value will affect the rendering in real-time, which can be useful for debugging but should be used carefully in production.
  3. Consider caching the value if it’s accessed frequently, to avoid potential performance impacts from repeatedly querying the console variable system.

#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:64

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:


	TAutoConsoleVariable<float> CVarEyeAdaptationBlackHistogramBucketInfluence(
		TEXT("r.EyeAdaptation.BlackHistogramBucketInfluence"),
		0.0,
		TEXT("This parameter controls how much weight to apply to completely dark 0.0 values in the exposure histogram.\n")
		TEXT("When set to 1.0, fully dark pixels will accumulate normally, whereas when set to 0.0 fully dark pixels\n")
		TEXT("will have no influence.\n"),
		ECVF_RenderThreadSafe);

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

		ECVF_RenderThreadSafe);

	TAutoConsoleVariable<float> CVarEyeAdaptationBlackHistogramBucketInfluence(
		TEXT("r.EyeAdaptation.BlackHistogramBucketInfluence"),
		0.0,
		TEXT("This parameter controls how much weight to apply to completely dark 0.0 values in the exposure histogram.\n")
		TEXT("When set to 1.0, fully dark pixels will accumulate normally, whereas when set to 0.0 fully dark pixels\n")
		TEXT("will have no influence.\n"),
		ECVF_RenderThreadSafe);

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

Scope (from outer to inner):

file
function     FEyeAdaptationParameters GetEyeAdaptationParameters

Source code excerpt:

	// Get the exposure compensation from the curve
	float ExposureCompensationCurve = GetAutoExposureCompensationFromCurve(View);
	const float BlackHistogramBucketInfluence = CVarEyeAdaptationBlackHistogramBucketInfluence.GetValueOnRenderThread();

	const float kMiddleGrey = 0.18f;

	// AEM_Histogram and AEM_Basic adjust their ExposureCompensation to middle grey (0.18). AEM_Manual ExposureCompensation is already calibrated to 1.0.
	const float GreyMult = (AutoExposureMethod == AEM_Manual) ? 1.0f : kMiddleGrey;