r.SSGI.TerminateCertainRay

r.SSGI.TerminateCertainRay

#Overview

name: r.SSGI.TerminateCertainRay

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.SSGI.TerminateCertainRay is to optimize the Screen Space Global Illumination (SSGI) ray tracing process in Unreal Engine’s rendering system. It controls whether to terminate ray tracing early when a certain ray doesn’t find any geometry, instead of falling back on other tracing techniques.

This setting variable is primarily used in the rendering system, specifically in the Screen Space Ray Tracing module of Unreal Engine. Based on the callsites, it’s part of the Renderer module.

The value of this variable is set through a console variable (CVarSSGITerminateCertainRay) in the ScreenSpaceRayTracing.cpp file. It’s initialized with a default value of 1 (enabled).

The variable interacts with other SSGI-related variables, such as CVarSSGIRejectUncertainRays and CVarSSGISkyDistance, which are defined in the same file and contribute to the overall SSGI system configuration.

Developers should be aware that enabling this optimization (setting to 1) may improve performance but could potentially affect the accuracy of global illumination in certain scenarios. It’s a trade-off between performance and visual quality.

Best practices when using this variable include:

  1. Testing the visual impact of enabling/disabling this optimization in various scenes.
  2. Considering the balance between performance gains and potential visual artifacts.
  3. Using it in conjunction with other SSGI settings for optimal results.

Regarding the associated variable CVarSSGITerminateCertainRay:

This is the actual console variable that controls the r.SSGI.TerminateCertainRay setting. It’s defined as a TAutoConsoleVariable, which means it’s an integer value that can be changed at runtime through the console.

The purpose of CVarSSGITerminateCertainRay is to provide a programmable interface for the r.SSGI.TerminateCertainRay setting. It allows developers and users to modify the behavior of the SSGI system dynamically.

This variable is used in the SetupCommonScreenSpaceRayParameters function to set up parameters for screen space ray tracing. The value is retrieved using GetValueOnRenderThread(), ensuring thread-safe access in the rendering pipeline.

Developers should be aware that changes to this console variable will take effect on the render thread, which may not be immediate depending on the current state of frame rendering.

Best practices for using CVarSSGITerminateCertainRay include:

  1. Using it for debugging and performance tuning during development.
  2. Providing a user-facing option in graphics settings that modifies this value if deemed necessary for end-users.
  3. Documenting any significant visual or performance impacts of changing this value in your project’s documentation.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ScreenSpaceRayTracing.cpp:67

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarSSGITerminateCertainRay(
	TEXT("r.SSGI.TerminateCertainRay"), 1,
	TEXT("Optimisations that if the screen space ray is certain and didn't find any geometry, don't fallback on otehr tracing technic."),
	ECVF_Scalability | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarSSGISkyDistance(
	TEXT("r.SSGI.SkyDistance"), 10000000,
	TEXT("Distance of the sky in KM."),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ScreenSpaceRayTracing.cpp:66

Scope: file

Source code excerpt:

	ECVF_Scalability | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSSGITerminateCertainRay(
	TEXT("r.SSGI.TerminateCertainRay"), 1,
	TEXT("Optimisations that if the screen space ray is certain and didn't find any geometry, don't fallback on otehr tracing technic."),
	ECVF_Scalability | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarSSGISkyDistance(
	TEXT("r.SSGI.SkyDistance"), 10000000,

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ScreenSpaceRayTracing.cpp:248

Scope (from outer to inner):

file
namespace    ScreenSpaceRayTracing
function     void SetupCommonScreenSpaceRayParameters

Source code excerpt:


	OutParameters->bRejectUncertainRays = CVarSSGIRejectUncertainRays.GetValueOnRenderThread() ? 1 : 0;
	OutParameters->bTerminateCertainRay = CVarSSGITerminateCertainRay.GetValueOnRenderThread() ? 1 : 0;
} // SetupCommonScreenSpaceRayParameters()

void SetupCommonScreenSpaceRayParameters(
	FRDGBuilder& GraphBuilder,
	const HybridIndirectLighting::FCommonParameters& CommonDiffuseParameters,
	const ScreenSpaceRayTracing::FPrevSceneColorMip& PrevSceneColor,