r.RayTracing.AutoInstance

r.RayTracing.AutoInstance

#Overview

name: r.RayTracing.AutoInstance

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.AutoInstance is to control whether static meshes should be automatically instanced in ray tracing scenarios. This setting is part of Unreal Engine 5’s ray tracing system, which is a rendering technique used to create more realistic lighting, reflections, and shadows in game environments.

This setting variable is primarily used in the Renderer module of Unreal Engine, specifically within the ray tracing subsystem. Based on the callsites, it’s clear that this variable is utilized in the process of gathering world instances for ray tracing scenes.

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

The associated variable CVarRayTracingAutoInstance directly interacts with r.RayTracing.AutoInstance. They share the same value and purpose, with CVarRayTracingAutoInstance being the actual TAutoConsoleVariable implementation.

Developers should be aware that:

  1. This setting affects performance and memory usage. Enabling auto-instancing can improve rendering performance by reducing the number of unique objects the ray tracing system needs to process.
  2. It specifically targets static meshes, not dynamic or skeletal meshes.
  3. The setting is render thread safe, meaning it can be changed without causing threading issues in the rendering pipeline.

Best practices when using this variable include:

  1. Leave it enabled (default value of 1) unless there’s a specific reason to disable it, as it generally improves performance.
  2. If disabling, ensure to profile the performance impact, as it might significantly affect ray tracing efficiency.
  3. Consider the trade-off between memory usage and rendering performance when adjusting this setting.

Regarding the associated variable CVarRayTracingAutoInstance:

The purpose of CVarRayTracingAutoInstance is identical to r.RayTracing.AutoInstance, as it’s the actual implementation of the console variable.

It’s defined in the Renderer module and is used directly in the ray tracing subsystem to determine whether auto-instancing should be applied.

The value is set during initialization with a default of 1, but can be modified at runtime through console commands or engine settings.

This variable directly controls the behavior of the auto-instancing feature in the ray tracing system. When its value is non-zero, the system will attempt to automatically instance static meshes.

Developers should be aware that:

  1. This is a render thread safe variable, allowing for real-time adjustments without causing threading issues.
  2. The variable is of type int32, but is effectively used as a boolean (0 for disabled, non-zero for enabled).

Best practices include:

  1. Use the GetValueOnRenderThread() method to safely access its value in render thread contexts.
  2. When modifying this variable, consider the potential performance implications and test thoroughly in various scenarios.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarRayTracingAutoInstance(
	TEXT("r.RayTracing.AutoInstance"),
	1,
	TEXT("Whether to auto instance static meshes\n"),
	ECVF_RenderThreadSafe
);

static int32 GRayTracingExcludeTranslucent = 0;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	TEXT("Dynamic geometries within this distance will have their LastRenderTime updated, so that visibility based ticking (like skeletal mesh) can work when the component is not directly visible in the view (but reflected)."));

static TAutoConsoleVariable<int32> CVarRayTracingAutoInstance(
	TEXT("r.RayTracing.AutoInstance"),
	1,
	TEXT("Whether to auto instance static meshes\n"),
	ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
namespace    RayTracing
function     bool GatherWorldInstancesForView
function     void DoTask

Source code excerpt:

					TRACE_CPUPROFILER_EVENT_SCOPE(RayTracingScene_AddStaticInstances);

					const bool bAutoInstance = CVarRayTracingAutoInstance.GetValueOnRenderThread() != 0;

					// Instance batches by FRelevantPrimitive::InstancingKey()
					Experimental::TSherwoodMap<uint64, FAutoInstanceBatch> InstanceBatches;

					// scan relevant primitives computing hash data to look for duplicate instances
					for (const FRelevantPrimitive& RelevantPrimitive : RelevantStaticPrimitives)