r.KeepOverrideVertexColorsOnCPU

r.KeepOverrideVertexColorsOnCPU

#Overview

name: r.KeepOverrideVertexColorsOnCPU

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 r.KeepOverrideVertexColorsOnCPU is to control whether a CPU copy of override vertex colors is kept for static mesh components. This setting is primarily related to the rendering system and memory management of vertex color data.

This setting variable is used within the Engine module, specifically in the StaticMeshComponent system. It affects how vertex color data is handled for static meshes, which is crucial for rendering and potentially for some gameplay mechanics.

The value of this variable is set through the console variable system in Unreal Engine. It’s initialized with a default value of 1 (true) and can be changed at runtime.

The associated variable GKeepKeepOverrideVertexColorsOnCPU directly interacts with r.KeepOverrideVertexColorsOnCPU. They share the same value, with GKeepKeepOverrideVertexColorsOnCPU being the actual integer variable used in the code logic.

Developers must be aware that this variable affects memory usage and potentially performance. Keeping vertex colors on the CPU can increase memory consumption but may be necessary for certain gameplay or blueprint operations that need to access this data on the CPU side.

Best practices when using this variable include:

  1. Leaving it enabled (1) if your game relies on CPU-side access to vertex colors for gameplay or blueprint logic.
  2. Consider disabling it (0) in shipping builds if CPU access to vertex colors is not needed, to potentially save memory.
  3. Be cautious when changing this setting, as it may affect the behavior of blueprints or systems that rely on CPU access to vertex colors.

Regarding the associated variable GKeepKeepOverrideVertexColorsOnCPU:

The purpose of GKeepKeepOverrideVertexColorsOnCPU is to serve as the actual integer variable that the engine code checks to determine whether to keep override vertex colors on the CPU.

This variable is used in the Engine module, specifically within the StaticMeshComponent serialization logic.

Its value is set through the console variable system, mirroring the value of r.KeepOverrideVertexColorsOnCPU.

It directly interacts with the r.KeepOverrideVertexColorsOnCPU console variable, serving as its backing store.

Developers should be aware that this variable is used in the serialization process of StaticMeshComponentLODInfo, affecting how vertex color data is handled during loading and saving.

Best practices include:

  1. Not modifying this variable directly, but instead using the r.KeepOverrideVertexColorsOnCPU console variable to change its value.
  2. Being aware of its impact on serialization and memory management when working with static meshes and their LODs.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/StaticMeshComponent.cpp:3646

Scope: file

Source code excerpt:

int32 GKeepKeepOverrideVertexColorsOnCPU = 1;
FAutoConsoleVariableRef CKeepOverrideVertexColorsOnCPU(
	TEXT("r.KeepOverrideVertexColorsOnCPU"),
	GKeepKeepOverrideVertexColorsOnCPU,
	TEXT("Keeps a CPU copy of override vertex colors.  May be required for some blueprints / object spawning."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

FArchive& operator<<(FArchive& Ar,FStaticMeshComponentLODInfo& I)

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/StaticMeshComponent.cpp:3644

Scope: file

Source code excerpt:

}

int32 GKeepKeepOverrideVertexColorsOnCPU = 1;
FAutoConsoleVariableRef CKeepOverrideVertexColorsOnCPU(
	TEXT("r.KeepOverrideVertexColorsOnCPU"),
	GKeepKeepOverrideVertexColorsOnCPU,
	TEXT("Keeps a CPU copy of override vertex colors.  May be required for some blueprints / object spawning."),
	ECVF_Scalability | ECVF_RenderThreadSafe
	);

FArchive& operator<<(FArchive& Ar,FStaticMeshComponentLODInfo& I)
{

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/StaticMeshComponent.cpp:3736

Scope (from outer to inner):

file
function     FArchive& operator<<

Source code excerpt:


			//we want to discard the vertex colors after rhi init when in cooked/client builds.
			const bool bNeedsCPUAccess = !Ar.IsLoading() || GIsEditor || IsRunningCommandlet() || (GKeepKeepOverrideVertexColorsOnCPU != 0);
			check(I.OverrideVertexColors != nullptr);
			I.OverrideVertexColors->Serialize(Ar, bNeedsCPUAccess);
			
			if (Ar.IsLoading())
			{
				//When IsSaving, we cannot have this situation since it is check before