renderdoc.ReferenceAllResources

renderdoc.ReferenceAllResources

#Overview

name: renderdoc.ReferenceAllResources

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.ReferenceAllResources is to control the inclusion of rendering resources in RenderDoc captures. This setting variable is specifically for the RenderDoc debugging and profiling tool integration within Unreal Engine 5.

This setting variable is primarily used by the RenderDoc plugin, which is part of the developer tools in Unreal Engine. It’s referenced in the RenderDocPluginModule, which is responsible for integrating RenderDoc functionality into the engine.

The value of this variable is set through a console variable (CVarRenderDocReferenceAllResources) in the RenderDocPluginModule.cpp file. It’s initialized with a default value of 0, meaning by default, only resources that are actually used during the frame will be included in the capture.

This variable interacts closely with other RenderDoc-related settings, such as CVarRenderDocCaptureCallstacks and CVarRenderDocSaveAllInitials. Together, these variables control various aspects of RenderDoc captures.

Developers must be aware that setting this variable to 1 will include all rendering resources in the capture, even those not used during the frame. This can significantly increase the capture size, which may impact performance and storage requirements.

Best practices when using this variable include:

  1. Keep it set to 0 (default) for normal debugging sessions to minimize capture size and performance impact.
  2. Only set it to 1 when you need to investigate issues related to unused resources or when you need a complete snapshot of all rendering resources.
  3. Be prepared for larger capture sizes and potential performance impacts when set to 1.

Regarding the associated variable CVarRenderDocReferenceAllResources:

The purpose of CVarRenderDocReferenceAllResources is to provide a programmatic way to control the renderdoc.ReferenceAllResources setting within the engine’s code.

This variable is used directly in the RenderDocPluginModule to set the corresponding RenderDoc API option. It’s accessed in the StartupModule and BeginFrameCapture functions to configure RenderDoc before capturing frames.

The value of this variable is set through the console variable system, allowing it to be changed at runtime through console commands or configuration files.

It interacts directly with the RenderDoc API, translating the Unreal Engine setting into the appropriate RenderDoc option (eRENDERDOC_Option_RefAllResources).

Developers should be aware that changes to this variable will take effect the next time a frame capture is started. It’s not retroactive for already captured frames.

Best practices for using this variable include:

  1. Use it in conjunction with other RenderDoc settings for comprehensive control over captures.
  2. Consider exposing it in debug UIs or config files for easy toggling during development.
  3. Be cautious about performance impacts when enabling it, especially in larger or more complex scenes.

#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:45

Scope: file

Source code excerpt:

	TEXT("1 - Capture callstacks for each API call."));
static TAutoConsoleVariable<int32> CVarRenderDocReferenceAllResources(
	TEXT("renderdoc.ReferenceAllResources"),
	0,
	TEXT("0 - Only include resources that are actually used. ")
	TEXT("1 - Include all rendering resources in the capture, even those that have not been used during the frame. ")
	TEXT("Please note that doing this will significantly increase capture size."));
static TAutoConsoleVariable<int32> CVarRenderDocSaveAllInitials(
	TEXT("renderdoc.SaveAllInitials"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	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,
	TEXT("0 - Only include resources that are actually used. ")
	TEXT("1 - Include all rendering resources in the capture, even those that have not been used during the frame. ")
	TEXT("Please note that doing this will significantly increase capture size."));
static TAutoConsoleVariable<int32> CVarRenderDocSaveAllInitials(

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

Scope (from outer to inner):

file
function     void FRenderDocPluginModule::StartupModule

Source code excerpt:


	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(
		TEXT("renderdoc.CaptureFrame"),

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

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;
	FRenderDocPluginModule* Plugin = this;