react-native-cesium 1.2.4 → 1.2.6

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

@@ -152,6 +152,22 @@ class HybridCesiumView(private val appContext: Context) : HybridCesiumViewSpec()
 
   override var onMetrics: ((metrics: CesiumMetrics) -> Unit)? = null
 
+  override var onActualCamera: ((camera: CameraState) -> Unit)? = null
+  // Both accessed only on the render thread; no extra locking needed.
+  private var actualCameraLastEmitSec: Double = 0.0
+  private var actualCameraLastSent: CameraState? = null
+
+  // Returns true when the two snapshots differ enough to warrant a JS dispatch.
+  // Thresholds mirror EngineTunables.hpp kActualCameraCallbackInterval* constants.
+  private fun actualCameraChanged(a: CameraState, b: CameraState): Boolean =
+    Math.abs(a.latitude       - b.latitude)       > 1e-7  ||
+    Math.abs(a.longitude      - b.longitude)      > 1e-7  ||
+    Math.abs(a.altitude       - b.altitude)       > 0.05  ||
+    Math.abs(a.heading        - b.heading)        > 0.01  ||
+    Math.abs(a.pitch          - b.pitch)          > 0.01  ||
+    Math.abs(a.roll           - b.roll)           > 0.01  ||
+    Math.abs(a.verticalFovDeg - b.verticalFovDeg) > 0.01
+
   override val view: View get() = surfaceView
 
   private val frameCallback = Choreographer.FrameCallback {
@@ -217,6 +233,27 @@ class HybridCesiumView(private val appContext: Context) : HybridCesiumViewSpec()
       }
     }
 
+    // onActualCamera: poll at 5 Hz (kActualCameraCallbackIntervalSec = 0.2 s),
+    // but only dispatch when at least one field has moved beyond its epsilon.
+    val acCb = if (isShutdown) null else onActualCamera
+    if (acCb != null && (nowSeconds - actualCameraLastEmitSec) >= 0.2) {
+      actualCameraLastEmitSec = nowSeconds
+      val candidate = CameraState(
+        latitude     = b.getActualLatitude(),
+        longitude    = b.getActualLongitude(),
+        altitude     = b.getActualAltitude(),
+        heading      = b.getActualHeading(),
+        pitch        = b.getActualPitch(),
+        roll         = b.getActualRoll(),
+        verticalFovDeg = b.getActualVerticalFovDeg(),
+      )
+      val prev = actualCameraLastSent
+      if (prev == null || actualCameraChanged(candidate, prev)) {
+        actualCameraLastSent = candidate
+        acCb(candidate)
+      }
+    }
+
     renderInFlight.set(false)
 
     surfaceView.post { scheduleNextFrame(immediate = nextImmediate) }
@@ -292,6 +329,8 @@ class HybridCesiumView(private val appContext: Context) : HybridCesiumViewSpec()
       // into a dying JS runtime.
       isShutdown = true
       onMetrics = null
+      onActualCamera = null
+      actualCameraLastSent = null
 
       val rh = renderHandler
       val ht = renderThread

package/cpp/engine/EngineTunables.hpp

@@ -69,8 +69,8 @@ inline constexpr int32_t kDefaultLoadingDescendantLimit       = 20;
 inline constexpr double kAlphaPos    = 0.6;   inline constexpr double kBetaPos    = 0.05;
 inline constexpr double kAlphaAlt    = 0.6;   inline constexpr double kBetaAlt    = 0.05;
 inline constexpr double kAlphaHdg    = 0.55;  inline constexpr double kBetaHdg    = 0.05;
-inline constexpr double kAlphaPitch  = 0.5;   inline constexpr double kBetaPitch  = 0.05;
-inline constexpr double kAlphaRoll   = 0.5;   inline constexpr double kBetaRoll   = 0.05;
+inline constexpr double kAlphaPitch  = 0.75;  inline constexpr double kBetaPitch  = 0.05;
+inline constexpr double kAlphaRoll   = 0.75;  inline constexpr double kBetaRoll   = 0.05;
 inline constexpr double kAlphaVfov     = 0.4;   // no velocity term
 inline constexpr double kAlphaViewCorr = 0.5;   // SLERP toward target
 
@@ -130,6 +130,18 @@ inline constexpr double kOutlierHeadingDeg  = 0.0;
 // Metrics throttle: emit telemetry every N rendered frames.
 inline constexpr int kMetricsEmitEveryFrames = 20;
 
