r.RayTracing.Geometry.StaticMeshes.WPO

r.RayTracing.Geometry.StaticMeshes.WPO

#Overview

name: r.RayTracing.Geometry.StaticMeshes.WPO

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

It is referenced in 9 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.RayTracing.Geometry.StaticMeshes.WPO is to control the evaluation of World Position Offset (WPO) for static meshes in ray tracing effects. It is part of the rendering system, specifically the ray tracing subsystem of Unreal Engine 5.

This setting variable is primarily used in the StaticMeshRender.cpp file, which is part of the Engine module. It affects how static meshes with World Position Offset are handled in ray tracing scenarios.

The value of this variable is set through a console variable (CVar) system, allowing it to be changed at runtime. It can have three possible values: 0: Static meshes with world position offset are hidden in ray tracing. 1: Static meshes with world position offset are visible in ray tracing, and WPO evaluation is enabled (default). 2: Static meshes with world position offset are visible in ray tracing, but WPO evaluation is disabled.

This variable interacts closely with the MaterialRelevance.bUsesWorldPositionOffset flag and the bEvaluateWorldPositionOffsetInRayTracing property of static mesh components.

Developers must be aware that changing this variable can have significant impacts on ray tracing performance and visual fidelity. When set to 1, it allows for dynamic geometry updates in ray tracing, which can be computationally expensive but provides accurate representation of WPO effects.

Best practices when using this variable include:

  1. Default to 1 for most scenarios to balance visual quality and performance.
  2. Use 0 if ray tracing performance is critical and WPO effects are not essential.
  3. Use 2 if you want to include static meshes with WPO in ray tracing but don’t need the WPO effect to be evaluated (e.g., for performance reasons).

The associated variable CVarRayTracingStaticMeshesWPO is the actual console variable that stores and provides access to the r.RayTracing.Geometry.StaticMeshes.WPO setting. It’s used throughout the code to check the current value of the setting and adjust behavior accordingly. This variable is initialized with a default value of 1 and can be changed at runtime through console commands or programmatically.

When using CVarRayTracingStaticMeshesWPO, developers should be aware that changes to this variable can trigger updates to the ray tracing scene, potentially affecting performance. It’s important to use this variable consistently across the codebase to ensure proper behavior of static meshes in ray tracing scenarios.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/StaticMeshRender.cpp:155

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarRayTracingStaticMeshesWPO(
	TEXT("r.RayTracing.Geometry.StaticMeshes.WPO"),
	1,
	TEXT("World position offset evaluation for static meshes with EvaluateWPO enabled in ray tracing effects.\n")
	TEXT(" 0: static meshes with world position offset hidden in ray tracing.\n")
	TEXT(" 1: static meshes with world position offset visible in ray tracing, WPO evaluation enabled (default).\n")
	TEXT(" 2: static meshes with world position offset visible in ray tracing, WPO evaluation disabled.")
);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Components/StaticMeshComponent.h:173

Scope: file

Source code excerpt:

	/** 
	 * Whether to evaluate World Position Offset for ray tracing. 
	 * This is only used when running with r.RayTracing.Geometry.StaticMeshes.WPO=1 
	 */
	UPROPERTY(EditAnywhere, AdvancedDisplay, BlueprintReadWrite, Category = RayTracing)
	uint8 bEvaluateWorldPositionOffsetInRayTracing : 1;

	/**
	 * Distance at which to disable World Position Offset for an entire instance (0 = Never disable WPO).
	 **/
	UPROPERTY(EditAnywhere, AdvancedDisplay, BlueprintReadOnly, Category = Rendering)
	int32 WorldPositionOffsetDisableDistance = 0;

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/StaticMeshRender.cpp:319

Scope (from outer to inner):

file
function     FStaticMeshSceneProxy::FStaticMeshSceneProxy

Source code excerpt:

		const bool bWantsRayTracingWPO = MaterialRelevance.bUsesWorldPositionOffset && InProxyDesc.bEvaluateWorldPositionOffsetInRayTracing;

		// r.RayTracing.Geometry.StaticMeshes.WPO is handled in the following way:
		// 0 - mark ray tracing geometry as dynamic but don't create any dynamic geometries since it won't be included in ray tracing scene
		// 1 - mark ray tracing geometry as dynamic and create dynamic geometries
		// 2 - don't mark ray tracing geometry as dynamic nor create any dynamic geometries since WPO evaluation is disabled

		// if r.RayTracing.Geometry.StaticMeshes.WPO == 2, WPO evaluation is disabled so don't need to mark geometry as dynamic
		if (bWantsRayTracingWPO && CVarRayTracingStaticMeshesWPO.GetValueOnAnyThread() != 2)
		{
			bDynamicRayTracingGeometry = true;

			// only need dynamic geometries when r.RayTracing.Geometry.StaticMeshes.WPO == 1
			bNeedsDynamicRayTracingGeometries = CVarRayTracingStaticMeshesWPO.GetValueOnAnyThread() == 1;
		}
	}
#endif

	for(int32 LODIndex = 0;LODIndex < RenderData->LODResources.Num();LODIndex++)

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/StaticMeshRender.cpp:424

Scope (from outer to inner):

