TransientsTracker.h

//
//  TransientsTracker.h
//  avara3d
//
//  Created by Morgan Davis on 8/11/26.
//  Copyright © 2026 Morgan K Davis. All rights reserved.
//
 
#ifndef AVARA3D_EXTENSION_TRANSIENTTRACKER_H
#define AVARA3D_EXTENSION_TRANSIENTTRACKER_H
 
#include <cstddef>
#include <cstdint>
#include <memory>
#include <optional>
#include <string>
#include <unordered_map>
#include <vector>
 
#include "a3d/Math.h"
#include "a3d/scene/Scene.h"
 
namespace a3d {
 
class Node;
 
} // namespace a3d
 
namespace a3d::ext {
 
class TransientsTracker {
 
public:
    // [Public Types]
 
    struct DistanceLimit {
 
        math::vec3 center {0.0f};
 
        float      radius {0.0f};
    };
 
    struct Policy {
 
        std::optional<std::size_t>   maxCount {};
 
        std::optional<double>        maxAge {};
 
        std::optional<DistanceLimit> distanceLimit {};
    };
 
    struct SweepPolicy {
 
        enum class Mode {
            EveryUpdate,   
            EveryNUpdates, 
            EveryInterval  
        };
 
        Mode               mode {Mode::EveryUpdate};
 
        std::uint64_t      updateInterval {1};
 
        double             timeInterval {0.0};
 
        static SweepPolicy EveryUpdate();
 
        static SweepPolicy EveryNUpdates(std::uint64_t updates);
 
        static SweepPolicy EveryInterval(double seconds);
    };
 
    // [Public Lifecycle Functions]
 
    explicit TransientsTracker(SweepPolicy sweepPolicy = SweepPolicy::EveryUpdate());
 
    TransientsTracker(const TransientsTracker&)            = delete;
    TransientsTracker& operator=(const TransientsTracker&) = delete;
 
    TransientsTracker(TransientsTracker&&)            = delete;
    TransientsTracker& operator=(TransientsTracker&&) = delete;
 
    ~TransientsTracker() = default;
 
    // [Public Member Functions]
 
    void               track(const std::shared_ptr<Node>& node, const std::string& group = {});
 
    void               track(const std::vector<std::shared_ptr<Node>>& nodes, const std::string& group = {});
 
    void               untrack(const Node& node);
 
    const Policy&      policy() const;
 
    void               policy(const Policy& policy);
 
    void               groupPolicy(const std::string& group, const Policy& policy);
 
    const SweepPolicy& sweepPolicy() const;
 
    void               sweepPolicy(const SweepPolicy& policy);
 
    void               update(const Scene::StepInfo& info);
 
    void               sweep(const Scene::StepInfo& info);
 
    void               clear();
 
    void               removeAll();
 
private:
    // [Private Types]
 
    struct Entry {
        std::weak_ptr<Node> node;
        std::string         group;
        double              creationTime {0.0};
    };
 
    // [Private Static Member Functions]
 
    static void validatePolicy(const Policy& policy);
    static void validateSweepPolicy(const SweepPolicy& policy);
    static void detachNodes(const std::vector<std::shared_ptr<Node>>& nodes);
 
    // [Private Member Functions]
 
    void        observeStepInfo(const Scene::StepInfo& info);
    bool        sweepDue(const Scene::StepInfo& info) const;
    void        performSweep(double simulationTime);
 
    bool        shouldRemove(const Entry& entry, const Node& node, double simulationTime) const;
    bool policyRemoves(const Policy& policy, const Entry& entry, const Node& node, double simulationTime) const;
 
    void pruneInactiveEntries();
    void enforceCountLimits(const std::string& group);
    void enforceMaxCount(std::size_t maxCount, const std::string* group);
 
    void resetSweepSchedule();
    void resetRuntimeState();
 
    // [Private Member Variables]
 
    std::vector<Entry>                      _entries;
    Policy                                  _policy;
    std::unordered_map<std::string, Policy> _groupPolicies;
    SweepPolicy                             _sweepPolicy;
    std::uint64_t                           _updatesSinceSweep;
    std::optional<double>                   _simulationTime;
    std::optional<double>                   _nextSweepTime;
};
 
} // namespace a3d::ext
 
#endif // AVARA3D_EXTENSION_TRANSIENTTRACKER_H