+// Minimum interval between onActualCamera callback emissions (seconds).
+// 0.2 s = 5 Hz — fast enough for HUD alignment, light on the JS bridge.
+inline constexpr double kActualCameraCallbackIntervalSec = 0.2;
+
+// Change-detection thresholds for onActualCamera.
+// A new snapshot is only dispatched to JS when at least one field has moved
+// by more than the corresponding epsilon since the last emission.
+inline constexpr double kActualCameraDeltaLatLonDeg = 1e-7;   // ~1 cm at equator
+inline constexpr double kActualCameraDeltaAltMeters = 0.05;   // 5 cm
+inline constexpr double kActualCameraDeltaAngleDeg  = 0.01;   // heading / pitch / roll
+inline constexpr double kActualCameraDeltaFovDeg    = 0.01;   // vertical FoV
+
 // Idle-probe interval (seconds): when the engine is idle, periodically tick
 // to catch late tile completions without redundant full draws.
 inline constexpr double kIdleProbeSeconds = 0.25;

package/ios/HybridCesiumView.swift

@@ -145,6 +145,23 @@ class HybridCesiumView: HybridCesiumViewSpec {
 
   var onMetrics: ((CesiumMetrics) -> Void)?
 
+  var onActualCamera: ((CameraState) -> Void)?
+  // Both accessed only on the render queue; no extra locking needed.
+  private var actualCameraLastEmitTime: CFTimeInterval = 0
+  private var actualCameraLastSent: CameraState? = nil
+
+  // Returns true when the two snapshots differ enough to warrant a JS dispatch.
+  // Thresholds mirror EngineTunables.hpp kActualCameraCallbackInterval* constants.
+  private func actualCameraChanged(_ a: CameraState, from b: CameraState) -> Bool {
+    abs(a.latitude       - b.latitude)       > 1e-7 ||
+    abs(a.longitude      - b.longitude)      > 1e-7 ||
+    abs(a.altitude       - b.altitude)       > 0.05 ||
+    abs(a.heading        - b.heading)        > 0.01 ||
+    abs(a.pitch          - b.pitch)          > 0.01 ||
+    abs(a.roll           - b.roll)           > 0.01 ||
+    abs(a.verticalFovDeg - b.verticalFovDeg) > 0.01
+  }
+
   // MARK: - Methods
 
   func getActualCamera() throws -> Promise<CameraState> {
@@ -544,12 +561,36 @@ class HybridCesiumView: HybridCesiumViewSpec {
       ) : nil
       if shouldEmitMetrics { self.metricsFrameCounter = 0 }
 
+      // onActualCamera: poll at 5 Hz (kActualCameraCallbackIntervalSec = 0.2 s),
+      // but only dispatch when at least one field has moved beyond its epsilon.
+      var actualCameraSnapshot: CameraState? = nil
+      if self.onActualCamera != nil && !self.isShutdown &&
+         (nowSeconds - self.actualCameraLastEmitTime) >= 0.2 {
+        self.actualCameraLastEmitTime = nowSeconds
+        let candidate = CameraState(
+          latitude: bridge.readActualLatitude(),
+          longitude: bridge.readActualLongitude(),
+          altitude: bridge.readActualAltitude(),
+          heading: bridge.readActualHeading(),
+          pitch: bridge.readActualPitch(),
+          roll: bridge.readActualRoll(),
+          verticalFovDeg: bridge.readActualVerticalFovDeg()
+        )
+        if self.actualCameraLastSent.map({ self.actualCameraChanged(candidate, from: $0) }) ?? true {
+          actualCameraSnapshot = candidate
+          self.actualCameraLastSent = candidate
+        }
+      }
+
       DispatchQueue.main.async { [weak self] in
         guard let self = self, !self.isShutdown else { return }
         self.setDisplayLinkFrameRate(idle: nextIsIdle)
         if let m = metricsSnapshot, let cb = self.onMetrics {
           cb(m)
         }
+        if let cam = actualCameraSnapshot, let cb = self.onActualCamera {
+          cb(cam)
+        }
       }
       // renderInFlight is cleared by the defer at the top of this closure.
     }
@@ -562,6 +603,8 @@ class HybridCesiumView: HybridCesiumViewSpec {
     // JS dispatcher that may already be gone.
     isShutdown = true
     onMetrics = nil
+    onActualCamera = nil
+    actualCameraLastSent = nil
 
     layoutPollTimer?.invalidate()
     layoutPollTimer = nil

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

@@ -93,6 +93,14 @@ export interface CesiumViewProps extends HybridViewProps {
     /** Maximum horizontal ground speed (metres per second). 0 = uncapped. */
     maxGroundSpeedMps?: number;
     onMetrics?: (metrics: CesiumMetrics) => void;
+    /**
+     * Called at ~5 Hz with the post-integration actual camera — the same state
+     * returned by `getActualCamera()`. Only fires when at least one field has
+     * changed beyond its epsilon threshold since the last emission, so a
+     * stationary camera produces no bridge traffic. Use this to keep HUD overlay
+     * symbology aligned with the rendered view without polling from JS.
+     */
+    onActualCamera?: (camera: CameraState) => void;
 }
 /**
  * Per-DoF camera control. Every setter records the measurement with the

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":"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"}
+{"version":3,"file":"cesium-view.nitro.d.ts","sourceRoot":"","sources":["../../../../src/specs/cesium-view.nitro.ts"],"names":[],"mappings":"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"}

package/nitrogen/generated/android/ReactNativeCesiumOnLoad.cpp

@@ -17,6 +17,7 @@
 
 #include "JHybridCesiumViewSpec.hpp"
 #include "JFunc_void_CesiumMetrics.hpp"
+#include "JFunc_void_CameraState.hpp"
 #include "views/JHybridCesiumViewStateUpdater.hpp"
 #include <NitroModules/DefaultConstructableObject.hpp>
 
@@ -44,6 +45,7 @@ void registerAllNatives() {
   // Register native JNI methods
   margelo::nitro::reactnativecesium::JHybridCesiumViewSpec::CxxPart::registerNatives();
   margelo::nitro::reactnativecesium::JFunc_void_CesiumMetrics_cxx::registerNatives();
+  margelo::nitro::reactnativecesium::JFunc_void_CameraState_cxx::registerNatives();
   margelo::nitro::reactnativecesium::views::JHybridCesiumViewStateUpdater::registerNatives();
 
   // Register Nitro Hybrid Objects

package/nitrogen/generated/android/c++/JFunc_void_CameraState.hpp

@@ -0,0 +1,77 @@
+///
+/// JFunc_void_CameraState.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#include <fbjni/fbjni.h>
+#include <functional>
+
+#include "CameraState.hpp"
+#include <functional>
+#include <NitroModules/JNICallable.hpp>
+#include "JCameraState.hpp"
+
+namespace margelo::nitro::reactnativecesium {
+
+  using namespace facebook;
+
+  /**
+   * Represents the Java/Kotlin callback `(camera: CameraState) -> Unit`.
+   * This can be passed around between C++ and Java/Kotlin.
+   */
+  struct JFunc_void_CameraState: public jni::JavaClass<JFunc_void_CameraState> {
+  public:
+    static constexpr auto kJavaDescriptor = "Lcom/margelo/nitro/reactnativecesium/Func_void_CameraState;";
+
+  public:
+    /**
+     * Invokes the function this `JFunc_void_CameraState` instance holds through JNI.
+     */
+    void invoke(const CameraState& camera) const {
+      static const auto method = javaClassStatic()->getMethod<void(jni::alias_ref<JCameraState> /* camera */)>("invoke");
+      method(self(), JCameraState::fromCpp(camera));
+    }
+  };
+
+  /**
+   * An implementation of Func_void_CameraState that is backed by a C++ implementation (using `std::function<...>`)
+   */
+  class JFunc_void_CameraState_cxx final: public jni::HybridClass<JFunc_void_CameraState_cxx, JFunc_void_CameraState> {
+  public:
+    static jni::local_ref<JFunc_void_CameraState::javaobject> fromCpp(const std::function<void(const CameraState& /* camera */)>& func) {
+      return JFunc_void_CameraState_cxx::newObjectCxxArgs(func);
+    }
+
+  public:
+    /**
+     * Invokes the C++ `std::function<...>` this `JFunc_void_CameraState_cxx` instance holds.
+     */
+    void invoke_cxx(jni::alias_ref<JCameraState> camera) {
+      _func(camera->toCpp());
+    }
+
+  public:
+    [[nodiscard]]
+    inline const std::function<void(const CameraState& /* camera */)>& getFunction() const {
+      return _func;
+    }
+
+  public:
+    static constexpr auto kJavaDescriptor = "Lcom/margelo/nitro/reactnativecesium/Func_void_CameraState_cxx;";
+    static void registerNatives() {
+      registerHybrid({makeNativeMethod("invoke_cxx", JFunc_void_CameraState_cxx::invoke_cxx)});
+    }
+
+  private:
+    explicit JFunc_void_CameraState_cxx(const std::function<void(const CameraState& /* camera */)>& func): _func(func) { }
+
+  private:
+    friend HybridBase;
+    std::function<void(const CameraState& /* camera */)> _func;
+  };
+
+} // namespace margelo::nitro::reactnativecesium

package/nitrogen/generated/android/c++/JHybridCesiumViewSpec.cpp

@@ -23,6 +23,7 @@ namespace margelo::nitro::reactnativecesium { struct Quaternion; }
 #include "JFunc_void_CesiumMetrics.hpp"
 #include <NitroModules/JNICallable.hpp>
 #include "JCesiumMetrics.hpp"
+#include "JFunc_void_CameraState.hpp"
 #include <NitroModules/Promise.hpp>
 #include <NitroModules/JPromise.hpp>
 #include "Quaternion.hpp"
@@ -318,6 +319,23 @@ namespace margelo::nitro::reactnativecesium {
     static const auto method = _javaPart->javaClassStatic()->getMethod<void(jni::alias_ref<JFunc_void_CesiumMetrics::javaobject> /* onMetrics */)>("setOnMetrics_cxx");
     method(_javaPart, onMetrics.has_value() ? JFunc_void_CesiumMetrics_cxx::fromCpp(onMetrics.value()) : nullptr);
   }
+  std::optional<std::function<void(const CameraState& /* camera */)>> JHybridCesiumViewSpec::getOnActualCamera() {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<jni::local_ref<JFunc_void_CameraState::javaobject>()>("getOnActualCamera_cxx");
+    auto __result = method(_javaPart);
+    return __result != nullptr ? std::make_optional([&]() -> std::function<void(const CameraState& /* camera */)> {
+      if (__result->isInstanceOf(JFunc_void_CameraState_cxx::javaClassStatic())) [[likely]] {
+        auto downcast = jni::static_ref_cast<JFunc_void_CameraState_cxx::javaobject>(__result);
+        return downcast->cthis()->getFunction();
+      } else {
+        auto __resultRef = jni::make_global(__result);
+        return JNICallable<JFunc_void_CameraState, void(CameraState)>(std::move(__resultRef));
+      }
+    }()) : std::nullopt;
+  }
+  void JHybridCesiumViewSpec::setOnActualCamera(const std::optional<std::function<void(const CameraState& /* camera */)>>& onActualCamera) {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<void(jni::alias_ref<JFunc_void_CameraState::javaobject> /* onActualCamera */)>("setOnActualCamera_cxx");
+    method(_javaPart, onActualCamera.has_value() ? JFunc_void_CameraState_cxx::fromCpp(onActualCamera.value()) : nullptr);
+  }
 
   // Methods
   void JHybridCesiumViewSpec::setPosition(double latitude, double longitude) {

package/nitrogen/generated/android/c++/JHybridCesiumViewSpec.hpp

@@ -106,6 +106,8 @@ namespace margelo::nitro::reactnativecesium {
     void setMaxGroundSpeedMps(std::optional<double> maxGroundSpeedMps) override;
     std::optional<std::function<void(const CesiumMetrics& /* metrics */)>> getOnMetrics() override;
     void setOnMetrics(const std::optional<std::function<void(const CesiumMetrics& /* metrics */)>>& onMetrics) override;
+    std::optional<std::function<void(const CameraState& /* camera */)>> getOnActualCamera() override;
+    void setOnActualCamera(const std::optional<std::function<void(const CameraState& /* camera */)>>& onActualCamera) override;
 
   public:
     // Methods

package/nitrogen/generated/android/c++/views/JHybridCesiumViewStateUpdater.cpp

@@ -149,6 +149,10 @@ void JHybridCesiumViewStateUpdater::updateViewProps(jni::alias_ref<jni::JClass>
     hybridView->setOnMetrics(props->onMetrics.value);
     props->onMetrics.isDirty = false;
   }
+  if (props->onActualCamera.isDirty) {
+    hybridView->setOnActualCamera(props->onActualCamera.value);
+    props->onActualCamera.isDirty = false;
+  }
 
   // Update hybridRef if it changed
   if (props->hybridRef.isDirty) {

package/nitrogen/generated/android/kotlin/com/margelo/nitro/reactnativecesium/Func_void_CameraState.kt

@@ -0,0 +1,80 @@
+///
+/// Func_void_CameraState.kt
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+package com.margelo.nitro.reactnativecesium
+
+import androidx.annotation.Keep
+import com.facebook.jni.HybridData
+import com.facebook.proguard.annotations.DoNotStrip
+import dalvik.annotation.optimization.FastNative
+
+
+/**
+ * Represents the JavaScript callback `(camera: struct) => void`.
+ * This can be either implemented in C++ (in which case it might be a callback coming from JS),
+ * or in Kotlin/Java (in which case it is a native callback).
+ */
+@DoNotStrip
+@Keep
+@Suppress("ClassName", "RedundantUnitReturnType")
+fun interface Func_void_CameraState: (CameraState) -> Unit {
+  /**
+   * Call the given JS callback.
+   * @throws Throwable if the JS function itself throws an error, or if the JS function/runtime has already been deleted.
+   */
+  @DoNotStrip
+  @Keep
+  override fun invoke(camera: CameraState): Unit
+}
+
+/**
+ * Represents the JavaScript callback `(camera: struct) => void`.
+ * This is implemented in C++, via a `std::function<...>`.
+ * The callback might be coming from JS.
+ */
+@DoNotStrip
+@Keep
+@Suppress(
+  "KotlinJniMissingFunction", "unused",
+  "RedundantSuppression", "RedundantUnitReturnType", "FunctionName",
+  "ConvertSecondaryConstructorToPrimary", "ClassName", "LocalVariableName",
+)
+class Func_void_CameraState_cxx: Func_void_CameraState {
+  @DoNotStrip
+  @Keep
+  private val mHybridData: HybridData
+
+  @DoNotStrip
+  @Keep
+  private constructor(hybridData: HybridData) {
+    mHybridData = hybridData
+  }
+
+  @DoNotStrip
+  @Keep
+  override fun invoke(camera: CameraState): Unit
+    = invoke_cxx(camera)
+
+  @FastNative
+  private external fun invoke_cxx(camera: CameraState): Unit
+}
+
+/**
+ * Represents the JavaScript callback `(camera: struct) => void`.
+ * This is implemented in Java/Kotlin, via a `(CameraState) -> Unit`.
+ * The callback is always coming from native.
+ */
+@DoNotStrip
+@Keep
+@Suppress("ClassName", "RedundantUnitReturnType", "unused")
+class Func_void_CameraState_java(private val function: (CameraState) -> Unit): Func_void_CameraState {
+  @DoNotStrip
+  @Keep
+  override fun invoke(camera: CameraState): Unit {
+    return this.function(camera)
+  }
+}

package/nitrogen/generated/android/kotlin/com/margelo/nitro/reactnativecesium/HybridCesiumViewSpec.kt

@@ -202,6 +202,20 @@ abstract class HybridCesiumViewSpec: HybridView() {
     set(value) {
       onMetrics = value?.let { it }
     }
+  
+  abstract var onActualCamera: ((camera: CameraState) -> Unit)?
+  
+  private var onActualCamera_cxx: Func_void_CameraState?
+    @Keep
+    @DoNotStrip
+    get() {
+      return onActualCamera?.let { Func_void_CameraState_java(it) }
+    }
+    @Keep
+    @DoNotStrip
+    set(value) {
+      onActualCamera = value?.let { it }
+    }
 
   // Methods
   @DoNotStrip

package/nitrogen/generated/ios/ReactNativeCesium-Swift-Cxx-Bridge.cpp

@@ -22,11 +22,11 @@ namespace margelo::nitro::reactnativecesium::bridge::swift {
     };
   }
   
-  // pragma MARK: std::function<void(const CameraState& /* result */)>
+  // pragma MARK: std::function<void(const CameraState& /* camera */)>
   Func_void_CameraState create_Func_void_CameraState(void* NON_NULL swiftClosureWrapper) noexcept {
     auto swiftClosure = ReactNativeCesium::Func_void_CameraState::fromUnsafe(swiftClosureWrapper);
-    return [swiftClosure = std::move(swiftClosure)](const CameraState& result) mutable -> void {
-      swiftClosure.call(result);
+    return [swiftClosure = std::move(swiftClosure)](const CameraState& camera) mutable -> void {
+      swiftClosure.call(camera);
     };
   }
   

package/nitrogen/generated/ios/ReactNativeCesium-Swift-Cxx-Bridge.hpp

@@ -108,40 +108,55 @@ namespace margelo::nitro::reactnativecesium::bridge::swift {
     return optional.value();
   }
   
-  // pragma MARK: std::shared_ptr<Promise<CameraState>>
-  /**
-   * Specialized version of `std::shared_ptr<Promise<CameraState>>`.
-   */
-  using std__shared_ptr_Promise_CameraState__ = std::shared_ptr<Promise<CameraState>>;
-  inline std::shared_ptr<Promise<CameraState>> create_std__shared_ptr_Promise_CameraState__() noexcept {
-    return Promise<CameraState>::create();
-  }
-  inline PromiseHolder<CameraState> wrap_std__shared_ptr_Promise_CameraState__(std::shared_ptr<Promise<CameraState>> promise) noexcept {
-    return PromiseHolder<CameraState>(std::move(promise));
-  }
-  
-  // pragma MARK: std::function<void(const CameraState& /* result */)>
+  // pragma MARK: std::function<void(const CameraState& /* camera */)>
   /**
    * Specialized version of `std::function<void(const CameraState&)>`.
    */
-  using Func_void_CameraState = std::function<void(const CameraState& /* result */)>;
+  using Func_void_CameraState = std::function<void(const CameraState& /* camera */)>;
   /**
-   * Wrapper class for a `std::function<void(const CameraState& / * result * /)>`, this can be used from Swift.
+   * Wrapper class for a `std::function<void(const CameraState& / * camera * /)>`, this can be used from Swift.
    */
   class Func_void_CameraState_Wrapper final {
   public:
-    explicit Func_void_CameraState_Wrapper(std::function<void(const CameraState& /* result */)>&& func): _function(std::make_unique<std::function<void(const CameraState& /* result */)>>(std::move(func))) {}
-    inline void call(CameraState result) const noexcept {
-      _function->operator()(result);
+    explicit Func_void_CameraState_Wrapper(std::function<void(const CameraState& /* camera */)>&& func): _function(std::make_unique<std::function<void(const CameraState& /* camera */)>>(std::move(func))) {}
+    inline void call(CameraState camera) const noexcept {
+      _function->operator()(camera);
     }
   private:
-    std::unique_ptr<std::function<void(const CameraState& /* result */)>> _function;
+    std::unique_ptr<std::function<void(const CameraState& /* camera */)>> _function;
   } SWIFT_NONCOPYABLE;
   Func_void_CameraState create_Func_void_CameraState(void* NON_NULL swiftClosureWrapper) noexcept;
   inline Func_void_CameraState_Wrapper wrap_Func_void_CameraState(Func_void_CameraState value) noexcept {
     return Func_void_CameraState_Wrapper(std::move(value));
   }
   
+  // pragma MARK: std::optional<std::function<void(const CameraState& /* camera */)>>
+  /**
+   * Specialized version of `std::optional<std::function<void(const CameraState& / * camera * /)>>`.
+   */
+  using std__optional_std__function_void_const_CameraState_____camera______ = std::optional<std::function<void(const CameraState& /* camera */)>>;
+  inline std::optional<std::function<void(const CameraState& /* camera */)>> create_std__optional_std__function_void_const_CameraState_____camera______(const std::function<void(const CameraState& /* camera */)>& value) noexcept {
+    return std::optional<std::function<void(const CameraState& /* camera */)>>(value);
+  }
+  inline bool has_value_std__optional_std__function_void_const_CameraState_____camera______(const std::optional<std::function<void(const CameraState& /* camera */)>>& optional) noexcept {
+    return optional.has_value();
+  }
+  inline std::function<void(const CameraState& /* camera */)> get_std__optional_std__function_void_const_CameraState_____camera______(const std::optional<std::function<void(const CameraState& /* camera */)>>& optional) noexcept {
+    return optional.value();
+  }
+  
+  // pragma MARK: std::shared_ptr<Promise<CameraState>>
+  /**
+   * Specialized version of `std::shared_ptr<Promise<CameraState>>`.
+   */
+  using std__shared_ptr_Promise_CameraState__ = std::shared_ptr<Promise<CameraState>>;
+  inline std::shared_ptr<Promise<CameraState>> create_std__shared_ptr_Promise_CameraState__() noexcept {
+    return Promise<CameraState>::create();
+  }
+  inline PromiseHolder<CameraState> wrap_std__shared_ptr_Promise_CameraState__(std::shared_ptr<Promise<CameraState>> promise) noexcept {
+    return PromiseHolder<CameraState>(std::move(promise));
+  }
+  
   // pragma MARK: std::function<void(const std::exception_ptr& /* error */)>
   /**
    * Specialized version of `std::function<void(const std::exception_ptr&)>`.

package/nitrogen/generated/ios/c++/HybridCesiumViewSpecSwift.hpp

@@ -261,6 +261,13 @@ namespace margelo::nitro::reactnativecesium {
     inline void setOnMetrics(const std::optional<std::function<void(const CesiumMetrics& /* metrics */)>>& onMetrics) noexcept override {
       _swiftPart.setOnMetrics(onMetrics);
     }
+    inline std::optional<std::function<void(const CameraState& /* camera */)>> getOnActualCamera() noexcept override {
+      auto __result = _swiftPart.getOnActualCamera();
+      return __result;
+    }
+    inline void setOnActualCamera(const std::optional<std::function<void(const CameraState& /* camera */)>>& onActualCamera) noexcept override {
+      _swiftPart.setOnActualCamera(onActualCamera);
+    }
 
   public:
     // Methods

package/nitrogen/generated/ios/c++/views/HybridCesiumViewComponent.mm

@@ -219,6 +219,11 @@ using namespace margelo::nitro::reactnativecesium::views;
     swiftPart.setOnMetrics(newViewProps.onMetrics.value);
     newViewProps.onMetrics.isDirty = false;
   }
+  // onActualCamera: optional
+  if (newViewProps.onActualCamera.isDirty) {
+    swiftPart.setOnActualCamera(newViewProps.onActualCamera.value);
+    newViewProps.onActualCamera.isDirty = false;
+  }
 
   swiftPart.afterUpdate();
 

package/nitrogen/generated/ios/swift/Func_void_CameraState.swift

@@ -8,21 +8,21 @@
 import NitroModules
 
 /**
- * Wraps a Swift `(_ value: CameraState) -> Void` as a class.
+ * Wraps a Swift `(_ camera: CameraState) -> Void` as a class.
  * This class can be used from C++, e.g. to wrap the Swift closure as a `std::function`.
  */
 public final class Func_void_CameraState {
   public typealias bridge = margelo.nitro.reactnativecesium.bridge.swift
 
-  private let closure: (_ value: CameraState) -> Void
+  private let closure: (_ camera: CameraState) -> Void
 
-  public init(_ closure: @escaping (_ value: CameraState) -> Void) {
+  public init(_ closure: @escaping (_ camera: CameraState) -> Void) {
     self.closure = closure
   }
 
   @inline(__always)
-  public func call(value: CameraState) -> Void {
-    self.closure(value)
+  public func call(camera: CameraState) -> Void {
+    self.closure(camera)
   }
 
   /**

package/nitrogen/generated/ios/swift/HybridCesiumViewSpec.swift

@@ -38,6 +38,7 @@ public protocol HybridCesiumViewSpec_protocol: HybridObject, HybridView {
   var maxClimbRateMps: Double? { get set }
   var maxGroundSpeedMps: Double? { get set }
   var onMetrics: ((_ metrics: CesiumMetrics) -> Void)? { get set }
+  var onActualCamera: ((_ camera: CameraState) -> Void)? { get set }
 
   // Methods
   func setPosition(latitude: Double, longitude: Double) throws -> Void

package/nitrogen/generated/ios/swift/HybridCesiumViewSpec_cxx.swift

@@ -683,6 +683,38 @@ open class HybridCesiumViewSpec_cxx {
       }()
     }
   }
+  
+  public final var onActualCamera: bridge.std__optional_std__function_void_const_CameraState_____camera______ {
+    @inline(__always)
+    get {
+      return { () -> bridge.std__optional_std__function_void_const_CameraState_____camera______ in
+        if let __unwrappedValue = self.__implementation.onActualCamera {
+          return bridge.create_std__optional_std__function_void_const_CameraState_____camera______({ () -> bridge.Func_void_CameraState in
+            let __closureWrapper = Func_void_CameraState(__unwrappedValue)
+            return bridge.create_Func_void_CameraState(__closureWrapper.toUnsafe())
+          }())
+        } else {
+          return .init()
+        }
+      }()
+    }
+    @inline(__always)
+    set {
+      self.__implementation.onActualCamera = { () -> ((_ camera: CameraState) -> Void)? in
+        if bridge.has_value_std__optional_std__function_void_const_CameraState_____camera______(newValue) {
+          let __unwrapped = bridge.get_std__optional_std__function_void_const_CameraState_____camera______(newValue)
+          return { () -> (CameraState) -> Void in
+            let __wrappedFunction = bridge.wrap_Func_void_CameraState(__unwrapped)
+            return { (__camera: CameraState) -> Void in
+              __wrappedFunction.call(__camera)
+            }
+          }()
+        } else {
+          return nil
+        }
+      }()
+    }
+  }
 
   // Methods
   @inline(__always)

package/nitrogen/generated/shared/c++/HybridCesiumViewSpec.cpp

@@ -70,6 +70,8 @@ namespace margelo::nitro::reactnativecesium {
       prototype.registerHybridSetter("maxGroundSpeedMps", &HybridCesiumViewSpec::setMaxGroundSpeedMps);
       prototype.registerHybridGetter("onMetrics", &HybridCesiumViewSpec::getOnMetrics);
       prototype.registerHybridSetter("onMetrics", &HybridCesiumViewSpec::setOnMetrics);
+      prototype.registerHybridGetter("onActualCamera", &HybridCesiumViewSpec::getOnActualCamera);
+      prototype.registerHybridSetter("onActualCamera", &HybridCesiumViewSpec::setOnActualCamera);
       prototype.registerHybridMethod("setPosition", &HybridCesiumViewSpec::setPosition);
       prototype.registerHybridMethod("setAltitude", &HybridCesiumViewSpec::setAltitude);
       prototype.registerHybridMethod("setHeading", &HybridCesiumViewSpec::setHeading);

package/nitrogen/generated/shared/c++/HybridCesiumViewSpec.hpp

@@ -111,6 +111,8 @@ namespace margelo::nitro::reactnativecesium {
       virtual void setMaxGroundSpeedMps(std::optional<double> maxGroundSpeedMps) = 0;
       virtual std::optional<std::function<void(const CesiumMetrics& /* metrics */)>> getOnMetrics() = 0;
       virtual void setOnMetrics(const std::optional<std::function<void(const CesiumMetrics& /* metrics */)>>& onMetrics) = 0;
+      virtual std::optional<std::function<void(const CameraState& /* camera */)>> getOnActualCamera() = 0;
+      virtual void setOnActualCamera(const std::optional<std::function<void(const CameraState& /* camera */)>>& onActualCamera) = 0;
 
     public:
       // Methods

package/nitrogen/generated/shared/c++/views/HybridCesiumViewComponent.cpp

@@ -306,6 +306,16 @@ namespace margelo::nitro::reactnativecesium::views {
         throw std::runtime_error(std::string("CesiumView.onMetrics: ") + exc.what());
       }
     }()),
+    onActualCamera([&]() -> CachedProp<std::optional<std::function<void(const CameraState& /* camera */)>>> {
+      try {
+        const react::RawValue* rawValue = rawProps.at("onActualCamera", nullptr, nullptr);
+        if (rawValue == nullptr) return sourceProps.onActualCamera;
+        const auto& [runtime, value] = (std::pair<jsi::Runtime*, jsi::Value>)*rawValue;
+        return CachedProp<std::optional<std::function<void(const CameraState& /* camera */)>>>::fromRawValue(*runtime, value.asObject(*runtime).getProperty(*runtime, PropNameIDCache::get(*runtime, "f")), sourceProps.onActualCamera);
+      } catch (const std::exception& exc) {
+        throw std::runtime_error(std::string("CesiumView.onActualCamera: ") + exc.what());
+      }
+    }()),
     hybridRef([&]() -> CachedProp<std::optional<std::function<void(const std::shared_ptr<HybridCesiumViewSpec>& /* ref */)>>> {
       try {
         const react::RawValue* rawValue = rawProps.at("hybridRef", nullptr, nullptr);
@@ -347,6 +357,7 @@ namespace margelo::nitro::reactnativecesium::views {
       case hashString("maxClimbRateMps"): return true;
       case hashString("maxGroundSpeedMps"): return true;
       case hashString("onMetrics"): return true;
+      case hashString("onActualCamera"): return true;
       case hashString("hybridRef"): return true;
       default: return false;
     }

package/nitrogen/generated/shared/c++/views/HybridCesiumViewComponent.hpp

@@ -72,6 +72,7 @@ namespace margelo::nitro::reactnativecesium::views {
     CachedProp<std::optional<double>> maxClimbRateMps;
     CachedProp<std::optional<double>> maxGroundSpeedMps;
     CachedProp<std::optional<std::function<void(const CesiumMetrics& /* metrics */)>>> onMetrics;
+    CachedProp<std::optional<std::function<void(const CameraState& /* camera */)>>> onActualCamera;
     CachedProp<std::optional<std::function<void(const std::shared_ptr<HybridCesiumViewSpec>& /* ref */)>>> hybridRef;
 
   private:

package/nitrogen/generated/shared/json/CesiumViewConfig.json

@@ -32,6 +32,7 @@
     "maxClimbRateMps": true,
     "maxGroundSpeedMps": true,
     "onMetrics": true,
+    "onActualCamera": true,
     "hybridRef": true
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-cesium",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "description": "Experimental Cesium rendering for React Native via Nitro (iOS/Metal today; Android planned)",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/module/index.js",

package/src/specs/cesium-view.nitro.ts

@@ -110,6 +110,15 @@ export interface CesiumViewProps extends HybridViewProps {
   maxGroundSpeedMps?: number
 
   onMetrics?: (metrics: CesiumMetrics) => void
+
+  /**
+   * Called at ~5 Hz with the post-integration actual camera — the same state
+   * returned by `getActualCamera()`. Only fires when at least one field has
+   * changed beyond its epsilon threshold since the last emission, so a
+   * stationary camera produces no bridge traffic. Use this to keep HUD overlay
+   * symbology aligned with the rendered view without polling from JS.
+   */
+  onActualCamera?: (camera: CameraState) => void
 }
 
 /**