r.RayTracing.Geometry.HierarchicalInstancedStaticMesh

r.RayTracing.Geometry.HierarchicalInstancedStaticMesh

#Overview

name: r.RayTracing.Geometry.HierarchicalInstancedStaticMesh

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

• type: Var
• help: Include HISM in ray tracing effects (default = 1)

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.RayTracing.Geometry.HierarchicalInstancedStaticMesh is to control the inclusion of Hierarchical Instanced Static Meshes (HISM) in ray tracing effects within Unreal Engine 5. This setting variable is primarily used in the rendering system, specifically for ray tracing functionality.

The Unreal Engine subsystems that rely on this setting variable are the rendering system and the ray tracing module. It is referenced in multiple files related to scene proxies, Nanite resources, and ray tracing implementation.

The value of this variable is set through a console variable (CVar) system. It is initialized with a default value of 1, which means HISMs are included in ray tracing effects by default.

This variable interacts with other ray tracing-related variables, such as r.RayTracing.Geometry.StaticMeshes, r.RayTracing.Geometry.NaniteProxies, and r.RayTracing.Geometry.LandscapeGrass. These variables collectively control which types of geometry are included in ray tracing calculations.

Developers must be aware that setting this variable to 0 or a negative value will exclude HISMs from ray tracing effects. This can significantly impact the visual quality and accuracy of ray-traced scenes that contain instanced geometry.

Best practices when using this variable include:

1. Keep it enabled (value of 1) for the most accurate and visually consistent results in scenes with instanced geometry.
2. Consider disabling it (value of 0) only if performance is a critical issue and the visual impact is acceptable.
3. Test thoroughly when changing this setting, as it can affect the appearance of ray-traced effects throughout the entire scene.
4. Be aware of its interaction with other ray tracing geometry settings to ensure consistent behavior across different types of scene elements.
5. Use it in conjunction with performance profiling tools to find the right balance between visual quality and rendering performance for your specific project needs.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/HierarchicalInstancedStaticMesh.cpp:139

Scope: file

Source code excerpt:

#if RHI_RAYTRACING
static TAutoConsoleVariable<int32> CVarRayTracingHISM(
	TEXT("r.RayTracing.Geometry.HierarchicalInstancedStaticMesh"),
	1,
	TEXT("Include HISM in ray tracing effects (default = 1)"));
#endif

DECLARE_CYCLE_STAT(TEXT("Traversal Time"),STAT_FoliageTraversalTime,STATGROUP_Foliage);
DECLARE_CYCLE_STAT(TEXT("Build Time"), STAT_FoliageBuildTime, STATGROUP_Foliage);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PrimitiveSceneProxy.cpp:1788

Scope (from outer to inner):

file
function     ERayTracingPrimitiveFlags FPrimitiveSceneProxy::GetCachedRayTracingInstance

Source code excerpt:

	}

	static const auto RayTracingHISMCVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.RayTracing.Geometry.HierarchicalInstancedStaticMesh"));

	if (bIsHierarchicalInstancedStaticMesh && RayTracingHISMCVar && RayTracingHISMCVar->GetValueOnRenderThread() <= 0)
	{
		return ERayTracingPrimitiveFlags::Exclude;
	}

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Rendering/NaniteResources.cpp:1930

Scope (from outer to inner):

file
namespace    Nanite
function     ERayTracingPrimitiveFlags FSceneProxy::GetCachedRayTracingInstance

Source code excerpt:

	}

	static const auto RayTracingHISMCVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.RayTracing.Geometry.HierarchicalInstancedStaticMesh"));

	if (bIsHierarchicalInstancedStaticMesh && RayTracingHISMCVar && RayTracingHISMCVar->GetValueOnRenderThread() <= 0)
	{
		return ERayTracingPrimitiveFlags::Exclude;
	}

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

Scope (from outer to inner):

file
function     static void RefreshRayTracingInstancesSinkFunction

Source code excerpt:

{
	static const auto RayTracingStaticMeshesCVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.RayTracing.Geometry.StaticMeshes"));
	static const auto RayTracingHISMCVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.RayTracing.Geometry.HierarchicalInstancedStaticMesh"));
	static const auto RayTracingNaniteProxiesCVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.RayTracing.Geometry.NaniteProxies"));
	static const auto RayTracingLandscapeGrassCVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.RayTracing.Geometry.LandscapeGrass"));

	static int32 CachedRayTracingStaticMeshes = RayTracingStaticMeshesCVar->GetValueOnGameThread();
	static int32 CachedRayTracingHISM = RayTracingHISMCVar->GetValueOnGameThread();
	static int32 CachedRayTracingNaniteProxies = RayTracingNaniteProxiesCVar->GetValueOnGameThread();