UDocumentation UE5.7 10.02.2026 (Source)
API documentation for Unreal Engine 5.7
ChaosVisualDebuggerTrace.h
Go to the documentation of this file.
1// Copyright Epic Games, Inc. All Rights Reserved.
2
3#pragma once
4#include "Chaos/Core.h"
7#include "Containers/Set.h"
8
13#include "HAL/ThreadSafeBool.h"
14
15#ifndef CHAOS_VISUAL_DEBUGGER_ENABLED
16 #define CHAOS_VISUAL_DEBUGGER_ENABLED WITH_CHAOS_VISUAL_DEBUGGER
17#endif
18
19#ifndef CHAOS_VISUAL_DEBUGGER_WITHOUT_TRACE
20 #define CHAOS_VISUAL_DEBUGGER_WITHOUT_TRACE 0
21#endif
22
25
26#if WITH_CHAOS_VISUAL_DEBUGGER
27
33#include "Trace/Trace.h"
34#include "Trace/Trace.inl"
35
36namespace Chaos
37{
38class FRigidClustering;
39class FAccelerationStructureHandle;
40class FCharacterGroundConstraintContainer;
41class FPBDConstraintContainer;
42class FPBDJointConstraints;
43}
44
46
55
60
66
72
76 UE_TRACE_MINIMAL_EVENT_FIELD(UE::Trace::WideString, StepName)
78
84
87 UE_TRACE_MINIMAL_EVENT_FIELD(UE::Trace::WideString, TypeName)
91 UE_TRACE_MINIMAL_EVENT_FIELD(bool, IsCompressed)
93
99
104
111
115 UE_TRACE_MINIMAL_EVENT_FIELD(UE::Trace::WideString, DebugName)
117
123 UE_TRACE_MINIMAL_EVENT_FIELD(UE::Trace::WideString, DebugName)
125
130
134
138
140 CVD_DEFINE_TRACE_VECTOR(Chaos::FReal, BoxMin)
141 CVD_DEFINE_TRACE_VECTOR(Chaos::FReal, BoxMax)
143
147
159
160namespace Chaos
161{
162 namespace VisualDebugger
163 {
164 class FChaosVDSerializableNameTable;
165 }
166
167 class FPBDCollisionConstraints;
168 class FPBDRigidsSOAs;
169 class FImplicitObject;
170 class FPhysicsSolverBase;
171 template <typename T, int d>
172 class TGeometryParticleHandles;
173
174 class FPBDCollisionConstraint;
175 class FParticlePairMidPhase;
176
177 template <typename PayloadType, typename T, int d>
178 class ISpatialAccelerationCollection;
179}
180
182using FChaosVDSerializableNameTable = Chaos::VisualDebugger::FChaosVDSerializableNameTable;
183
185{
186 None = 0,
189 ForceTrace = 1 << 0
190};
192
194
195namespace Chaos::VD
196{
197 template<typename TObjectID>
199 {
200 public:
201
202 template<typename ObjectType, typename HashProducer>
204 {
205 if (ObjectPtr == nullptr)
206 {
207 return 0;
208 }
209
210 bool bHasCachedID = true;
211 TObjectID FoundID = CachedIDsByPtr.FindOrProduce(reinterpret_cast<const void*>(ObjectPtr), [&InHashProducer, &bHasCachedID]()
212 {
213 bHasCachedID = false;
214 return InHashProducer();
215 });
216
217 if (bHasCachedID)
218 {
219 OutWasAlreadyCached = true;
220 return FoundID;
221 }
222
223 return FoundID;
224 }
225
226 template<typename ObjectType>
227 void RemoveCachedTraceObjectID(const ObjectType* Implicit)
228 {
229 if (Implicit == nullptr)
230 {
231 return;
232 }
233
234 CachedIDsByPtr.Remove(reinterpret_cast<const void*>(Implicit));
235 }
236
237 void Reset()
238 {
239 CachedIDsByPtr.Reset();
240 }
241
242 private:
243
244 static constexpr int32 StripCount = 32;
246 };
247
249 {
251
254
258
262
264
265 std::atomic<bool> bIsTracing;
266
268
270
272
274 {
275 uint64 NewID = 0;
277 {
279 };
280
281 return NewID;
282 }
283
284 static constexpr uint64 InvalidUniqueID = 0;
285
286 private:
287 std::atomic<uint64> InternalGenericIDCounter;
288 };
289}
290
292class FChaosVisualDebuggerTrace
293{
294public:
299 static CHAOS_API void TraceParticle(const Chaos::FGeometryParticleHandle* ParticleHandle);
300
307
312 static CHAOS_API void TraceParticleDestroyed(const Chaos::FGeometryParticleHandle* ParticleHandle);
313
319
321 template<typename ParticleType>
323
325 static CHAOS_API void TraceMidPhase(const Chaos::FParticlePairMidPhase* MidPhase);
326
329
332
335
338
341
344
346 static CHAOS_API void TraceSolverFrameStart(const FChaosVDContext& ContextData, const FString& InDebugName, int32 FrameNumber = INDEX_NONE);
347
349 static CHAOS_API void TraceSolverFrameEnd(const FChaosVDContext& ContextData);
350
354 static CHAOS_API void TraceSolverStepStart(FStringView StepName);
356 static CHAOS_API void TraceSolverStepEnd();
357
362
368 static CHAOS_API void TraceBinaryData(TConstArrayView<uint8> InData, FStringView TypeName, EChaosVDTraceBinaryDataOptions Options = EChaosVDTraceBinaryDataOptions::None);
369
375 UE_DEPRECATED(5.7, "Use the TraceImplicitObject version that takes a ptr to the implicit object itself")
377
385
393
399
405
418 static CHAOS_API void TraceSceneQueryStart(const Chaos::FImplicitObject* InputGeometry, const FQuat& GeometryOrientation, const FVector& Start, const FVector& End, ECollisionChannel TraceChannel, FChaosVDCollisionQueryParams&& Params, FChaosVDCollisionResponseParams&& ResponseParams, FChaosVDCollisionObjectQueryParams&& ObjectParams, EChaosVDSceneQueryType QueryType, EChaosVDSceneQueryMode QueryMode, int32 SolverID, bool bIsRetry);
419
424
428 static CHAOS_API void TraceSceneAccelerationStructures(const Chaos::ISpatialAccelerationCollection<Chaos::FAccelerationStructureHandle, Chaos::FReal, 3>* InAccelerationCollection);
429
435
443
452
461
470
478 static CHAOS_API void TraceDebugDrawImplicitObject(const Chaos::FImplicitObject* Implicit, const FTransform& InParentTransform, FName Tag = NAME_None, FColor Color = FColor::Blue, int32 SolverID = INDEX_NONE);
479
485
486 /*
487 * Returns the currently bounding box used to determine if we should trace data or not, for objects that can be applied to.
488 */
490 {
491 return SessionState.TraceRelevancyVolume;
492 }
493
500 {
501 if (!SessionState.TraceRelevancyVolume.IsValid)
502 {
503 // An invalid volume means we want to trace everything
504 return true;
505 }
506
507 return SessionState.TraceRelevancyVolume.Intersect(FBox(InChaosBounds.Min(), InChaosBounds.Max()));
508 }
509
515 static bool IsInRelevancyVolume(const FBox& InBounds)
516 {
517 if (!SessionState.TraceRelevancyVolume.IsValid)
518 {
519 // An invalid volume means we want to trace everything
520 return true;
521 }
522
523 return SessionState.TraceRelevancyVolume.Intersect(InBounds);
524 }
525
532 static bool IsInRelevancyVolume(const FVector& Center, double Radius)
533 {
534 if (!SessionState.TraceRelevancyVolume.IsValid)
535 {
536 // An invalid volume means we want to trace everything
537 return true;
538 }
539
540 return FMath::SphereAABBIntersection(Center, Radius * Radius, SessionState.TraceRelevancyVolume);
541 }
542
549 {
550 if (!SessionState.TraceRelevancyVolume.IsValid)
551 {
552 // An invalid volume means we want to trace everything
553 return true;
554 }
555
556 return FMath::PointBoxIntersection(InPosition, SessionState.TraceRelevancyVolume);
557 }
558
566 {
567 if (!SessionState.TraceRelevancyVolume.IsValid)
568 {
569 // An invalid volume means we want to trace everything
570 return true;
571 }
572
573 return SessionState.TraceRelevancyVolume.Intersect(FBox(FVector::Min(InStartPoint, InEndPoint), FVector::Max(InStartPoint, InEndPoint)));
574 }
575
578
582 template<typename WorldType>
583 static int32 GetSolverIDFromWorld(WorldType* World);
584
588 static int32 CHAOS_API GetSolverID(Chaos::FPhysicsSolverBase& Solver);
589
591 static CHAOS_API bool ShouldPerformFullCapture(int32 SolverID);
592
599 template<typename T>
601
605 template<typename T>
606 static FString GetDebugName(T& ObjectWithDebugName);
607
609 static CHAOS_API bool IsTracing();
610
612 static void RegisterEventHandlers();
613
615 static void UnregisterEventHandlers();
616
618
624
625 static CHAOS_API void RegisterExternalParticleDebugNameGenerator(const Chaos::VD::FRecordingSessionState::FParticleMetaDataGeneratorDelegate& InCallback);
626
627private:
628
636
642 static CHAOS_API void TraceParticle(Chaos::FGeometryParticleHandle* ParticleHandle, const FChaosVDContext& ContextData);
643
651
659
667
669 static void Reset();
670
671 static void HandleRecordingStop();
672 static void TraceArchiveHeader();
673 static void HandleRecordingStart();
674
677
680
681 static Chaos::VD::FRecordingSessionState SessionState;
682
683 friend class FChaosEngineModule;
684};
685
686template <typename ParticleType>
687void FChaosVisualDebuggerTrace::TraceParticlesView(const Chaos::TParticleView<ParticleType>& ParticlesView)
688{
689 if (!IsTracing())
690 {
691 return;
692 }
693
694 const FChaosVDContext* CVDContextData = FChaosVDThreadContext::Get().GetCurrentContext(EChaosVDContextType::Solver);
696 {
697 return;
698 }
699
701
702 ParticlesView.ParallelFor([CopyContext](auto& Particle, int32 Index)
703 {
705 TraceParticle(Particle.Handle());
706 });
707}
708
709template <typename WorldType>
710int32 FChaosVisualDebuggerTrace::GetSolverIDFromWorld(WorldType* World)
711{
712 int32 SolverID = INDEX_NONE;
713 if (World)
714 {
715 if (Chaos::FPhysicsSolverBase* Solver = World->GetPhysicsScene() ? World->GetPhysicsScene()->GetSolver() : nullptr)
716 {
717 SolverID = GetSolverID(*Solver);
718 }
719 }
720
721 return SolverID;
722}
723
724template <typename T>
725void FChaosVisualDebuggerTrace::GetCVDContext(T& ObjectWithContext, FChaosVDContext& OutCVDContext)
726{
727 OutCVDContext = ObjectWithContext.GetChaosVDContextData();
728}
729
730template <typename T>
731FString FChaosVisualDebuggerTrace::GetDebugName(T& ObjectWithDebugName)
732{
733#if CHAOS_SOLVER_DEBUG_NAME
734 return ObjectWithDebugName.GetDebugName().ToString();
735#else
736 return FString("COMPILED OUT");
737#endif
738}
739
741{
743 {
745 }
746
748 {
750 }
751};
752
753template<typename T>
755{
757 {
759 }
760
762 {
764 }
765
766 T& SolverRef;
767};
768
770{
772 {
773 }
774
776 {
778 }
779
781};
782
783namespace Chaos::VisualDebugger
784{
785 template<typename TDataToSerialize>
787 {
788 FChaosVDMemoryWriter MemWriterAr(InOutDataBuffer, FChaosVisualDebuggerTrace::GetNameTableInstance());
789 MemWriterAr.SetShouldSkipUpdateCustomVersion(true);
790
791 Data.Serialize(MemWriterAr);
792 }
793
794 template<typename TDataToSerialize, typename TArchive>
796 {
797 FChaosVDMemoryWriter MemWriterAr(InOutDataBuffer, FChaosVisualDebuggerTrace::GetNameTableInstance());
799 Ar.SetShouldSkipUpdateCustomVersion(true);
800
801 Data.Serialize(Ar);
802 }
803}
804#endif // WITH_CHAOS_VISUAL_DEBUGGER
#define ensure( InExpression)
Definition AssertionMacros.h:464
#define CVD_SCOPE_CONTEXT(InContext)
Definition ChaosVDContextProvider.h:219
EChaosVDSceneQueryMode
Definition ChaosVDQueryDataWrappers.h:20
EChaosVDSceneQueryType
Definition ChaosVDQueryDataWrappers.h:11
#define CVD_TRACE_SOLVER_START_FRAME(SolverType, SolverRef)
Definition ChaosVDTraceMacros.h:238
#define CVD_TRACE_SOLVER_STEP_END()
Definition ChaosVDTraceMacros.h:254
#define CVD_TRACE_SCENE_QUERY_VISIT(InQueryVisitData)
Definition ChaosVDTraceMacros.h:312
#define CVD_TRACE_SOLVER_STEP_START(StepName)
Definition ChaosVDTraceMacros.h:250
#define CVD_TRACE_SOLVER_END_FRAME(SolverType, SolverRef)
Definition ChaosVDTraceMacros.h:242
@ INDEX_NONE
Definition CoreMiscDefines.h:150
#define UE_DEPRECATED(Version, Message)
Definition CoreMiscDefines.h:302
FPlatformTypes::int32 int32
A 32-bit signed integer.
Definition Platform.h:1125
FPlatformTypes::uint64 uint64
A 64-bit unsigned integer.
Definition Platform.h:1117
UE_FORCEINLINE_HINT TSharedRef< CastToType, Mode > StaticCastSharedRef(TSharedRef< CastFromType, Mode > const &InSharedRef)
Definition SharedPointer.h:127
#define DECLARE_DELEGATE_RetVal_TwoParams(ReturnValueType, DelegateName, Param1Type, Param2Type)
Definition DelegateCombinations.h:63
ECollisionChannel
Definition EngineTypes.h:1088
#define ENUM_CLASS_FLAGS(Enum)
Definition EnumClassFlags.h:6
UE::Math::TBox< double > FBox
Definition MathFwd.h:55
#define UE_TRACE_MINIMAL_EVENT_FIELD(FieldType, FieldName)
Definition Trace.h:463
#define UE_TRACE_MINIMAL_EVENT_BEGIN_EXTERN(LoggerName, EventName,...)
Definition Trace.h:462
#define UE_TRACE_MINIMAL_EVENT_END()
Definition Trace.h:465
#define UE_TRACE_MINIMAL_CHANNEL_EXTERN(ChannelName,...)
Definition Trace.h:475
UE_INTRINSIC_CAST UE_REWRITE constexpr std::remove_reference_t< T > && MoveTemp(T &&Obj) noexcept
Definition UnrealTemplate.h:520
uint32 Offset
Definition VulkanMemory.cpp:4033
uint8_t uint8
Definition binka_ue_file_header.h:8
uint32_t uint32
Definition binka_ue_file_header.h:6
Container class for all character ground constraints on the physics thread.
Definition CharacterGroundConstraintContainer.h:228
Definition ImplicitObject.h:111
A contact constraint.
Definition PBDCollisionConstraint.h:225
Definition PBDCollisionConstraints.h:49
Definition PBDJointConstraints.h:168
Definition PBDRigidsSOAs.h:269
Produce collisions for a particle pair A FParticlePairMidPhase object is created for every particle p...
Definition ParticlePairMidPhase.h:192
Definition PhysicsSolverBase.h:313
Definition PBDRigidClustering.h:56
Definition ParticleHandle.h:436
Definition ParticleHandle.h:2663
Definition PBDRigidParticles.h:22
Definition ParticleIterator.h:639
Definition ChaosVDSerializedNameTable.h:32
Definition ChaosModule.h:8
Definition IDelegateInstance.h:14
Definition NameTypes.h:617
Definition PhysicsProxyBase.h:97
Definition ArrayView.h:139
Definition Array.h:670
Definition SharedPointer.h:153
Definition StripedMap.h:780
Definition CriticalSection.h:14
GeometryCollection::Facades::FMuscleActivationData Data
Definition MuscleActivationConstraints.h:15
Definition ChaosVDEngineEditorBridge.h:7
Definition ChaosVDDataWrapperUtils.cpp:19
Definition SkeletalMeshComponent.h:307
UE_TRACE_API bool IsTracing() UE_TRACE_IMPL(false)
WideString
Definition Trace.h:53
Definition AdvancedWidgetsModule.cpp:13
U16 Index
Definition radfft.cpp:71
Definition ChaosVDQueryDataWrappers.h:66
Definition ChaosVDQueryDataWrappers.h:129
Definition ChaosVDQueryDataWrappers.h:29
Definition ChaosVDImplicitObjectDataWrapper.h:14
Definition ChaosVDParticleDataWrapper.h:46
Definition ChaosVDQueryDataWrappers.h:366
Definition CollisionQueryParams.h:430
Definition CollisionQueryParams.h:43
Definition CollisionQueryParams.h:324
Definition Color.h:486
static bool PointBoxIntersection(const UE::Math::TVector< FReal > &Point, const UE::Math::TBox< FReal > &Box)
Definition Box.h:1030
static bool SphereAABBIntersection(const UE::Math::TVector< FReal > &SphereCenter, const FReal RadiusSquared, const UE::Math::TBox< FReal > &AABB)
Definition Box.h:1190
bool Intersect(const TBox< T > &Other) const
Definition Box.h:811
static TVector< double > Max(const TVector< double > &A, const TVector< double > &B)
Definition Vector.h:2506
static TVector< double > Min(const TVector< double > &A, const TVector< double > &B)
Definition Vector.h:2496