p.SerializeSQSampleCount

p.SerializeSQSampleCount

#Overview

name: p.SerializeSQSampleCount

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.SerializeSQSampleCount is to control the number of samples taken when measuring the performance of scene queries (SQ) in Unreal Engine’s physics system. It is specifically used for debugging and profiling purposes, particularly when scene queries are taking longer than expected.

This variable is primarily used in the collision system, which is part of Unreal Engine’s physics module. It’s referenced in the SceneQueryLowLevel.cpp file, which handles low-level scene query operations.

The value of this variable is set through the console variable system, as indicated by the FAutoConsoleVariableRef declaration. It can be changed at runtime using console commands.

The associated variable SerializeSQSamples interacts directly with p.SerializeSQSampleCount. They share the same value and are used interchangeably in the code.

Developers should be aware that this variable is only active in non-shipping builds (#if !UE_BUILD_SHIPPING). It’s used in conjunction with other debug variables like p.SerializeSQs to capture and serialize scene queries that exceed a certain duration threshold.

Best practices when using this variable include:

  1. Use it sparingly, as it can cause performance hitches due to the repeated sampling of scene queries.
  2. Adjust the value based on the specific profiling needs. Higher values provide more accurate averages but increase the performance impact.
  3. Use it in conjunction with other scene query debug variables for comprehensive profiling.

Regarding the associated variable SerializeSQSamples:

The purpose of SerializeSQSamples is the same as p.SerializeSQSampleCount. It’s an internal representation of the console variable.

It’s used in the same collision system and physics module as p.SerializeSQSampleCount.

Its value is set by the console variable system through p.SerializeSQSampleCount.

It directly interacts with the logic that measures and potentially serializes scene queries that exceed duration thresholds.

Developers should be aware that modifying SerializeSQSamples directly in code won’t have an effect, as it’s controlled by the console variable system.

The best practice is to modify this value through the console variable p.SerializeSQSampleCount rather than changing SerializeSQSamples directly in the code.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Collision/SceneQueryLowLevel.cpp:24

Scope: file

Source code excerpt:


FAutoConsoleVariableRef CVarSerializeSQs(TEXT("p.SerializeSQs"), SerializeSQs, TEXT("If enabled, we create a sq capture per sq that takes more than provided value in microseconds. This can be very expensive as the entire scene is saved out"));
FAutoConsoleVariableRef CVarSerializeSQSamples(TEXT("p.SerializeSQSampleCount"), SerializeSQSamples, TEXT("If Query exceeds duration threshold, we will re-measure SQ this many times before serializing. Larger values cause hitching."));
FAutoConsoleVariableRef CVarReplaySweeps(TEXT("p.ReplaySQs"), ReplaySQs, TEXT("If enabled, we rerun the sq against chaos"));
FAutoConsoleVariableRef CVarSerializeBadSweeps(TEXT("p.SerializeBadSQs"), SerializeBadSQs, TEXT("If enabled, we create a sq capture whenever chaos and physx diverge"));
FAutoConsoleVariableRef CVarSerializeSQsRaycastEnabled(TEXT("p.SerializeSQsRaycastEnabled"), EnableRaycastSQCapture, TEXT("If disabled, p.SerializeSQs will not consider raycasts"));
FAutoConsoleVariableRef CVarSerializeSQsOverlapEnabled(TEXT("p.SerializeSQsOverlapEnabled"), EnableOverlapSQCapture, TEXT("If disabled, p.SerializeSQs will not consider overlaps"));
FAutoConsoleVariableRef CVarSerializeSQsSweepEnabled(TEXT("p.SerializeSQsSweepEnabled"), EnableSweepSQCapture, TEXT("If disabled, p.SerializeSQs will not consider sweeps"));
#else

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Collision/SceneQueryLowLevel.cpp:16

Scope: file

Source code excerpt:

#if !UE_BUILD_SHIPPING
int32 SerializeSQs = 0;
int32 SerializeSQSamples = 100;
int32 SerializeBadSQs = 0;
int32 ReplaySQs = 0;
int32 EnableRaycastSQCapture = 1;
int32 EnableOverlapSQCapture = 1;
int32 EnableSweepSQCapture = 1;

FAutoConsoleVariableRef CVarSerializeSQs(TEXT("p.SerializeSQs"), SerializeSQs, TEXT("If enabled, we create a sq capture per sq that takes more than provided value in microseconds. This can be very expensive as the entire scene is saved out"));
FAutoConsoleVariableRef CVarSerializeSQSamples(TEXT("p.SerializeSQSampleCount"), SerializeSQSamples, TEXT("If Query exceeds duration threshold, we will re-measure SQ this many times before serializing. Larger values cause hitching."));
FAutoConsoleVariableRef CVarReplaySweeps(TEXT("p.ReplaySQs"), ReplaySQs, TEXT("If enabled, we rerun the sq against chaos"));
FAutoConsoleVariableRef CVarSerializeBadSweeps(TEXT("p.SerializeBadSQs"), SerializeBadSQs, TEXT("If enabled, we create a sq capture whenever chaos and physx diverge"));
FAutoConsoleVariableRef CVarSerializeSQsRaycastEnabled(TEXT("p.SerializeSQsRaycastEnabled"), EnableRaycastSQCapture, TEXT("If disabled, p.SerializeSQs will not consider raycasts"));
FAutoConsoleVariableRef CVarSerializeSQsOverlapEnabled(TEXT("p.SerializeSQsOverlapEnabled"), EnableOverlapSQCapture, TEXT("If disabled, p.SerializeSQs will not consider overlaps"));
FAutoConsoleVariableRef CVarSerializeSQsSweepEnabled(TEXT("p.SerializeSQsSweepEnabled"), EnableSweepSQCapture, TEXT("If disabled, p.SerializeSQs will not consider sweeps"));
#else
constexpr int32 SerializeSQs = 0;
constexpr int32 ReplaySQs = 0;
constexpr int32 SerializeSQSamples = 0;
constexpr int32 EnableRaycastSQCapture = 0;
constexpr int32 EnableOverlapSQCapture = 0;
constexpr int32 EnableSweepSQCapture = 0;
#endif

namespace

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Collision/SceneQueryLowLevel.cpp:120

Scope (from outer to inner):

file
namespace    anonymous
function     void SweepSQCaptureHelper

Source code excerpt:

			// Measure average time of query over multiple samples to reduce fluke from context switches or that kind of thing.
			uint32 Cycles = 0.0;
			const uint32 SampleCount = SerializeSQSamples;
			for (uint32 Samples = 0; Samples < SampleCount; ++Samples)
			{
				// Reset output to not skew times with large buffer
				FPhysicsHitCallback<FHitSweep> ScratchHitBuffer = FPhysicsHitCallback<FHitSweep>(HitBuffer.WantsSingleResult());

				uint32 StartTime = FPlatformTime::Cycles();

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Collision/SceneQueryLowLevel.cpp:157

Scope (from outer to inner):

file
namespace    anonymous
function     void RaycastSQCaptureHelper

Source code excerpt:

			// Measure average time of query over multiple samples to reduce fluke from context switches or that kind of thing.
			uint32 Cycles = 0.0;
			const uint32 SampleCount = SerializeSQSamples;
			for (uint32 Samples = 0; Samples < SampleCount; ++Samples)
			{
				// Reset output to not skew times with large buffer
				FPhysicsHitCallback<FHitRaycast> ScratchHitBuffer = FPhysicsHitCallback<FHitRaycast>(HitBuffer.WantsSingleResult());

				uint32 StartTime = FPlatformTime::Cycles();

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Collision/SceneQueryLowLevel.cpp:194

Scope (from outer to inner):

file
namespace    anonymous
function     void OverlapSQCaptureHelper

Source code excerpt:

			// Measure average time of query over multiple samples to reduce fluke from context switches or that kind of thing.
			uint32 Cycles = 0.0;
			const uint32 SampleCount = SerializeSQSamples;
			for (uint32 Samples = 0; Samples < SampleCount; ++Samples)
			{
				// Reset output to not skew times with large buffer
				FPhysicsHitCallback<FHitOverlap> ScratchHitBuffer = FPhysicsHitCallback<FHitOverlap>(HitBuffer.WantsSingleResult());

				uint32 StartTime = FPlatformTime::Cycles();