r.RayTracing.Geometry.InstancedStaticMeshes.SimulationCount

r.RayTracing.Geometry.InstancedStaticMeshes.SimulationCount

#Overview

name: r.RayTracing.Geometry.InstancedStaticMeshes.SimulationCount

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.SimulationCount is to control the maximum number of instances to simulate per instanced static mesh in ray tracing scenarios. This setting is specifically related to the rendering system, particularly the ray tracing functionality in Unreal Engine 5.

This setting variable is primarily used in the Engine module, specifically within the InstancedStaticMesh rendering system. It’s referenced in the InstancedStaticMesh.cpp file, which handles the rendering of instanced static meshes.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 1 and can be changed at runtime through console commands or project settings.

The associated variable CVarRayTracingSimulatedInstanceCount directly interacts with this setting. They share the same value and purpose.

Developers must be aware that:

  1. This value is capped at 256, as mentioned in the description.
  2. It affects performance and visual fidelity in ray tracing scenarios.
  3. A value of -1 is treated specially, using the total instance count instead.

Best practices when using this variable include:

  1. Carefully balancing between performance and visual quality. Higher values may provide better visual results but at the cost of performance.
  2. Testing different values to find the optimal setting for specific scenes or use cases.
  3. Considering the total number of instanced static meshes in the scene when setting this value.

Regarding the associated variable CVarRayTracingSimulatedInstanceCount:

The purpose of CVarRayTracingSimulatedInstanceCount is identical to r.RayTracing.Geometry.InstancedStaticMeshes.SimulationCount. It’s the actual console variable implementation that controls the setting.

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

The value is set when the engine initializes the console variables, but can be changed at runtime through console commands or project settings.

It directly controls the r.RayTracing.Geometry.InstancedStaticMeshes.SimulationCount setting and is used in the GetDynamicRayTracingInstances function to determine the number of instances to simulate.

Developers should be aware that:

  1. This variable directly affects ray tracing performance and quality.
  2. It’s used in conjunction with other ray tracing and instanced mesh settings.

Best practices include:

  1. Using this variable in conjunction with other ray tracing settings for optimal results.
  2. Profiling the performance impact of different values in your specific use case.
  3. Considering exposing this setting to end-users for performance tuning, if appropriate for your project.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarRayTracingSimulatedInstanceCount(
	TEXT("r.RayTracing.Geometry.InstancedStaticMeshes.SimulationCount"),
	1,
	TEXT("Maximum number of instances to simulate per instanced static mesh, presently capped to 256")
);

#if WITH_EDITOR
static TAutoConsoleVariable<int32> CVarEnableViewportSMInstanceSelection(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	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,
	TEXT("Maximum number of instances to simulate per instanced static mesh, presently capped to 256")
);

#if WITH_EDITOR

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

Scope (from outer to inner):

file
function     void FInstancedStaticMeshSceneProxy::GetDynamicRayTracingInstances

Source code excerpt:

	TArray<FVisibleInstance> VisibleInstances;

	const uint32 RequestedSimulatedInstances = CVarRayTracingSimulatedInstanceCount.GetValueOnRenderThread();
	const uint32 SimulatedInstances = FMath::Min(RequestedSimulatedInstances == -1 ? InstanceCount : FMath::Clamp(RequestedSimulatedInstances, 1u, InstanceCount), MaxSimulatedInstances);

	const int32 WPOEvalMode = CVarRayTracingInstancesEvaluateWPO.GetValueOnRenderThread();
	const bool bWantsWPOEvaluation = WPOEvalMode < 0 ? bDynamicRayTracingGeometry : WPOEvalMode != 0;
	const bool bHasWorldPositionOffset = bWantsWPOEvaluation && bAnySegmentUsesWorldPositionOffset;