react-native-cesium 1.0.6 → 1.2.0

package/android/src/main/java/com/margelo/nitro/reactnativecesium/HybridCesiumView.kt

@@ -1,6 +1,10 @@
 package com.margelo.nitro.reactnativecesium
 
 import android.content.Context
+import android.os.Handler
+import android.os.HandlerThread
+import android.os.Process
+import android.util.Log
 import android.view.Choreographer
 import android.view.SurfaceHolder
 import android.view.SurfaceView
@@ -8,28 +12,53 @@ import android.view.View
 import com.margelo.nitro.core.Promise
 import java.io.File
 import java.io.FileOutputStream
+import java.util.concurrent.atomic.AtomicBoolean
 
 class HybridCesiumView(private val appContext: Context) : HybridCesiumViewSpec() {
   private val surfaceView = SurfaceView(appContext)
-  private var bridge: CesiumBridgeJNI? = null
+  /// Bridge is only ever read on the render thread. The UI thread posts
+  /// requests via `renderHandler`. Marked volatile so init/shutdown observers
+  /// (`bridge != null`) on the UI thread see the latest reference, but real
+  /// work is always serialized through the render thread.
+  @Volatile private var bridge: CesiumBridgeJNI? = null
   private var metricsFrameCounter = 0
   private var idleProbeAccumulator = 0.0
-  private var usingLowRefreshRate = false
   private var lastFrameTimeNanos = 0L
+  /// Last-pushed camera state — read/written on the render thread (via
+  /// `renderHandler.post`), never directly on the UI thread.
   private var lastPushedCamera: CameraState? = null
   private var lastPushedViewCorrection: Quaternion? = null
+  /// Camera state requested by `setCamera` before the bridge was ready.
+  /// Updated on the UI thread, drained on the render thread.
+  @Volatile private var pendingRuntimeCamera: CameraState? = null
+  @Volatile private var pendingRuntimeViewCorrection: Quaternion? = null
+  /// True while a Choreographer frame callback is pending. Mutated on the UI
+  /// thread inside the callback / scheduleNextFrame.
   private var renderLoopActive = false
+  /// Drops Choreographer ticks while the render thread is still finishing the
+  /// previous frame. Set on UI thread when posting; cleared on render thread
+  /// after the bridge call completes.
+  private val renderInFlight = AtomicBoolean(false)
+
+  /// Dedicated render thread — owns all CesiumEngine + GPU work. Created lazily
+  /// when the first SurfaceHolder.Callback fires. The Choreographer (UI thread)
+  /// posts render requests here; bridge config setters likewise post here so
+  /// they serialize with rendering and never race with engine state.
+  private var renderThread: HandlerThread? = null
+  private var renderHandler: Handler? = null
 
   override var ionAccessToken: String = ""
     set(value) {
       field = value
-      bridge?.updateIonAccessToken(value, ionAssetId.toLong())
+      val assetId = ionAssetId.toLong()
+      postToRender { bridge?.updateIonAccessToken(value, assetId) }
     }
 
   override var ionAssetId: Double = 1.0
     set(value) {
       field = value
-      bridge?.updateIonAccessToken(ionAccessToken, value.toLong())
+      val token = ionAccessToken
+      postToRender { bridge?.updateIonAccessToken(token, value.toLong()) }
     }
 
   override var initialCamera: CameraState = CameraState(
@@ -46,25 +75,51 @@ class HybridCesiumView(private val appContext: Context) : HybridCesiumViewSpec()
     set(value) {
       field = value
       if (!value) {
-        bridge?.markNeedsRender()
-        scheduleNextFrame()
+        postToRender { bridge?.markNeedsRender() }
+        scheduleNextFrame(immediate = true)
       }
     }
 
   override var maximumScreenSpaceError: Double = 32.0
-    set(value) { field = value; bridge?.setMaxSSE(value) }
+    set(value) { field = value; postToRender { bridge?.setMaxSSE(value) } }
 
   override var maximumSimultaneousTileLoads: Double = 12.0
-    set(value) { field = value; bridge?.setMaxSimLoads(value.toInt()) }
+    set(value) { field = value; postToRender { bridge?.setMaxSimLoads(value.toInt()) } }
 
   override var loadingDescendantLimit: Double = 20.0
-    set(value) { field = value; bridge?.setLoadDescLim(value.toInt()) }
+    set(value) { field = value; postToRender { bridge?.setLoadDescLim(value.toInt()) } }
 
   override var msaaSampleCount: Double = 1.0
-    set(value) { field = value; bridge?.setMsaa(value.toInt()) }
+    set(value) { field = value; postToRender { bridge?.setMsaa(value.toInt()) } }
 
   override var ionImageryAssetId: Double = 1.0
-    set(value) { field = value; bridge?.updateImageryAssetId(value.toLong()) }
+    set(value) { field = value; postToRender { bridge?.updateImageryAssetId(value.toLong()) } }
+
+  // ── Optional perf / quality knobs ────────────────────────────────────────
+  override var maximumCachedMiB: Double? = null
+    set(value) { field = value; if (value != null) postToRender { bridge?.setMaximumCachedMiB(value.toInt()) } }
+  override var preloadAncestors: Boolean? = null
+    set(value) { field = value; if (value != null) postToRender { bridge?.setPreloadAncestors(value) } }
+  override var preloadSiblings: Boolean? = null
+    set(value) { field = value; if (value != null) postToRender { bridge?.setPreloadSiblings(value) } }
+  override var forbidHoles: Boolean? = null
+    set(value) { field = value; if (value != null) postToRender { bridge?.setForbidHoles(value) } }
+  override var enableWaterMask: Boolean? = null
+    set(value) { field = value; if (value != null) postToRender { bridge?.setEnableWaterMask(value) } }
+  override var enableFogCulling: Boolean? = null
+    set(value) { field = value; if (value != null) postToRender { bridge?.setEnableFogCulling(value) } }
+  override var enforceCulledScreenSpaceError: Boolean? = null
+    set(value) { field = value; if (value != null) postToRender { bridge?.setEnforceCulledScreenSpaceError(value) } }
+  override var culledScreenSpaceError: Double? = null
+    set(value) { field = value; if (value != null) postToRender { bridge?.setCulledScreenSpaceError(value) } }
+  override var enableLodTransitionPeriod: Boolean? = null
+    set(value) { field = value; if (value != null) postToRender { bridge?.setEnableLodTransitionPeriod(value) } }
+  override var lodTransitionLength: Double? = null
+    set(value) { field = value; if (value != null) postToRender { bridge?.setLodTransitionLength(value) } }
+  override var sqliteCacheMaxRows: Double? = null
+    set(value) { field = value; if (value != null) postToRender { bridge?.setSqliteCacheMaxRows(value.toInt()) } }
+  override var taskProcessorThreads: Double? = null
+    set(value) { field = value; if (value != null) postToRender { bridge?.setTaskProcessorThreads(value.toInt()) } }
 
   override var onMetrics: ((metrics: CesiumMetrics) -> Unit)? = null
 
@@ -72,7 +127,9 @@ class HybridCesiumView(private val appContext: Context) : HybridCesiumViewSpec()
 
   private val frameCallback = Choreographer.FrameCallback { frameTimeNanos ->
     renderLoopActive = false
-    if (pauseRendering || bridge == null) return@FrameCallback
+    if (pauseRendering || bridge == null) {
+      return@FrameCallback
+    }
 
     val dt = if (lastFrameTimeNanos > 0) {
       (frameTimeNanos - lastFrameTimeNanos).coerceAtLeast(1_000_000L) / 1_000_000_000.0
@@ -81,37 +138,71 @@ class HybridCesiumView(private val appContext: Context) : HybridCesiumViewSpec()
     }
     lastFrameTimeNanos = frameTimeNanos
 
-    val shouldRender = bridge?.shouldRenderNextFrame() ?: false
+    // Drop the tick if the previous frame's render hasn't finished — keeps the
+    // render thread from queuing up an unbounded backlog under stutter.
+    if (!renderInFlight.compareAndSet(false, true)) {
+      // Re-arm so we try again next vsync.
+      scheduleNextFrame(immediate = true)
+      return@FrameCallback
+    }
+
+    val rh = renderHandler
+    if (rh == null) {
+      renderInFlight.set(false)
+      return@FrameCallback
+    }
+    rh.post { runFrameOnRenderThread(dt) }
+  }
+
+  /// Called on the render thread. Owns ALL CesiumEngine + GPU access; the UI
+  /// thread only signals demand here. Safe to read `onMetrics` because Nitro
+  /// callbacks dispatch internally to the JS thread.
+  private fun runFrameOnRenderThread(dt: Double) {
+    val b = bridge
+    if (b == null) {
+      renderInFlight.set(false)
+      return
+    }
+
+    val shouldRender = b.shouldRenderNextFrame()
+    val nextImmediate: Boolean
     if (shouldRender) {
-      usingLowRefreshRate = false
       idleProbeAccumulator = 0.0
-      bridge?.renderFrame(dt)
+      b.renderFrame(dt)
+      nextImmediate = true
     } else {
-      usingLowRefreshRate = true
       idleProbeAccumulator += dt
       if (idleProbeAccumulator >= 0.25) {
         idleProbeAccumulator = 0.0
-        bridge?.markNeedsRender()
+        b.markNeedsRender()
       }
+      nextImmediate = false
     }
 
     metricsFrameCounter++
     if (metricsFrameCounter >= 20) {
       metricsFrameCounter = 0
-      val b = bridge ?: return@FrameCallback
-      val cb = onMetrics ?: return@FrameCallback
-      cb(CesiumMetrics(
-        fps = b.getMetricsFps(),
-        tilesRendered = b.getMetricsTilesRendered().toDouble(),
-        tilesLoading = b.getMetricsTilesLoading().toDouble(),
-        tilesVisited = b.getMetricsTilesVisited().toDouble(),
-        ionTokenConfigured = b.getMetricsIonTokenConfigured(),
-        tilesetReady = b.getMetricsTilesetReady(),
-        creditsPlainText = b.getMetricsCreditsPlainText(),
-      ))
+      val cb = onMetrics
+      if (cb != null) {
+        cb(CesiumMetrics(
+          fps = b.getMetricsFps(),
+          tilesRendered = b.getMetricsTilesRendered().toDouble(),
+          tilesLoading = b.getMetricsTilesLoading().toDouble(),
+          tilesVisited = b.getMetricsTilesVisited().toDouble(),
+          ionTokenConfigured = b.getMetricsIonTokenConfigured(),
+          tlsConfigured = b.getMetricsTlsConfigured(),
+          tilesetReady = b.getMetricsTilesetReady(),
+          creditsPlainText = b.getMetricsCreditsPlainText(),
+        ))
+      }
     }
 
-    scheduleNextFrame()
+    renderInFlight.set(false)
+
+    // Re-arm on the UI thread so Choreographer remains the source of truth
+    // for vsync timing. Posting a no-op runnable to surfaceView keeps us off
+    // the render thread for that small piece of bookkeeping.
+    surfaceView.post { scheduleNextFrame(immediate = nextImmediate) }
   }
 
   private val surfaceCallback = object : SurfaceHolder.Callback {
@@ -121,35 +212,109 @@ class HybridCesiumView(private val appContext: Context) : HybridCesiumViewSpec()
       val h = surfaceView.height
       if (w <= 0 || h <= 0) return
 
-      val b = CesiumBridgeJNI()
+      // Spin up the render thread on first surfaceCreated. If we previously
+      // tore it down (e.g. on backgrounding), re-spawn cleanly.
+      ensureRenderThread()
+      val rh = renderHandler ?: return
+
       val cacheDir = appContext.cacheDir.absolutePath
       val cacertPath = extractCacert()
-      b.init(surface, w, h, cacheDir, cacertPath)
-      bridge = b
+      // Init runs on the render thread because Vulkan instance/device creation
+      // and Cesium Native init both touch state we'd rather only ever poke
+      // from one thread.
+      rh.post {
+        val b = CesiumBridgeJNI()
+        b.init(surface, w, h, cacheDir, cacertPath)
+        bridge = b
+        syncBridgePropsOnRenderThread(b)
+
+        b.updateCamera(
+          initialCamera.latitude, initialCamera.longitude, initialCamera.altitude,
+          initialCamera.heading, initialCamera.pitch, initialCamera.roll,
+        )
+        b.setVerticalFovDeg(initialCamera.verticalFovDeg)
+        lastPushedCamera = initialCamera
+
+        val pending = pendingRuntimeCamera
+        if (pending != null) {
+          val q = pendingRuntimeViewCorrection
+          if (q != null) {
+            b.updateCameraQuaternion(
+              pending.latitude, pending.longitude, pending.altitude,
+              pending.heading, pending.pitch, pending.roll,
+              q.w, q.x, q.y, q.z,
+            )
+            lastPushedViewCorrection = q
+          } else {
+            b.updateCamera(
+              pending.latitude, pending.longitude, pending.altitude,
+              pending.heading, pending.pitch, pending.roll,
+            )
+          }
+          b.setVerticalFovDeg(pending.verticalFovDeg)
+          lastPushedCamera = pending
+        }
 
-      syncPropsTobridge()
-      if (ionAccessToken.isNotEmpty()) {
-        b.updateIonAccessToken(ionAccessToken, ionAssetId.toLong())
-      }
-      pushCameraIfChanged(initialCamera)
-      if (ionImageryAssetId != 1.0) {
-        b.updateImageryAssetId(ionImageryAssetId.toLong())
-      }
-      b.setMsaa(msaaSampleCount.toInt())
+        if (ionAccessToken.isNotEmpty()) {
+          b.updateIonAccessToken(ionAccessToken, ionAssetId.toLong())
+        }
+        if (ionImageryAssetId != 1.0) {
+          b.updateImageryAssetId(ionImageryAssetId.toLong())
+        }
+        b.setMsaa(msaaSampleCount.toInt())
 
-      lastFrameTimeNanos = 0L
-      scheduleNextFrame()
+        // Start the rendering loop here, after the bridge is fully
+        // initialized. scheduleNextFrame must be invoked on the UI thread
+        // because Choreographer.postFrameCallback() requires it.
+        surfaceView.post { scheduleNextFrame(immediate = true) }
+      }
     }
 
     override fun surfaceChanged(holder: SurfaceHolder, format: Int, width: Int, height: Int) {
-      bridge?.resize(width, height)
-      bridge?.markNeedsRender()
+      postToRender {
+        bridge?.resize(width, height)
+        bridge?.markNeedsRender()
+        // Re-arm the loop in case surfaceChanged fires before the bridge was
+        // created (rare, but possible on cold starts). Idempotent: scheduleNextFrame
+        // early-returns if the loop is already active.
+        surfaceView.post { scheduleNextFrame(immediate = true) }
+      }
     }
 
     override fun surfaceDestroyed(holder: SurfaceHolder) {
-      bridge?.shutdown()
-      bridge?.destroy()
-      bridge = null
+      val rh = renderHandler
+      val ht = renderThread
+
+      if (rh == null || ht == null) {
+        // Nothing to drain; clear bridge reference if it somehow exists.
+        bridge?.shutdown()
+        bridge?.destroy()
+        bridge = null
+        return
+      }
+
+      // Block the UI thread (briefly) until the render thread has shut the
+      // bridge down — surfaceDestroyed contract requires the surface to be
+      // released before this returns. We cap our wait so a stuck GPU teardown
+      // can't hang the UI thread indefinitely (matches our 1s shutdown
+      // semaphore policy on the Vulkan / Metal side).
+      val done = java.util.concurrent.CountDownLatch(1)
+      rh.post {
+        try {
+          bridge?.shutdown()
+          bridge?.destroy()
+        } catch (t: Throwable) {
+          Log.w("CesiumView", "render-thread shutdown threw", t)
+        } finally {
+          bridge = null
+          done.countDown()
+        }
+      }
+      if (!done.await(1500, java.util.concurrent.TimeUnit.MILLISECONDS)) {
+        Log.w("CesiumView", "Render-thread shutdown did not complete in 1.5s; "
+                + "tearing down handler thread anyway.")
+      }
+      stopRenderThread()
     }
   }
 
@@ -157,6 +322,37 @@ class HybridCesiumView(private val appContext: Context) : HybridCesiumViewSpec()
     surfaceView.holder.addCallback(surfaceCallback)
   }
 
