r.LumenScene.SurfaceCache.AtlasSize

r.LumenScene.SurfaceCache.AtlasSize

#Overview

name: r.LumenScene.SurfaceCache.AtlasSize

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

• type: Var
• help: Surface cache card atlas size.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.LumenScene.SurfaceCache.AtlasSize is to define the size of the surface cache card atlas used in Unreal Engine 5’s Lumen global illumination system. This setting is specifically related to the rendering system, particularly the Lumen scene surface cache.

This setting variable is primarily used in the Lumen subsystem of Unreal Engine’s rendering module. Based on the callsites, it’s clear that this variable is utilized in the LumenScene.cpp file, which is part of the Renderer’s private implementation.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 4096, but can be changed at runtime or through configuration files. The associated C++ variable is CVarLumenSceneSurfaceCacheAtlasSize, which is defined as a TAutoConsoleVariable.

This variable interacts with other parts of the Lumen system, particularly in the GetDesiredPhysicalAtlasSizeInPages function. Here, it’s used to calculate the size of the physical atlas in pages, which is then clamped between 1 and 64.

Developers should be aware that this variable affects the memory usage and potentially the performance of the Lumen global illumination system. A larger atlas size may provide better quality but at the cost of increased memory usage.

Best practices when using this variable include:

1. Adjusting it based on the specific needs of your project and target hardware.
2. Monitoring performance and memory usage when changing this value.
3. Considering the trade-off between quality and performance/memory usage.

Regarding the associated variable CVarLumenSceneSurfaceCacheAtlasSize:

The purpose of CVarLumenSceneSurfaceCacheAtlasSize is to provide a programmatic interface to the r.LumenScene.SurfaceCache.AtlasSize console variable within the C++ code.

This variable is used directly in the Lumen subsystem of the rendering module. It’s defined in the LumenScene.cpp file and is used to retrieve the current value of the atlas size.

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

This variable is used in the GetDesiredPhysicalAtlasSizeInPages function to calculate the size of the physical atlas. It interacts with other parts of the Lumen system in this calculation.

Developers should be aware that this variable provides the C++ interface to the console variable, and any changes to the console variable will be reflected here.

Best practices include using GetValueOnRenderThread() to safely access the value from the render thread, as demonstrated in the provided code.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScene.cpp:68

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarLumenSceneSurfaceCacheAtlasSize(
	TEXT("r.LumenScene.SurfaceCache.AtlasSize"),
	4096,
	TEXT("Surface cache card atlas size."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

namespace Lumen

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScene.cpp:67

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarLumenSceneSurfaceCacheAtlasSize(
	TEXT("r.LumenScene.SurfaceCache.AtlasSize"),
	4096,
	TEXT("Surface cache card atlas size."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScene.cpp:217

Scope (from outer to inner):

file
function     static FIntPoint GetDesiredPhysicalAtlasSizeInPages

Source code excerpt:

static FIntPoint GetDesiredPhysicalAtlasSizeInPages(float SurfaceCacheResolution)
{
	int32 AtlasSizeInPages = FMath::DivideAndRoundUp<uint32>(CVarLumenSceneSurfaceCacheAtlasSize.GetValueOnRenderThread(), Lumen::PhysicalPageSize);
	AtlasSizeInPages = AtlasSizeInPages * SurfaceCacheResolution;
	AtlasSizeInPages = FMath::Clamp(AtlasSizeInPages, 1, 64);
	return FIntPoint(AtlasSizeInPages, AtlasSizeInPages);
}

static FIntPoint GetDesiredPhysicalAtlasSize(float SurfaceCacheResolution)