VoxelForge/Source/VoxelForge/Public/VoxelDensityProfile.h

// Opt-in density-path profiling used by the editor commandlet and targeted PIE diagnostics.
// Disabled by default so the shipping density path pays only one predictable branch in the
// scoped timers below.

#pragma once

#include "CoreMinimal.h"
#include "HAL/PlatformTime.h"

#include <atomic>

namespace VoxelDensityProfile
{
    enum class EMode : uint8
    {
        Disabled,
        Sampled,
        // Low-overhead attribution: keeps the parent and stage ledger trustworthy, samples
        // hot component scopes, and collects classifier detail without the old full-scope storm.
        Attribution,
        Full,
    };

    // Count-based sampling is deterministic with respect to the profiler's own counters, but the
    // report is intentionally diagnostic only.  It never participates in density or mesh output.
    constexpr uint32 DefaultSampleInterval = 128;

    enum class EBucket : uint8
    {
        GetDensityAt,
        ApplyDisturbances,
        PassageModifier,
        PassageLandingAir,
        PassageLandingFloor,
        PassageLandingRoomFloor,
        PassageTunnelAir,
        PassageStructuralPosts,
        TunnelCoreSupport,
        TunnelCoreSdf,
        TunnelCorePosts,
        StructuralTail,
        RoomGraphSource,
        SdfCarve,
        CaveRoughnessMod,
        CaveTerraceMod,
        LayerLineMod,
        RibbingMod,
        CaveOverhangMod,
        CaveCliffMod,
        ScallopMod,
        CaveArchMod,
        RoomColumnMod,
        DomeMod,
        PinchMod,
        FloorBiasMod,
        WormFieldSource,
        OriginSpineOp,
        BoundarySealOp,
        PassageCarveOp,
        XYEdgeSealOp,
        OtherOp,
        // Attribution components.  These are nested diagnostics; the non-overlapping phase
        // buckets below remain the density accounting ledger.
        FusedEvaluator,
        InterpretedOpStack,
        OperatorBlock,
        RoomGraphBuild,
        RoomGraphSdf,
        TunnelCoreWorld,
        FusedDetail,
        FusedWorm,
        FusedStructural,
        ClassifierTotal,
        ClassifierIntervalProof,
        ClassifierExactCore,
        ClassifierExactFinal,
        ClassifierRoomTail,
        RuntimeStreamBuilding,
        // Non-overlapping top-level phases.  The named operation buckets above are intentionally
        // nested diagnostics; these phase buckets are the accounting ledger that must add up to
        // GetDensityAt without double-counting a stack op inside its enclosing phase.
        DensityPrologue,
        DensityCore,
        DensityDisturbances,
        DensityStructuralPosts,
        DensityBoundarySeal,
        DensityDiffLayer,
        DensityTail,
        // Mesher-side accounting.  GenerateMesh is the inclusive total; the following buckets
        // cover its regular-grid work and its non-grid setup/finalisation.
        MesherGenerateMesh,
        MesherDensityGrid,
        MesherCellClassification,
        MesherGradientNormals,
        MesherVertexInterpolation,
        MesherStreamBuilding,
        MesherOther,
        Count
    };

    constexpr int32 BucketCount = static_cast<int32>(EBucket::Count);

