r.TranslucentSortPolicy

r.TranslucentSortPolicy

#Overview

name: r.TranslucentSortPolicy

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

It is referenced in 11 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.TranslucentSortPolicy is to control the sorting method for translucent primitives in Unreal Engine’s rendering system. This setting affects how translucent objects are ordered and how their order changes as the camera moves.

The r.TranslucentSortPolicy variable is primarily used in the rendering system of Unreal Engine. Based on the callsites, it’s utilized in the following subsystems and modules:

  1. Engine module (SceneView.cpp, SceneView.h)
  2. Renderer module (MeshDrawCommands.cpp, MeshDrawCommands.h)

The value of this variable is set through the console variable system, as seen in ConsoleManager.cpp. It can also be configured through the URendererSettings class, which is part of the Engine’s configuration system.

The r.TranslucentSortPolicy interacts with the TranslucentSortPolicy variable, which is of type ETranslucentSortPolicy::Type. They share the same value, with r.TranslucentSortPolicy being the console variable and TranslucentSortPolicy being the in-code representation.

Developers should be aware of the following when using this variable:

  1. It affects the performance and visual quality of translucent objects in the scene.
  2. The setting requires that Separate Translucency (under Postprocessing) is enabled to take effect.
  3. There are three possible values (0, 1, 2), each representing a different sorting method.

Best practices when using this variable include:

  1. Choose the appropriate sorting policy based on the game’s needs (3D vs 2D).
  2. Consider the performance implications of each sorting method.
  3. Test thoroughly with different scenes and camera movements to ensure the chosen policy works well for your specific use case.

Regarding the associated variable TranslucentSortPolicy:

The purpose of TranslucentSortPolicy is to represent the chosen translucent sorting method within the engine’s code. It’s used in various parts of the rendering pipeline to determine how to sort translucent objects.

This variable is set based on the value of the r.TranslucentSortPolicy console variable. It’s used in the SceneView construction and in the mesh drawing commands to apply the correct sorting method.

Developers should be aware that changing TranslucentSortPolicy directly won’t have an effect unless it’s done through the proper channels (i.e., changing the console variable or the URendererSettings).

Best practices for TranslucentSortPolicy include:

  1. Avoid modifying it directly in code; instead, use the provided configuration methods.
  2. When reading its value, consider caching it for performance if it’s accessed frequently.
  3. Be aware of its impact on the TranslucentSortAxis variable, which is used when the policy is set to SortAlongAxis.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Core/Private/HAL/ConsoleManager.cpp:3458

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarTranslucentSortPolicy(
	TEXT("r.TranslucentSortPolicy"),
	0,
	TEXT("0: Sort based on distance from camera centerpoint to bounding sphere centerpoint. (default, best for 3D games)\n"
		 "1: Sort based on projected distance to camera.\n"
		 "2: Sort based on the projection onto a fixed axis. (best for 2D games)"),
	ECVF_RenderThreadSafe);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Engine/RendererSettings.h:609

Scope (from outer to inner):

file
class        class URendererSettings : public UDeveloperSettings

Source code excerpt:


	UPROPERTY(config, EditAnywhere, Category=Translucency, meta=(
		ConsoleVariable="r.TranslucentSortPolicy",DisplayName="Translucent Sort Policy",
		ToolTip="The sort mode for translucent primitives, affecting how they are ordered and how they change order as the camera moves. Requires that Separate Translucency (under Postprocessing) is true."))
	TEnumAsByte<ETranslucentSortPolicy::Type> TranslucentSortPolicy;

	UPROPERTY(config, EditAnywhere, Category=Translucency, meta=(
		DisplayName="Translucent Sort Axis",
		ToolTip="The axis that sorting will occur along when Translucent Sort Policy is set to SortAlongAxis."))

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

Scope (from outer to inner):

file
function     FSceneView::FSceneView

Source code excerpt:

	InvDeviceZToWorldZTransform = CreateInvDeviceZToWorldZTransform(ProjectionMatrixUnadjustedForRHI);

	static TConsoleVariableData<int32>* SortPolicyCvar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.TranslucentSortPolicy"));
	TranslucentSortPolicy = static_cast<ETranslucentSortPolicy::Type>(SortPolicyCvar->GetValueOnAnyThread());

	TranslucentSortAxis = GetDefault<URendererSettings>()->TranslucentSortAxis;

	// As the world is only accessible from the game thread, bIsGameView should be explicitly
	// set on any other thread.

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Engine/RendererSettings.h:611

Scope (from outer to inner):

file
class        class URendererSettings : public UDeveloperSettings

Source code excerpt:

		ConsoleVariable="r.TranslucentSortPolicy",DisplayName="Translucent Sort Policy",
		ToolTip="The sort mode for translucent primitives, affecting how they are ordered and how they change order as the camera moves. Requires that Separate Translucency (under Postprocessing) is true."))
	TEnumAsByte<ETranslucentSortPolicy::Type> TranslucentSortPolicy;

	UPROPERTY(config, EditAnywhere, Category=Translucency, meta=(
		DisplayName="Translucent Sort Axis",
		ToolTip="The axis that sorting will occur along when Translucent Sort Policy is set to SortAlongAxis."))
	FVector TranslucentSortAxis;

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

