r.SceneCapture.CullByDetailMode

r.SceneCapture.CullByDetailMode

#Overview

name: r.SceneCapture.CullByDetailMode

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.SceneCapture.CullByDetailMode is to control whether scene capture updates are prevented based on the current detail mode. This setting variable is part of the rendering system, specifically related to scene capture functionality in Unreal Engine 5.

This setting variable is primarily used by the Scene Capture components in the Engine module. It affects both USceneCaptureComponent2D and USceneCaptureComponentCube classes, which are responsible for capturing scenes and rendering them to textures.

The value of this variable is set through a console variable (CVar) named CVarSCCullByDetailMode. It is initialized with a default value of 1 (true), meaning scene capture culling by detail mode is enabled by default.

The associated variable CVarSCCullByDetailMode directly interacts with r.SceneCapture.CullByDetailMode. They share the same value and purpose.

Developers must be aware that when this setting is enabled (set to 1), scene captures may not update if the current detail mode is lower than the component’s DetailMode. This can affect the rendering of captured scenes in various situations, such as when using render targets or reflections.

Best practices when using this variable include:

  1. Consider the performance implications of disabling this culling mechanism, as it may lead to unnecessary scene capture updates.
  2. Adjust the DetailMode of scene capture components appropriately to ensure they update as expected when this setting is enabled.
  3. Use the CaptureScene() and CaptureSceneDeferred() functions with caution, as they respect this setting.

Regarding the associated variable CVarSCCullByDetailMode:

The purpose of CVarSCCullByDetailMode is to provide programmatic access to the r.SceneCapture.CullByDetailMode setting within the engine’s C++ code.

This console variable is used internally by the Scene Capture components to determine whether culling by detail mode should be applied. It’s primarily accessed through the IsCulledByDetailMode() function in the USceneCaptureComponent class.

The value of CVarSCCullByDetailMode is set when the engine initializes the console variables, and it can be changed at runtime through console commands.

Developers should be aware that changing the value of CVarSCCullByDetailMode at runtime will affect all scene capture components in the game. It’s a global setting that can have performance implications if modified carelessly.

Best practices for using CVarSCCullByDetailMode include:

  1. Avoid frequently changing its value during gameplay, as it may lead to inconsistent rendering behavior.
  2. Consider exposing a user-friendly setting in your game options that modifies this value if you want to give players control over scene capture performance.
  3. When debugging scene capture issues, check the value of this variable to ensure it’s not unexpectedly culling your captures.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/SceneCaptureComponent.cpp:70

Scope: file

Source code excerpt:


static TAutoConsoleVariable<bool> CVarSCCullByDetailMode(
	TEXT("r.SceneCapture.CullByDetailMode"),
	1,
	TEXT("Whether to prevent scene capture updates according to the current detail mode"),
	ECVF_Scalability);

ASceneCapture::ASceneCapture(const FObjectInitializer& ObjectInitializer)
	: Super(ObjectInitializer)

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Components/SceneCaptureComponent2D.h:176

Scope (from outer to inner):

file
class        class USceneCaptureComponent2D : public USceneCaptureComponent

Source code excerpt:

	/**
	 * Render the scene to the texture the next time the main view is rendered.
	 * If r.SceneCapture.CullByDetailMode is set, nothing will happen if DetailMode is higher than r.DetailMode.
	 */
	ENGINE_API void CaptureSceneDeferred();

	// For backwards compatibility
	void UpdateContent() { CaptureSceneDeferred(); }

	/** 
	 * Render the scene to the texture target immediately.  
	 * This should not be used if bCaptureEveryFrame is enabled, or the scene capture will render redundantly. 
	 * If r.SceneCapture.CullByDetailMode is set, nothing will happen if DetailMode is higher than r.DetailMode.
	 */
	UFUNCTION(BlueprintCallable,Category = "Rendering|SceneCapture")
	ENGINE_API void CaptureScene();

	ENGINE_API void UpdateSceneCaptureContents(FSceneInterface* Scene) override;

	/* Return if orthographic tiling rendering is enabled or not */
	ENGINE_API bool GetEnableOrthographicTiling() const;

	/* Return number of X tiles to render (to be used when orthographic tiling rendering is enabled) */

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Components/SceneCaptureComponentCube.h:43

Scope (from outer to inner):

file
class        class USceneCaptureComponentCube : public USceneCaptureComponent

Source code excerpt:

	/**
	 * Render the scene to the texture the next time the main view is rendered.
	 * If r.SceneCapture.CullByDetailMode is set, nothing will happen if DetailMode is higher than r.DetailMode.
	 */
	ENGINE_API void CaptureSceneDeferred();

	/** 
	 * Render the scene to the texture target immediately.  
	 * This should not be used if bCaptureEveryFrame is enabled, or the scene capture will render redundantly. 
	 * If r.SceneCapture.CullByDetailMode is set, nothing will happen if DetailMode is higher than r.DetailMode.
	 */
	UFUNCTION(BlueprintCallable,Category = "Rendering|SceneCapture")
	ENGINE_API void CaptureScene();

	// For backwards compatibility
	void UpdateContent() { CaptureSceneDeferred(); }

	ENGINE_API void UpdateSceneCaptureContents(FSceneInterface* Scene) override;

	/** Whether this component is a USceneCaptureComponentCube */

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/SceneCaptureComponent.cpp:69

Scope: file

Source code excerpt:

	ECVF_Scalability);

static TAutoConsoleVariable<bool> CVarSCCullByDetailMode(
	TEXT("r.SceneCapture.CullByDetailMode"),
	1,
	TEXT("Whether to prevent scene capture updates according to the current detail mode"),
	ECVF_Scalability);

ASceneCapture::ASceneCapture(const FObjectInitializer& ObjectInitializer)

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/SceneCaptureComponent.cpp:542

Scope (from outer to inner):

file
function     bool USceneCaptureComponent::IsCulledByDetailMode

Source code excerpt:

bool USceneCaptureComponent::IsCulledByDetailMode() const
{
	return CVarSCCullByDetailMode.GetValueOnAnyThread() && DetailMode > GetCachedScalabilityCVars().DetailMode;
}

// -----------------------------------------------


USceneCaptureComponent2D::USceneCaptureComponent2D(const FObjectInitializer& ObjectInitializer)