    enum class ECounter : uint8
    {
        TunnelCacheLookup,
        TunnelCacheHit,
        TunnelCacheMiss,
        SdfCacheBuild,
        SdfSpatialIndexBuild,
        SdfBrickIndexBuild,
        RoomGraphBuildGeneratorTile,
        RoomGraphBuildGeneratorTunnelCore,
        RoomGraphBuildOpShared,
        RoomGraphBuildOpLocal,
        RoomGraphBuildClassifierShared,
        RoomGraphBuildClassifierLocal,
        RoomGraphBuildUnknown,
        CaveRoomCandidates,
        CaveRoomEvaluated,
        CaveTunnelCandidates,
        CaveTunnelEvaluated,
        TunnelCoreCandidates,
        TunnelCoreEvaluated,
        TunnelSupportColumnBuilds,
        TunnelSupportColumnCandidates,
        TunnelSupportFloorQueries,
        TunnelSupportFloorChecks,
        TunnelSupportFloorBackstopFires,
        TunnelRoomFloorBackstopFires,
        TunnelAuthoredFloorSamples,
        TunnelAuthoredFloorProtectionClamps,
        TunnelAuthoredFloorDisturbanceSkips,
        TunnelFloorProfileFallbacks,
        TunnelFloorProfileBuilds,
        TunnelFloorProfileSegments,
        TunnelFloorProfileLedges,
        TunnelFloorProfileLedgesBelow2Voxels,
        TunnelFloorProfileLedges2To4Voxels,
        TunnelFloorProfileLedges4To8Voxels,
        TunnelFloorProfileLedges8PlusVoxels,
        // One count per authored graph edge.  MultiStepEdges is an invariant guard: it must stay
        // zero now that old per-segment staircase quantisation is removed.
        TunnelFloorSteepEdges,
        TunnelFloorWindingEdges,
        TunnelFloorDropEdges,
        TunnelFloorMultiStepEdges,
        PassageSupportFloorBackstopFires,
        PassageNativeFloorCompositions,
        PassageCandidates,
        PassageEvaluated,
        MesherBlockTests,
        MesherBlockAllSolid,
        MesherBlockAllAir,
        TileClassifyCalls,
        TileClassifyAllSolid,
        TileClassifyAllAir,
        TileClassifyMixed,
        FusedTunnelSamples,
        FusedTunnelDetailSamples,
        FusedTunnelDetailSkipped,
        WormEligibleSamples,
        WormBlockProofs,
        WormBlockSkippedSamples,
        OpBlockBuilds,
        OpBlockSamples,
        OpBlockOperators,
        OpBlockActiveOperators,
        OpBlockPrunedOperators,
        MesherDensityGridBytes,
        MesherSharedGridReadBytes,
        MesherOutputArrayBytes,
        MesherOutputAllocatedBytes,
        OpBlockScratchBytes,
        OpBlockCopyBytes,
        Count
    };

    constexpr int32 CounterCount = static_cast<int32>(ECounter::Count);

    // Export the one fast-path bit so callers in the editor module can skip instrumentation
    // without crossing the DLL boundary for every scoped timer or counter.  It is diagnostic
    // state only; it never participates in density or mesh decisions.
    VOXELFORGE_API extern std::atomic<bool> GEnabled;
    VOXELFORGE_API extern std::atomic<EMode> GMode;
    inline thread_local bool GSampledScopeActive = false;

    // Resident allocator-backed bytes for one worker's generation cache family.  The profiler
    // aggregates this by worker; the fields intentionally describe allocations owned by the
    // cache, not the inline size of the enclosing C++ object.  SlotStorageBytes is the one
    // exception: it is the inline/static storage reserved for the worker's fixed cache table.
    struct FCacheMemoryBreakdown
    {
        uint64 SlotStorageBytes = 0;
        uint64 OpStackBytes = 0;
        uint64 RoomsBytes = 0;
        uint64 RoomFloorJoinsBytes = 0;
        uint64 TunnelsBytes = 0;
        uint64 PitsBytes = 0;
        uint64 ChimneysBytes = 0;
        uint64 ColumnsBytes = 0;
        uint64 SupportColumnEntriesBytes = 0;
        uint64 SupportColumnsBytes = 0;
        uint64 SupportColumnIntervalsBytes = 0;
        uint64 SpatialIndexBytes = 0;
        uint64 TotalBytes() const
        {
            return SlotStorageBytes + OpStackBytes
                + RoomsBytes + RoomFloorJoinsBytes + TunnelsBytes + PitsBytes
                + ChimneysBytes + ColumnsBytes + SupportColumnEntriesBytes
                + SupportColumnsBytes + SupportColumnIntervalsBytes + SpatialIndexBytes;
        }

        uint64 DynamicBytes() const
        {
            return TotalBytes() - SlotStorageBytes;
        }

        FCacheMemoryBreakdown& operator+=(const FCacheMemoryBreakdown& Other)
        {
            SlotStorageBytes += Other.SlotStorageBytes;
            OpStackBytes += Other.OpStackBytes;
            RoomsBytes += Other.RoomsBytes;
            RoomFloorJoinsBytes += Other.RoomFloorJoinsBytes;
            TunnelsBytes += Other.TunnelsBytes;
            PitsBytes += Other.PitsBytes;
            ChimneysBytes += Other.ChimneysBytes;
            ColumnsBytes += Other.ColumnsBytes;
            SupportColumnEntriesBytes += Other.SupportColumnEntriesBytes;
            SupportColumnsBytes += Other.SupportColumnsBytes;
            SupportColumnIntervalsBytes += Other.SupportColumnIntervalsBytes;
            SpatialIndexBytes += Other.SpatialIndexBytes;
            return *this;
        }
    };

    struct FSnapshot
    {
        uint64 Calls[BucketCount]{};
        // Sum of sampled worker time. Useful for CPU-work accounting, but not directly comparable
        // with an export wall clock when the mesher runs in parallel.
        uint64 Cycles[BucketCount]{};
        uint64 Samples[BucketCount]{};
        // Largest estimated worker contribution. This is the report-facing parallel wall
        // estimate; it avoids mistaking several parallel workers for several exports.
        uint64 WallCycles[BucketCount]{};
        uint32 ActiveWorkers[BucketCount]{};
        uint64 Counters[CounterCount]{};

