HitProxySize

HitProxySize

#Overview

name: HitProxySize

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 8 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of HitProxySize is to define the size of the region used for hit proxy detection in Unreal Engine’s viewport system. This variable is primarily used for input handling and object selection in the engine’s rendering and interaction systems.

HitProxySize is mainly utilized by the Engine’s viewport subsystem and is also referenced in the VirtualCamera plugin. The primary modules that rely on this setting variable are:

  1. Engine’s core rendering and viewport system
  2. VirtualCamera plugin

The value of this variable is typically set in the constructor of the FViewport class. In editor builds, it’s initialized to 5 and can be configured through the GEditorIni file under the “UnrealEd.HitProxy” section.

HitProxySize interacts with viewport coordinates and is used to determine the area around a specific point (usually the mouse cursor position) for hit detection. It’s used in conjunction with other viewport-related variables like the viewport size.

Developers should be aware that:

  1. The value of HitProxySize affects the precision and performance of hit detection.
  2. It’s clamped between 1 and MAX_HITPROXYSIZE to ensure valid values.
  3. In editor builds, it can be configured, while in runtime builds, it’s usually set to a default value.

Best practices when using this variable include:

  1. Avoid modifying it directly unless absolutely necessary, as it can affect hit detection across the entire engine.
  2. If customizing hit detection behavior, consider using the existing methods that utilize HitProxySize rather than reimplementing the logic.
  3. Be mindful of performance implications when increasing the HitProxySize, as larger values will increase the area checked for hit detection, potentially impacting performance in scenes with many objects.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEditor.ini:223, section: [UnrealEd.HitProxy]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/VirtualProduction/VirtualCamera/Source/VirtualCamera/Private/FunctionLibraries/VCamBlueprintFunctionLibrary.cpp:549

Scope (from outer to inner):

file
namespace    UE::VirtualCamera::Private
function     static TTuple<int32, int32, TArray<HHitProxy*>> GetProxyMap

