renderdoc.CaptureCallstacks

renderdoc.CaptureCallstacks

#Overview

name: renderdoc.CaptureCallstacks

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of renderdoc.CaptureCallstacks is to control whether RenderDoc, a graphics debugging tool, captures callstacks for each API call during frame capture. This setting is part of the RenderDoc plugin for Unreal Engine 5, which is used for debugging and profiling rendering operations.

The RenderDoc plugin module relies on this setting variable. It is primarily used in the RenderDocPluginModule, which is part of the Developer plugin category in Unreal Engine.

The value of this variable is set through a console variable (CVarRenderDocCaptureCallstacks) with a default value of 1, meaning callstack capture is enabled by default. Users can change this value at runtime using console commands.

This variable interacts closely with other RenderDoc-related settings, such as CVarRenderDocReferenceAllResources and CVarRenderDocSaveAllInitials. These settings collectively control various aspects of RenderDoc’s capture behavior.

Developers should be aware that enabling callstack capture (setting the value to 1) may introduce some performance overhead during capture. It’s useful for detailed debugging but might slow down the capture process.

Best practices for using this variable include:

  1. Enable it (set to 1) when detailed API call information is needed for debugging.
  2. Disable it (set to 0) when performance during capture is a priority or when callstack information is not necessary.
  3. Consider the impact on capture file size, as capturing callstacks can significantly increase the size of capture files.

Regarding the associated variable CVarRenderDocCaptureCallstacks:

The purpose of CVarRenderDocCaptureCallstacks is to provide a console-accessible way to control the renderdoc.CaptureCallstacks setting. It’s part of the RenderDoc plugin’s configuration system within Unreal Engine.

This console variable is used in the RenderDocPluginModule to set the corresponding RenderDoc API option (eRENDERDOC_Option_CaptureCallstacks) when initializing the module and before beginning a frame capture.

The value of CVarRenderDocCaptureCallstacks is set at declaration with a default of 1, but can be changed at runtime through the console.

It interacts directly with the RenderDoc API, translating the console variable value to the appropriate API call.

Developers should be aware that changes to this console variable take effect immediately and will affect subsequent capture operations.

Best practices for using CVarRenderDocCaptureCallstacks include:

  1. Use it to dynamically toggle callstack capture without recompiling the engine.
  2. Combine it with other RenderDoc console variables for comprehensive capture configuration.
  3. Document its usage in project-specific debugging guidelines to ensure consistent use across the development team.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/Developer/RenderDocPlugin/Source/RenderDocPlugin/Private/RenderDocPluginModule.cpp:40

Scope: file

Source code excerpt:

	TEXT("1 - RenderDoc will capture all activity, in all viewports and editor windows for the entire frame."));
static TAutoConsoleVariable<int32> CVarRenderDocCaptureCallstacks(
	TEXT("renderdoc.CaptureCallstacks"),
	1,
	TEXT("0 - Callstacks will not be captured by RenderDoc. ")
	TEXT("1 - Capture callstacks for each API call."));
static TAutoConsoleVariable<int32> CVarRenderDocReferenceAllResources(
	TEXT("renderdoc.ReferenceAllResources"),
	0,

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/Developer/RenderDocPlugin/Source/RenderDocPlugin/Private/RenderDocPluginModule.cpp:39

Scope: file

Source code excerpt:

	TEXT("0 - RenderDoc will only capture data from the current viewport. ")
	TEXT("1 - RenderDoc will capture all activity, in all viewports and editor windows for the entire frame."));
static TAutoConsoleVariable<int32> CVarRenderDocCaptureCallstacks(
	TEXT("renderdoc.CaptureCallstacks"),
	1,
	TEXT("0 - Callstacks will not be captured by RenderDoc. ")
	TEXT("1 - Capture callstacks for each API call."));
static TAutoConsoleVariable<int32> CVarRenderDocReferenceAllResources(
	TEXT("renderdoc.ReferenceAllResources"),

#Loc: <Workspace>/Engine/Plugins/Developer/RenderDocPlugin/Source/RenderDocPlugin/Private/RenderDocPluginModule.cpp:299

Scope (from outer to inner):

file
function     void FRenderDocPluginModule::StartupModule

Source code excerpt:

	RenderDocAPI->SetCaptureKeys(nullptr, 0);

	RenderDocAPI->SetCaptureOptionU32(eRENDERDOC_Option_CaptureCallstacks, CVarRenderDocCaptureCallstacks.GetValueOnAnyThread() ? 1 : 0);
	RenderDocAPI->SetCaptureOptionU32(eRENDERDOC_Option_RefAllResources, CVarRenderDocReferenceAllResources.GetValueOnAnyThread() ? 1 : 0);
	RenderDocAPI->SetCaptureOptionU32(eRENDERDOC_Option_SaveAllInitials, CVarRenderDocSaveAllInitials.GetValueOnAnyThread() ? 1 : 0);

	RenderDocAPI->MaskOverlayBits(eRENDERDOC_Overlay_None, eRENDERDOC_Overlay_None);

	static FAutoConsoleCommand CCmdRenderDocCaptureFrame = FAutoConsoleCommand(

#Loc: <Workspace>/Engine/Plugins/Developer/RenderDocPlugin/Source/RenderDocPlugin/Private/RenderDocPluginModule.cpp:341

Scope (from outer to inner):

file
function     void FRenderDocPluginModule::BeginFrameCapture

Source code excerpt:


	pRENDERDOC_SetCaptureOptionU32 SetOptions = Loader.RenderDocAPI->SetCaptureOptionU32;
	int ok = SetOptions(eRENDERDOC_Option_CaptureCallstacks, CVarRenderDocCaptureCallstacks.GetValueOnAnyThread() ? 1 : 0); check(ok);
		ok = SetOptions(eRENDERDOC_Option_RefAllResources, CVarRenderDocReferenceAllResources.GetValueOnAnyThread() ? 1 : 0); check(ok);
		ok = SetOptions(eRENDERDOC_Option_SaveAllInitials, CVarRenderDocSaveAllInitials.GetValueOnAnyThread() ? 1 : 0); check(ok);

	HWND WindowHandle = GetActiveWindow();

	typedef FRenderDocPluginLoader::RENDERDOC_API_CONTEXT RENDERDOC_API_CONTEXT;