GeometryCache.TrailingSeconds

GeometryCache.TrailingSeconds

#Overview

name: GeometryCache.TrailingSeconds

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 GeometryCache.TrailingSeconds is to control the amount of geometry cache data to keep resident in memory, opposite to the playback direction. This setting is part of the geometry cache streaming system in Unreal Engine 5.

This setting variable is primarily used in the GeometryCache plugin, specifically within the GeometryCache module. The GeometryCache plugin is responsible for handling animated geometry data, often used for complex animations that can’t be efficiently represented using traditional skeletal or morph target animations.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 2.5 seconds, but can be adjusted at runtime or through configuration files.

The associated variable CVarTrailingSeconds directly interacts with GeometryCache.TrailingSeconds. They share the same value and purpose.

Developers should be aware that this variable affects memory usage and streaming behavior of geometry caches. A higher value will keep more data in memory, potentially improving playback smoothness at the cost of increased memory usage. Conversely, a lower value will reduce memory usage but might lead to more frequent data streaming, potentially causing hitches if the data can’t be loaded quickly enough.

Best practices when using this variable include:

  1. Balancing the value based on the specific needs of the project and target hardware capabilities.
  2. Testing different values to find the optimal balance between memory usage and playback smoothness.
  3. Considering the relationship between this variable and GeometryCache.LookaheadSeconds for overall streaming behavior.
  4. Being mindful of the impact on different playback speeds and directions.

Regarding the associated variable CVarTrailingSeconds:

The purpose of CVarTrailingSeconds is to provide programmatic access to the GeometryCache.TrailingSeconds setting within the C++ code of the GeometryCache module.

This variable is used directly in the GeometryCacheStreamingManager to calculate the start time for data requests based on the current playback position and direction.

The value of CVarTrailingSeconds is set through the console variable system and can be accessed in code using the GetValueOnGameThread() method.

CVarTrailingSeconds interacts closely with the playback system of geometry caches, influencing which data is kept resident in memory.

Developers should be aware that changes to CVarTrailingSeconds will immediately affect the streaming behavior of all geometry caches in the scene.

Best practices for using CVarTrailingSeconds include:

  1. Using GetValueOnGameThread() when accessing the value to ensure thread-safety.
  2. Considering performance implications when frequently querying or changing this value.
  3. Coordinating changes to this variable with overall memory management strategies in the project.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/GeometryCache/Source/GeometryCache/Private/GeometryCacheStreamingManager.cpp:25

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarTrailingSeconds(
	TEXT("GeometryCache.TrailingSeconds"),
	2.5,
	TEXT("The amount of data (expressed in seconds of animation) to try and keep resident inverse to the playback direction for geometry caches."),
	ECVF_Scalability | ECVF_RenderThreadSafe);


struct FGeometryCacheStreamingManager : public IGeometryCacheStreamingManager

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/GeometryCache/Source/GeometryCache/Private/GeometryCacheStreamingManager.cpp:24

Scope: file

Source code excerpt:

	ECVF_Scalability | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarTrailingSeconds(
	TEXT("GeometryCache.TrailingSeconds"),
	2.5,
	TEXT("The amount of data (expressed in seconds of animation) to try and keep resident inverse to the playback direction for geometry caches."),
	ECVF_Scalability | ECVF_RenderThreadSafe);

#Loc: <Workspace>/Engine/Plugins/Runtime/GeometryCache/Source/GeometryCache/Private/GeometryCacheStreamingManager.cpp:113

Scope (from outer to inner):

file
function     void FGeometryCacheStreamingManager::UpdateResourceStreaming

Source code excerpt:

					if (DataPtr)
					{
						float RequestStartTime = Component->GetAnimationTime() - (Component->GetPlaybackDirection() * CVarTrailingSeconds.GetValueOnGameThread());

						// We currently simply stream the next 5 seconds in animation time. Note that due to the playback speed
						// in wall-time this may be longer/shorter. It would be easy enough to change... need to test what's better
						float RequestEndTime = RequestStartTime + Component->GetPlaybackDirection() * CVarLookaheadSeconds.GetValueOnGameThread();
						if (RequestStartTime > RequestEndTime)
						{