Slate.DeferRetainedRenderingRenderThread

Slate.DeferRetainedRenderingRenderThread

#Overview

name: Slate.DeferRetainedRenderingRenderThread

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 Slate.DeferRetainedRenderingRenderThread is to control whether retained rendering in Slate (Unreal Engine’s UI framework) should be deferred to happen at the same time as other Slate render thread work.

This setting variable is primarily used in the rendering system, specifically for Slate UI rendering and Widget Components. It is part of the UMG (Unreal Motion Graphics) module, which is responsible for creating and managing user interfaces in Unreal Engine.

The Unreal Engine subsystems that rely on this setting variable are:

  1. Slate rendering system
  2. UMG (Widget Components)

The value of this variable is set through a console variable, which allows it to be changed at runtime. It is initialized with the value of PLATFORM_REQUIRES_DEFERRED_RETAINER_UPDATE, which suggests that the default value may vary depending on the platform.

This variable interacts with an associated variable named GDeferRetainedRenderingRenderThread. They share the same value and are used interchangeably in the code.

Developers must be aware of the following when using this variable:

  1. Changing this value affects the timing of retained rendering updates.
  2. When enabled (non-zero value), it can help avoid extra render target switching in the middle of the frame.
  3. The trade-off is that UI updates may be a frame late when deferred rendering is enabled.

Best practices when using this variable include:

  1. Consider the performance implications of enabling or disabling deferred retained rendering on your target platforms.
  2. Test your UI performance with both settings to determine which works best for your specific use case.
  3. Be aware of the potential one-frame delay in UI updates when using deferred rendering.

Regarding the associated variable GDeferRetainedRenderingRenderThread: The purpose of GDeferRetainedRenderingRenderThread is the same as Slate.DeferRetainedRenderingRenderThread. It is an integer variable that controls whether retained rendering should be deferred.

This variable is used directly in the UMG module, specifically in the SRetainerWidget and WidgetComponent classes. It affects how and when retained content is painted and updated.

The value of GDeferRetainedRenderingRenderThread is set through the console variable Slate.DeferRetainedRenderingRenderThread, allowing for runtime configuration.

Developers should be aware that this variable is used in performance-critical rendering code, and changing its value can affect both rendering performance and UI update latency.

Best practices for using GDeferRetainedRenderingRenderThread include:

  1. Use it in conjunction with profiling tools to determine the optimal setting for your game’s UI performance.
  2. Consider the trade-off between potential performance improvements and the increased UI update latency when enabled.
  3. Be consistent in using either the console variable or this global variable throughout your codebase to avoid confusion.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/UMG/Private/Slate/SRetainerWidget.cpp:63

Scope: file

Source code excerpt:

int32 GDeferRetainedRenderingRenderThread = PLATFORM_REQUIRES_DEFERRED_RETAINER_UPDATE;
FAutoConsoleVariableRef DeferRetainedRenderingRT(
	TEXT("Slate.DeferRetainedRenderingRenderThread"),
	GDeferRetainedRenderingRenderThread,
	TEXT("Whether or not to defer retained rendering to happen at the same time as the rest of slate render thread work"));


class FRetainerWidgetRenderingResources : public FDeferredCleanupInterface, public FGCObject
{

#Loc: <Workspace>/Engine/Source/Runtime/UMG/Private/Components/WidgetComponent.cpp:1424

Scope (from outer to inner):

file
function     void UWidgetComponent::DrawWidgetToRenderTarget

Source code excerpt:

		if (bUseInvalidationInWorldSpace)
		{
			static IConsoleVariable* CVar = IConsoleManager::Get().FindConsoleVariable(TEXT("Slate.DeferRetainedRenderingRenderThread"));
			ensure(CVar);
			bool bDeferRetainedRenderingRenderThread = CVar ? CVar->GetInt() != 0 : false;

			FPaintArgs PaintArgs(nullptr, SlateWindow->GetHittestGrid(), FVector2D::ZeroVector, FApp::GetCurrentTime(), DeltaTime);
			TSharedRef<SVirtualWindow> WindowToDraw = SlateWindow.ToSharedRef();

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/SlateCore/Public/Rendering/SlateRenderer.h:551

Scope: file

Source code excerpt:

	 * @param Context						The context that describes what we're rendering to
	 * @param bDeferredRenderTargetUpdate	Whether or not the update is deferred until the end of the frame when it is potentially less expensive to update the render target. 
											See GDeferRetainedRenderingRenderThread for more info.
											Care must be taken to destroy anything referenced in the context when it is safe to do so.
	 */
	virtual void AddWidgetRendererUpdate(const struct FRenderThreadUpdateContext& Context, bool bDeferredRenderTargetUpdate) {}

	virtual EPixelFormat GetSlateRecommendedColorFormat() { return PF_B8G8R8A8; }

	virtual void OnVirtualDesktopSizeChanged(const FDisplayMetrics& NewDisplayMetric) {}
private:

	// Non-copyable
	SLATECORE_API FSlateRenderer(const FSlateRenderer&);
	SLATECORE_API FSlateRenderer& operator=(const FSlateRenderer&);

#Loc: <Workspace>/Engine/Source/Runtime/UMG/Private/Slate/SRetainerWidget.cpp:61

Scope: file

Source code excerpt:

 * in order to avoid extra render target switching in the middle of the frame. The downside is that the UI update will be a frame late
 */
int32 GDeferRetainedRenderingRenderThread = PLATFORM_REQUIRES_DEFERRED_RETAINER_UPDATE;
FAutoConsoleVariableRef DeferRetainedRenderingRT(
	TEXT("Slate.DeferRetainedRenderingRenderThread"),
	GDeferRetainedRenderingRenderThread,
	TEXT("Whether or not to defer retained rendering to happen at the same time as the rest of slate render thread work"));


class FRetainerWidgetRenderingResources : public FDeferredCleanupInterface, public FGCObject
{
public:

#Loc: <Workspace>/Engine/Source/Runtime/UMG/Private/Slate/SRetainerWidget.cpp:575

Scope (from outer to inner):

file
function     SRetainerWidget::EPaintRetainedContentResult SRetainerWidget::PaintRetainedContentImpl

Source code excerpt:

				VirtualWindow->Resize(WindowSize);

				bool bRepaintedWidgets = WidgetRenderer->DrawInvalidationRoot(VirtualWindow, RenderTarget, *this, Context, GDeferRetainedRenderingRenderThread != 0);
				bRenderRequested = false;
				Shared_WaitingToRender.Remove(this);

				LastDrawTime = FApp::GetCurrentTime();

				return bRepaintedWidgets ? EPaintRetainedContentResult::Painted : EPaintRetainedContentResult::NotPainted;