r.LumenScene.Heightfield.Tracing

r.LumenScene.Heightfield.Tracing

#Overview

name: r.LumenScene.Heightfield.Tracing

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.LumenScene.Heightfield.Tracing is to enable or disable heightfield (Landscape) software ray tracing in the Lumen global illumination system of Unreal Engine 5.

This setting variable is primarily used in the rendering system, specifically in the Lumen subsystem, which is responsible for real-time global illumination. It is part of the Renderer module of Unreal Engine 5.

The value of this variable is set through a console variable (CVarLumenSceneHeightfieldTracing) in the Lumen subsystem. It is defined with a default value of 1, meaning heightfield tracing is enabled by default.

This variable interacts with the LumenSceneData structure, particularly the Heightfields array within it. It is used in conjunction with the presence of heightfields to determine whether heightfield tracing should be used for voxel lighting and other Lumen-related rendering processes.

Developers must be aware that this variable affects the performance and quality of global illumination for landscapes in their scenes. Enabling this feature (value 1) allows for more accurate lighting of landscape features but may have performance implications.

Best practices when using this variable include:

  1. Testing the performance impact in your specific scene with the feature enabled and disabled.
  2. Considering the importance of accurate landscape lighting in your project versus potential performance costs.
  3. Being aware that changes to this variable will affect the rendering thread, so it should be modified with care.

Regarding the associated variable CVarLumenSceneHeightfieldTracing:

The purpose of CVarLumenSceneHeightfieldTracing is to provide a programmatic way to access and modify the r.LumenScene.Heightfield.Tracing setting within the engine’s C++ code.

This variable is used directly in the Lumen subsystem of the Renderer module. It’s typically accessed on the render thread to determine whether heightfield tracing should be used.

The value of this variable is set when the engine initializes the console variables, but it can be changed at runtime through console commands or programmatically.

CVarLumenSceneHeightfieldTracing interacts closely with the LumenSceneData structure and is often used in conjunction with checking the number of heightfields in the scene.

Developers should be aware that this variable is marked as render thread safe (ECVF_RenderThreadSafe), meaning it can be safely accessed and modified on the render thread.

Best practices for using CVarLumenSceneHeightfieldTracing include:

  1. Accessing its value using the GetValueOnRenderThread() method when on the render thread.
  2. Considering the performance implications of enabling or disabling this feature dynamically during gameplay.
  3. Using this variable in conjunction with other Lumen settings for fine-tuning the global illumination system’s behavior and performance.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenHeightfields.cpp:5

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarLumenSceneHeightfieldTracing(
	TEXT("r.LumenScene.Heightfield.Tracing"),
	1,
	TEXT("Enables heightfield (Landscape) software ray tracing (default = 1)"),
	ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarLumenSceneHeightfieldMaxTracingSteps(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenHeightfields.cpp:4

Scope: file

Source code excerpt:

#include "ComponentRecreateRenderStateContext.h"

TAutoConsoleVariable<int32> CVarLumenSceneHeightfieldTracing(
	TEXT("r.LumenScene.Heightfield.Tracing"),
	1,
	TEXT("Enables heightfield (Landscape) software ray tracing (default = 1)"),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenHeightfields.cpp:27

Scope (from outer to inner):

file
function     bool Lumen::UseHeightfieldTracingForVoxelLighting

Source code excerpt:

bool Lumen::UseHeightfieldTracingForVoxelLighting(const FLumenSceneData& LumenSceneData)
{
	bool bHeightfieldEnabled = CVarLumenSceneHeightfieldTracing.GetValueOnRenderThread() != 0;
	bool bHasHeightfields = LumenSceneData.Heightfields.Num() > 0;
	return bHeightfieldEnabled && bHasHeightfields;
}

bool Lumen::UseHeightfieldTracing(const FSceneViewFamily& ViewFamily, const FLumenSceneData& LumenSceneData)
{