XInput.ForceControllerStateUpdate

XInput.ForceControllerStateUpdate

#Overview

name: XInput.ForceControllerStateUpdate

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of XInput.ForceControllerStateUpdate is to control whether the XInput system should forcibly refresh the controller state on each frame. This setting is part of the input handling system, specifically for XInput devices on Windows platforms.

This setting variable is primarily used in the XInputDevice plugin, which is part of Unreal Engine’s input system. It’s utilized within the XInputInterface class, which is responsible for interfacing with XInput-compatible controllers.

The value of this variable is set through the Unreal Engine Console Variable (CVar) system. It’s defined as an FAutoConsoleVariableRef, which means it can be modified at runtime through console commands or configuration files.

The associated variable ForceControllerStateUpdate directly interacts with XInput.ForceControllerStateUpdate. They share the same value, with ForceControllerStateUpdate being the actual int32 variable used in the code logic.

Developers must be aware that enabling this setting (setting it to 1) will cause the XInput system to refresh the controller state on every frame, which could potentially impact performance, especially in scenarios with multiple controllers or on less powerful hardware.

Best practices when using this variable include:

  1. Keeping it disabled (0) by default for optimal performance.
  2. Only enabling it (1) when debugging input-related issues or when rapid input state updates are absolutely necessary.
  3. Being cautious about enabling it in shipping builds, as it could unnecessarily increase CPU usage.

Regarding the associated variable ForceControllerStateUpdate:

This is the actual int32 variable used in the code logic. It’s initialized to 0 and can be modified through the XInput.ForceControllerStateUpdate console variable.

In the XInputInterface::SendControllerEvents function, ForceControllerStateUpdate is used in a condition to determine whether to update the controller state. If it’s non-zero, the controller state will be updated regardless of other conditions.

Developers should be aware that modifying ForceControllerStateUpdate directly in code is not recommended. Instead, they should use the XInput.ForceControllerStateUpdate console variable to ensure consistency across the engine.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/Windows/XInputDevice/Source/XInputDevice/Private/XInputInterface.cpp:17

Scope: file

Source code excerpt:

static int32 ForceControllerStateUpdate = 0;
FAutoConsoleVariableRef CVarForceControllerStateUpdate(
	TEXT("XInput.ForceControllerStateUpdate"),
	ForceControllerStateUpdate,
	TEXT("Force XInput refresh of controller state on each frame.\n")
	TEXT("0: Not Enabled, 1: Enabled"),
	ECVF_Default);

TSharedRef< XInputInterface > XInputInterface::Create(  const TSharedRef< FGenericApplicationMessageHandler >& InMessageHandler, bool bShouldBePrimaryDevice )

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/Windows/XInputDevice/Source/XInputDevice/Private/XInputInterface.cpp:15

Scope: file

Source code excerpt:

#pragma pack (pop)

static int32 ForceControllerStateUpdate = 0;
FAutoConsoleVariableRef CVarForceControllerStateUpdate(
	TEXT("XInput.ForceControllerStateUpdate"),
	ForceControllerStateUpdate,
	TEXT("Force XInput refresh of controller state on each frame.\n")
	TEXT("0: Not Enabled, 1: Enabled"),
	ECVF_Default);

TSharedRef< XInputInterface > XInputInterface::Create(  const TSharedRef< FGenericApplicationMessageHandler >& InMessageHandler, bool bShouldBePrimaryDevice )
{

#Loc: <Workspace>/Engine/Plugins/Runtime/Windows/XInputDevice/Source/XInputDevice/Private/XInputInterface.cpp:158

Scope (from outer to inner):

file
function     void XInputInterface::SendControllerEvents

Source code excerpt:

		bWereConnected[ControllerIndex] = ControllerState.bIsConnected;

		if (ControllerState.bIsConnected || bNeedsControllerStateUpdate || ForceControllerStateUpdate != 0)
		{
			XINPUT_STATE& XInputState = XInputStates[ControllerIndex];
			FMemory::Memzero( &XInputState, sizeof(XINPUT_STATE) );

			ControllerState.bIsConnected = ( XInputGetState( ControllerIndex, &XInputState ) == ERROR_SUCCESS ) ? true : false;