Source code excerpt:

	 * @see FViewport::GetHitProxyMap.
	 */
	static TTuple<int32, int32, TArray<HHitProxy*>> GetProxyMap(FViewport& Viewport, const FVector2D& InScreenPosition, const uint32 HitProxySize)
	{
		// See FViewport::GetHitProxy.
		// Compute a HitProxySize x HitProxySize test region with the center at (X,Y).
		int32 MinX = InScreenPosition.X - HitProxySize;
		int32 MinY = InScreenPosition.Y - HitProxySize;
		int32 MaxX = InScreenPosition.X + HitProxySize;
		int32 MaxY = InScreenPosition.Y + HitProxySize;
		
		// Clip the region to the viewport bounds.
		const FIntPoint ViewportSize = Viewport.GetSizeXY();
		MinX = FMath::Clamp(MinX, 0, ViewportSize.X - 1);
		MinY = FMath::Clamp(MinY, 0, ViewportSize.Y - 1);
		MaxX = FMath::Clamp(MaxX, 0, ViewportSize.X - 1);

#Loc: <Workspace>/Engine/Plugins/VirtualProduction/VirtualCamera/Source/VirtualCamera/Private/FunctionLibraries/VCamBlueprintFunctionLibrary.cpp:583

Scope (from outer to inner):

file
namespace    UE::VirtualCamera::Private
function     static void EnumerateHitProxies

Source code excerpt:

		FViewport& Viewport,
		const FVector2D& InScreenPosition,
		const uint32 HitProxySize,
		TFunctionRef<EBreakBehaviour(const UPrimitiveComponent& Component)> Callback
		)
	{
		auto[TestSizeX, TestSizeY, ProxyMap] = GetProxyMap(Viewport, InScreenPosition, HitProxySize);
		if (ProxyMap.IsEmpty())
		{
			return;
		}
		
		const auto ProcessProxy = [&Callback](HHitProxy* Proxy) -> EBreakBehaviour

#Loc: <Workspace>/Engine/Plugins/VirtualProduction/VirtualCamera/Source/VirtualCamera/Private/FunctionLibraries/VCamBlueprintFunctionLibrary.cpp:653

Scope (from outer to inner):

file
function     bool UVCamBlueprintFunctionLibrary::MultiTraceHitProxyOnViewport

Source code excerpt:

	using namespace UE::VirtualCamera::Private;
	TArray<FVCamTraceHitProxyResult> HitResults;
	EnumerateHitProxies(*Viewport, InScreenPosition, FMath::Max(InQueryParams.HitProxySize, 0), [&InQueryParams, &HitResults](const UPrimitiveComponent& Component)
	{
		if (PassesFilters(Component, InQueryParams))
		{
			// Component is in a HActor proxy, which keeps a const reference. We cannot safely use const_cast without invoking undefined behavior.
			// Hence we must resort to this runtime search hack.
			TArray<UActorComponent*> Components = Component.GetOwner()->GetComponents().Array();

#Loc: <Workspace>/Engine/Plugins/VirtualProduction/VirtualCamera/Source/VirtualCamera/Public/FunctionLibraries/VCamBlueprintFunctionLibrary.h:31

Scope: file

Source code excerpt:

	/** Determine the size of the query area around the center pixel. */
	UPROPERTY(EditAnywhere, BlueprintreadWrite, Category = "VirtualCamera")
	int32 HitProxySize = 5;

	/** Components on these actors should not be considered. */
	UPROPERTY(EditAnywhere, BlueprintreadWrite, Category = "VirtualCamera")
	TArray<AActor*> IgnoredActors;
};

#Loc: <Workspace>/Engine/Plugins/VirtualProduction/VirtualCamera/Source/VirtualCamera/Public/FunctionLibraries/VCamBlueprintFunctionLibrary.h:228

Scope (from outer to inner):

file
function     class VIRTUALCAMERA_API UVCamBlueprintFunctionLibrary : public UBlueprintFunctionLibrary { GENERATED_BODY

Source code excerpt:

	/**
	 * Traces from the viewport and returns all components that contribute to the pixels surrounding InScreenPosition.
	 * The size of the pixel area checked is controlled by InQueryParams.HitProxySize.
	 * 
	 * This finds actors that have NoCollision set. The actor is found by determining which actors contribute to the specified pixel.
	 * This function is designed for Editor builds; in Runtime builds, it returns false.
	 *
	 * @param InScreenPosition The viewport position to trace
	 * @param InTargetViewport The viewport to trace in
	 * @param InQueryParams Parameters for how the actors should be queried
	 * @param Result The result, set if this function returns true.
	 *
	 * @return Whether Result was written to
	 */
	UFUNCTION(BlueprintPure, Category = "VirtualCamera")
	static bool MultiTraceHitProxyOnViewport(const FVector2D& InScreenPosition, EVCamTargetViewportID InTargetViewport, FVCamTraceHitProxyQueryParams InQueryParams, TArray<FVCamTraceHitProxyResult>& Result);

private:

#if WITH_EDITOR
	/** Returns the current sequencer. */
	static TWeakPtr<ISequencer> GetSequencer();

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/UnrealClient.cpp:1320

Scope (from outer to inner):

file
function     FViewport::FViewport

Source code excerpt:

{
	//initialize the hit proxy kernel
	HitProxySize = 5;
	if (GIsEditor) 
	{
		GConfig->GetInt( TEXT("UnrealEd.HitProxy"), TEXT("HitProxySize"), (int32&)HitProxySize, GEditorIni );
		HitProxySize = FMath::Clamp( HitProxySize, (uint32)1, (uint32)MAX_HITPROXYSIZE );
	}

	// Cache the viewport client's hit proxy storage requirement.
	bRequiresHitProxyStorage = ViewportClient && ViewportClient->RequiresHitProxyStorage();
#if !WITH_EDITOR && !(UE_BUILD_SHIPPING || UE_BUILD_TEST)
	if ( bRequiresHitProxyStorage )

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/UnrealClient.cpp:1946

Scope (from outer to inner):

file
function     HHitProxy* FViewport::GetHitProxy

Source code excerpt:

HHitProxy* FViewport::GetHitProxy(int32 X,int32 Y)
{
	// Compute a HitProxySize x HitProxySize test region with the center at (X,Y).
	int32	MinX = X - HitProxySize,
			MinY = Y - HitProxySize,
			MaxX = X + HitProxySize,
			MaxY = Y + HitProxySize;

	FIntPoint VPSize = GetSizeXY();
	
	// Clip the region to the viewport bounds.
	MinX = FMath::Clamp(MinX, 0, VPSize.X - 1);
	MinY = FMath::Clamp(MinY, 0, VPSize.Y - 1);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/UnrealClient.h:803

Scope (from outer to inner):

file
class        class FViewport : public FRenderTarget, protected FRenderResource

Source code excerpt:


	/** The size of the region to check hit proxies */
	uint32 HitProxySize;

	/** What is the current window mode. */
	EWindowMode::Type WindowMode;

	/** True if the viewport client requires hit proxy storage. */
	uint32 bRequiresHitProxyStorage : 1;