r.Ortho.AutoPlanes.ShiftPlanes

r.Ortho.AutoPlanes.ShiftPlanes

#Overview

name: r.Ortho.AutoPlanes.ShiftPlanes

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Ortho.AutoPlanes.ShiftPlanes is to shift the entire frustum in the Z direction for orthographic projections. This setting is primarily used in the camera and rendering systems 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 FMinimalViewInfo::AutoCalculateOrthoPlanes function, which is responsible for automatically calculating the near and far clip planes for orthographic projections.

The value of this variable is set through a console variable (CVarOrthoAutoPlaneShift) with an initial value of 0.0f. It can be modified at runtime through console commands or programmatically.

The associated variable CVarOrthoAutoPlaneShift interacts directly with r.Ortho.AutoPlanes.ShiftPlanes. They share the same value and are used interchangeably in the code.

Developers must be aware that modifying this variable will affect the positioning of both the near and far clip planes in orthographic projections. This can be particularly useful for adjusting the view in 2.5D scenes or when fine-tuning the visible range in orthographic views.

Best practices when using this variable include:

  1. Use it sparingly and only when necessary to adjust the orthographic view.
  2. Be mindful of its impact on performance and rendering artifacts, especially when setting extreme values.
  3. Consider the interaction with other camera and rendering settings to ensure desired results.
  4. Document any non-default values used in your project for easier maintenance and debugging.

Regarding the associated variable CVarOrthoAutoPlaneShift:

The purpose of CVarOrthoAutoPlaneShift is to provide a programmatic interface to the r.Ortho.AutoPlanes.ShiftPlanes setting. It’s used internally by the Engine to access and modify the shift value.

This variable is part of the Engine module and is used in the same contexts as r.Ortho.AutoPlanes.ShiftPlanes.

The value of CVarOrthoAutoPlaneShift is set when the console variable is initialized and can be accessed or modified using the GetValueOnAnyThread() method.

CVarOrthoAutoPlaneShift directly interacts with r.Ortho.AutoPlanes.ShiftPlanes, as they represent the same setting.

Developers should be aware that this is an internal variable and should generally use the console variable r.Ortho.AutoPlanes.ShiftPlanes for adjusting the setting.

Best practices for CVarOrthoAutoPlaneShift include:

  1. Use GetValueOnAnyThread() to read the current value when needed in code.
  2. Avoid directly modifying this variable; instead, use the console variable system to change the value.
  3. Be aware of potential thread safety issues when accessing this variable, as indicated by the ECVF_RenderThreadSafe flag.

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float>  CVarOrthoAutoPlaneShift(
	TEXT("r.Ortho.AutoPlanes.ShiftPlanes"),
	0.0f,
	TEXT("Shifts the whole frustum in the Z direction.")
	TEXT("This can be useful if, for example you need the Near plane closer to the camera, at the reduction of the Far plane value (e.g. a horizontal 2.5D scene)."),
	ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     bool FMinimalViewInfo::AutoCalculateOrthoPlanes

Source code excerpt:

		 * The NearPlane calculation is a scaled OrthoHeight depending on the camera angle, 
		 * which maxes out at 45 degrees by default as this captures the entire scene for the majority of angles.
		 * r.Ortho.AutoPlanes.ShiftPlanes should be used to account for views outside of this.
		 * 
		 * The FarPlane is the required depth precision interpretation for the UnitPerPixelRatio. 
		 * We clamp this to remove the Near plane difference, and also max out at the previously set maximum FPValue. 
		 * This setup should help for possible future implementations where we can increase the depth range (i.e. LWC + double float depth buffers).
		 */
		float SinAngle = FMath::Clamp(1.0f - CosAngle, 0.707107f, 1.0f);
		float NearPlane = FMath::Max(OrthoWidth, OrthoHeight) * FMath::Max((FMath::Clamp(CosAngle, 0.707107f, 1.0f) - (1.0f/SinAngle)), -0.5f) - CameraArmLength;
		FarPlane = FMath::Clamp(FarPlane, OrthoHeight, MaxFPValue + NearPlane);

		//The Planes can be scaled in the Z axis without restriction to ensure a user can capture their entire view.
		const float GlobalAutoPlaneShift = CVarOrthoAutoPlaneShift.GetValueOnAnyThread();
		OrthoNearClipPlane = NearPlane + AutoPlaneShift + GlobalAutoPlaneShift;
		OrthoFarClipPlane = FarPlane + AutoPlaneShift + GlobalAutoPlaneShift;
		InOutProjectionData.CameraToViewTarget = CameraToViewTarget;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<float>  CVarOrthoAutoPlaneShift(
	TEXT("r.Ortho.AutoPlanes.ShiftPlanes"),
	0.0f,
	TEXT("Shifts the whole frustum in the Z direction.")
	TEXT("This can be useful if, for example you need the Near plane closer to the camera, at the reduction of the Far plane value (e.g. a horizontal 2.5D scene)."),
	ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     bool FMinimalViewInfo::AutoCalculateOrthoPlanes

Source code excerpt:


		//The Planes can be scaled in the Z axis without restriction to ensure a user can capture their entire view.
		const float GlobalAutoPlaneShift = CVarOrthoAutoPlaneShift.GetValueOnAnyThread();
		OrthoNearClipPlane = NearPlane + AutoPlaneShift + GlobalAutoPlaneShift;
		OrthoFarClipPlane = FarPlane + AutoPlaneShift + GlobalAutoPlaneShift;
		InOutProjectionData.CameraToViewTarget = CameraToViewTarget;
		return true;
	}
	return false;