r.TranslucentLightingVolume

r.TranslucentLightingVolume

#Overview

name: r.TranslucentLightingVolume

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

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

It is referenced in 8 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.TranslucentLightingVolume is to control the updating of translucent lighting volumes in Unreal Engine’s rendering system. This setting variable is primarily used for managing the translucent lighting effects in the engine.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, specifically the parts dealing with translucent lighting and deferred shading.

The value of this variable is set through the console variable system. It’s initialized with a default value of 1 (enabled) and can be changed at runtime.

The associated variable GUseTranslucentLightingVolumes interacts directly with r.TranslucentLightingVolume. They share the same value and are used interchangeably in the code.

Developers must be aware of the following when using this variable:

  1. Setting it to 0 disables the updating of translucent lighting volumes.
  2. It affects performance and visual quality, especially for scenes with translucent objects.
  3. On Mac Metal, this feature is forcibly disabled due to lack of support for point light cubemap shadows.

Best practices when using this variable include:

  1. Keep it enabled (default value of 1) for better visual quality in scenes with translucent objects.
  2. Consider disabling it for performance optimization on lower-end hardware.
  3. Be aware of its impact on different platforms, especially Mac Metal.

Regarding the associated variable GUseTranslucentLightingVolumes:

The purpose of GUseTranslucentLightingVolumes is the same as r.TranslucentLightingVolume - to control the use of translucent lighting volumes in the rendering pipeline.

This variable is used in various parts of the rendering code, including deferred shading, light rendering, and translucent lighting calculations.

The value of GUseTranslucentLightingVolumes is set through the r.TranslucentLightingVolume console variable.

It interacts with other rendering features, such as volume texture rendering (GSupportsVolumeTextureRendering) and translucency volume blur (GUseTranslucencyVolumeBlur).

Developers should be aware that this variable is checked in performance-critical rendering code, so changing its value can have significant impacts on rendering performance and quality.

Best practices for using GUseTranslucentLightingVolumes include:

  1. Use it in conjunction with other related variables like GSupportsVolumeTextureRendering for comprehensive control over translucent lighting.
  2. Consider its impact on different lighting scenarios, especially those involving translucent objects.
  3. Use it for fine-tuning performance in scenes with complex translucent lighting.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseDeviceProfiles.ini:295, section: [IOS DeviceProfile]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/TranslucentLighting.cpp:62

Scope: file

Source code excerpt:

int32 GUseTranslucentLightingVolumes = 1;
FAutoConsoleVariableRef CVarUseTranslucentLightingVolumes(
	TEXT("r.TranslucentLightingVolume"),
	GUseTranslucentLightingVolumes,
	TEXT("Whether to allow updating the translucent lighting volumes.\n")
	TEXT("0:off, otherwise on, default is 1"),
	ECVF_RenderThreadSafe | ECVF_Scalability
	);

#Loc: <Workspace>/Engine/Source/Runtime/Apple/MetalRHI/Private/MetalRHI.cpp:587

Scope: file

Source code excerpt:

	{
		// Disable point light cubemap shadows on Mac Metal as currently they aren't supported.
		static auto CVarTranslucentLightingVolume = IConsoleManager::Get().FindConsoleVariable(TEXT("r.TranslucentLightingVolume"));
		if(CVarTranslucentLightingVolume && CVarTranslucentLightingVolume->GetInt() != 0)
		{
			CVarTranslucentLightingVolume->Set(0);
		}
	}

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightRendering.cpp:55

Scope: file

Source code excerpt:

DECLARE_DWORD_COUNTER_STAT(TEXT("VSM Light Projections (Local One Pass Fast)"), STAT_VSMLocalProjectionOnePassFast, STATGROUP_ShadowRendering);

extern int32 GUseTranslucentLightingVolumes;

static int32 GAllowDepthBoundsTest = 1;
static FAutoConsoleVariableRef CVarAllowDepthBoundsTest(
	TEXT("r.AllowDepthBoundsTest"),
	GAllowDepthBoundsTest,
	TEXT("If true, use enable depth bounds test when rendering deferred lights.")

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/LightRendering.cpp:1368

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::RenderLights

Source code excerpt:

		}

		if (ViewFamily.EngineShowFlags.DirectLighting && GUseTranslucentLightingVolumes && GSupportsVolumeTextureRendering)
		{
			RDG_EVENT_SCOPE(GraphBuilder, "InjectTranslucencyLightingVolume");

			if (SimpleLights.InstanceData.Num() > 0)
			{
				auto& SimpleLightsByView = *GraphBuilder.AllocObject<TArray<FSimpleLightArray, SceneRenderingAllocator>>();

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/TranslucentLighting.cpp:60

Scope: file

Source code excerpt:

DECLARE_GPU_STAT_NAMED(TranslucentLighting, TEXT("Translucent Lighting"));
 
int32 GUseTranslucentLightingVolumes = 1;
FAutoConsoleVariableRef CVarUseTranslucentLightingVolumes(
	TEXT("r.TranslucentLightingVolume"),
	GUseTranslucentLightingVolumes,
	TEXT("Whether to allow updating the translucent lighting volumes.\n")
	TEXT("0:off, otherwise on, default is 1"),
	ECVF_RenderThreadSafe | ECVF_Scalability
	);

float GTranslucentVolumeMinFOV = 45;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/TranslucentLighting.cpp:927

Scope (from outer to inner):

file
function     void InjectTranslucencyLightingVolumeAmbientCubemap

Source code excerpt:

	const FTranslucencyLightingVolumeTextures& Textures)
{
	if (!GUseTranslucentLightingVolumes || !GSupportsVolumeTextureRendering)
	{
		return;
	}

	RDG_EVENT_SCOPE(GraphBuilder, "InjectAmbientCubemapTranslucentVolumeLighting");
	RDG_GPU_STAT_SCOPE(GraphBuilder, TranslucentLighting);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/TranslucentLighting.cpp:1096

Scope: file

Source code excerpt:

	const FTranslucentLightInjectionCollector& Collector)
{
	if (!GUseTranslucentLightingVolumes || !GSupportsVolumeTextureRendering)
	{
		return;
	}

	const FTranslucentLightInjectionCollector::FInjectionDataArray& LightInjectionData = Collector.InjectionDataPerView[ViewIndex];

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/TranslucentLighting.cpp:1387

Scope (from outer to inner):

file
function     void FilterTranslucencyLightingVolume

Source code excerpt:

	FTranslucencyLightingVolumeTextures& Textures)
{
	if (!GUseTranslucentLightingVolumes || !GSupportsVolumeTextureRendering || !GUseTranslucencyVolumeBlur)
	{
		return;
	}

	FRHISamplerState* SamplerStateRHI = TStaticSamplerState<SF_Bilinear, AM_Clamp, AM_Clamp, AM_Clamp>::GetRHI();