grass.GrassMap.UseAsyncFetch

grass.GrassMap.UseAsyncFetch

#Overview

name: grass.GrassMap.UseAsyncFetch

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

• type: Var
• help: Enable async fetch tasks to readback the runtime grass maps from the GPU. When disabled, it the fetch is performed on the game thread, when enabled it uses an async task instead.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of grass.GrassMap.UseAsyncFetch is to control the method of fetching runtime grass maps from the GPU. It is specifically designed for the landscape and grass rendering system in Unreal Engine 5.

This setting variable is primarily used by the Landscape module, as evidenced by its location in the LandscapeGrassMapsBuilder.cpp file. It affects the grass map generation and fetching process, which is a crucial part of the landscape rendering system.

The value of this variable is set through a console variable (CVar) named “grass.GrassMap.UseAsyncFetch”. It is initialized to 0 by default, meaning the async fetch is disabled.

The associated variable GGrassMapUseAsyncFetch directly interacts with grass.GrassMap.UseAsyncFetch. They share the same value, with GGrassMapUseAsyncFetch being the actual integer variable used in the code logic.

Developers must be aware that when this variable is set to 0 (disabled), the grass map fetch is performed on the game thread. When enabled (set to a non-zero value), it uses an async task instead. This can have implications for performance and threading behavior.

Best practices when using this variable include:

1. Consider enabling it (setting to 1) if you want to offload the grass map fetching from the game thread, potentially improving performance.
2. Monitor performance metrics when changing this setting to ensure it benefits your specific use case.
3. Be aware of potential threading issues that might arise from using async tasks.

Regarding the associated variable GGrassMapUseAsyncFetch:

• Its purpose is to serve as the actual integer representation of the grass.GrassMap.UseAsyncFetch setting in the code.
• It is used directly in conditional statements to determine whether to use async fetching or not.
• The value is set through the console variable system, allowing for runtime modification.
• Developers should treat this variable as read-only in most cases, relying on the console variable system to modify its value.
• When working with grass map fetching in custom code, developers should check this variable to maintain consistency with the engine’s behavior.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Landscape/Private/LandscapeGrassMapsBuilder.cpp:44

Scope: file

Source code excerpt:

int32 GGrassMapUseAsyncFetch = 0;
FAutoConsoleVariableRef CVarGrassMapUseAsyncFetch(
	TEXT("grass.GrassMap.UseAsyncFetch"),
	GGrassMapUseAsyncFetch,
	TEXT("Enable async fetch tasks to readback the runtime grass maps from the GPU.  When disabled, it the fetch is performed on the game thread, when enabled it uses an async task instead."));

int32 GGrassMapAlwaysBuildRuntimeGenerationResources = 0;
static FAutoConsoleVariableRef CVarGrassMapAlwaysBuildRuntimeGenerationResources(
	TEXT("grass.GrassMap.AlwaysBuildRuntimeGenerationResources"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Landscape/Private/LandscapeGrassMapsBuilder.cpp:42

Scope: file

Source code excerpt:

	TEXT("Enable runtime grass map generation to save disk space and runtime memory.  When enabled the grass density maps are not serialized and are built on the fly at runtime."));

int32 GGrassMapUseAsyncFetch = 0;
FAutoConsoleVariableRef CVarGrassMapUseAsyncFetch(
	TEXT("grass.GrassMap.UseAsyncFetch"),
	GGrassMapUseAsyncFetch,
	TEXT("Enable async fetch tasks to readback the runtime grass maps from the GPU.  When disabled, it the fetch is performed on the game thread, when enabled it uses an async task instead."));

int32 GGrassMapAlwaysBuildRuntimeGenerationResources = 0;
static FAutoConsoleVariableRef CVarGrassMapAlwaysBuildRuntimeGenerationResources(
	TEXT("grass.GrassMap.AlwaysBuildRuntimeGenerationResources"),
	GGrassMapAlwaysBuildRuntimeGenerationResources,

#Loc: <Workspace>/Engine/Source/Runtime/Landscape/Private/LandscapeGrassMapsBuilder.cpp:455

Scope (from outer to inner):

file
function     bool FLandscapeGrassMapsBuilder::UpdateTrackedComponents

Source code excerpt:

					if (bComplete)
					{
						if (GGrassMapUseAsyncFetch != 0)
						{
							LaunchAsyncFetchTask(*State);
						}
						else
						{
							PopulateGrassDataFromReadback(*State);