r.Ortho.AllowNearPlaneCorrection

r.Ortho.AllowNearPlaneCorrection

#Overview

name: r.Ortho.AllowNearPlaneCorrection

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.AllowNearPlaneCorrection is to enable automatic correction of orthographic camera near planes to resolve lighting issues behind the camera position in Unreal Engine.

This setting variable is primarily used in the rendering system, specifically for orthographic camera projection and lighting calculations. It is part of the Engine module, as evidenced by its location in the SceneView.cpp file within the Engine source directory.

The Unreal Engine rendering subsystem relies on this setting variable to determine whether to apply the near plane correction for orthographic cameras. It is used in the FSceneViewProjectionData::UpdateOrthoPlanes function, which is responsible for updating the orthographic projection planes.

The value of this variable is set through a console variable (CVar) system. It is initialized with a default value of true, but can be changed at runtime through console commands or programmatically.

This variable interacts closely with the orthographic camera’s near plane and the ProjectionMatrix. It affects how the camera position is adjusted in relation to the near plane for lighting calculations.

Developers must be aware that enabling this variable can change the behavior of orthographic cameras in their scenes. It may affect lighting calculations and potentially the visual output of orthographic views.

Best practices when using this variable include:

  1. Testing scenes with both enabled and disabled states to ensure desired lighting behavior.
  2. Being cautious when manually manipulating orthographic camera positions, as this correction may override some manual adjustments.
  3. Considering performance implications, as this correction may introduce additional calculations in the rendering pipeline.

Regarding the associated variable CVarAllowOrthoNearPlaneCorrection:

This is the actual console variable that controls the behavior described above. It is defined using the TAutoConsoleVariable template, which allows it to be easily accessed and modified at runtime.

The purpose of CVarAllowOrthoNearPlaneCorrection is the same as r.Ortho.AllowNearPlaneCorrection, as they represent the same setting.

It is used in the Engine module, specifically in the SceneView.cpp file, which is part of the rendering system.

The value of this variable is set when the engine initializes, but can be changed at runtime through console commands or programmatically using the console variable interface.

This variable directly controls the behavior of the orthographic near plane correction. It is checked in the UpdateOrthoPlanes function to determine whether to apply the correction.

Developers should be aware that this variable can be accessed from multiple threads, as evidenced by the use of GetValueOnAnyThread() in the code.

Best practices for using this variable include:

  1. Using the provided console variable interface for reading and writing its value, rather than accessing it directly.
  2. Considering thread safety when modifying or reading this variable in multi-threaded contexts.
  3. Documenting any changes to this variable’s value in project settings or configuration files to ensure consistency across development and deployment environments.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SceneView.cpp:342

Scope: file

Source code excerpt:


static TAutoConsoleVariable<bool> CVarAllowOrthoNearPlaneCorrection(
	TEXT("r.Ortho.AllowNearPlaneCorrection"),
	true,
	TEXT("Orthographic near planes can be behind the camera position, which causes some issues with Unreal resolving lighting behind the camera position ")
	TEXT("This CVar enables the Orthographic cameras globally to automatically update the camera location to match the NearPlane location, ")
	TEXT("and force the pseudo camera position to be the replaced near plane location for the projection matrix calculation. ")
	TEXT("This means Unreal can resolve lighting behind the camera correctly."),
	ECVF_Default

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SceneView.cpp:341

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<bool> CVarAllowOrthoNearPlaneCorrection(
	TEXT("r.Ortho.AllowNearPlaneCorrection"),
	true,
	TEXT("Orthographic near planes can be behind the camera position, which causes some issues with Unreal resolving lighting behind the camera position ")
	TEXT("This CVar enables the Orthographic cameras globally to automatically update the camera location to match the NearPlane location, ")
	TEXT("and force the pseudo camera position to be the replaced near plane location for the projection matrix calculation. ")
	TEXT("This means Unreal can resolve lighting behind the camera correctly."),

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SceneView.cpp:613

Scope (from outer to inner):

file
function     bool FSceneViewProjectionData::UpdateOrthoPlanes

Source code excerpt:

bool FSceneViewProjectionData::UpdateOrthoPlanes(FSceneViewProjectionData* InOutProjectionData, float& NearPlane, float& FarPlane, float HalfOrthoWidth, bool bUseCameraHeightAsViewTarget)
{
	if (!InOutProjectionData || !CVarAllowOrthoNearPlaneCorrection.GetValueOnAnyThread())
	{
		return false;
	}
	
	//Get the ViewForward vector from the RotationMatrix + ensure it is normalized.
	FVector ViewForward = InOutProjectionData->ViewRotationMatrix.GetColumn(2);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SceneView.cpp:667

Scope (from outer to inner):

file
function     bool FSceneViewProjectionData::UpdateOrthoPlanes

Source code excerpt:

	*/
	if(IsPerspectiveProjection() 
		|| !CVarAllowOrthoNearPlaneCorrection.GetValueOnAnyThread()
		|| ProjectionMatrix.M[2][2] == 0.0 
		|| ProjectionMatrix.M[2][2] == ProjectionMatrix.M[2][3])
	{ 
		return false;	
	}