r.RayTracing.SkyLight.EnableMaterials

r.RayTracing.SkyLight.EnableMaterials

#Overview

name: r.RayTracing.SkyLight.EnableMaterials

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.RayTracing.SkyLight.EnableMaterials is to control material shader binding for shadow rays in ray-traced skylight rendering. This setting variable is part of Unreal Engine 5’s ray tracing system, specifically for the skylight component.

This setting variable is primarily used in the Renderer module, specifically within the ray tracing subsystem for skylights. It’s referenced in the RaytracingSkylight.cpp file, which is responsible for implementing ray-traced skylight rendering.

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

This variable interacts closely with other ray tracing settings, particularly those related to skylight rendering. It’s used in conjunction with other variables like CVarRayTracingSkyLightEnableTwoSidedGeometry and CVarRayTracingSkyLightDecoupleSampleGeneration to determine the permutation vector for the ray generation shader.

Developers should be aware that disabling this variable (setting it to 0) will cause the renderer to use a default trivial shader for shadow rays instead of binding material shaders. This can affect the visual quality and performance of ray-traced skylights in the scene.

Best practices when using this variable include:

  1. Keep it enabled (default value of 1) for higher visual quality.
  2. Consider disabling it for performance optimization if the visual difference is negligible for your specific use case.
  3. Test your scenes with both settings to understand the impact on visual quality and performance.

Regarding the associated variable CVarRayTracingSkyLightEnableMaterials:

This is the actual console variable that controls the r.RayTracing.SkyLight.EnableMaterials setting. It’s defined as a TAutoConsoleVariable in the Unreal Engine codebase.

The purpose of CVarRayTracingSkyLightEnableMaterials is to provide a runtime-configurable way to enable or disable material shader binding for shadow rays in ray-traced skylight rendering.

This variable is used in the Renderer module, specifically in the ray tracing subsystem for skylights. It’s accessed in various parts of the RaytracingSkylight.cpp file to determine shader permutations and pipeline configurations.

The value of this variable is set when it’s defined, with a default value of 1. It can be changed at runtime through console commands or project settings.

CVarRayTracingSkyLightEnableMaterials interacts with other ray tracing variables and is used to set up shader permutations and pipeline states for ray-traced skylight rendering.

Developers should be aware that this variable directly affects the behavior of ray-traced skylight rendering. When disabled, it forces the use of a default trivial shader for shadow rays, which can impact visual quality.

Best practices for using this variable include:

  1. Use GetValueOnRenderThread() when accessing its value in render thread code.
  2. Consider exposing this setting in your project’s graphics options if you want to give users control over this aspect of ray tracing quality.
  3. Profile your application with different values to understand the performance implications in your specific use case.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RaytracingSkylight.cpp:85

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarRayTracingSkyLightEnableMaterials(
	TEXT("r.RayTracing.SkyLight.EnableMaterials"),
	1,
	TEXT("Enables material shader binding for shadow rays. If this is disabled, then a default trivial shader is used. (default = 1)"),
	ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarRayTracingSkyLightDecoupleSampleGeneration(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RaytracingSkylight.cpp:84

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarRayTracingSkyLightEnableMaterials(
	TEXT("r.RayTracing.SkyLight.EnableMaterials"),
	1,
	TEXT("Enables material shader binding for shadow rays. If this is disabled, then a default trivial shader is used. (default = 1)"),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RaytracingSkylight.cpp:461

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::RenderRayTracingSkyLight

Source code excerpt:

		FRayTracingSkyLightRGS::FPermutationDomain PermutationVector;
		PermutationVector.Set<FRayTracingSkyLightRGS::FEnableTwoSidedGeometryDim>(CVarRayTracingSkyLightEnableTwoSidedGeometry.GetValueOnRenderThread() != 0);
		PermutationVector.Set<FRayTracingSkyLightRGS::FEnableMaterialsDim>(CVarRayTracingSkyLightEnableMaterials.GetValueOnRenderThread() != 0);
		PermutationVector.Set<FRayTracingSkyLightRGS::FDecoupleSampleGeneration>(CVarRayTracingSkyLightDecoupleSampleGeneration.GetValueOnRenderThread() != 0);
		PermutationVector.Set<FRayTracingSkyLightRGS::FHairLighting>(bUseHairLighting ? 1 : 0);
		TShaderMapRef<FRayTracingSkyLightRGS> RayGenerationShader(GetGlobalShaderMap(FeatureLevel), PermutationVector);
		ClearUnusedGraphResources(RayGenerationShader, PassParameters);

		FIntPoint RayTracingResolution = View.ViewRect.Size() / UpscaleFactor;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RaytracingSkylight.cpp:479

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::RenderRayTracingSkyLight
lambda-function

Source code excerpt:

			FRayTracingPipelineState* Pipeline = View.RayTracingMaterialPipeline;
			FRHIRayTracingScene* RayTracingSceneRHI = View.GetRayTracingSceneChecked();
			if (CVarRayTracingSkyLightEnableMaterials.GetValueOnRenderThread() == 0)
			{
				// Declare default pipeline
				FRayTracingPipelineStateInitializer Initializer;
				Initializer.MaxPayloadSizeInBytes = GetRayTracingPayloadTypeMaxSize(ERayTracingPayloadType::RayTracingMaterial);
				FRHIRayTracingShader* RayGenShaderTable[] = { RayGenerationShader.GetRayTracingShader() };
				Initializer.SetRayGenShaderTable(RayGenShaderTable);