MoviePipeline.FlushLayersDebug

MoviePipeline.FlushLayersDebug

#Overview

name: MoviePipeline.FlushLayersDebug

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

• type: Var
• help: This is a debug cvar intended to help diagnose issues in the MoviePipeline multi-layer rendering mode\nthat flushes any outstanding rendering commands for each layer. This can have a large performance impact,\nas it effectively removes any parallelism between the Game Thread and Render Thread!\n 0 - Don\'t flush (default)\n 1 - Flush (but negatively impacts performance)

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of MoviePipeline.FlushLayersDebug is to serve as a debug console variable (cvar) for diagnosing issues in the MoviePipeline multi-layer rendering mode. It controls whether to flush outstanding rendering commands for each layer during the movie pipeline rendering process.

This setting variable is primarily used in the MovieRenderPipeline plugin, specifically within the MovieRenderPipelineRenderPasses module. It affects the rendering system, particularly the interaction between the Game Thread and Render Thread.

The value of this variable is set through the console variable system in Unreal Engine. It’s defined as a boolean value, defaulting to false.

The associated variable CVarMoviePipelineFlushRenderingPerLayerHack directly interacts with MoviePipeline.FlushLayersDebug. They share the same value and purpose.

Developers must be aware of several important points when using this variable:

1. Enabling this variable (setting it to true) can have a significant negative impact on performance.
2. When enabled, it effectively removes parallelism between the Game Thread and Render Thread.
3. It’s intended for debugging purposes only and should not be enabled in production builds.

Best practices for using this variable include:

1. Only enable it when specifically debugging issues related to multi-layer rendering in the MoviePipeline.
2. Be prepared for performance degradation when the variable is enabled.
3. Always disable it after debugging is complete to restore normal performance.
4. Use it in conjunction with other debugging tools to isolate rendering issues.

Regarding the associated variable CVarMoviePipelineFlushRenderingPerLayerHack:

The purpose of CVarMoviePipelineFlushRenderingPerLayerHack is identical to MoviePipeline.FlushLayersDebug. It’s the actual C++ variable that implements the functionality controlled by the console variable.

This variable is used within the UMovieGraphImagePassBaseNode::RenderImpl function to determine whether to flush rendering commands after each layer is processed. When the value is true, it calls FlushRenderingCommands() after rendering each layer.

The same considerations and best practices apply to CVarMoviePipelineFlushRenderingPerLayerHack as to MoviePipeline.FlushLayersDebug. Developers should be cautious when enabling this feature due to its performance implications and should only use it for debugging purposes.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/MovieScene/MovieRenderPipeline/Source/MovieRenderPipelineRenderPasses/Private/Graph/Nodes/MovieGraphImagePassBaseNode.cpp:5

Scope: file

Source code excerpt:

static TAutoConsoleVariable<bool> CVarMoviePipelineFlushRenderingPerLayerHack(
	TEXT("MoviePipeline.FlushLayersDebug"),
	false,
	TEXT("This is a debug cvar intended to help diagnose issues in the MoviePipeline multi-layer rendering mode\n")
	TEXT("that flushes any outstanding rendering commands for each layer. This can have a large performance impact,\n")
	TEXT("as it effectively removes any parallelism between the Game Thread and Render Thread!\n")
	TEXT(" 0 - Don't flush (default)\n")
	TEXT(" 1 - Flush (but negatively impacts performance)"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/MovieScene/MovieRenderPipeline/Source/MovieRenderPipelineRenderPasses/Private/Graph/Nodes/MovieGraphImagePassBaseNode.cpp:4

Scope: file

Source code excerpt:

static TAutoConsoleVariable<bool> CVarMoviePipelineFlushRenderingPerLayerHack(
	TEXT("MoviePipeline.FlushLayersDebug"),
	false,
	TEXT("This is a debug cvar intended to help diagnose issues in the MoviePipeline multi-layer rendering mode\n")
	TEXT("that flushes any outstanding rendering commands for each layer. This can have a large performance impact,\n")
	TEXT("as it effectively removes any parallelism between the Game Thread and Render Thread!\n")
	TEXT(" 0 - Don't flush (default)\n")

#Loc: <Workspace>/Engine/Plugins/MovieScene/MovieRenderPipeline/Source/MovieRenderPipelineRenderPasses/Private/Graph/Nodes/MovieGraphImagePassBaseNode.cpp:69

Scope (from outer to inner):

file
function     void UMovieGraphImagePassBaseNode::RenderImpl

Source code excerpt:

		// recreated which can be used to see if it fixes various issues, but
		// this comes at a big performance cost as it effectively removes GT/RT parallelism.
		if (CVarMoviePipelineFlushRenderingPerLayerHack.GetValueOnGameThread())
		{
			FlushRenderingCommands();
		}

		Instance->Render(InFrameTraversalContext, InTimeData);

#Loc: <Workspace>/Engine/Plugins/MovieScene/MovieRenderPipeline/Source/MovieRenderPipelineRenderPasses/Private/Graph/Nodes/MovieGraphImagePassBaseNode.cpp:83

Scope (from outer to inner):

file
function     void UMovieGraphImagePassBaseNode::RenderImpl

Source code excerpt:

		}

		if (CVarMoviePipelineFlushRenderingPerLayerHack.GetValueOnGameThread())
		{
			FlushRenderingCommands();
		}
	}
}