file
function     void FStaticMeshSceneProxy::SetEvaluateWorldPositionOffsetInRayTracing

Source code excerpt:

	}

	// if r.RayTracing.Geometry.StaticMeshes.WPO == 2, WPO evaluation is disabled so don't need to mark geometry as dynamic
	NewValue &= MaterialRelevance.bUsesWorldPositionOffset && CVarRayTracingStaticMeshesWPO.GetValueOnAnyThread() != 2;

	if (NewValue && !bDynamicRayTracingGeometry)
	{
		bDynamicRayTracingGeometry = true;

		// only need dynamic geometries when r.RayTracing.Geometry.StaticMeshes.WPO == 1
		bNeedsDynamicRayTracingGeometries = CVarRayTracingStaticMeshesWPO.GetValueOnAnyThread() == 1;

		if (GetPrimitiveSceneInfo())
		{
			GetPrimitiveSceneInfo()->bIsRayTracingStaticRelevant = IsRayTracingStaticRelevant();
		}

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/StaticMeshRender.cpp:154

Scope: file

Source code excerpt:

	TEXT("Include static meshes in ray tracing effects (default = 1 (static meshes enabled in ray tracing))"));

static TAutoConsoleVariable<int32> CVarRayTracingStaticMeshesWPO(
	TEXT("r.RayTracing.Geometry.StaticMeshes.WPO"),
	1,
	TEXT("World position offset evaluation for static meshes with EvaluateWPO enabled in ray tracing effects.\n")
	TEXT(" 0: static meshes with world position offset hidden in ray tracing.\n")
	TEXT(" 1: static meshes with world position offset visible in ray tracing, WPO evaluation enabled (default).\n")
	TEXT(" 2: static meshes with world position offset visible in ray tracing, WPO evaluation disabled.")

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/StaticMeshRender.cpp:165

Scope (from outer to inner):

file
lambda-function

Source code excerpt:

FAutoConsoleVariableSink CVarRayTracingStaticMeshesWPOSink(FConsoleCommandDelegate::CreateLambda([]()
{
	static int32 CachedRayTracingStaticMeshesWPO = CVarRayTracingStaticMeshesWPO.GetValueOnGameThread();

	int32 RayTracingStaticMeshesWPO = CVarRayTracingStaticMeshesWPO.GetValueOnGameThread();

	if (CachedRayTracingStaticMeshesWPO != RayTracingStaticMeshesWPO)
	{
		CachedRayTracingStaticMeshesWPO = RayTracingStaticMeshesWPO;

		// NV-JIRA UE-668: Do this as a task on the game thread to break up a possible

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/StaticMeshRender.cpp:325

Scope (from outer to inner):

file
function     FStaticMeshSceneProxy::FStaticMeshSceneProxy

Source code excerpt:


		// if r.RayTracing.Geometry.StaticMeshes.WPO == 2, WPO evaluation is disabled so don't need to mark geometry as dynamic
		if (bWantsRayTracingWPO && CVarRayTracingStaticMeshesWPO.GetValueOnAnyThread() != 2)
		{
			bDynamicRayTracingGeometry = true;

			// only need dynamic geometries when r.RayTracing.Geometry.StaticMeshes.WPO == 1
			bNeedsDynamicRayTracingGeometries = CVarRayTracingStaticMeshesWPO.GetValueOnAnyThread() == 1;
		}
	}
#endif

	for(int32 LODIndex = 0;LODIndex < RenderData->LODResources.Num();LODIndex++)
	{

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/StaticMeshRender.cpp:425

Scope (from outer to inner):

file
function     void FStaticMeshSceneProxy::SetEvaluateWorldPositionOffsetInRayTracing

Source code excerpt:


	// if r.RayTracing.Geometry.StaticMeshes.WPO == 2, WPO evaluation is disabled so don't need to mark geometry as dynamic
	NewValue &= MaterialRelevance.bUsesWorldPositionOffset && CVarRayTracingStaticMeshesWPO.GetValueOnAnyThread() != 2;

	if (NewValue && !bDynamicRayTracingGeometry)
	{
		bDynamicRayTracingGeometry = true;

		// only need dynamic geometries when r.RayTracing.Geometry.StaticMeshes.WPO == 1
		bNeedsDynamicRayTracingGeometries = CVarRayTracingStaticMeshesWPO.GetValueOnAnyThread() == 1;

		if (GetPrimitiveSceneInfo())
		{
			GetPrimitiveSceneInfo()->bIsRayTracingStaticRelevant = IsRayTracingStaticRelevant();
		}

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/StaticMeshRender.cpp:1890

Scope (from outer to inner):

file
function     void FStaticMeshSceneProxy::GetDynamicRayTracingInstances

Source code excerpt:

	}

	checkf(CVarRayTracingStaticMeshesWPO.GetValueOnRenderThread() == 1,
		TEXT("Proxy should only have entries in DynamicRayTracingGeometries when WPO evaluation is enabled"));

	if (!ensureMsgf(IsRayTracingRelevant(),
		TEXT("GetDynamicRayTracingInstances() is only expected to be called for scene proxies that are compatible with ray tracing. ")
		TEXT("RT-relevant primitive gathering code in FDeferredShadingSceneRenderer may be wrong.")))
	{