AutomationAllowFrameTraceCapture

AutomationAllowFrameTraceCapture

#Overview

name: AutomationAllowFrameTraceCapture

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 AutomationAllowFrameTraceCapture is to control whether automation processes are allowed to capture frame traces during testing. This setting variable is primarily used in the context of Unreal Engine’s automation and testing system.

This setting variable is relied upon by the Engine module, specifically within the automation testing subsystem. It’s used in the AutomationCommon namespace, which suggests it’s a core part of the automation framework.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 1, meaning frame trace capture is allowed by default. However, this can be changed at runtime through console commands or configuration files.

The associated variable CVarAutomationAllowFrameTraceCapture is the actual TAutoConsoleVariable that stores and manages the value of AutomationAllowFrameTraceCapture. They essentially represent the same setting, with CVarAutomationAllowFrameTraceCapture being the programmatic interface to access and modify the value.

Developers must be aware that this variable affects the behavior of automation tests, particularly those that involve frame trace capture. When set to 0, it will prevent frame traces from being captured during automation, which could impact certain types of performance or rendering tests.

Best practices when using this variable include:

  1. Only disable it if there’s a specific reason to prevent frame trace capture.
  2. Be aware of its state when debugging automation tests that rely on frame traces.
  3. Consider exposing it as a configurable option for your automation test suites.

Regarding the associated variable CVarAutomationAllowFrameTraceCapture:

The purpose of CVarAutomationAllowFrameTraceCapture is to provide a programmatic interface to the AutomationAllowFrameTraceCapture setting. It’s an instance of TAutoConsoleVariable, which is Unreal Engine’s mechanism for creating runtime-configurable variables.

This variable is used directly in the Engine module’s automation system. It’s checked in the CaptureFrameTrace function within the AutomationCommon namespace to determine whether frame trace capture should proceed.

The value of CVarAutomationAllowFrameTraceCapture is set when it’s declared, but can be modified at runtime through the console variable system.

It interacts directly with the RenderDocPlugin and the IRenderCaptureProvider interface, as seen in the code where it’s used.

Developers should be aware that accessing this variable should be done using the GetValueOnGameThread() method to ensure thread-safe access.

Best practices for using CVarAutomationAllowFrameTraceCapture include:

  1. Use GetValueOnGameThread() when accessing its value.
  2. Consider the performance implications of frequent checks against this variable.
  3. If you’re extending the automation system, follow the pattern shown in the CaptureFrameTrace function for consistency.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Tests/AutomationCommon.cpp:32

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarAutomationAllowFrameTraceCapture(
	TEXT("AutomationAllowFrameTraceCapture"),
	1,
	TEXT("Allow automation to capture frame traces."),
	ECVF_Default
	);

//declare static variable

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Tests/AutomationCommon.cpp:31

Scope: file

Source code excerpt:

DEFINE_LOG_CATEGORY(LogEngineAutomationTests);

static TAutoConsoleVariable<int32> CVarAutomationAllowFrameTraceCapture(
	TEXT("AutomationAllowFrameTraceCapture"),
	1,
	TEXT("Allow automation to capture frame traces."),
	ECVF_Default
	);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Tests/AutomationCommon.cpp:160

Scope (from outer to inner):

file
namespace    AutomationCommon
function     TArray<uint8> CaptureFrameTrace

Source code excerpt:

		TArray<uint8> FrameTrace;

		if (CVarAutomationAllowFrameTraceCapture.GetValueOnGameThread() != 0
			&& IRenderCaptureProvider::IsAvailable()
			&& FModuleManager::Get().IsModuleLoaded("RenderDocPlugin"))
		{
			const FString MapAndTest = MapOrContext / FPaths::MakeValidFileName(TestName, TEXT('_'));
			FString ScreenshotPath = GetScreenshotPath(MapAndTest);
			FString TempCaptureFilePath = FPaths::ChangeExtension(FPaths::ConvertRelativePathToFull(FPaths::AutomationDir() / TEXT("Incoming/") / ScreenshotPath), TEXT(".rdc"));