Sequencer.MaterialParameterEntityLifetimeTracking

Sequencer.MaterialParameterEntityLifetimeTracking

#Overview

name: Sequencer.MaterialParameterEntityLifetimeTracking

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 Sequencer.MaterialParameterEntityLifetimeTracking is to enable tracking and verification of entity cleanup in the Unreal Engine’s Sequencer system, specifically for material parameter entities.

This setting variable is primarily used in the MovieSceneTracks module, which is part of Unreal Engine’s Sequencer system. It’s specifically utilized in the MovieSceneMaterialParameterSystem, which handles animation of material parameters in cinematics.

The value of this variable is set through a console variable (cvar) using the FAutoConsoleVariableRef class. It’s initialized to false by default, meaning the tracking is disabled unless explicitly enabled.

The associated variable GMaterialParameterEntityLifetimeTracking directly interacts with Sequencer.MaterialParameterEntityLifetimeTracking. They share the same value, with GMaterialParameterEntityLifetimeTracking being the actual boolean variable used in the code logic.

Developers must be aware that enabling this variable may report false positives, particularly when the linker and material system are cleaned up simultaneously. This is why it’s disabled by default.

Best practices when using this variable include:

  1. Only enable it for debugging purposes, not in production builds.
  2. Be prepared to analyze and filter out potential false positives in the results.
  3. Use it in conjunction with other debugging tools to get a comprehensive view of entity lifetime management.

Regarding the associated variable GMaterialParameterEntityLifetimeTracking:

Its purpose is to act as the actual boolean flag that controls the entity lifetime tracking behavior within the code.

It’s used directly in the MovieSceneMaterialParameterSystem, specifically in the destructor of FAnimatedMaterialParameterInfo.

The value is set by the console variable Sequencer.MaterialParameterEntityLifetimeTracking.

When this variable is true, it triggers additional checks in the FAnimatedMaterialParameterInfo destructor to ensure that all entities have been properly cleaned up.

Developers should be cautious when enabling this variable, as it can impact performance and may produce false positives.

Best practices include using it temporarily for debugging entity lifetime issues and disabling it in production or performance-critical scenarios.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/MovieSceneTracks/Private/Systems/MovieSceneMaterialParameterSystem.cpp:31

Scope (from outer to inner):

file
namespace    UE::MovieScene

Source code excerpt:

bool GMaterialParameterEntityLifetimeTracking = false;
FAutoConsoleVariableRef CVarMaterialParameterEntityLifetimeTracking(
	TEXT("Sequencer.MaterialParameterEntityLifetimeTracking"),
	GMaterialParameterEntityLifetimeTracking,
	TEXT("(Default: false) Ensure on destruction that all entities have been cleaned up. This can report false positives (when the linker and material system are both cleaned up together) so is not enabled by default.\n"),
	ECVF_Default
);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/MovieSceneTracks/Private/Systems/MovieSceneMaterialParameterSystem.cpp:29

Scope (from outer to inner):

file
namespace    UE::MovieScene

Source code excerpt:

);

bool GMaterialParameterEntityLifetimeTracking = false;
FAutoConsoleVariableRef CVarMaterialParameterEntityLifetimeTracking(
	TEXT("Sequencer.MaterialParameterEntityLifetimeTracking"),
	GMaterialParameterEntityLifetimeTracking,
	TEXT("(Default: false) Ensure on destruction that all entities have been cleaned up. This can report false positives (when the linker and material system are both cleaned up together) so is not enabled by default.\n"),
	ECVF_Default
);


void CollectGarbageForOutput(FAnimatedMaterialParameterInfo* Output)

#Loc: <Workspace>/Engine/Source/Runtime/MovieSceneTracks/Private/Systems/MovieSceneMaterialParameterSystem.cpp:65

Scope (from outer to inner):

file
namespace    UE::MovieScene
function     FAnimatedMaterialParameterInfo::~FAnimatedMaterialParameterInfo

Source code excerpt:

FAnimatedMaterialParameterInfo::~FAnimatedMaterialParameterInfo()
{
	if (GMaterialParameterEntityLifetimeTracking)
	{
		ensureAlways(!OutputEntityID.IsValid() && !BlendChannelID.IsValid());
	}
}

/** Apply scalar material parameters */