geometry.GeometryScript.AllowUnclampedGridDimensions

geometry.GeometryScript.AllowUnclampedGridDimensions

#Overview

name: geometry.GeometryScript.AllowUnclampedGridDimensions

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

• type: Var
• help: Flag to disable grid dimension clamping in GeometryScript grid-based operations

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of geometry.GeometryScript.AllowUnclampedGridDimensions is to control grid dimension clamping in GeometryScript grid-based operations within Unreal Engine 5.

This setting variable is primarily used in the GeometryScripting plugin, specifically within the GeometryScriptingCore module. It affects grid-based operations in the Geometry Scripting system.

The value of this variable is set as a console variable (CVar) with a default value of false. It can be changed at runtime through the console or configuration files.

This variable interacts closely with its associated variable CVarGeometryScriptUnclampedGridDimensions, which is the actual TAutoConsoleVariable instance that stores and manages the value.

Developers must be aware that this variable affects the maximum allowed grid dimensions in GeometryScript operations. When set to false (default), it limits grid resolutions to 256 cells in any dimension to prevent excessive memory usage and computation time.

Best practices when using this variable include:

1. Keep it disabled (false) for most use cases to prevent performance issues.
2. Enable it only when higher resolution grids are absolutely necessary and the performance impact is acceptable.
3. When enabled, carefully monitor memory usage and computation time in grid-based operations.

Regarding the associated variable CVarGeometryScriptUnclampedGridDimensions:

Its purpose is to implement the functionality of the geometry.GeometryScript.AllowUnclampedGridDimensions setting within the C++ code.

It is used in the same GeometryScripting plugin and GeometryScriptingCore module.

The value is set when the TAutoConsoleVariable is initialized, but can be changed at runtime using console commands.

This variable directly interacts with the clamping logic in functions like GetClampedGridResolution and GetClampedCellSize.

Developers should be aware that this variable is checked during runtime in grid-based operations, affecting performance and memory usage.

Best practices for using CVarGeometryScriptUnclampedGridDimensions include:

1. Use GetValueOnGameThread() to access its current value in C++ code.
2. Consider caching the value if it’s accessed frequently in performance-critical sections.
3. Be prepared to handle potential out-of-memory situations when this is set to true, as it allows for much larger grid dimensions.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/GeometryScripting/Source/GeometryScriptingCore/Private/MeshVoxelFunctions.cpp:19

Scope: file

Source code excerpt:

static TAutoConsoleVariable<bool> CVarGeometryScriptUnclampedGridDimensions(
	TEXT("geometry.GeometryScript.AllowUnclampedGridDimensions"),
	false,
	TEXT("Flag to disable grid dimension clamping in GeometryScript grid-based operations"));



static int32 GetClampedGridResolution(int32 TargetResolution, FString ToolName, UGeometryScriptDebug* Debug)

#Loc: <Workspace>/Engine/Plugins/Runtime/GeometryScripting/Source/GeometryScriptingCore/Private/MeshVoxelFunctions.cpp:31

Scope (from outer to inner):

file
function     static int32 GetClampedGridResolution

Source code excerpt:

	{
		UE::Geometry::AppendError(Debug, EGeometryScriptErrorType::InvalidInputs,
			FText::Format(LOCTEXT("ClampedGridResolution", "{0}: Requested GridResolution clamped to 256 to avoid significant memory/computation. Use CVar geometry.GeometryScript.AllowUnclampedGridDimensions to disable this limit."), FText::FromString(ToolName)));
		ClampResolution = 256;
	}
	return ClampResolution;
}

static double GetClampedCellSize(double TargetCellSize, FAxisAlignedBox3d BoundingBox, FString ToolName, UGeometryScriptDebug* Debug)

#Loc: <Workspace>/Engine/Plugins/Runtime/GeometryScripting/Source/GeometryScriptingCore/Private/MeshVoxelFunctions.cpp:44

Scope (from outer to inner):

file
function     static double GetClampedCellSize

Source code excerpt:

	{
		UE::Geometry::AppendError(Debug, EGeometryScriptErrorType::InvalidInputs, 
			FText::Format(LOCTEXT("ClampedCellSize", "{0}: Requested GridCellSize will require significant memory/computation, clamping to 256 cells. Use CVar geometry.GeometryScript.AllowUnclampedGridDimensions to disable this limit."), FText::FromString(ToolName)));
		UseCellSize = (float)BoundingBox.MaxDim() / 256.0;
	}
	return UseCellSize;
}

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/GeometryScripting/Source/GeometryScriptingCore/Private/MeshVoxelFunctions.cpp:18

Scope: file

Source code excerpt:

static TAutoConsoleVariable<bool> CVarGeometryScriptUnclampedGridDimensions(
	TEXT("geometry.GeometryScript.AllowUnclampedGridDimensions"),
	false,
	TEXT("Flag to disable grid dimension clamping in GeometryScript grid-based operations"));

#Loc: <Workspace>/Engine/Plugins/Runtime/GeometryScripting/Source/GeometryScriptingCore/Private/MeshVoxelFunctions.cpp:28

Scope (from outer to inner):

file
function     static int32 GetClampedGridResolution

Source code excerpt:

{
	int ClampResolution = FMath::Max(4, TargetResolution);
	if (ClampResolution > 256 && CVarGeometryScriptUnclampedGridDimensions.GetValueOnGameThread() == false)
	{
		UE::Geometry::AppendError(Debug, EGeometryScriptErrorType::InvalidInputs,
			FText::Format(LOCTEXT("ClampedGridResolution", "{0}: Requested GridResolution clamped to 256 to avoid significant memory/computation. Use CVar geometry.GeometryScript.AllowUnclampedGridDimensions to disable this limit."), FText::FromString(ToolName)));
		ClampResolution = 256;
	}
	return ClampResolution;

#Loc: <Workspace>/Engine/Plugins/Runtime/GeometryScripting/Source/GeometryScriptingCore/Private/MeshVoxelFunctions.cpp:41

Scope (from outer to inner):

file
function     static double GetClampedCellSize

Source code excerpt:

	double UseCellSize = FMath::Max(0.001, TargetCellSize);
	int MaxGridDimEstimate = (int32)(BoundingBox.MaxDim() / UseCellSize);
	if (MaxGridDimEstimate > 256 && CVarGeometryScriptUnclampedGridDimensions.GetValueOnGameThread() == false)
	{
		UE::Geometry::AppendError(Debug, EGeometryScriptErrorType::InvalidInputs, 
			FText::Format(LOCTEXT("ClampedCellSize", "{0}: Requested GridCellSize will require significant memory/computation, clamping to 256 cells. Use CVar geometry.GeometryScript.AllowUnclampedGridDimensions to disable this limit."), FText::FromString(ToolName)));
		UseCellSize = (float)BoundingBox.MaxDim() / 256.0;
	}
	return UseCellSize;