r.PathTracing.EnableEmissive

r.PathTracing.EnableEmissive

#Overview

name: r.PathTracing.EnableEmissive

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

• type: Var
• help: Indicates if emissive materials should contribute to scene lighting (default = -1 (driven by postprocesing volume)

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.PathTracing.EnableEmissive is to control whether emissive materials contribute to scene lighting in path tracing rendering.

This setting variable is primarily used by the rendering system, specifically the path tracing subsystem within Unreal Engine 5. It is implemented in the Renderer module, as evidenced by its location in the PathTracing.cpp file.

The value of this variable is set through a console variable (CVar) named CVarPathTracingEnableEmissive. It is initialized with a default value of -1, which means it’s driven by the post-processing volume settings by default.

The variable interacts with the post-processing volume settings. When its value is -1, the actual behavior is determined by the PathTracingEnableEmissiveMaterials setting in the post-processing volume.

Developers should be aware that:

1. A value of -1 means the setting is controlled by the post-processing volume.
2. A value of 0 disables emissive materials in path tracing.
3. A value of 1 enables emissive materials in path tracing.

Best practices when using this variable include:

1. Use post-processing volumes for most cases to control this setting.
2. Only override it via console command when necessary for debugging or specific use cases.
3. Be aware of its impact on rendering performance and visual quality.

Regarding the associated variable CVarPathTracingEnableEmissive:

This is the actual console variable that stores the value of r.PathTracing.EnableEmissive. It is defined as an integer with a default value of -1. The variable is marked as render thread safe, meaning it can be safely accessed and modified from the render thread.

The value of CVarPathTracingEnableEmissive is used in the PreparePathTracingData function to determine whether emissive materials should contribute to the scene lighting. If the value is less than 0, it defers to the post-processing volume setting. Otherwise, it enables emissive materials if the value is non-zero.

Developers should be aware that changing this console variable at runtime will affect the path tracing rendering immediately. They should also note that this variable interacts with other path tracing settings and the global illumination showflag, so its effects may not be visible if these other settings are not properly configured.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PathTracing.cpp:179

Scope: file

Source code excerpt:

TAutoConsoleVariable<int32> CVarPathTracingEnableEmissive(
	TEXT("r.PathTracing.EnableEmissive"),
	-1,
	TEXT("Indicates if emissive materials should contribute to scene lighting (default = -1 (driven by postprocesing volume)"),
	ECVF_RenderThreadSafe
);

TAutoConsoleVariable<int32> CVarPathTracingEnableCameraBackfaceCulling(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PathTracing.cpp:178

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarPathTracingEnableEmissive(
	TEXT("r.PathTracing.EnableEmissive"),
	-1,
	TEXT("Indicates if emissive materials should contribute to scene lighting (default = -1 (driven by postprocesing volume)"),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PathTracing.cpp:697

Scope (from outer to inner):

file
function     static void PreparePathTracingData

Source code excerpt:

	if (ShowFlags.GlobalIllumination != 0)
	{
		const int EnableEmissiveCVar = CVarPathTracingEnableEmissive.GetValueOnRenderThread();
		const bool bEnableEmissive = EnableEmissiveCVar < 0 ? PPV.PathTracingEnableEmissiveMaterials : EnableEmissiveCVar != 0;
		PathTracingData.EnabledIndirectLightingContributions |= (bEnableEmissive                                                       ) ? PATHTRACER_CONTRIBUTION_EMISSIVE : 0;
		PathTracingData.EnabledIndirectLightingContributions |= (PPV.PathTracingIncludeIndirectDiffuse  != 0 && ShowFlags.Diffuse  != 0) ? PATHTRACER_CONTRIBUTION_DIFFUSE  : 0;
		PathTracingData.EnabledIndirectLightingContributions |= (PPV.PathTracingIncludeIndirectSpecular != 0 && ShowFlags.Specular != 0) ? PATHTRACER_CONTRIBUTION_SPECULAR : 0;
		PathTracingData.EnabledIndirectLightingContributions |= (PPV.PathTracingIncludeIndirectVolume   != 0                           ) ? PATHTRACER_CONTRIBUTION_VOLUME   : 0;
	}