Sequencer.UseSoftObjectPtrsForPreAnimatedMaterial

Sequencer.UseSoftObjectPtrsForPreAnimatedMaterial

#Overview

name: Sequencer.UseSoftObjectPtrsForPreAnimatedMaterial

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 Sequencer.UseSoftObjectPtrsForPreAnimatedMaterial is to control how the Unreal Engine Sequencer system references pre-animated material states. Specifically, it determines whether to use soft object pointers or strong object pointers for this purpose.

This setting variable is primarily used in the Unreal Engine’s MovieScene subsystem, particularly within the MovieSceneTracks module. It affects how material references are handled in the animation sequencing system.

The value of this variable is set through an FAutoConsoleVariableRef, which means it can be changed at runtime through the console. By default, it is set to true, favoring the use of soft object pointers.

The associated variable GUseSoftObjectPtrsForPreAnimatedMaterial directly interacts with this setting. It’s a boolean variable that holds the actual value used in the code logic.

Developers must be aware that this setting affects memory management and loading behavior of materials in sequencer animations. When set to true (default), it uses TSoftObjectPtr, which allows for more flexible loading and potentially reduced memory usage. When false, it uses TObjectPtr, which keeps a strong reference to the material.

Best practices when using this variable include:

  1. Consider performance implications when changing this setting, especially for projects with many material animations.
  2. Be aware that changing this setting might affect loading times and memory usage of your sequences.
  3. Test thoroughly if you decide to change from the default setting, as it may impact the behavior of existing sequences.

Regarding the associated variable GUseSoftObjectPtrsForPreAnimatedMaterial:

This is a global boolean variable that directly reflects the state of the console variable. It’s used in the actual logic of the MovieSceneMaterialSystem to determine how to store and retrieve material references.

The purpose of this variable is to provide a quick, in-memory access point for the setting, allowing the system to efficiently check the current state without having to query the console variable each time.

It’s primarily used in the FMovieScenePreAnimatedMaterialParameters struct to decide whether to use SoftPreviousMaterial (TSoftObjectPtr) or PreviousMaterial (TObjectPtr) for storing material references.

Developers should be aware that this variable is not meant to be directly modified in code. Instead, changes should be made through the console variable Sequencer.UseSoftObjectPtrsForPreAnimatedMaterial.

Best practices for this variable include:

  1. Treat it as read-only in your code.
  2. If you need to change its value, do so through the console variable.
  3. Be aware of its state when debugging material-related issues in sequencer animations.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/MovieSceneTracks/Private/Systems/MovieSceneMaterialSystem.cpp:7

Scope (from outer to inner):

file
namespace    UE::MovieScene

Source code excerpt:

bool GUseSoftObjectPtrsForPreAnimatedMaterial = true;
FAutoConsoleVariableRef CVarUseSoftObjectPtrsForPreAnimatedMaterial(
	TEXT("Sequencer.UseSoftObjectPtrsForPreAnimatedMaterial"),
	GUseSoftObjectPtrsForPreAnimatedMaterial,
	TEXT("Defines whether to use soft-object-ptrs for referencing pre-animated state (default), or strong TObjectPtrs.\n"),
	ECVF_Default
);

} // namespace UE::MovieScene

#Loc: <Workspace>/Engine/Source/Runtime/MovieSceneTracks/Public/Systems/MovieSceneMaterialSystem.h:34

Scope: file

Source code excerpt:

private:

	/** Strong ptr to the previously assigned material interface (used when Sequencer.UseSoftObjectPtrsForPreAnimatedMaterial is false) */
	UPROPERTY()
	TObjectPtr<UMaterialInterface> PreviousMaterial;

	/** Soft ptr to the previously assigned material interface (used when Sequencer.UseSoftObjectPtrsForPreAnimatedMaterial is true) */
	UPROPERTY()
	TSoftObjectPtr<UMaterialInterface> SoftPreviousMaterial;
};

namespace UE::MovieScene
{

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/MovieSceneTracks/Private/Systems/MovieSceneMaterialSystem.cpp:5

Scope (from outer to inner):

file
namespace    UE::MovieScene

Source code excerpt:

{

bool GUseSoftObjectPtrsForPreAnimatedMaterial = true;
FAutoConsoleVariableRef CVarUseSoftObjectPtrsForPreAnimatedMaterial(
	TEXT("Sequencer.UseSoftObjectPtrsForPreAnimatedMaterial"),
	GUseSoftObjectPtrsForPreAnimatedMaterial,
	TEXT("Defines whether to use soft-object-ptrs for referencing pre-animated state (default), or strong TObjectPtrs.\n"),
	ECVF_Default
);

} // namespace UE::MovieScene

#Loc: <Workspace>/Engine/Source/Runtime/MovieSceneTracks/Private/Systems/MovieSceneMaterialSystem.cpp:18

Scope (from outer to inner):

file
function     UMaterialInterface* FMovieScenePreAnimatedMaterialParameters::GetMaterial

Source code excerpt:

UMaterialInterface* FMovieScenePreAnimatedMaterialParameters::GetMaterial() const
{
	if (UE::MovieScene::GUseSoftObjectPtrsForPreAnimatedMaterial)
	{
		UMaterialInterface* Material = SoftPreviousMaterial.Get();
		if (!Material)
		{
			Material = SoftPreviousMaterial.LoadSynchronous();
		}

#Loc: <Workspace>/Engine/Source/Runtime/MovieSceneTracks/Private/Systems/MovieSceneMaterialSystem.cpp:35

Scope (from outer to inner):

file
function     void FMovieScenePreAnimatedMaterialParameters::SetMaterial

Source code excerpt:

void FMovieScenePreAnimatedMaterialParameters::SetMaterial(UMaterialInterface* InMaterial)
{
	if (UE::MovieScene::GUseSoftObjectPtrsForPreAnimatedMaterial)
	{
		SoftPreviousMaterial = InMaterial;
	}
	else
	{
		PreviousMaterial = InMaterial;