r.SceneCulling.DebugRenderMode

r.SceneCulling.DebugRenderMode

#Overview

name: r.SceneCulling.DebugRenderMode

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.SceneCulling.DebugRenderMode is to control the debug rendering mode for scene culling in Unreal Engine 5. This setting variable is primarily used for debugging and visualizing the scene culling process in the rendering system.

This setting variable is utilized by the Renderer module of Unreal Engine 5, specifically within the scene culling subsystem. The callsites are located in the SceneCullingRenderer.cpp file, which is part of the runtime renderer implementation.

The value of this variable is set through a console variable (CVar) system. It is defined as a TAutoConsoleVariable with an initial value of 0 (disabled by default). Users can change this value at runtime through the console or configuration files.

The associated variable CVarSceneCullingDebugRenderMode directly interacts with r.SceneCulling.DebugRenderMode. They share the same value and are used interchangeably in the code.

Developers must be aware that enabling this debug render mode (by setting the value to 1) may impact performance, as it forces ShaderPrint on and allocates additional space for debug rendering. It should only be used during development and debugging sessions, not in production builds.

Best practices when using this variable include:

  1. Use it only when necessary for debugging scene culling issues.
  2. Remember to disable it (set to 0) after debugging to avoid performance impacts.
  3. Be aware that it may not capture all information in a single frame due to the one-frame lag mentioned in the code.

Regarding the associated variable CVarSceneCullingDebugRenderMode:

The purpose of CVarSceneCullingDebugRenderMode is to provide a programmatic way to access and modify the r.SceneCulling.DebugRenderMode setting within the C++ code.

This variable is used directly in the Renderer module, specifically in the SceneCullingRenderer class. It allows the code to check the current debug render mode and adjust behavior accordingly.

The value of CVarSceneCullingDebugRenderMode is set automatically by the CVar system when r.SceneCulling.DebugRenderMode is modified. It can be accessed using the GetValueOnRenderThread() method.

Developers should be aware that this variable is marked as ECVF_RenderThreadSafe, meaning it’s safe to access from the render thread. However, they should still ensure they’re accessing it from the correct thread context.

Best practices for using CVarSceneCullingDebugRenderMode include:

  1. Always use GetValueOnRenderThread() when accessing its value in render thread code.
  2. Consider caching the value if it’s used multiple times in performance-critical sections to avoid repeated CVar lookups.
  3. Be cautious about changing this value during runtime, as it may affect ongoing rendering processes.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneCulling/SceneCullingRenderer.cpp:9

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarSceneCullingDebugRenderMode(
	TEXT("r.SceneCulling.DebugRenderMode"), 
	0, 
	TEXT("SceneCulling debug render mode.\n")
	TEXT(" 0 = Disabled (default)\n")
	TEXT(" 1 = Enabled"),
	ECVF_RenderThreadSafe);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneCulling/SceneCullingRenderer.cpp:8

Scope: file

Source code excerpt:

#include "ShaderPrintParameters.h"

static TAutoConsoleVariable<int32> CVarSceneCullingDebugRenderMode(
	TEXT("r.SceneCulling.DebugRenderMode"), 
	0, 
	TEXT("SceneCulling debug render mode.\n")
	TEXT(" 0 = Disabled (default)\n")
	TEXT(" 1 = Enabled"),
	ECVF_RenderThreadSafe);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneCulling/SceneCullingRenderer.cpp:113

Scope (from outer to inner):

file
function     void FSceneCullingRenderer::DebugRender

Source code excerpt:

	int32 MaxCellCount = SceneCulling.CellHeaders.Num();

	if (CVarSceneCullingDebugRenderMode.GetValueOnRenderThread() != 0 && MaxCellCount > 0)
	{
		// Force ShaderPrint on.
		ShaderPrint::SetEnabled(true); 

		// This lags by one frame, so may miss some in one frame, also overallocates since we will cull a lot.
		ShaderPrint::RequestSpaceForLines(MaxCellCount * 12 * Views.Num());