r.PathTracing.SkylightCaching

r.PathTracing.SkylightCaching

#Overview

name: r.PathTracing.SkylightCaching

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.PathTracing.SkylightCaching is to control the caching behavior of skylight data in the path tracing rendering system of Unreal Engine 5. It specifically attempts to re-use skylight data between frames to improve performance.

This setting variable is primarily used in the rendering subsystem of Unreal Engine, specifically within the path tracing module. Based on the callsites, it’s implemented in the PathTracing.cpp file, which is part of the Renderer module.

The value of this variable is set through a console variable (CVarPathTracingSkylightCaching) with a default value of 1 (enabled). It can be changed at runtime through console commands or programmatically.

The associated variable CVarPathTracingSkylightCaching directly interacts with r.PathTracing.SkylightCaching. They share the same value and purpose.

Developers must be aware that when this variable is set to 0, the skylight texture and importance sampling data will be regenerated every frame. This can significantly impact performance and is mainly intended for benchmarking and debugging purposes.

Best practices when using this variable include:

  1. Keep it enabled (value 1) for normal gameplay and production builds to maximize performance.
  2. Only disable it (value 0) when debugging skylight-related issues or when benchmarking the impact of skylight caching on performance.
  3. Be cautious when changing this value during runtime, as it could cause sudden changes in performance or visual quality.

Regarding the associated variable CVarPathTracingSkylightCaching:

The purpose of CVarPathTracingSkylightCaching is to provide a programmatic way to control the r.PathTracing.SkylightCaching setting. It’s an instance of TAutoConsoleVariable, which allows for runtime modification of the setting.

This variable is used in the same Renderer module and PathTracing.cpp file. Its value is typically accessed using the GetValueOnAnyThread() method, as seen in the provided code excerpt.

The value of CVarPathTracingSkylightCaching is set when the variable is initialized, with a default value of 1. It can be changed through console commands or programmatically at runtime.

Developers should be aware that changes to CVarPathTracingSkylightCaching will directly affect the skylight caching behavior in the path tracing system. They should also note that accessing its value is thread-safe, as indicated by the ECVF_RenderThreadSafe flag.

Best practices for using CVarPathTracingSkylightCaching include:

  1. Use GetValueOnAnyThread() to safely access its value from any thread.
  2. Consider exposing this setting in debug or development builds for easy toggling during testing.
  3. Be mindful of performance implications when changing this value, especially in performance-critical sections of code.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarPathTracingSkylightCaching(
	TEXT("r.PathTracing.SkylightCaching"),
	1,
	TEXT("Attempts to re-use skylight data between frames. (default = 1 (enabled))\n")
	TEXT("When set to 0, the skylight texture and importance samping data will be regenerated every frame. This is mainly intended as a benchmarking and debugging aid\n"),
	ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarPathTracingSkylightCaching(
	TEXT("r.PathTracing.SkylightCaching"),
	1,
	TEXT("Attempts to re-use skylight data between frames. (default = 1 (enabled))\n")
	TEXT("When set to 0, the skylight texture and importance samping data will be regenerated every frame. This is mainly intended as a benchmarking and debugging aid\n"),
	ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     bool PrepareSkyTexture

Source code excerpt:


	// should we remember the skylight prep for the next frame?
	const bool IsSkylightCachingEnabled = CVarPathTracingSkylightCaching.GetValueOnAnyThread() != 0;
	FLinearColor SkyColor = Scene->SkyLight->GetEffectiveLightColor();
	const bool bSkylightColorChanged = SkyColor != Scene->PathTracingSkylightColor;
	if (!IsSkylightCachingEnabled || bSkylightColorChanged)
	{
		// we don't want any caching (or the light color changed)
		// release what we might have been holding onto so we get the right texture for this frame