        // Classifier detail is sampled separately from the timer buckets.  Calls is the exact
        // number of classifier invocations; the remaining fields are worker-local samples
        // expanded at Snapshot() using Calls / SampledCalls.
        struct FClassifierStats
        {
            uint64 Calls = 0;
            uint64 SampledCalls = 0;
            uint64 RefineNodes = 0;
            uint64 StackBoxCalls = 0;
            uint64 WholeMixedNodes = 0;
            uint64 WholeSolidNodes = 0;
            uint64 WholeAirNodes = 0;
            uint64 NeedsFinalFieldNodes = 0;
            uint64 SplitNodes = 0;
            uint64 MaxRefinementDepth = 0;
            uint64 ExactCoreSamples = 0;
            uint64 ExactFinalSamples = 0;
            uint64 ExactCoreCacheHits = 0;
            uint64 ExactFinalCacheHits = 0;
            uint64 ExactCoreLeaves = 0;
            uint64 ExactFinalLeaves = 0;
            uint64 StackBoxCycles = 0;
            uint64 ExactCoreCycles = 0;
            uint64 ExactFinalCycles = 0;
            uint64 RoomTailQueries = 0;
            uint64 RoomTailEvaluated = 0;
            uint64 RoomTailCycles = 0;
            uint64 RoomPropagateCycles = 0;
            uint64 RoomExactPrimitiveCycles = 0;
            uint64 RoomCacheWindowCycles = 0;
            uint64 RoomNumRooms = 0;
            uint64 RoomNumTunnels = 0;
            uint64 RoomNumRoomFloorJoins = 0;
            uint64 RoomNumPits = 0;
            uint64 RoomNumChimneys = 0;
        };
        FClassifierStats Classifier;

        uint64 TimerPairCycles = 0;
        uint32 SampleInterval = DefaultSampleInterval;
        EMode Mode = EMode::Disabled;

        // Opt-in worker-cache footprint snapshot.  These are current per-thread values (not
        // allocation-event counters), so Snapshot() reports the resident cache footprint at the
        // end of a profiling run rather than multiplying bytes by cache churn.
        uint64 TunnelCacheWorkers = 0;
        uint64 TunnelCacheCapacityEntries = 0;
        uint64 TunnelCacheValidEntries = 0;
        uint64 TunnelCacheStaticBytes = 0;
        uint64 TunnelCacheDynamicBytes = 0;
        uint64 TunnelCacheEntryBytes = 0;
        uint64 TunnelCacheLargestEntryBytes = 0;
        uint64 TunnelCacheLargestWorkerValidEntries = 0;
        uint64 TunnelCacheLargestWorkerBytes = 0;
        FCacheMemoryBreakdown TunnelCacheBreakdown;

        uint64 RoomGraphCacheWorkers = 0;
        uint64 RoomGraphCacheCapacityEntries = 0;
        uint64 RoomGraphCacheValidEntries = 0;
        uint64 RoomGraphCacheStaticBytes = 0;
        uint64 RoomGraphCacheDynamicBytes = 0;
        uint64 RoomGraphCacheEntryBytes = 0;
        uint64 RoomGraphCacheLargestEntryBytes = 0;
        uint64 RoomGraphCacheLargestWorkerValidEntries = 0;
        uint64 RoomGraphCacheLargestWorkerBytes = 0;
        FCacheMemoryBreakdown RoomGraphCacheBreakdown;
    };

