r.VisualizeLightingOnProbes

r.VisualizeLightingOnProbes

#Overview

name: r.VisualizeLightingOnProbes

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

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.VisualizeLightingOnProbes is to enable debug probe rendering for visualizing diffuse and specular lighting (both direct and indirect) on simple spheres scattered throughout the world. This setting is primarily used for debugging and visualizing lighting in the rendering system.

The Unreal Engine’s rendering module relies on this setting variable, as evident from its usage in the DebugProbeRendering.cpp file within the Renderer subsystem.

The value of this variable is set through a console variable (CVarVisualizeLightingOnProbes) with four possible states: 0: Disabled 1: Camera probes only 2: World probes only 3: Camera and world probes

This variable interacts closely with the engine’s show flag “VisualizeLightingOnProbes”. In some cases, the engine show flag takes precedence over the console variable.

Developers must be aware that changing this variable causes a full shader recompile, which can impact performance during development. They should also note that this visualization tool is not available for reflection captures.

Best practices when using this variable include:

  1. Use it primarily for debugging lighting issues
  2. Be mindful of the performance impact when enabling it
  3. Consider using it in conjunction with other lighting visualization tools for a comprehensive understanding of the scene’s lighting

Regarding the associated variable CVarVisualizeLightingOnProbes:

This is the actual TAutoConsoleVariable that controls the r.VisualizeLightingOnProbes setting. It’s defined in the same file and shares the same value and purpose as r.VisualizeLightingOnProbes.

The CVarVisualizeLightingOnProbes variable is used directly in the rendering code to determine whether and how to render the debug probes. It’s typically accessed using the GetValueOnRenderThread() method, ensuring thread-safe access to its value.

Developers should be aware that this console variable can be changed at runtime, allowing for dynamic toggling of the debug visualization. However, they should remember that changes will trigger a shader recompile.

When working with CVarVisualizeLightingOnProbes, developers should:

  1. Use GetValueOnRenderThread() when accessing its value in render thread code
  2. Be prepared to handle any of the four possible states (0-3) in the rendering code
  3. Consider the interaction between this variable and the engine show flags when implementing lighting visualization features

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DebugProbeRendering.cpp:18

Scope: file

Source code excerpt:

// Changing this causes a full shader recompile
static TAutoConsoleVariable<int32> CVarVisualizeLightingOnProbes(
	TEXT("r.VisualizeLightingOnProbes"),
	0,
	TEXT("Enables debug probes rendering to visualise diffuse/specular lighting (direct and indirect) on simple sphere scattered in the world.") \
	TEXT(" 0: disabled.\n")
	TEXT(" 1: camera probes only.\n")
	TEXT(" 2: world probes only.\n")
	TEXT(" 3: camera and world probes.\n")

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DebugProbeRendering.cpp:17

Scope: file

Source code excerpt:


// Changing this causes a full shader recompile
static TAutoConsoleVariable<int32> CVarVisualizeLightingOnProbes(
	TEXT("r.VisualizeLightingOnProbes"),
	0,
	TEXT("Enables debug probes rendering to visualise diffuse/specular lighting (direct and indirect) on simple sphere scattered in the world.") \
	TEXT(" 0: disabled.\n")
	TEXT(" 1: camera probes only.\n")
	TEXT(" 2: world probes only.\n")

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DebugProbeRendering.cpp:104

Scope (from outer to inner):

file
function     static void CommonStampDeferredDebugProbeDrawCall

Source code excerpt:

	PassParameters->MaxBytesPerPixel = View.SubstrateViewData.SceneData->EffectiveMaxBytesPerPixel;
	PassParameters->bRoughDiffuse = View.SubstrateViewData.SceneData->bRoughDiffuse ? 1 : 0;
	PassParameters->DebugProbesMode = View.Family->EngineShowFlags.VisualizeLightingOnProbes ? 3 : FMath::Clamp(CVarVisualizeLightingOnProbes.GetValueOnRenderThread(), 0, 3);
		
	FStampDeferredDebugProbePS::FPermutationDomain PermutationVector;
	PermutationVector.Set<FStampDeferredDebugProbePS::FRenderPass>(RenderPass);
	PermutationVector.Set<FStampDeferredDebugProbePS::FIlluminanceMeter>(bIlluminanceMeter);
	TShaderMapRef<FStampDeferredDebugProbePS> PixelShader(View.ShaderMap, PermutationVector);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DebugProbeRendering.cpp:135

Scope (from outer to inner):

file
function     void StampDeferredDebugProbeDepthPS

Source code excerpt:

	RDG_GPU_STAT_SCOPE(GraphBuilder, StampDeferredDebugProbe);

	const bool bVisualizeLightingOnProbes = CVarVisualizeLightingOnProbes.GetValueOnRenderThread() > 0;
	for (const FViewInfo& View : Views)
	{
		const bool bViewRequiresAndSupportsIlluminanceMeter = ViewRequiresAndSupportsIlluminanceMeter(View);
		if (!(bVisualizeLightingOnProbes || View.Family->EngineShowFlags.VisualizeLightingOnProbes) || View.bIsReflectionCapture || bViewRequiresAndSupportsIlluminanceMeter)
		{
			// When "Visualizing HDR with Illuminance Meter", we want to evaluated the illuminance on the surface behind the target square patch.

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DebugProbeRendering.cpp:169

Scope (from outer to inner):

file
function     void StampDeferredDebugProbeMaterialPS

Source code excerpt:

	RDG_GPU_STAT_SCOPE(GraphBuilder, StampDeferredDebugProbe);

	const bool bVisualizeLightingOnProbes = CVarVisualizeLightingOnProbes.GetValueOnRenderThread() > 0;
	for (const FViewInfo& View : Views)
	{
		const bool bViewRequiresAndSupportsIlluminanceMeter = ViewRequiresAndSupportsIlluminanceMeter(View);
		if (!(bVisualizeLightingOnProbes || View.Family->EngineShowFlags.VisualizeLightingOnProbes || bViewRequiresAndSupportsIlluminanceMeter) || View.bIsReflectionCapture)
		{
			continue;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/DebugProbeRendering.cpp:234

Scope (from outer to inner):

file
function     void StampDeferredDebugProbeVelocityPS

Source code excerpt:

	RDG_GPU_STAT_SCOPE(GraphBuilder, StampDeferredDebugProbe);

	const bool bVisualizeLightingOnProbes = CVarVisualizeLightingOnProbes.GetValueOnRenderThread() > 0;
	for (const FViewInfo& View : Views)
	{
		const bool bViewRequiresAndSupportsIlluminanceMeter = ViewRequiresAndSupportsIlluminanceMeter(View);
		if (!(bVisualizeLightingOnProbes || View.Family->EngineShowFlags.VisualizeLightingOnProbes) || View.bIsReflectionCapture || bViewRequiresAndSupportsIlluminanceMeter)
		{
			// When "Visualizing HDR with Illuminance Meter", we want to evaluated the illuminance on the surface behind the target square patch.