+  // ── Render-thread helpers ────────────────────────────────────────────────
+
+  private fun ensureRenderThread() {
+    if (renderThread != null) return
+    val ht = HandlerThread("CesiumRender", Process.THREAD_PRIORITY_DISPLAY)
+    ht.start()
+    renderHandler = Handler(ht.looper)
+    renderThread = ht
+  }
+
+  private fun stopRenderThread() {
+    val ht = renderThread ?: return
+    renderHandler = null
+    renderThread = null
+    ht.quitSafely()
+  }
+
+  /// Posts an action to the render thread. When the render thread isn't
+  /// running yet (early prop assignment, or after teardown), we silently drop
+  /// the action — bridges always take their initial config from the
+  /// `syncBridgePropsOnRenderThread` step inside surfaceCreated.
+  private fun postToRender(action: () -> Unit) {
+    renderHandler?.post(action)
+  }
+
+  /// Camera reads cross the JNI from the JS thread (Nitro promise resolution).
+  /// They read snapshot scalar values through CesiumBridgeAndroid → engine →
+  /// GlobeCamera, none of which is mutated outside the render thread, so the
+  /// worst that can happen is observing a value from a frame slightly behind
+  /// what the render thread is encoding right now — acceptable for a UI-driven
+  /// camera read.
   override fun getCameraState(): Promise<CameraState> {
     val b = bridge ?: return Promise.resolved(initialCamera)
     return Promise.resolved(CameraState(
@@ -171,13 +367,25 @@ class HybridCesiumView(private val appContext: Context) : HybridCesiumViewSpec()
   }
 
   override fun setCamera(camera: CameraState) {
-    initialCamera = camera
-    pushCameraIfChanged(camera)
+    // Runtime camera control. Does NOT mutate `initialCamera` (which is
+    // construction-time only).
+    pendingRuntimeCamera = camera
+    pendingRuntimeViewCorrection = null
+    postToRender {
+      pushCameraIfChanged(camera)
+      bridge?.markNeedsRender()
+    }
+    scheduleNextFrame(immediate = true)
   }
 
   override fun setCameraQuaternion(camera: CameraState, viewCorrection: Quaternion) {
-    initialCamera = camera
-    pushCameraQuaternionIfChanged(camera, viewCorrection)
+    pendingRuntimeCamera = camera
+    pendingRuntimeViewCorrection = viewCorrection
+    postToRender {
+      pushCameraQuaternionIfChanged(camera, viewCorrection)
+      bridge?.markNeedsRender()
+    }
+    scheduleNextFrame(immediate = true)
   }
 
   override fun getViewCorrection(): Promise<Quaternion> {
@@ -248,16 +456,45 @@ class HybridCesiumView(private val appContext: Context) : HybridCesiumViewSpec()
     b.setVerticalFovDeg(camera.verticalFovDeg)
   }
 
-  private fun syncPropsTobridge() {
-    bridge?.setMaxSSE(maximumScreenSpaceError)
-    bridge?.setMaxSimLoads(maximumSimultaneousTileLoads.toInt())
-    bridge?.setLoadDescLim(loadingDescendantLimit.toInt())
+  /// Run on the render thread immediately after the bridge is created, before
+  /// the first frame. Matches Swift's syncBridgeOptionsFromProps and pushes
+  /// every prop into the freshly-built CesiumEngine so the consumer doesn't
+  /// have to re-set them after the surface comes up.
+  private fun syncBridgePropsOnRenderThread(b: CesiumBridgeJNI) {
+    b.setMaxSSE(maximumScreenSpaceError)
+    b.setMaxSimLoads(maximumSimultaneousTileLoads.toInt())
+    b.setLoadDescLim(loadingDescendantLimit.toInt())
+    maximumCachedMiB?.let { b.setMaximumCachedMiB(it.toInt()) }
+    preloadAncestors?.let { b.setPreloadAncestors(it) }
+    preloadSiblings?.let { b.setPreloadSiblings(it) }
+    forbidHoles?.let { b.setForbidHoles(it) }
+    enableWaterMask?.let { b.setEnableWaterMask(it) }
+    enableFogCulling?.let { b.setEnableFogCulling(it) }
+    enforceCulledScreenSpaceError?.let { b.setEnforceCulledScreenSpaceError(it) }
+    culledScreenSpaceError?.let { b.setCulledScreenSpaceError(it) }
+    enableLodTransitionPeriod?.let { b.setEnableLodTransitionPeriod(it) }
+    lodTransitionLength?.let { b.setLodTransitionLength(it) }
+    sqliteCacheMaxRows?.let { b.setSqliteCacheMaxRows(it.toInt()) }
+    taskProcessorThreads?.let { b.setTaskProcessorThreads(it.toInt()) }
   }
 
-  private fun scheduleNextFrame() {
+  /**
+   * Schedule the next frame callback.
+   *
+   * - `immediate = true`: the engine wants to render this vsync (active pan,
+   *   tile loading, prop change). Re-post on the next available vsync.
+   * - `immediate = false`: the engine is idle. Re-post in 250ms — matches the
+   *   iOS low-refresh range and keeps the main thread mostly asleep while
+   *   still picking up late tile completions / network responses.
+   */
+  private fun scheduleNextFrame(immediate: Boolean) {
     if (renderLoopActive || pauseRendering || bridge == null) return
     renderLoopActive = true
-    Choreographer.getInstance().postFrameCallback(frameCallback)
+    if (immediate) {
+      Choreographer.getInstance().postFrameCallback(frameCallback)
+    } else {
+      Choreographer.getInstance().postFrameCallbackDelayed(frameCallback, 250L)
+    }
   }
 
   private fun extractCacert(): String {

package/cpp/engine/CameraSmoother.cpp

@@ -0,0 +1,99 @@
+#include "CameraSmoother.hpp"
+
+#include "EngineTunables.hpp"
+
+#include <algorithm>
+#include <cmath>
+
+namespace reactnativecesium {
+
+namespace {
+
+inline double lerpAngleDeg(double a, double b, double t) {
+  // Wraps difference to [-180, 180] before applying the mix factor so we
+  // always rotate the short way around the unit circle.
+  double diff = std::fmod(b - a + 540.0, 360.0) - 180.0;
+  return a + diff * t;
+}
+
+inline double angleDeltaAbsDeg(double a, double b) {
+  return std::abs(std::fmod(b - a + 540.0, 360.0) - 180.0);
+}
+
+inline double quatDotAbs(const glm::dquat& a, const glm::dquat& b) {
+  return std::abs(glm::dot(glm::normalize(a), glm::normalize(b)));
+}
+
+inline double wrapLonDeltaDeg(double a, double b) {
+  return std::fmod(b - a + 540.0, 360.0) - 180.0;
+}
+
+} // namespace
+
+CameraParams CameraSmoother::step(
+    const CameraParams& current, const CameraParams& target, double dt,
+    double recentIntervalSec) {
+  CameraParams next = current;
+
+  // ── lat/lon: adaptive exponential smoothing ─────────────────────────────
+  // τ scales with the cadence of incoming setCamera calls so gestures feel
+  // instant (τ at the floor) while sparse GPS-rate updates ease across each
+  // interval (τ near the ceiling).
+  const double tau  = std::clamp(
+      tunables::kSmoothPositionAlpha * recentIntervalSec,
+      tunables::kSmoothPositionTauMin,
+      tunables::kSmoothPositionTauMax);
+  const double aPos = 1.0 - std::exp(-dt / tau);
+
+  const double dLat = target.latitude - current.latitude;
+  const double dLon = wrapLonDeltaDeg(current.longitude, target.longitude);
+  const bool snapThrough =
+      std::abs(dLat) > tunables::kPosSnapThroughDeg ||
+      std::abs(dLon) > tunables::kPosSnapThroughDeg;
+
+  if (snapThrough) {
+    next.latitude  = target.latitude;
+    next.longitude = target.longitude;
+  } else {
+    next.latitude  = current.latitude + aPos * dLat;
+    next.longitude = lerpAngleDeg(current.longitude, target.longitude, aPos);
+  }
+
+  const double aAlt   = 1.0 - std::exp(-tunables::kSmoothAltitude * dt);
+  const double aHdg   = 1.0 - std::exp(-tunables::kSmoothHeading  * dt);
+  const double aPitch = 1.0 - std::exp(-tunables::kSmoothPitch    * dt);
+  const double aRoll  = 1.0 - std::exp(-tunables::kSmoothRoll     * dt);
+  const double aViewQ = 1.0 - std::exp(-tunables::kSmoothViewCorr * dt);
+
+  next.altitude = current.altitude + aAlt * (target.altitude - current.altitude);
+  next.heading  = lerpAngleDeg(current.heading, target.heading, aHdg);
+  next.pitch    = lerpAngleDeg(current.pitch,   target.pitch,   aPitch);
+  next.roll     = lerpAngleDeg(current.roll,    target.roll,    aRoll);
+
+  glm::dquat cq = glm::normalize(current.viewCorrection);
+  glm::dquat tq = glm::normalize(target.viewCorrection);
+  if (glm::dot(cq, tq) < 0.0) tq = -tq;
+  next.viewCorrection = glm::normalize(glm::slerp(cq, tq, aViewQ));
+
+  // Eventually-exact convergence: snap once the residual is sub-epsilon.
+  if (std::abs(target.latitude - next.latitude) <= tunables::kEpsLatLon)
+    next.latitude = target.latitude;
+  if (std::abs(wrapLonDeltaDeg(next.longitude, target.longitude))
+        <= tunables::kEpsLatLon)
+    next.longitude = target.longitude;
+  if (std::abs(target.altitude - next.altitude) <= tunables::kEpsAltitudeMeters)
+    next.altitude = target.altitude;
+  if (angleDeltaAbsDeg(next.heading, target.heading) <= tunables::kEpsAngleDeg)
+    next.heading = target.heading;
+  if (angleDeltaAbsDeg(next.pitch, target.pitch) <= tunables::kEpsAngleDeg)
+    next.pitch = target.pitch;
+  if (angleDeltaAbsDeg(next.roll, target.roll) <= tunables::kEpsAngleDeg)
+    next.roll = target.roll;
+  if ((1.0 - quatDotAbs(next.viewCorrection, target.viewCorrection))
+        <= tunables::kEpsQuatDot)
+    next.viewCorrection = target.viewCorrection;
+
+  return next;
+}
+
+} // namespace reactnativecesium

package/cpp/engine/CameraSmoother.hpp

@@ -0,0 +1,29 @@
+#pragma once
+
+#include "GlobeCamera.hpp"
+
+namespace reactnativecesium {
+
+// Stateless helper. Given a current camera state and a target camera state,
+// returns the next camera state for a frame of duration `dt` seconds.
+//
+// Per-DoF smoothing rules:
+//   - lat / lon: adaptive exponential smoothing `1 - exp(-dt/τ)` where
+//     τ = clamp(α · recentIntervalSec, τmin, τmax). High update rates (60 Hz
+//     gestures) drive τ to the floor so the camera tracks the finger without
+//     perceptible lag; sparse updates (1 Hz GPS) widen τ so each sample
+//     interpolates smoothly across its interval. Snap-through guard for
+//     genuine teleports keeps cross-planet `setCamera` jumps instant.
+//   - altitude / heading / pitch / roll / viewCorrection: exponential decay
+//     `1 - exp(-k * dt)` per DoF with k taken from EngineTunables.
+//   - When the delta drops below the matching epsilon, the value is snapped
+//     to the target so we eventually reach exact equality.
+class CameraSmoother {
+public:
+  static CameraParams step(const CameraParams& current,
+                           const CameraParams& target,
+                           double dt,
+                           double recentIntervalSec);
+};
+
+} // namespace reactnativecesium

package/cpp/engine/CameraTargetState.cpp

@@ -0,0 +1,49 @@
+#include "CameraTargetState.hpp"
+
+#include <cmath>
+
+namespace reactnativecesium {
+
+namespace {
+inline double angleDeltaAbsDeg(double a, double b) {
+  return std::abs(std::fmod(b - a + 540.0, 360.0) - 180.0);
+}
+inline double quatDotAbs(const glm::dquat& a, const glm::dquat& b) {
+  return std::abs(glm::dot(glm::normalize(a), glm::normalize(b)));
+}
+} // namespace
+
+bool CameraTargetState::deltaExceedsEpsilon(
+    const CameraParams& a, const CameraParams& b) {
+  return std::abs(a.latitude  - b.latitude)  > tunables::kEpsLatLon
+      || std::abs(a.longitude - b.longitude) > tunables::kEpsLatLon
+      || std::abs(a.altitude  - b.altitude)  > tunables::kEpsAltitudeMeters
+      || angleDeltaAbsDeg(a.heading, b.heading) > tunables::kEpsAngleDeg
+      || angleDeltaAbsDeg(a.pitch,   b.pitch)   > tunables::kEpsAngleDeg
+      || angleDeltaAbsDeg(a.roll,    b.roll)    > tunables::kEpsAngleDeg
+      || (1.0 - quatDotAbs(a.viewCorrection, b.viewCorrection))
+             > tunables::kEpsQuatDot;
+}
+
+void CameraTargetState::noteUpdateCadence() noexcept {
+  const auto now = std::chrono::steady_clock::now();
+  if (!hasLastUpdate_) {
+    // Seed the EWMA with τmax so the first sample after a quiet period uses
+    // the full smoothing budget rather than the floor (5 ms ≈ snap).
+    ewmaIntervalSec_.store(tunables::kSmoothPositionTauMax / tunables::kSmoothPositionAlpha,
+                           std::memory_order_release);
+    lastUpdateTime_ = now;
+    hasLastUpdate_  = true;
+    return;
+  }
+
+  const double dt = std::chrono::duration<double>(now - lastUpdateTime_).count();
+  lastUpdateTime_ = now;
+  if (dt <= 0.0) return; // back-to-back writes from the same frame: ignore.
+
+  const double prev = ewmaIntervalSec_.load(std::memory_order_relaxed);
+  const double next = prev + tunables::kEwmaIntervalAlpha * (dt - prev);
+  ewmaIntervalSec_.store(next, std::memory_order_release);
+}
+
+} // namespace reactnativecesium