r.RayTracing.Geometry.InstancedStaticMeshes.SimulationClusterRadius

r.RayTracing.Geometry.InstancedStaticMeshes.SimulationClusterRadius

#Overview

name: r.RayTracing.Geometry.InstancedStaticMeshes.SimulationClusterRadius

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.RayTracing.Geometry.InstancedStaticMeshes.SimulationClusterRadius is to control the clustering of instanced static meshes for ray tracing simulations, specifically for World Position Offset (WPO) calculations.

This setting variable is primarily used in the rendering system, specifically for ray tracing of instanced static meshes. It is part of Unreal Engine’s ray tracing subsystem within the Engine module.

The value of this variable is set through a console variable (CVar) system. It is defined with a default value of 500.0f (5 meters) in the InstancedStaticMesh.cpp file.

This variable interacts with other ray tracing-related variables, particularly CVarRayTracingSimulatedInstanceCount, which controls the number of instances to simulate.

Developers must be aware that:

  1. This variable affects performance and visual quality in ray-traced scenes with instanced static meshes.
  2. Setting the value to 0 or below will disable the clustering behavior.
  3. The value represents a radius in Unreal units (typically centimeters), with the default being 5 meters.

Best practices when using this variable include:

  1. Adjusting the value based on the scale and density of instanced meshes in your scene.
  2. Balancing between performance and visual quality, as larger radius values may improve performance but potentially reduce accuracy.
  3. Using in conjunction with CVarRayTracingSimulatedInstanceCount for fine-tuning ray tracing performance.

Regarding the associated variable CVarRayTracingInstancesSimulationClusterRadius:

This is the actual console variable object that stores and manages the r.RayTracing.Geometry.InstancedStaticMeshes.SimulationClusterRadius value. It is used in the C++ code to retrieve the current value of the setting.

The purpose of CVarRayTracingInstancesSimulationClusterRadius is to provide a programmatic interface to access and modify the simulation cluster radius setting.

This variable is used within the Engine module, specifically in the InstancedStaticMesh rendering code.

The value of this variable is set when the r.RayTracing.Geometry.InstancedStaticMeshes.SimulationClusterRadius console command is used or when modified through code.

It interacts directly with the ray tracing system, influencing how instanced static meshes are processed for ray tracing.

Developers should be aware that:

  1. This variable is accessed on the render thread, so changes may not be immediately visible.
  2. It’s used in performance-critical code, so frequent changes might impact rendering performance.

Best practices for using this variable include:

  1. Accessing it through the GetValueOnRenderThread() method when used in rendering code.
  2. Avoiding frequent changes during runtime to prevent performance fluctuations.
  3. Using it in conjunction with other ray tracing settings for a holistic approach to optimization.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarRayTracingInstancesSimulationClusterRadius(
	TEXT("r.RayTracing.Geometry.InstancedStaticMeshes.SimulationClusterRadius"),
	500.0f, // 5 m
	TEXT("Bucket instances based on distance to camera for simulating WPO (default = 500 (5m), disable if <= 0)"));

static TAutoConsoleVariable<int32> CVarRayTracingSimulatedInstanceCount(
	TEXT("r.RayTracing.Geometry.InstancedStaticMeshes.SimulationCount"),
	1,

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<float> CVarRayTracingInstancesSimulationClusterRadius(
	TEXT("r.RayTracing.Geometry.InstancedStaticMeshes.SimulationClusterRadius"),
	500.0f, // 5 m
	TEXT("Bucket instances based on distance to camera for simulating WPO (default = 500 (5m), disable if <= 0)"));

static TAutoConsoleVariable<int32> CVarRayTracingSimulatedInstanceCount(
	TEXT("r.RayTracing.Geometry.InstancedStaticMeshes.SimulationCount"),

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

Scope (from outer to inner):

file
function     void FInstancedStaticMeshSceneProxy::GetDynamicRayTracingInstances

Source code excerpt:

	if (bHasWorldPositionOffset && VisibleInstances.Num() > 0)
	{
		float SimulationClusterRadius = CVarRayTracingInstancesSimulationClusterRadius.GetValueOnRenderThread();

		if (SimulationClusterRadius > 0.0)
		{
			if (SimulatedInstances < (uint32)VisibleInstances.Num())
			{
				const FMatrix& InvProjMatrix = Context.ReferenceView->ViewMatrices.GetInvProjectionMatrix();