Scope (from outer to inner):

file
function     FSceneView::FSceneView

Source code excerpt:


	static TConsoleVariableData<int32>* SortPolicyCvar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.TranslucentSortPolicy"));
	TranslucentSortPolicy = static_cast<ETranslucentSortPolicy::Type>(SortPolicyCvar->GetValueOnAnyThread());

	TranslucentSortAxis = GetDefault<URendererSettings>()->TranslucentSortAxis;

	// As the world is only accessible from the game thread, bIsGameView should be explicitly
	// set on any other thread.
	if(IsInGameThread())

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/SceneView.h:1517

Scope: file

Source code excerpt:

	FIntRect CameraConstrainedViewRect;

	/** Sort axis for when TranslucentSortPolicy is SortAlongAxis */
	FVector TranslucentSortAxis;

	/** Translucent sort mode */
	TEnumAsByte<ETranslucentSortPolicy::Type> TranslucentSortPolicy;
	
	/** The frame index to override, useful for keeping determinism when rendering sequences. **/
	TOptional<uint32> OverrideFrameIndexValue;

	/** In some cases, the principal point of the lens is not at the center of the screen, especially for overlapped tile
	 *  rendering. So given a UV in [-1,1] viewport space, convert it to the [-1,1] viewport space of the lens using

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/MeshDrawCommands.cpp:145

Scope (from outer to inner):

file
function     void UpdateTranslucentMeshSortKeys

Source code excerpt:

*/
void UpdateTranslucentMeshSortKeys(
	ETranslucentSortPolicy::Type TranslucentSortPolicy,
	const FVector& TranslucentSortAxis,
	const FVector& ViewOrigin,
	const FMatrix& ViewMatrix,
	const TScenePrimitiveArray<FPrimitiveBounds>& PrimitiveBounds,
	ETranslucencyPass::Type TranslucencyPass, 
	bool bInverseSorting,

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/MeshDrawCommands.cpp:165

Scope (from outer to inner):

file
function     void UpdateTranslucentMeshSortKeys

Source code excerpt:


		float Distance = 0.0f;
		if (TranslucentSortPolicy == ETranslucentSortPolicy::SortByDistance)
		{
			//sort based on distance to the view position, view rotation is not a factor
			Distance = (BoundsOrigin - ViewOrigin).Size();
		}
		else if (TranslucentSortPolicy == ETranslucentSortPolicy::SortAlongAxis)
		{
			// Sort based on enforced orthogonal distance
			const FVector CameraToObject = BoundsOrigin - ViewOrigin;
			Distance = FVector::DotProduct(CameraToObject, TranslucentSortAxis);
		}
		else
		{
			// Sort based on projected Z distance
			check(TranslucentSortPolicy == ETranslucentSortPolicy::SortByProjectedZ);
			Distance = ViewMatrix.TransformPosition(BoundsOrigin).Z;
		}

		// Apply distance offset from the primitive
		const uint32 PackedOffset = VisibleCommand.SortKey.Translucent.Distance;
		const float DistanceOffset = *((float*)&PackedOffset);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/MeshDrawCommands.cpp:1108

Scope (from outer to inner):

file
class        class FMeshDrawCommandPassSetupTask
function     void AnyThreadTask

Source code excerpt:


				UpdateTranslucentMeshSortKeys(
					Context.TranslucentSortPolicy,
					Context.TranslucentSortAxis,
					Context.ViewOrigin,
					Context.ViewMatrix,
					*Context.PrimitiveBounds,
					Context.TranslucencyPass,
					bInverseSorting,

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/MeshDrawCommands.cpp:1384

Scope (from outer to inner):

file
function     void FParallelMeshDrawCommandPass::DispatchPassSetup

Source code excerpt:

	// Setup translucency sort key update pass based on view.
	TaskContext.TranslucencyPass = ETranslucencyPass::TPT_MAX;
	TaskContext.TranslucentSortPolicy = View.TranslucentSortPolicy;
	TaskContext.TranslucentSortAxis = View.TranslucentSortAxis;
	TaskContext.ViewOrigin = View.ViewMatrices.GetViewOrigin();
	TaskContext.ViewMatrix = View.ViewMatrices.GetViewMatrix();
	TaskContext.PrimitiveBounds = &Scene->PrimitiveBounds;

	switch (PassType)

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/MeshDrawCommands.h:94

Scope (from outer to inner):

file
class        class FMeshDrawCommandPassSetupTaskContext

Source code excerpt:

	// For UpdateTranslucentMeshSortKeys.
	ETranslucencyPass::Type TranslucencyPass;
	ETranslucentSortPolicy::Type TranslucentSortPolicy;
	FVector TranslucentSortAxis;
	FVector ViewOrigin;
	FMatrix ViewMatrix;
	const TScenePrimitiveArray<struct FPrimitiveBounds>* PrimitiveBounds;

	// For logging instancing stats.