fix: close STEP-085 V4 renderer efficiency

include/mbgl/particle/field/field_projection_materialization.hpp

@@ -4,21 +4,22 @@
 #include <mbgl/particle/field/field_data_adapter.hpp>
 
 #include <optional>
+#include <memory>
 
 namespace mbgl::particle {
 
 // Renderer-neutral canonical snapshots. QBIN stays confined to ingress and
 // field Core; renderers receive only the existing canonical field shape.
 struct MaterializedColorProjection {
-    ParticleFieldSnapshot t0;
-    ParticleFieldSnapshot t1;
+    std::shared_ptr<const ParticleFieldSnapshot> t0;
+    std::shared_ptr<const ParticleFieldSnapshot> t1;
     ColorProjectionContentIdentity contentIdentity;
     FieldSampleState sampleState;
 };
 
 struct MaterializedParticleProjection {
-    ParticleFieldSnapshot t0;
-    ParticleFieldSnapshot t1;
+    std::shared_ptr<const ParticleFieldSnapshot> t0;
+    std::shared_ptr<const ParticleFieldSnapshot> t1;
     ParticleProjectionContentIdentity contentIdentity;
     FieldSampleState sampleState;
 };

include/mbgl/particle/renderer_debug_counters.hpp

@@ -0,0 +1,68 @@
+#pragma once
+
+#include <atomic>
+#include <cstddef>
+#include <cstdint>
+
+namespace mbgl::particle {
+
+// Debug/Validation-only cumulative renderer observability. These atomics are
+// intentionally not connected to Host APIs and compile to no-ops in release.
+enum class RendererDebugCounter : uint8_t {
+    WeatherColorNeedsRepaint,
+    ParticleNeedsRepaint,
+    WeatherColorUpdate,
+    ParticleUpdate,
+    ParticleSimulationAdvance,
+    WeatherColorDrawableRebuild,
+    ParticleDrawableRebuild,
+    FieldTextureUpload,
+    GpuResourceCreate,
+    GpuResourceRelease,
+    TrailTargetCreateOrResize,
+    V4ProjectionMaterialize,
+    FieldWindowRevision,
+    Count,
+};
+
+#ifndef NDEBUG
+struct RendererDebugCounterSnapshot {
+    uint64_t weatherColorNeedsRepaint = 0;
+    uint64_t particleNeedsRepaint = 0;
+    uint64_t weatherColorUpdate = 0;
+    uint64_t particleUpdate = 0;
+    uint64_t particleSimulationAdvance = 0;
+    uint64_t weatherColorDrawableRebuild = 0;
+    uint64_t particleDrawableRebuild = 0;
+    uint64_t fieldTextureUpload = 0;
+    uint64_t gpuResourceCreate = 0;
+    uint64_t gpuResourceRelease = 0;
+    uint64_t trailTargetCreateOrResize = 0;
+    uint64_t v4ProjectionMaterialize = 0;
+    uint64_t fieldWindowRevision = 0;
+};
+
+inline std::atomic_uint64_t* rendererDebugCounterStorage() {
+    static std::atomic_uint64_t counters[static_cast<size_t>(RendererDebugCounter::Count)]{};
+    return counters;
+}
+
+inline void incrementRendererDebugCounter(const RendererDebugCounter counter) {
+    rendererDebugCounterStorage()[static_cast<size_t>(counter)].fetch_add(1, std::memory_order_relaxed);
+}
+
+inline RendererDebugCounterSnapshot rendererDebugCounterSnapshot() {
+    const auto* values = rendererDebugCounterStorage();
+    return {values[0].load(std::memory_order_relaxed), values[1].load(std::memory_order_relaxed),
+            values[2].load(std::memory_order_relaxed), values[3].load(std::memory_order_relaxed),
+            values[4].load(std::memory_order_relaxed), values[5].load(std::memory_order_relaxed),
+            values[6].load(std::memory_order_relaxed), values[7].load(std::memory_order_relaxed),
+            values[8].load(std::memory_order_relaxed), values[9].load(std::memory_order_relaxed),
+            values[10].load(std::memory_order_relaxed), values[11].load(std::memory_order_relaxed),
+            values[12].load(std::memory_order_relaxed)};
+}
+#else
+inline void incrementRendererDebugCounter(RendererDebugCounter) {}
+#endif
+
+} // namespace mbgl::particle

include/mbgl/style/sources/raster_array_source.hpp

@@ -65,6 +65,24 @@ struct RasterArrayCadenceAdvance {
     bool advanced = false;
 };
 
+// A backend-neutral cadence gate for renderer-owned visual simulation. Unlike
+// the legacy timeline it has no field entries and never advances forecast
+// time; Android/iOS may merely request a future MapLibre frame at its deadline.
+class RasterArrayRendererCadence final {
+public:
+    bool consumeIfDue(std::chrono::steady_clock::time_point);
+    bool cadenceDue(std::chrono::steady_clock::time_point) const;
+    void setTargetFps(RasterArrayTargetFps);
+    RasterArrayTargetFps targetFps() const;
+    uint64_t revision() const;
+
+private:
+    mutable std::mutex mutex;
+    RasterArrayTargetFps targetFps_ = RasterArrayTargetFps::Auto;
+    std::chrono::steady_clock::time_point lastTick{};
+    uint64_t revision_ = 0;
+};
+
 // Source-owned playback state. Android only sends low-frequency commands;
 // render frames obtain an immutable T0/T1 pair and scalar mix from Core.
 class RasterArrayTimelineRuntime {