r.TranslucentSortPolicy
r.TranslucentSortPolicy
#Overview
name: r.TranslucentSortPolicy
This variable is created as a Console Variable (cvar).
- type:
Var
- help:
0: Sort based on distance from camera centerpoint to bounding sphere centerpoint. (default, best for 3D games)\n1: Sort based on projected distance to camera.\n2: Sort based on the projection onto a fixed axis. (best for 2D games)
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:
- Engine module (SceneView.cpp, SceneView.h)
- 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:
- It affects the performance and visual quality of translucent objects in the scene.
- The setting requires that Separate Translucency (under Postprocessing) is enabled to take effect.
- There are three possible values (0, 1, 2), each representing a different sorting method.
Best practices when using this variable include:
- Choose the appropriate sorting policy based on the game’s needs (3D vs 2D).
- Consider the performance implications of each sorting method.
- 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:
- Avoid modifying it directly in code; instead, use the provided configuration methods.
- When reading its value, consider caching it for performance if it’s accessed frequently.
- 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.