MaxOcclusionPixelsFraction

MaxOcclusionPixelsFraction

#Overview

name: MaxOcclusionPixelsFraction

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of MaxOcclusionPixelsFraction is to control the maximum screen pixel fraction threshold for occlusion culling in Unreal Engine’s rendering system. This setting helps optimize rendering performance by determining when to retest potentially occluded objects.

MaxOcclusionPixelsFraction is primarily used by the Renderer module of Unreal Engine, specifically in the occlusion culling system. The main file referencing this variable is SceneVisibility.cpp, which is responsible for managing visibility and occlusion of scene objects.

The value of this variable is set in the Engine configuration, as indicated by the UPROPERTY(config) decorator in the UEngine class definition.

This variable interacts with other occlusion-related variables and systems, such as PrimitiveOcclusionHistory and GRHISupportsExactOcclusionQueries. It’s used in calculations to determine whether to run occlusion queries for specific primitives.

Developers should be aware that this variable directly impacts rendering performance and visual quality. A higher value will result in more aggressive occlusion culling, potentially improving performance but risking visual artifacts if set too high. Conversely, a lower value will lead to more conservative culling, potentially reducing performance but ensuring better visual accuracy.

Best practices when using this variable include:

  1. Carefully tuning the value based on the specific needs of the game or application, balancing performance and visual quality.
  2. Testing the impact of different values in various scenarios to find the optimal setting.
  3. Considering the target hardware capabilities when adjusting this value, as lower-end devices may benefit from more aggressive culling.
  4. Monitoring performance metrics and visual quality when making changes to this variable.
  5. Documenting any custom settings and their impacts for future reference and team communication.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:287, section: [/Script/Engine.Engine]

#References in C++ code

#Callsites

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

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

Scope (from outer to inner):

file
class        class UEngine : public UObject , public FExec

Source code excerpt:

	/** Max screen pixel fraction where retesting when unoccluded is worth the GPU time. */
	UPROPERTY(config)
	float MaxOcclusionPixelsFraction;

	/** Whether to pause the game if focus is lost. */
	UPROPERTY(config)
	uint32 bPauseOnLossOfFocus:1;

	/**

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneVisibility.cpp:2584

Scope: file

Source code excerpt:

						else
						{
							PrimitiveOcclusionHistory->LastPixelsPercentage = GEngine->MaxOcclusionPixelsFraction;
						}
					}
				}

				if (GVisualizeOccludedPrimitives && bIsOccluded)
				{

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/SceneVisibility.cpp:2674

Scope: file

Source code excerpt:

							if (GRHISupportsExactOcclusionQueries)
							{
								float FractionMultiplier = FMath::Max(PrimitiveOcclusionHistory->LastPixelsPercentage / GEngine->MaxOcclusionPixelsFraction, 1.0f);
								bRunQuery = (FractionMultiplier * Rnd) < GEngine->MaxOcclusionPixelsFraction;
							}
							else
							{
								bRunQuery = CurrentRealTime - PrimitiveOcclusionHistory->LastProvenVisibleTime > PrimitiveProbablyVisibleTime * (0.5f * 0.25f * Rnd);
							}
						}