r.RayTracing.Geometry.InstancedStaticMeshes.CullClusterRadius

r.RayTracing.Geometry.InstancedStaticMeshes.CullClusterRadius

#Overview

name: r.RayTracing.Geometry.InstancedStaticMeshes.CullClusterRadius

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

• type: Var
• help: Ignore instances outside of this radius in ray tracing effects (default = 10000 (100m))

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.RayTracing.Geometry.InstancedStaticMeshes.CullClusterRadius is to control the culling radius for instanced static meshes in ray tracing effects. It defines a distance threshold beyond which instances are ignored in ray tracing calculations.

This setting variable is primarily used in the rendering system, specifically for ray tracing optimizations in Unreal Engine 5. It is part of the Engine module and is utilized in the InstancedStaticMesh component.

The value of this variable is set as a console variable with a default value of 10000.0f (100 meters). It can be modified at runtime through the console or configuration files.

The variable interacts with other ray tracing-related variables, such as CVarRayTracingInstancesLowScaleThreshold and CVarRayTracingInstancesLowScaleCullRadius, to define the culling behavior for instanced static meshes in ray tracing.

Developers must be aware that this variable directly impacts performance and visual quality in ray tracing effects. A larger value will include more distant instances in ray tracing calculations, potentially improving visual quality at the cost of performance. Conversely, a smaller value will cull more distant instances, improving performance but potentially reducing visual quality for far-away objects.

Best practices when using this variable include:

1. Adjusting the value based on the scale and requirements of your scene.
2. Balancing between performance and visual quality.
3. Testing different values to find the optimal setting for your specific use case.
4. Considering the interaction with other related variables for comprehensive culling behavior.

Regarding the associated variable CVarRayTracingInstancesCullClusterRadius:

The purpose of CVarRayTracingInstancesCullClusterRadius is the same as r.RayTracing.Geometry.InstancedStaticMeshes.CullClusterRadius. It’s an internal representation of the console variable used in the C++ code.

This variable is used within the Engine module, specifically in the InstancedStaticMesh component’s rendering logic.

The value of this variable is set through the TAutoConsoleVariable declaration, which links it to the console variable r.RayTracing.Geometry.InstancedStaticMeshes.CullClusterRadius.

It interacts directly with the rendering logic for instanced static meshes in ray tracing, influencing which instances are included in ray tracing calculations.

Developers should be aware that this is the internal representation of the console variable and is used directly in the rendering code. Any changes to the console variable will affect this variable’s value.

Best practices for this variable include:

1. Using GetValueOnRenderThread() when accessing the value in render thread code.
2. Avoiding direct modification of this variable; instead, modify the console variable it represents.
3. Considering the performance implications when adjusting the value, as it directly impacts the number of instances processed in ray tracing.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/InstancedStaticMesh.cpp:126

Scope: file

Source code excerpt:

static TAutoConsoleVariable<float> CVarRayTracingInstancesCullClusterRadius(
	TEXT("r.RayTracing.Geometry.InstancedStaticMeshes.CullClusterRadius"),
	10000.0f, // 100 m
	TEXT("Ignore instances outside of this radius in ray tracing effects (default = 10000 (100m))"));

static TAutoConsoleVariable<float> CVarRayTracingInstancesLowScaleThreshold(
	TEXT("r.RayTracing.Geometry.InstancedStaticMeshes.LowScaleRadiusThreshold"),
	50.0f, // Instances with a radius smaller than this threshold get culled after CVarRayTracingInstancesLowScaleCullRadius

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/InstancedStaticMesh.cpp:125

Scope: file

Source code excerpt:

	TEXT("Multiplier for the maximum instance size (default = 20)"));

static TAutoConsoleVariable<float> CVarRayTracingInstancesCullClusterRadius(
	TEXT("r.RayTracing.Geometry.InstancedStaticMeshes.CullClusterRadius"),
	10000.0f, // 100 m
	TEXT("Ignore instances outside of this radius in ray tracing effects (default = 10000 (100m))"));

static TAutoConsoleVariable<float> CVarRayTracingInstancesLowScaleThreshold(
	TEXT("r.RayTracing.Geometry.InstancedStaticMeshes.LowScaleRadiusThreshold"),

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/InstancedStaticMesh.cpp:1741

Scope (from outer to inner):

file
function     void FInstancedStaticMeshSceneProxy::GetDynamicRayTracingInstances

Source code excerpt:

			//    Check nodes for being within minimum distances
			//
			const float BVHCullRadius = CVarRayTracingInstancesCullClusterRadius.GetValueOnRenderThread();
			const float BVHLowScaleThreshold = CVarRayTracingInstancesLowScaleThreshold.GetValueOnRenderThread();
			const float BVHLowScaleRadius = CVarRayTracingInstancesLowScaleCullRadius.GetValueOnRenderThread();
			const bool ApplyGeneralCulling = BVHCullRadius > 0.0f;
			const bool ApplyLowScaleCulling = BVHLowScaleThreshold > 0.0f && BVHLowScaleRadius > 0.0f;

			for (uint32 InstanceIndex = 0; InstanceIndex < InstanceCount; InstanceIndex++)