r.FreezeMouseCursor

r.FreezeMouseCursor

#Overview

name: r.FreezeMouseCursor

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 r.FreezeMouseCursor is to freeze the mouse cursor position for debugging purposes, particularly for rendering passes that use the cursor position to display debug information.

This setting variable is primarily used in the rendering system of Unreal Engine. It is referenced in the Engine module, specifically in the SceneView.cpp file, which is part of the core rendering pipeline.

The value of this variable is set through a console command. It is defined as a TAutoConsoleVariable, which means it can be changed at runtime through the console or configuration files.

The variable interacts with an associated variable named CVarFreezeMouseCursor. They share the same value and are used interchangeably in the code.

Developers must be aware that this variable is only active in non-shipping and non-test builds (as indicated by the #if !(UE_BUILD_SHIPPING || UE_BUILD_TEST) preprocessor directive). It’s intended for debugging and development purposes only.

Best practices when using this variable include:

  1. Only use it for debugging rendering issues related to cursor position.
  2. Remember to disable it after debugging to ensure normal cursor behavior.
  3. Be cautious when using it in multiplayer scenarios, as it may affect only the local client.

Regarding the associated variable CVarFreezeMouseCursor:

The purpose of CVarFreezeMouseCursor is the same as r.FreezeMouseCursor. It’s an implementation detail of how the console variable is stored and accessed in the C++ code.

This variable is used directly in the FSceneView::SetupCommonViewUniformBufferParameters function to determine whether to update the cursor position in the view uniform shader parameters.

The value of CVarFreezeMouseCursor is set when the r.FreezeMouseCursor console command is used.

Developers should be aware that this variable is checked on the render thread (GetValueOnRenderThread()), which means changes to it will be reflected in the next frame.

Best practices for CVarFreezeMouseCursor are the same as for r.FreezeMouseCursor, as they represent the same setting. However, when accessing the value in C++ code, developers should use CVarFreezeMouseCursor.GetValueOnRenderThread() to ensure thread-safe access in rendering code.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SceneView.cpp:67

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarFreezeMouseCursor(
	TEXT("r.FreezeMouseCursor"),
	0,
	TEXT("Free the mouse cursor position, for passes which use it to display debug information.\n")
	TEXT("0: default\n")
	TEXT("1: freeze mouse cursor position at current location"),
	ECVF_Cheat);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SceneView.cpp:66

Scope: file

Source code excerpt:

#if !(UE_BUILD_SHIPPING || UE_BUILD_TEST)

static TAutoConsoleVariable<int32> CVarFreezeMouseCursor(
	TEXT("r.FreezeMouseCursor"),
	0,
	TEXT("Free the mouse cursor position, for passes which use it to display debug information.\n")
	TEXT("0: default\n")
	TEXT("1: freeze mouse cursor position at current location"),
	ECVF_Cheat);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SceneView.cpp:2742

Scope (from outer to inner):

file
function     void FSceneView::SetupCommonViewUniformBufferParameters

Source code excerpt:

#if !(UE_BUILD_SHIPPING || UE_BUILD_TEST)
	static FIntPoint LockedCursorPos = CursorPos;
	if (CVarFreezeMouseCursor.GetValueOnRenderThread() == 0 && CursorPos.X >= 0 && CursorPos.Y >= 0)
	{
		LockedCursorPos = CursorPos;
	}
	ViewUniformShaderParameters.CursorPosition = LockedCursorPos;
#endif