react-native-cesium 1.2.2 → 1.2.4

package/ios/HybridCesiumView.swift

@@ -2,8 +2,18 @@ import Foundation
 import Metal
 import MetalKit
 import NitroModules
+import QuartzCore
 import UIKit
 
+/// Weak proxy for CADisplayLink so the timer does not strongly retain its
+/// owning view. Without this, CADisplayLink → HybridCesiumView → displayLink
+/// forms a cycle that prevents `deinit` from ever firing, which in turn
+/// prevents the C++ engine and SqliteCache handle from being released.
+private final class DisplayLinkProxy {
+  weak var owner: HybridCesiumView?
+  @objc func tick() { owner?.handleDisplayLinkTick() }
+}
+
 class HybridCesiumView: HybridCesiumViewSpec {
   // MARK: - Props
 
@@ -22,9 +32,9 @@ class HybridCesiumView: HybridCesiumViewSpec {
     }
   }
 
-  /// Construction-time seed camera. Used exactly once when the native bridge
-  /// is created; subsequent prop writes are ignored. Use `setCamera(_:)` to
-  /// drive the camera at runtime — it does NOT mutate this value.
+  /// Construction-time seed camera. Used exactly once via `teleport(...)`
+  /// when the native bridge is created; subsequent prop writes are ignored.
+  /// Use the per-DoF setters (or `teleport(...)`) for runtime updates.
   var initialCamera: CameraState = CameraState(
     latitude: 46.15,
     longitude: 7.35,
@@ -55,7 +65,6 @@ class HybridCesiumView: HybridCesiumViewSpec {
   var msaaSampleCount: Double = 1 {
     didSet {
       let s = Int32(msaaSampleCount)
-      // applyMtkViewMsaa touches MTKView/UIKit so it stays on main.
       applyMtkViewMsaa(Int(s))
       postToRender { [weak self] in self?.bridge?.setMsaaSampleCount(s) }
     }
@@ -105,12 +114,31 @@ class HybridCesiumView: HybridCesiumViewSpec {
     didSet { if let v = minAltitudeAboveTerrain { postToRender { [weak self] in self?.bridge?.setMinAltitudeAboveTerrain(Float(v)) } } }
   }
 
+  // ── Rate caps ────────────────────────────────────────────────────────────
+  var maxYawRateDegSec: Double?   { didSet { pushRateCaps() } }
+  var maxPitchRateDegSec: Double? { didSet { pushRateCaps() } }
+  var maxRollRateDegSec: Double?  { didSet { pushRateCaps() } }
+  var maxClimbRateMps: Double?    { didSet { pushRateCaps() } }
+  var maxGroundSpeedMps: Double?  { didSet { pushRateCaps() } }
+
+  private func pushRateCaps() {
+    let yaw   = maxYawRateDegSec ?? 0
+    let pitch = maxPitchRateDegSec ?? 0
+    let roll  = maxRollRateDegSec ?? 0
+    let climb = maxClimbRateMps ?? 0
+    let gnd   = maxGroundSpeedMps ?? 0
+    postToRender { [weak self] in
+      self?.bridge?.setRateCapsYaw(yaw, pitch: pitch, roll: roll,
+                                   climb: climb, groundSpeed: gnd)
+    }
+  }
+
   // MARK: - Render-thread dispatch helper
 
   /// Posts a closure to the dedicated render queue. Used by every prop setter
-  /// that mutates engine state, so the EngineConfig + GPU resources are only
-  /// ever touched from one thread (renderQueue) — the render path itself, the
-  /// surface init, and bridge teardown all run there.
+  /// that mutates engine state. Camera demand setters do **not** hop here —
+  /// the CameraIntegrator's mutex makes per-DoF writes safe from any thread,
+  /// and skipping the dispatch keeps latency minimal for high-rate updates.
   private func postToRender(_ action: @escaping () -> Void) {
     renderQueue.async { action() }
   }
@@ -119,7 +147,30 @@ class HybridCesiumView: HybridCesiumViewSpec {
 
   // MARK: - Methods
 
-  func getCameraState() throws -> Promise<CameraState> {
+  func getActualCamera() throws -> Promise<CameraState> {
+    guard let b = bridge else {
+      return Promise.rejected(
+        withError: NSError(
+          domain: "HybridCesiumView",
+          code: 1,
+          userInfo: [NSLocalizedDescriptionKey: "Native bridge not initialized"]
+        )
+      )
+    }
+    return Promise.resolved(
+      withResult: CameraState(
+        latitude: b.readActualLatitude(),
+        longitude: b.readActualLongitude(),
+        altitude: b.readActualAltitude(),
+        heading: b.readActualHeading(),
+        pitch: b.readActualPitch(),
+        roll: b.readActualRoll(),
+        verticalFovDeg: b.readActualVerticalFovDeg()
+      )
+    )
+  }
+
+  func getDemandCamera() throws -> Promise<CameraState> {
     guard let b = bridge else {
       return Promise.rejected(
         withError: NSError(
@@ -129,47 +180,79 @@ class HybridCesiumView: HybridCesiumViewSpec {
         )
       )
     }
-    let s = CameraState(
-      latitude: b.readCameraLatitude(),
-      longitude: b.readCameraLongitude(),
-      altitude: b.readCameraAltitude(),
-      heading: b.readCameraHeading(),
-      pitch: b.readCameraPitch(),
-      roll: b.readCameraRoll(),
-      verticalFovDeg: b.readVerticalFovDeg()
+    return Promise.resolved(
+      withResult: CameraState(
+        latitude: b.readDemandLatitude(),
+        longitude: b.readDemandLongitude(),
+        altitude: b.readDemandAltitude(),
+        heading: b.readDemandHeading(),
+        pitch: b.readDemandPitch(),
+        roll: b.readDemandRoll(),
+        verticalFovDeg: b.readDemandVerticalFovDeg()
+      )
     )
-    return Promise.resolved(withResult: s)
   }
 
-  func setCamera(camera: CameraState) throws {
-    // Runtime camera updates flow through this method. We do *not* mutate
-    // `initialCamera` (it is construction-time only). If the view is not
-    // ready yet, the value is buffered in `pendingRuntimeCamera` and pushed
-    // during initialization.
-    pendingRuntimeCamera = camera
-    pendingRuntimeViewCorrection = nil
-    postToRender { [weak self] in self?.pushCameraStateIfChanged(camera) }
+  func setPosition(latitude: Double, longitude: Double) throws {
+    if let b = bridge {
+      b.setPositionLatitude(latitude, longitude: longitude)
+    } else {
+      pendingLat = latitude
+      pendingLon = longitude
+    }
+  }
+
+  func setAltitude(altitudeMeters: Double) throws {
+    if let b = bridge { b.setAltitude(altitudeMeters) }
+    else              { pendingAltitude = altitudeMeters }
+  }
+
+  func setHeading(headingDeg: Double) throws {
+    if let b = bridge { b.setHeadingDeg(headingDeg) }
+    else              { pendingHeading = headingDeg }
+  }
+
+  func setAttitude(pitchDeg: Double, rollDeg: Double) throws {
+    if let b = bridge { b.setAttitudePitch(pitchDeg, roll: rollDeg) }
+    else              { pendingPitch = pitchDeg; pendingRoll = rollDeg }
+  }
+
+  func setViewCorrection(q: Quaternion) throws {
+    if let b = bridge { b.setViewCorrectionW(q.w, x: q.x, y: q.y, z: q.z) }
+    else              { pendingViewCorrection = q }
   }
 
-  func setCameraQuaternion(camera: CameraState, viewCorrection: Quaternion) throws {
-    pendingRuntimeCamera = camera
-    pendingRuntimeViewCorrection = viewCorrection
-    postToRender { [weak self] in self?.pushCameraQuaternionIfChanged(camera, viewCorrection: viewCorrection) }
+  func setVerticalFov(deg: Double) throws {
+    if let b = bridge { b.setVerticalFovDeg(deg) }
+    else              { pendingVfov = deg }
+  }
+
+  func teleport(camera: CameraState) throws {
+    if let b = bridge {
+      b.teleportLatitude(camera.latitude,
+                         longitude: camera.longitude,
+                         altitude: camera.altitude,
+                         heading: camera.heading,
+                         pitch: camera.pitch,
+                         roll: camera.roll,
+                         verticalFovDeg: camera.verticalFovDeg)
+    } else {
+      pendingTeleport = camera
+    }
   }
 
   func getViewCorrection() throws -> Promise<Quaternion> {
     guard let b = bridge else {
-      return Promise.resolved(
-        withResult: Quaternion(w: 1, x: 0, y: 0, z: 0)
-      )
+      return Promise.resolved(withResult: Quaternion(w: 1, x: 0, y: 0, z: 0))
     }
-    let q = Quaternion(
-      w: b.readViewCorrectionW(),
-      x: b.readViewCorrectionX(),
-      y: b.readViewCorrectionY(),
-      z: b.readViewCorrectionZ()
+    return Promise.resolved(
+      withResult: Quaternion(
+        w: b.readViewCorrectionW(),
+        x: b.readViewCorrectionX(),
+        y: b.readViewCorrectionY(),
+        z: b.readViewCorrectionZ()
+      )
     )
-    return Promise.resolved(withResult: q)
   }
 
   // MARK: - View
@@ -177,36 +260,50 @@ class HybridCesiumView: HybridCesiumViewSpec {
   private let metalView: MTKView
   private var bridge: CesiumBridge?
   private var displayLink: CADisplayLink?
+  private let displayLinkProxy = DisplayLinkProxy()
   private var layoutPollTimer: Timer?
   private var metricsFrameCounter: Int = 0
   private var idleProbeAccumulator: Double = 0
   private var usingLowRefreshRate = false
   private var hasConfiguredFrameRate = false
-  private var lastPushedCameraState: CameraState?
-  /// Last quaternion pushed via `setCameraQuaternion`; `nil` if only `setCamera` has been used.
-  private var lastPushedViewCorrection: Quaternion?
-  /// Camera state requested by `setCamera` before the bridge was ready.
-  private var pendingRuntimeCamera: CameraState?
-  private var pendingRuntimeViewCorrection: Quaternion?
   private var lastBridgePixelSize: CGSize = .zero
 
+  /// Demand values that arrived before the bridge was created. Drained once
+  /// in `ensureInitialized()` after the seed teleport.
+  private var pendingTeleport: CameraState?
+  private var pendingLat: Double?
+  private var pendingLon: Double?
+  private var pendingAltitude: Double?
+  private var pendingHeading: Double?
+  private var pendingPitch: Double?
+  private var pendingRoll: Double?
+  private var pendingVfov: Double?
+  private var pendingViewCorrection: Quaternion?
+
   /// Dedicated serial render queue. CADisplayLink fires on `.main`, but the
   /// actual `bridge.shouldRenderNextFrame()` / `bridge.renderFrame(...)` work
   /// is dispatched here so the main thread is never blocked on Cesium tile
   /// loading or Metal command-buffer encoding. All bridge prop setters also
   /// dispatch here so they serialize with rendering and never race with
-  /// engine state.
+  /// engine state. Per-DoF camera writes deliberately bypass this hop —
+  /// CameraIntegrator's internal mutex handles cross-thread safety.
   private let renderQueue = DispatchQueue(
     label: "com.margelo.cesium.render",
     qos: .userInteractive
   )
   /// Drops a CADisplayLink tick if the render queue is still finishing the
-  /// previous frame — keeps it from queuing up an unbounded backlog under
-  /// stutter (Metal's frameSemaphore would already throttle, but this saves
-  /// the dispatch hop and keeps `dt` accurate).
+  /// previous frame.
   private var renderInFlight = false
   private let renderInFlightLock = NSLock()
 
+  /// Set to true at the start of `deinit`. Any work still queued on the
+  /// render or main queues checks this before touching the bridge or
+  /// invoking JS callbacks. Avoids two classes of warnings during fast
+  /// refresh / unmount: Nitro "Dispatcher has already been destroyed"
+  /// when emitting `onMetrics` into a dying JS runtime, and stray frame
+  /// ticks running after the bridge has been torn down.
+  private var isShutdown = false
+
   var view: UIView { metalView }
 
   override init() {
@@ -270,17 +367,29 @@ class HybridCesiumView: HybridCesiumViewSpec {
     if !ionAccessToken.isEmpty {
       bridge?.updateIonAccessToken(ionAccessToken, assetId: Int64(ionAssetId))
     }
-    // Apply construction-time seed first; if the consumer already invoked
-    // setCamera / setCameraQuaternion before we were ready, replay it last so
-    // the runtime value wins.
-    pushCameraStateIfChanged(initialCamera)
-    if let runtime = pendingRuntimeCamera {
-      if let q = pendingRuntimeViewCorrection {
-        pushCameraQuaternionIfChanged(runtime, viewCorrection: q)
-      } else {
-        pushCameraStateIfChanged(runtime)
-      }
+    // Seed from initialCamera, then replay anything the consumer set before
+    // we were ready.
+    let seed = pendingTeleport ?? initialCamera
+    bridge?.teleportLatitude(seed.latitude,
+                             longitude: seed.longitude,
+                             altitude: seed.altitude,
+                             heading: seed.heading,
+                             pitch: seed.pitch,
+                             roll: seed.roll,
+                             verticalFovDeg: seed.verticalFovDeg)
+    pendingTeleport = nil
+
+    if let la = pendingLat, let lo = pendingLon {
+      bridge?.setPositionLatitude(la, longitude: lo); pendingLat = nil; pendingLon = nil
     }
+    if let a = pendingAltitude       { bridge?.setAltitude(a);                           pendingAltitude = nil }
+    if let h = pendingHeading        { bridge?.setHeadingDeg(h);                         pendingHeading  = nil }
+    if let p = pendingPitch, let r = pendingRoll {
+      bridge?.setAttitudePitch(p, roll: r); pendingPitch = nil; pendingRoll = nil
+    }
+    if let f = pendingVfov           { bridge?.setVerticalFovDeg(f);                     pendingVfov     = nil }
+    if let q = pendingViewCorrection { bridge?.setViewCorrectionW(q.w, x: q.x, y: q.y, z: q.z); pendingViewCorrection = nil }
+
     if ionImageryAssetId != 1 {
       bridge?.updateImageryAssetId(Int64(ionImageryAssetId))
     }
@@ -289,6 +398,8 @@ class HybridCesiumView: HybridCesiumViewSpec {
     bridge?.setMsaaSampleCount(sc)
     applyMtkViewMsaa(Int(sc))
 
+    pushRateCaps()
+
     startRenderLoop()
   }
 
@@ -325,69 +436,14 @@ class HybridCesiumView: HybridCesiumViewSpec {
     if let v = minAltitudeAboveTerrain { bridge?.setMinAltitudeAboveTerrain(Float(v)) }
   }
 
-  /// Pushes camera state into native bridge only when values changed.
-  private func pushCameraStateIfChanged(_ camera: CameraState) {
-    guard bridge != nil else { return }
-    if let last = lastPushedCameraState,
-       last.latitude == camera.latitude,
-       last.longitude == camera.longitude,
-       last.altitude == camera.altitude,
-       last.heading == camera.heading,
-       last.pitch == camera.pitch,
-       last.roll == camera.roll,
-       last.verticalFovDeg == camera.verticalFovDeg {
-      return
-    }
-    lastPushedCameraState = camera
-    bridge?.updateCameraLatitude(
-      camera.latitude,
-      longitude: camera.longitude,
-      altitude: camera.altitude,
-      heading: camera.heading,
-      pitch: camera.pitch,
-      roll: camera.roll
-    )
-    bridge?.setVerticalFovDeg(camera.verticalFovDeg)
-  }
-
-  private func pushCameraQuaternionIfChanged(_ camera: CameraState, viewCorrection: Quaternion) {
-    guard bridge != nil else { return }
-    if let lastCam = lastPushedCameraState,
-       let lastQ = lastPushedViewCorrection,
-       lastCam.latitude == camera.latitude,
-       lastCam.longitude == camera.longitude,
-       lastCam.altitude == camera.altitude,
-       lastCam.heading == camera.heading,
-       lastCam.pitch == camera.pitch,
-       lastCam.roll == camera.roll,
-       lastCam.verticalFovDeg == camera.verticalFovDeg,
-       lastQ.w == viewCorrection.w,
-       lastQ.x == viewCorrection.x,
-       lastQ.y == viewCorrection.y,
-       lastQ.z == viewCorrection.z {
-      return
-    }
-    lastPushedCameraState = camera
-    lastPushedViewCorrection = viewCorrection
-    bridge?.updateCameraQuaternionLatitude(
-      camera.latitude,
-      longitude: camera.longitude,
-      altitude: camera.altitude,
-      heading: camera.heading,
-      pitch: camera.pitch,
-      roll: camera.roll,
-      viewCorrectionW: viewCorrection.w,
-      x: viewCorrection.x,
-      y: viewCorrection.y,
-      z: viewCorrection.z
-    )
-    bridge?.setVerticalFovDeg(camera.verticalFovDeg)
-  }
-
   // MARK: - Render Loop
 
   private func startRenderLoop() {
-    displayLink = CADisplayLink(target: self, selector: #selector(renderFrame))
+    displayLinkProxy.owner = self
+    displayLink = CADisplayLink(
+      target: displayLinkProxy,
+      selector: #selector(DisplayLinkProxy.tick)
+    )
     setDisplayLinkFrameRate(idle: false)
     displayLink?.add(to: .main, forMode: .common)
     displayLink?.isPaused = pauseRendering
@@ -403,13 +459,12 @@ class HybridCesiumView: HybridCesiumViewSpec {
       : CAFrameRateRange(minimum: 30, maximum: 60, preferred: 60)
   }
 
-  @objc private func renderFrame() {
+  /// Invoked by `DisplayLinkProxy` on every CADisplayLink tick (main thread).
+  fileprivate func handleDisplayLinkTick() {
     guard !pauseRendering,
-          let dl = displayLink,
+          !isShutdown,
           let bridge else { return }
 
-    let dt = max(dl.targetTimestamp - dl.timestamp, 1.0 / 120.0)
-
     // metalView.bounds / drawableSize are UIKit, must stay on main.
     let scale = metalView.contentScaleFactor
     let w = Int(metalView.bounds.width * scale)
@@ -424,9 +479,7 @@ class HybridCesiumView: HybridCesiumViewSpec {
       }
     }
 
-    // Throttle: drop the tick if the render queue hasn't finished the previous
-    // frame yet. This keeps the dispatch backlog at zero and lets the next
-    // CADisplayLink fire pick up a fresh dt.
+    // Drop the tick if the render queue hasn't finished the previous frame yet.
     renderInFlightLock.lock()
     if renderInFlight {
       renderInFlightLock.unlock()
@@ -435,16 +488,24 @@ class HybridCesiumView: HybridCesiumViewSpec {
     renderInFlight = true
     renderInFlightLock.unlock()
 
+    // Wall-clock time used for the metrics-only frame-dt EMA inside the
+    // bridge. The camera integrator owns its own clock — see
+    // CameraIntegrator::step().
+    let nowSeconds = CACurrentMediaTime()
+
     let resizedW = w
     let resizedH = h
-    let weakSelf = self  // captured for main-thread post-frame work
     renderQueue.async { [weak self, weak bridge] in
-      guard let self = self, let bridge = bridge else {
-        weakSelf.renderInFlightLock.lock()
-        weakSelf.renderInFlight = false
-        weakSelf.renderInFlightLock.unlock()
-        return
+      guard let self = self else { return }
+      // `renderInFlight` must always be cleared so a single dropped tick
+      // doesn't permanently wedge the render loop. defer guarantees it
+      // regardless of which early-return path we take below.
+      defer {
+        self.renderInFlightLock.lock()
+        self.renderInFlight = false
+        self.renderInFlightLock.unlock()
       }
+      guard let bridge = bridge else { return }
 
       if didResize {
         bridge.resize(Int32(resizedW), height: Int32(resizedH))
@@ -455,12 +516,13 @@ class HybridCesiumView: HybridCesiumViewSpec {
       let nextIsIdle: Bool
       if shouldRenderNow {
         self.idleProbeAccumulator = 0
-        bridge.renderFrame(withDt: dt)
+        bridge.renderFrame(at: nowSeconds)
         nextIsIdle = false
       } else {
-        self.idleProbeAccumulator += dt
+        // Approximate dt for the idle probe. We don't need precision here.
+        let probeDt = 1.0 / 60.0
+        self.idleProbeAccumulator += probeDt
         if self.idleProbeAccumulator >= 0.25 {
-          // Safety probe: occasionally tick engine state for late tile completions.
           self.idleProbeAccumulator = 0
           bridge.markNeedsRender()
         }
@@ -469,7 +531,7 @@ class HybridCesiumView: HybridCesiumViewSpec {
 
       self.metricsFrameCounter += 1
       let shouldEmitMetrics =
-        self.metricsFrameCounter >= 20 && self.onMetrics != nil
+        self.metricsFrameCounter >= 20 && self.onMetrics != nil && !self.isShutdown
       let metricsSnapshot: CesiumMetrics? = shouldEmitMetrics ? CesiumMetrics(
         fps: bridge.metricsFps,
         tilesRendered: Double(bridge.metricsTilesRendered),
@@ -482,32 +544,38 @@ class HybridCesiumView: HybridCesiumViewSpec {
       ) : nil
       if shouldEmitMetrics { self.metricsFrameCounter = 0 }
 
-      // Hop back to main to update CADisplayLink rate (UIKit) and emit the
-      // metrics callback (consumer may touch UI from it).
       DispatchQueue.main.async { [weak self] in
-        guard let self = self else { return }
+        guard let self = self, !self.isShutdown else { return }
         self.setDisplayLinkFrameRate(idle: nextIsIdle)
         if let m = metricsSnapshot, let cb = self.onMetrics {
           cb(m)
         }
       }
-
-      self.renderInFlightLock.lock()
-      self.renderInFlight = false
-      self.renderInFlightLock.unlock()
+      // renderInFlight is cleared by the defer at the top of this closure.
     }
   }
 
   deinit {
+    // Set the shutdown gate first so any in-flight render-queue tick and
+    // any queued main-queue follow-on (metric emission, frame-rate update)
+    // bail out before they touch the bridge or invoke onMetrics into a
+    // JS dispatcher that may already be gone.
+    isShutdown = true
+    onMetrics = nil
+
     layoutPollTimer?.invalidate()
+    layoutPollTimer = nil
     displayLink?.invalidate()
+    displayLink = nil
+    displayLinkProxy.owner = nil
 
-    // Drain the render queue so we don't release `bridge` while it's
-    // mid-encode. `sync` here is bounded by Metal's frameSemaphore wait —
-    // which itself is already bounded to 1 s in MetalBackend::shutdown().
     let bridgeRef = bridge
     bridge = nil
     if let b = bridgeRef {
+      // Drain anything already on the render queue, then ask the bridge
+      // to release its engine + Metal backend synchronously. We do this
+      // inside the sync hop so the SqliteCache file handle is closed
+      // before any subsequent CesiumView mount can open the same cache.
       renderQueue.sync {
         b.shutdown()
       }

package/lib/typescript/src/specs/cesium-view.nitro.d.ts

@@ -1,5 +1,8 @@
 import type { HybridView, HybridViewProps, HybridViewMethods } from 'react-native-nitro-modules';
-/** Snapshot of the native camera for persistence / sync with React state. */
+/**
+ * Snapshot of the native camera for persistence / sync with React state.
+ * Returned by `getActualCamera()` and `getDemandCamera()`.
+ */
 export interface CameraState {
     latitude: number;
     longitude: number;
@@ -10,8 +13,9 @@ export interface CameraState {
     verticalFovDeg: number;
 }
 /**
- * Unit quaternion (w + xi + yj + zk). Used for camera-space view correction.
- * Non-unit values are normalized on the native side.
+ * Unit quaternion (w + xi + yj + zk). Used for camera-space view correction
+ * applied after HPR (boresight / HUD alignment). Non-unit values are
+ * normalised on the native side.
  */
 export interface Quaternion {
     w: number;
@@ -34,7 +38,11 @@ export interface CesiumMetrics {
 export interface CesiumViewProps extends HybridViewProps {
     ionAccessToken: string;
     ionAssetId: number;
-    /** Construction-time seed camera. Use `setCamera()` for runtime updates. */
+    /**
+     * Initial camera applied via `teleport(...)` once when the native bridge is
+     * created. Subsequent prop writes are ignored — use the per-DoF setters or
+     * `teleport(...)` for runtime updates.
+     */
     initialCamera: CameraState;
     pauseRendering: boolean;
     maximumScreenSpaceError: number;
@@ -74,22 +82,78 @@ export interface CesiumViewProps extends HybridViewProps {
      * terrain mesh vertex to the camera nadir.
      */
     minAltitudeAboveTerrain?: number;
+    /** Maximum yaw rate (degrees per second). 0 = uncapped. */
+    maxYawRateDegSec?: number;
+    /** Maximum pitch rate (degrees per second). 0 = uncapped. */
+    maxPitchRateDegSec?: number;
+    /** Maximum roll rate (degrees per second). 0 = uncapped. */
+    maxRollRateDegSec?: number;
+    /** Maximum climb / descent rate (metres per second). 0 = uncapped. */
+    maxClimbRateMps?: number;
+    /** Maximum horizontal ground speed (metres per second). 0 = uncapped. */
+    maxGroundSpeedMps?: number;
     onMetrics?: (metrics: CesiumMetrics) => void;
 }
+/**
+ * Per-DoF camera control. Every setter records the measurement with the
+ * native steady_clock time of arrival and feeds it into an α-β tracker
+ * (constant-velocity predictor) that owns both demand and actual state.
+ *
+ * All setters are synchronous and thread-safe. Calling them from a
+ * Reanimated worklet via a Nitro `hybridRef` is the supported path for
+ * high-frequency updates; the worklet thread takes the integrator's mutex
+ * briefly and returns immediately.
+ *
+ * Getters return Promises and should be called from the JS thread (e.g. a
+ * `useEffect` or a throttled HUD update), not from a worklet.
+ */
 export interface CesiumViewMethods extends HybridViewMethods {
-    /** Returns the current native camera state. */
-    getCameraState(): Promise<CameraState>;
     /**
-     * Runtime camera control (heading/pitch/roll + position + VFOV).
-     * Does not change the view-correction quaternion; use `setCameraQuaternion` to set that.
+     * New geographic position demand (latitude / longitude in degrees). Use
+     * for GPS or scripted position updates. Latitude is clamped to ±90 by the
+     * integrator; longitude is continuous (no wrap normalisation) so the
+     * shortest-arc residual maths stays correct across the antimeridian.
+     */
+    setPosition(latitude: number, longitude: number): void;
+    /** New altitude demand (metres above mean sea level). */
+    setAltitude(altitudeMeters: number): void;
+    /** New heading demand (degrees, 0 = north, increasing clockwise). */
+    setHeading(headingDeg: number): void;
+    /**
+     * New attitude demand (pitch and roll in degrees). Bundled because almost
+     * every IMU emits them together — but you can pass the previous value for
+     * either axis if you only have one of them.
+     */
+    setAttitude(pitchDeg: number, rollDeg: number): void;
+    /**
+     * New camera-space rotation applied after HPR (unit quaternion). Use for
+     * boresight calibration or screen-fixed HUD alignment. SLERPed toward the
+     * latest demand each frame.
+     */
+    setViewCorrection(q: Quaternion): void;
+    /** New vertical field-of-view demand (degrees). Clamped to 20..100. */
+    setVerticalFov(deg: number): void;
+    /**
+     * Atomically reset every DoF to the given camera state (value, velocity
+     * and demand all snap to the target). Bypasses the integrator entirely;
+     * use for `Fly to coordinate` actions or initial seeding from saved
+     * state.
+     */
+    teleport(camera: CameraState): void;
+    /**
+     * Most recent camera that was rendered (post-integration). This is what
+     * the user is currently looking at and is what a HUD overlay should
+     * mirror. Differs from `getDemandCamera()` while a glide is in progress
+     * or when the terrain-floor clamp has raised the altitude.
      */
-    setCamera(camera: CameraState): void;
+    getActualCamera(): Promise<CameraState>;
     /**
-     * Same fields as `setCamera`, plus a camera-space rotation applied after HPR
-     * (e.g. boresight / HUD alignment). See README.
+     * What the consumer last asked for (per-DoF demand). Useful for
+     * diagnostics or for showing the requested camera alongside the rendered
+     * one.
      */
-    setCameraQuaternion(camera: CameraState, viewCorrection: Quaternion): void;
-    /** Current view-correction quaternion (identity if never set via `setCameraQuaternion`). */
+    getDemandCamera(): Promise<CameraState>;
+    /** Current view-correction quaternion (smoothed toward the latest demand). */
     getViewCorrection(): Promise<Quaternion>;
 }
 export type CesiumView = HybridView<CesiumViewProps, CesiumViewMethods>;

package/lib/typescript/src/specs/cesium-view.nitro.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cesium-view.nitro.d.ts","sourceRoot":"","sources":["../../../../src/specs/cesium-view.nitro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,eAAe,EACf,iBAAiB,EAClB,MAAM,4BAA4B,CAAA;AAEnC,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,cAAc,EAAE,MAAM,CAAA;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACV;AAED,iEAAiE;AACjE,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,MAAM,CAAA;IACpB,kBAAkB,EAAE,OAAO,CAAA;IAC3B,+DAA+D;IAC/D,aAAa,EAAE,OAAO,CAAA;IACtB,YAAY,EAAE,OAAO,CAAA;IACrB,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,eAAgB,SAAQ,eAAe;IACtD,cAAc,EAAE,MAAM,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,4EAA4E;IAC5E,aAAa,EAAE,WAAW,CAAA;IAC1B,cAAc,EAAE,OAAO,CAAA;IACvB,uBAAuB,EAAE,MAAM,CAAA;IAC/B,4BAA4B,EAAE,MAAM,CAAA;IACpC,sBAAsB,EAAE,MAAM,CAAA;IAC9B,6CAA6C;IAC7C,eAAe,EAAE,MAAM,CAAA;IACvB,iBAAiB,EAAE,MAAM,CAAA;IAGzB,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,mGAAmG;IACnG,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,mEAAmE;IACnE,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,gFAAgF;IAChF,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,oEAAoE;IACpE,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,2EAA2E;IAC3E,6BAA6B,CAAC,EAAE,OAAO,CAAA;IACvC,4FAA4F;IAC5F,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,8EAA8E;IAC9E,yBAAyB,CAAC,EAAE,OAAO,CAAA;IACnC,mDAAmD;IACnD,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,mDAAmD;IACnD,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,4EAA4E;IAC5E,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAA;IAEhC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAA;CAC7C;AAED,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC1D,+CAA+C;IAC/C,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;IACtC;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;IACpC;;;OAGG;IACH,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,GAAG,IAAI,CAAA;IAC1E,4FAA4F;IAC5F,iBAAiB,IAAI,OAAO,CAAC,UAAU,CAAC,CAAA;CACzC;AAED,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,eAAe,EAAE,iBAAiB,CAAC,CAAA"}
+{"version":3,"file":"cesium-view.nitro.d.ts","sourceRoot":"","sources":["../../../../src/specs/cesium-view.nitro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,eAAe,EACf,iBAAiB,EAClB,MAAM,4BAA4B,CAAA;AAEnC;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,cAAc,EAAE,MAAM,CAAA;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACV;AAED,iEAAiE;AACjE,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,MAAM,CAAA;IACpB,kBAAkB,EAAE,OAAO,CAAA;IAC3B,+DAA+D;IAC/D,aAAa,EAAE,OAAO,CAAA;IACtB,YAAY,EAAE,OAAO,CAAA;IACrB,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,eAAgB,SAAQ,eAAe;IACtD,cAAc,EAAE,MAAM,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,aAAa,EAAE,WAAW,CAAA;IAC1B,cAAc,EAAE,OAAO,CAAA;IACvB,uBAAuB,EAAE,MAAM,CAAA;IAC/B,4BAA4B,EAAE,MAAM,CAAA;IACpC,sBAAsB,EAAE,MAAM,CAAA;IAC9B,6CAA6C;IAC7C,eAAe,EAAE,MAAM,CAAA;IACvB,iBAAiB,EAAE,MAAM,CAAA;IAGzB,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,mGAAmG;IACnG,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,mEAAmE;IACnE,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,gFAAgF;IAChF,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,oEAAoE;IACpE,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,2EAA2E;IAC3E,6BAA6B,CAAC,EAAE,OAAO,CAAA;IACvC,4FAA4F;IAC5F,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,8EAA8E;IAC9E,yBAAyB,CAAC,EAAE,OAAO,CAAA;IACnC,mDAAmD;IACnD,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,mDAAmD;IACnD,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,4EAA4E;IAC5E,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAA;IAOhC,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,6DAA6D;IAC7D,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,4DAA4D;IAC5D,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,sEAAsE;IACtE,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,yEAAyE;IACzE,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAE1B,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAA;CAC7C;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC1D;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IAEtD,yDAAyD;IACzD,WAAW,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAEzC,qEAAqE;IACrE,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IAEpC;;;;OAIG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAEpD;;;;OAIG;IACH,iBAAiB,CAAC,CAAC,EAAE,UAAU,GAAG,IAAI,CAAA;IAEtC,uEAAuE;IACvE,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAEjC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;IAEnC;;;;;OAKG;IACH,eAAe,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;IAEvC;;;;OAIG;IACH,eAAe,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;IAEvC,8EAA8E;IAC9E,iBAAiB,IAAI,OAAO,CAAC,UAAU,CAAC,CAAA;CACzC;AAED,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,eAAe,EAAE,iBAAiB,CAAC,CAAA"}