GeometryCache.LookaheadSeconds

GeometryCache.LookaheadSeconds

#Overview

name: GeometryCache.LookaheadSeconds

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.LookaheadSeconds is to control the amount of data that should be kept resident in advance for geometry caches. This setting is used to optimize the streaming and performance of geometry cache animations in Unreal Engine 5.

This setting variable is primarily used by the Geometry Cache plugin, which is part of Unreal Engine’s runtime modules. Based on the callsites, it’s clear that this variable is utilized within the GeometryCacheStreamingManager, which is responsible for managing the streaming of geometry cache data.

The value of this variable is set using a console variable (CVar) system. It’s initialized with a default value of 5.0 seconds, but can be adjusted at runtime through console commands or project settings.

The associated variable CVarLookaheadSeconds directly interacts with GeometryCache.LookaheadSeconds. They share the same value and purpose, with CVarLookaheadSeconds being the actual C++ variable used in the code to access the console variable’s value.

Developers must be aware that this variable affects the memory usage and performance of geometry cache animations. A higher value will keep more data resident 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 potential hitches if data isn’t streamed in time.

Best practices when using this variable include:

  1. Adjusting the value based on the specific needs of your project and target hardware capabilities.
  2. Monitoring performance and memory usage when changing this value.
  3. Considering the typical playback speeds and directions of your geometry cache animations when setting this value.
  4. Being aware that this setting applies globally to all geometry cache components in the project.

Regarding the associated variable CVarLookaheadSeconds:

The purpose of CVarLookaheadSeconds is to provide a programmatic interface to access and modify the GeometryCache.LookaheadSeconds setting within the C++ code of the Geometry Cache plugin.

This variable is used directly in the GeometryCacheStreamingManager to determine how much animation data to keep resident in memory. It’s accessed using the GetValueOnGameThread() method, which suggests that its value can be safely read from the game thread.

The value of CVarLookaheadSeconds is set through the console variable system, which allows for runtime modification.

Developers should be aware that changes to CVarLookaheadSeconds will immediately affect the behavior of the geometry cache streaming system. It’s important to use this variable consistently throughout the codebase when referring to the lookahead time for geometry caches.

Best practices for using CVarLookaheadSeconds include:

  1. Using the GetValueOnGameThread() method to access its value, ensuring thread-safe access.
  2. Considering performance implications when frequently accessing or modifying this value.
  3. Using this variable in conjunction with other streaming-related variables (like CVarTrailingSeconds) to fine-tune the streaming behavior of geometry caches.

#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:19

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarLookaheadSeconds(
	TEXT("GeometryCache.LookaheadSeconds"),
	5.0,
	TEXT("The amount of data (expressed in seconds of animation) to try and keep resident in advance for geometry caches. Note this works regardless of the playback direction."),
	ECVF_Scalability | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarTrailingSeconds(
	TEXT("GeometryCache.TrailingSeconds"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

DEFINE_LOG_CATEGORY(LogGeoCaStreaming);

static TAutoConsoleVariable<float> CVarLookaheadSeconds(
	TEXT("GeometryCache.LookaheadSeconds"),
	5.0,
	TEXT("The amount of data (expressed in seconds of animation) to try and keep resident in advance for geometry caches. Note this works regardless of the playback direction."),
	ECVF_Scalability | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<float> CVarTrailingSeconds(

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

Scope (from outer to inner):

file
function     void FGeometryCacheStreamingManager::UpdateResourceStreaming

Source code excerpt:

						// 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)
						{
							float tmp = RequestEndTime;
							RequestEndTime = RequestStartTime;
							RequestStartTime = tmp;
						}