    VOXELFORGE_API void SetMode(EMode Mode, uint32 SampleInterval = DefaultSampleInterval);
    // Counters are collected only while a diagnostic mode is enabled.  In the ordinary clean
    // path this is a single relaxed load, so the measurement hooks stay dormant.
    FORCEINLINE bool IsEnabledFast()
    {
        return GEnabled.load(std::memory_order_relaxed);
    }
    FORCEINLINE bool AreCountersEnabled() { return IsEnabledFast(); }
    FORCEINLINE bool ShouldProbeScopeFast(EBucket Bucket)
    {
        const EMode Mode = GMode.load(std::memory_order_relaxed);
        if (Mode == EMode::Full)
        {
            return true;
        }
        if (Mode == EMode::Sampled)
        {
            return Bucket == EBucket::GetDensityAt
                || Bucket == EBucket::MesherGenerateMesh
                || Bucket == EBucket::MesherDensityGrid
                || Bucket == EBucket::MesherOther;
        }
        if (Mode == EMode::Attribution)
        {
            switch (Bucket)
            {
            case EBucket::GetDensityAt:
            case EBucket::MesherGenerateMesh:
            case EBucket::MesherDensityGrid:
            case EBucket::MesherCellClassification:
            case EBucket::MesherGradientNormals:
            case EBucket::MesherVertexInterpolation:
            case EBucket::MesherStreamBuilding:
            case EBucket::MesherOther:
            case EBucket::RoomGraphBuild:
                return true;
            default:
                return GSampledScopeActive;
            }
        }
        return false;
    }
    VOXELFORGE_API bool IsEnabled();
    VOXELFORGE_API bool IsCycleTimingEnabled();
    VOXELFORGE_API EMode GetMode();
    VOXELFORGE_API uint32 GetSampleInterval();
    VOXELFORGE_API uint64 GetTimerPairCycles();
    VOXELFORGE_API void CalibrateTimer();
    VOXELFORGE_API void Reset();
    VOXELFORGE_API FSnapshot Snapshot();
    // Worker-local snapshot for a tile profile.  GenerateTileResult is single-owner on its worker,
    // so this avoids attributing another worker's concurrent tile to the current tile diagnostic.
    VOXELFORGE_API FSnapshot SnapshotCurrentThread();
    VOXELFORGE_API void AddCounter(ECounter Counter, uint64 Amount = 1);
    VOXELFORGE_API void AddMeasurement(EBucket Bucket, uint64 Cycles, uint64 Calls = 1);
    VOXELFORGE_API void RecordCall(EBucket Bucket);
    VOXELFORGE_API void RecordClassifierCall(bool bSampled);
    VOXELFORGE_API void AddClassifierStats(const FSnapshot::FClassifierStats& Stats);
    VOXELFORGE_API bool ShouldSample(EBucket Bucket);
    VOXELFORGE_API void AddSampledMeasurement(EBucket Bucket, uint64 RawCycles);

    VOXELFORGE_API void SetWorkerTunnelCacheFootprint(
        uint64 CapacityEntries, uint64 ValidEntries,
        uint64 StaticBytes, uint64 DynamicBytes,
        uint64 EntryBytes, uint64 LargestEntryBytes,
        uint64 LargestWorkerValidEntries,
        const FCacheMemoryBreakdown& Breakdown);
    VOXELFORGE_API void SetWorkerRoomGraphCacheFootprint(
        uint64 CapacityEntries, uint64 ValidEntries,
        uint64 StaticBytes, uint64 DynamicBytes,
        uint64 EntryBytes, uint64 LargestEntryBytes,
        uint64 LargestWorkerValidEntries,
        const FCacheMemoryBreakdown& Breakdown);
    VOXELFORGE_API const TCHAR* CounterName(ECounter Counter);
    VOXELFORGE_API EBucket BucketFromName(const TCHAR* Name);
    VOXELFORGE_API const TCHAR* BucketName(EBucket Bucket);

    struct FScopeToken
    {
        bool bEntered;
        bool bSampled;
        bool bBlockTiming;
        bool bPreviousSampled;
        bool bPreviousSampledScopeActive;
        uint64 StartCycles;
    };

    VOXELFORGE_API FScopeToken BeginScope(EBucket Bucket);
    VOXELFORGE_API void EndScope(EBucket Bucket, const FScopeToken& Token);

    class FScopedTimer final
    {
    public:
        explicit FScopedTimer(EBucket InBucket)
        {
            if (IsEnabledFast() && ShouldProbeScopeFast(InBucket))
            {
                Bucket = InBucket;
                Token = BeginScope(InBucket);
                bActive = Token.bEntered;
            }
        }

        explicit FScopedTimer(const TCHAR* InName)
        {
            if (IsEnabledFast())
            {
                Bucket = BucketFromName(InName);
                if (ShouldProbeScopeFast(Bucket))
                {
                    Token = BeginScope(Bucket);
                    bActive = Token.bEntered;
                }
            }
        }

        FORCEINLINE ~FScopedTimer()
        {
            End();
        }

        // End a range before its lexical scope ends.  This lets GetDensityAt split its enclosing
        // total into disjoint prologue/core/post phases without moving the large cache block.
        FORCEINLINE void End()
        {
            if (!bActive)
            {
                return;
            }
            EndScope(Bucket, Token);
            Token.bEntered = false;
            bActive = false;
        }

        FScopedTimer(const FScopedTimer&) = delete;
        FScopedTimer& operator=(const FScopedTimer&) = delete;

    private:
        EBucket Bucket;
        FScopeToken Token;
        bool bActive = false;
    };
}