r.OIT.SortedTriangles.Debug

r.OIT.SortedTriangles.Debug

#Overview

name: r.OIT.SortedTriangles.Debug

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.OIT.SortedTriangles.Debug is to enable per-instance triangle sorting debug rendering in the Order-Independent Transparency (OIT) system of Unreal Engine 5.

This setting variable is primarily used in the rendering system, specifically in the OIT subsystem. Based on the callsites, it is implemented in the Renderer module of Unreal Engine 5.

The value of this variable is set through a console variable (CVarOIT_SortedTriangles_Debug) with an initial value of 0, meaning it’s disabled by default. It can be changed at runtime through console commands or programmatically.

The associated variable CVarOIT_SortedTriangles_Debug interacts directly with r.OIT.SortedTriangles.Debug. They share the same value and purpose.

Developers must be aware that enabling this debug feature may impact rendering performance, as it adds additional debug rendering for per-instance triangle sorting. It should only be used when debugging OIT-related issues or when analyzing the behavior of the triangle sorting algorithm.

Best practices for using this variable include:

  1. Only enable it when necessary for debugging or analysis.
  2. Disable it in production builds to avoid performance overhead.
  3. Use it in conjunction with other OIT-related debug tools for comprehensive analysis.
  4. Be cautious when enabling it in performance-critical scenarios.

Regarding the associated variable CVarOIT_SortedTriangles_Debug:

This is a TAutoConsoleVariable that directly controls the r.OIT.SortedTriangles.Debug setting. It is defined in the OIT.cpp file and is used to toggle the debug rendering feature.

The variable is checked in the render thread (GetValueOnRenderThread()) to determine if debug rendering should be enabled. When enabled (value > 0), it triggers the creation of debug data buffers and potentially additional render passes for visualizing the per-instance triangle sorting.

Developers should use this console variable to dynamically toggle the debug rendering feature during runtime, which can be particularly useful for real-time debugging and analysis of the OIT system’s behavior.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/OIT/OIT.cpp:27

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarOIT_SortedTriangles_Debug(
	TEXT("r.OIT.SortedTriangles.Debug"), 
	0, 
	TEXT("Enable per-instance triangle sorting debug rendering."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarOIT_SortedTriangles_Pool(
	TEXT("r.OIT.SortedTriangles.Pool"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/OIT/OIT.cpp:26

Scope: file

Source code excerpt:

	ECVF_ReadOnly | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarOIT_SortedTriangles_Debug(
	TEXT("r.OIT.SortedTriangles.Debug"), 
	0, 
	TEXT("Enable per-instance triangle sorting debug rendering."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarOIT_SortedTriangles_Pool(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/OIT/OIT.cpp:861

Scope: file

Source code excerpt:

		RDG_EVENT_SCOPE(GraphBuilder, "OIT::IndexSorting");

		const bool bDebugEnable = CVarOIT_SortedTriangles_Debug.GetValueOnRenderThread() > 0;
		FOITDebugData DebugData;
		if (bDebugEnable)
		{
			const uint32 ValidAllocationCount = OITSceneData.Allocations.Num();
			DebugData.Buffer = GraphBuilder.CreateBuffer(FRDGBufferDesc::CreateBufferDesc(4u, 10*ValidAllocationCount + 1), TEXT("OIT.DebugData"));
			AddClearUAVPass(GraphBuilder, GraphBuilder.CreateUAV(DebugData.Buffer, FOITDebugData::Format), 0u);