p.Chaos.MultiRes.SparseWeightMap

p.Chaos.MultiRes.SparseWeightMap

#Overview

name: p.Chaos.MultiRes.SparseWeightMap

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

• type: Var
• help: Exploit the sparse weight map structure and skip the particles with 0 stiffness at the beginning and at the end

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.MultiRes.SparseWeightMap is to optimize the performance of multi-resolution constraints in the Chaos physics system by exploiting the sparse weight map structure and skipping particles with zero stiffness at the beginning and end of the particle array.

This setting variable is primarily used in the Chaos physics subsystem, which is part of Unreal Engine’s experimental physics engine. It’s specifically related to the multi-resolution constraint solver within Chaos.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized as false and can be toggled at runtime.

The associated variable bChaos_MultiRes_SparseWeightMap_Enabled directly interacts with p.Chaos.MultiRes.SparseWeightMap. They share the same value and are used interchangeably in the code.

Developers should be aware that:

1. This optimization is only available in non-shipping builds (#if !UE_BUILD_SHIPPING).
2. It requires the stiffness entries to be initialized (bStiffnessEntriesInitialized).
3. It’s used in conjunction with ISPC (Intel SPMD Program Compiler) optimizations.

Best practices when using this variable include:

1. Enable it only when dealing with sparse weight maps in multi-resolution constraints.
2. Ensure that the stiffness entries are properly initialized before relying on this optimization.
3. Test thoroughly to ensure that skipping zero stiffness particles doesn’t introduce unexpected behavior in your physics simulations.

Regarding the associated variable bChaos_MultiRes_SparseWeightMap_Enabled:

• Its purpose is identical to p.Chaos.MultiRes.SparseWeightMap.
• It’s used directly in the C++ code to conditionally execute optimized code paths.
• It’s set through the same console variable system.
• Developers should treat it as equivalent to p.Chaos.MultiRes.SparseWeightMap in terms of usage and considerations.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/SoftsMultiResConstraints.cpp:22

Scope: file

Source code excerpt:

FAutoConsoleVariableRef CVarChaosMultiResISPCEnabled(TEXT("p.Chaos.MultiRes.ISPC"), bChaos_MultiRes_ISPC_Enabled, TEXT("Whether to use ISPC optimizations in MultiRes constraints"));
bool bChaos_MultiRes_SparseWeightMap_Enabled = false;
FAutoConsoleVariableRef CVarChaosMultiResSparseWeightMapEnabled(TEXT("p.Chaos.MultiRes.SparseWeightMap"), bChaos_MultiRes_SparseWeightMap_Enabled, TEXT("Exploit the sparse weight map structure and skip the particles with 0 stiffness at the beginning and at the end"));
#endif

namespace Chaos::Softs {

static bool bMultiResConstraintApplyTargetNormalOffset = true;
static FAutoConsoleVariableRef CVarMultiResConstraintApplyTargetNormalOffset(TEXT("p.Chaos.MultiRes.ApplyTargetNormalOffset"), bMultiResConstraintApplyTargetNormalOffset, TEXT("Apply normal offset to targets."));

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/SoftsMultiResConstraints.cpp:21

Scope: file

Source code excerpt:

bool bChaos_MultiRes_ISPC_Enabled = true;
FAutoConsoleVariableRef CVarChaosMultiResISPCEnabled(TEXT("p.Chaos.MultiRes.ISPC"), bChaos_MultiRes_ISPC_Enabled, TEXT("Whether to use ISPC optimizations in MultiRes constraints"));
bool bChaos_MultiRes_SparseWeightMap_Enabled = false;
FAutoConsoleVariableRef CVarChaosMultiResSparseWeightMapEnabled(TEXT("p.Chaos.MultiRes.SparseWeightMap"), bChaos_MultiRes_SparseWeightMap_Enabled, TEXT("Exploit the sparse weight map structure and skip the particles with 0 stiffness at the beginning and at the end"));
#endif

namespace Chaos::Softs {

static bool bMultiResConstraintApplyTargetNormalOffset = true;
static FAutoConsoleVariableRef CVarMultiResConstraintApplyTargetNormalOffset(TEXT("p.Chaos.MultiRes.ApplyTargetNormalOffset"), bMultiResConstraintApplyTargetNormalOffset, TEXT("Apply normal offset to targets."));

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/SoftsMultiResConstraints.cpp:159

Scope (from outer to inner):

file
namespace    Chaos::Softs
function     void FMultiResConstraints::Apply

Source code excerpt:

		{
#if !UE_BUILD_SHIPPING
			if (bChaos_MultiRes_SparseWeightMap_Enabled && bStiffnessEntriesInitialized)
			{
				check(NonZeroStiffnessMax != INDEX_NONE && NonZeroStiffnessMin != INDEX_NONE)
				ispc::ApplyMultiResConstraintsWithWeightMaps(
					(ispc::FVector4f*)&Particles.GetPAndInvM().GetData()[NonZeroStiffnessMin],
					(const ispc::FVector3f*)&Particles.XArray().GetData()[NonZeroStiffnessMin],
					(const ispc::FVector3f*)&FineTargetPositions.GetData()[NonZeroStiffnessMin],

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/SoftsMultiResConstraints.cpp:276

Scope (from outer to inner):

file
namespace    Chaos::Softs
function     void FMultiResConstraints::UpdateFineTargets

Source code excerpt:

		{
#if !UE_BUILD_SHIPPING
			if (Stiffness.HasWeightMap() && bChaos_MultiRes_SparseWeightMap_Enabled && bStiffnessEntriesInitialized)
			{
				ispc::MultiResUpdateFineTargets(
					(ispc::FVector3f*)&FineTargetPositions.GetData()[NonZeroStiffnessMin],
					(ispc::FVector3f*)&FineTargetVelocities.GetData()[NonZeroStiffnessMin],
					(const ispc::FVector3f*)CoarseX.GetData(),
					(const ispc::FVector3f*)Normals.GetData(),