r.Ortho.AutoPlanes.ScaleIncrementingUnits

r.Ortho.AutoPlanes.ScaleIncrementingUnits

#Overview

name: r.Ortho.AutoPlanes.ScaleIncrementingUnits

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

• type: Var
• help: Select whether to scale the Near/Far plane Min/Max values as we increase in unit to pixel ratio (i.e. as we go from CM to M to KM)

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Ortho.AutoPlanes.ScaleIncrementingUnits is to control the scaling of Near/Far plane Min/Max values in orthographic projection as the unit to pixel ratio increases. This setting is primarily used in the camera system of Unreal Engine 5.

This setting variable is relied upon by the Engine module, specifically within the camera stack implementation. It’s used in the CameraStackTypes.cpp file, which suggests it’s part of the camera system’s core functionality.

The value of this variable is set using a TAutoConsoleVariable, which means it can be changed at runtime through console commands. Its default value is set to true.

This variable interacts closely with other camera-related variables, particularly CVarOrthoClampToMaxFPBuffer and CVarOrthoAutoDepthScale. It’s used in conjunction with these variables to determine the appropriate scaling and clamping of orthographic projection planes.

Developers must be aware that this variable affects the behavior of orthographic cameras, especially in scenarios where the scale of the world varies significantly (from centimeters to kilometers). It’s particularly important when using 16-bit depth buffers, as indicated by the condition checking for CVarOrthoClampToMaxFPBuffer.

Best practices when using this variable include:

1. Consider the scale of your world and whether you need this automatic scaling.
2. Be aware of its interaction with depth buffer precision, especially when using 16-bit depth buffers.
3. Test thoroughly at different world scales to ensure desired behavior.

Regarding the associated variable CVarOrthoScaleIncrementingUnits, it’s the actual console variable that stores the value of r.Ortho.AutoPlanes.ScaleIncrementingUnits. This variable is defined using TAutoConsoleVariable, which allows it to be changed at runtime.

The purpose of CVarOrthoScaleIncrementingUnits is the same as r.Ortho.AutoPlanes.ScaleIncrementingUnits - to control the scaling of orthographic projection planes. It’s used directly in the AutoCalculateOrthoPlanes function of the FMinimalViewInfo struct, which is likely a core part of the camera system.

When working with CVarOrthoScaleIncrementingUnits, developers should:

1. Use GetValueOnAnyThread() to access its current value safely from any thread.
2. Be aware that changing this value at runtime will affect orthographic cameras immediately.
3. Consider the performance implications of frequently changing this value, especially in scenes with many orthographic cameras.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Camera/CameraStackTypes.cpp:36

Scope: file

Source code excerpt:

static TAutoConsoleVariable<bool> CVarOrthoScaleIncrementingUnits(
	TEXT("r.Ortho.AutoPlanes.ScaleIncrementingUnits"),
	true,
	TEXT("Select whether to scale the Near/Far plane Min/Max values as we increase in unit to pixel ratio (i.e. as we go from CM to M to KM)"),
	ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<float>  CVarOrthoAutoDepthScale(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Camera/CameraStackTypes.cpp:35

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<bool> CVarOrthoScaleIncrementingUnits(
	TEXT("r.Ortho.AutoPlanes.ScaleIncrementingUnits"),
	true,
	TEXT("Select whether to scale the Near/Far plane Min/Max values as we increase in unit to pixel ratio (i.e. as we go from CM to M to KM)"),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Camera/CameraStackTypes.cpp:351

Scope (from outer to inner):

file
function     bool FMinimalViewInfo::AutoCalculateOrthoPlanes

Source code excerpt:

		//First check if we are using 16bit buffer and unit scaling, then set the min/max values accordingly
		const bool bUse16bitDepth = CVarOrthoClampToMaxFPBuffer.GetValueOnAnyThread() == 1;
		const bool bScaleIncrementingUnits = CVarOrthoScaleIncrementingUnits.GetValueOnAnyThread() && bUse16bitDepth;
		const float MaxFPValue = bScaleIncrementingUnits ? UE_LARGE_WORLD_MAX : UE_OLD_WORLD_MAX;
		float FPScale = bUse16bitDepth ? 66504.0f : UE_OLD_WORLD_MAX;

		const float AutoDepthScale = CVarOrthoAutoDepthScale.GetValueOnAnyThread();
		if (AutoDepthScale > 0.0f)
		{