r.Lumen.TranslucencyVolume.VoxelTraceStartDistanceScale

r.Lumen.TranslucencyVolume.VoxelTraceStartDistanceScale

#Overview

name: r.Lumen.TranslucencyVolume.VoxelTraceStartDistanceScale

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

• type: Var
• help: .

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.TranslucencyVolume.VoxelTraceStartDistanceScale is to control the starting distance for voxel tracing in Lumen’s translucency volume lighting system. This setting is part of Unreal Engine 5’s Lumen global illumination system, specifically targeting the rendering of translucent objects.

• The Lumen subsystem within the Unreal Engine 5 renderer relies on this setting variable. It’s specifically used in the translucency volume lighting component of Lumen.

• The value of this variable is set through the Unreal Engine console variable system. It’s defined as an FAutoConsoleVariableRef, which allows it to be adjusted at runtime.

• This variable interacts directly with GTranslucencyVolumeVoxelTraceStartDistanceScale, which is the actual float value used in the rendering calculations. The console variable r.Lumen.TranslucencyVolume.VoxelTraceStartDistanceScale is linked to this global variable.

• Developers should be aware that this variable affects the performance and quality of translucency lighting. Adjusting this value will change where the voxel tracing starts in the lighting calculations for translucent objects, which can impact both visual quality and performance.

• Best practices for using this variable include:

  1. Start with the default value (1.0f) and adjust only if necessary.
  2. Lower values may improve performance but could reduce lighting accuracy for translucent objects.
  3. Higher values may increase lighting accuracy but at the cost of performance.
  4. Test thoroughly in various lighting conditions and with different translucent materials to ensure desired results.

Regarding the associated variable GTranslucencyVolumeVoxelTraceStartDistanceScale:

• This is the actual float value used in the rendering calculations.
• It’s initialized with a default value of 1.0f.
• It’s used directly in the ComputeLumenTranslucencyGIVolume function to set the VoxelTraceStartDistanceScale parameter for trace setup.
• Changes to the console variable r.Lumen.TranslucencyVolume.VoxelTraceStartDistanceScale will directly affect this variable.
• Developers should note that this variable is marked with ECVF_Scalability and ECVF_RenderThreadSafe flags, indicating it’s safe to adjust for scalability purposes and can be modified from the render thread.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenTranslucencyVolumeLighting.cpp:132

Scope: file

Source code excerpt:

float GTranslucencyVolumeVoxelTraceStartDistanceScale = 1.0f;
FAutoConsoleVariableRef CVarTranslucencyVoxelTraceStartDistanceScale(
	TEXT("r.Lumen.TranslucencyVolume.VoxelTraceStartDistanceScale"),
	GTranslucencyVolumeVoxelTraceStartDistanceScale,
	TEXT("."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

float GTranslucencyVolumeMaxRayIntensity = 20.0f;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenTranslucencyVolumeLighting.cpp:130

Scope: file

Source code excerpt:

);

float GTranslucencyVolumeVoxelTraceStartDistanceScale = 1.0f;
FAutoConsoleVariableRef CVarTranslucencyVoxelTraceStartDistanceScale(
	TEXT("r.Lumen.TranslucencyVolume.VoxelTraceStartDistanceScale"),
	GTranslucencyVolumeVoxelTraceStartDistanceScale,
	TEXT("."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

float GTranslucencyVolumeMaxRayIntensity = 20.0f;
FAutoConsoleVariableRef CVarTranslucencyVolumeMaxRayIntensity(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenTranslucencyVolumeLighting.cpp:772

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::ComputeLumenTranslucencyGIVolume

Source code excerpt:

				TraceSetupParameters.StepFactor = FMath::Clamp(GTranslucencyVolumeTraceStepFactor, .1f, 10.0f);
				TraceSetupParameters.MaxTraceDistance = Lumen::GetMaxTraceDistance(View);
				TraceSetupParameters.VoxelTraceStartDistanceScale = GTranslucencyVolumeVoxelTraceStartDistanceScale;
				TraceSetupParameters.MaxRayIntensity = GTranslucencyVolumeMaxRayIntensity;
			}

			const FIntVector OctahedralAtlasSize(
				TranslucencyGridSize.X * GTranslucencyVolumeTracingOctahedronResolution, 
				TranslucencyGridSize.Y * GTranslucencyVolumeTracingOctahedronResolution,