Transients.h

//
//  Transients.h
//  avara3d
//
//  Created by Morgan Davis on 8/11/26.
//  Copyright © 2026 Morgan K Davis. All rights reserved.
//
 
#ifndef AVARA3D_EXTENSION_TRANSIENTS_H
#define AVARA3D_EXTENSION_TRANSIENTS_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::ext {
 
    class Transients {
 
    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 Transients(SweepPolicy sweepPolicy = SweepPolicy::EveryUpdate());
 
        Transients(const Transients&)            = delete;
        Transients& operator=(const Transients&) = delete;
 
        Transients(Transients&&)            = delete;
        Transients& operator=(Transients&&) = delete;
 
        ~Transients() = 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;
    };
 
}
 
#endif // AVARA3D_EXTENSION_TRANSIENTS_H