react-native-cesium 1.2.8 → 1.2.10

package/android/src/main/cpp/CesiumBridgeAndroid.cpp

@@ -25,12 +25,22 @@ CesiumBridgeAndroid::~CesiumBridgeAndroid() {
 
 void CesiumBridgeAndroid::init(JNIEnv* env, jobject surface, int width, int height,
                                const std::string& cacheDir,
-                               const std::string& cacertPath) {
+                               const std::string& cacertPath,
+                               const std::string& ionAccessToken,
+                               int64_t ionAssetId) {
   config_.cacheDatabasePath = cacheDir.empty() ? "" : cacheDir + "/cesium_cache.db";
   config_.tlsCaBundlePath   = cacertPath;
   viewportWidth_  = width;
   viewportHeight_ = height;
 
+  // Seed the ion credentials before buildEngine so createTileset() can
+  // immediately start the async tileset.json HTTP round-trip, letting it
+  // overlap with Vulkan PSO compilation rather than run serially after it.
+  if (!ionAccessToken.empty()) {
+    config_.ionAccessToken = ionAccessToken;
+    config_.ionAssetId     = ionAssetId;
+  }
+
   // ANativeWindow_fromSurface() acquires one strong reference on the
   // returned window; we own it now and must call ANativeWindow_release() in
   // shutdown() (or before re-acquiring) to avoid leaking it on every view
@@ -302,17 +312,15 @@ void CesiumBridgeAndroid::renderFrame(double nowSeconds) {
 
   // ── Terrain floor clamp ───────────────────────────────────────────────
   const float minAbove = engine_->getConfig().minAltitudeAboveTerrain;
-  if (minAbove > 0.0f) {
-    const double geoidOffset =
+  if (minAbove > 0.0f && engine_->terrainFloorKnown()) {
+    const double geoidN =
         reactnativecesium::mslToEllipsoidMeters(actual.latitude, actual.longitude, 0.0);
-    const double camEllipsoid =
-        reactnativecesium::mslToEllipsoidMeters(actual.latitude, actual.longitude, actual.altitude);
-    const double minEllipsoid =
-        static_cast<double>(engine_->terrainFloorEllipsoidMeters()) + minAbove;
-    if (camEllipsoid < minEllipsoid) {
-      const double clampedMsl = minEllipsoid - geoidOffset;
-      integrator_->clampActualAltitude(clampedMsl);
-      actual.altitude = clampedMsl;
+    const double floorMsl =
+        static_cast<double>(engine_->terrainFloorEllipsoidMeters()) - geoidN;
+    const double minMsl = floorMsl + static_cast<double>(minAbove);
+    if (actual.altitude < minMsl) {
+      integrator_->clampActualAltitude(minMsl);
+      actual.altitude = minMsl;
     }
   }
 
@@ -408,12 +416,15 @@ Java_com_margelo_nitro_reactnativecesium_CesiumBridgeJNI_nativeCreate(JNIEnv*, j
 JNIEXPORT void JNICALL
 Java_com_margelo_nitro_reactnativecesium_CesiumBridgeJNI_nativeInit(
     JNIEnv* env, jobject, jlong ptr, jobject surface, jint w, jint h,
-    jstring cacheDir, jstring cacertPath) {
+    jstring cacheDir, jstring cacertPath, jstring ionAccessToken, jlong ionAssetId) {
   const char* cacheDirC = env->GetStringUTFChars(cacheDir, nullptr);
   const char* cacertC   = env->GetStringUTFChars(cacertPath, nullptr);
-  getBridge(ptr)->init(env, surface, w, h, cacheDirC, cacertC);
+  const char* tokenC    = env->GetStringUTFChars(ionAccessToken, nullptr);
+  getBridge(ptr)->init(env, surface, w, h, cacheDirC, cacertC,
+                       tokenC ? tokenC : "", static_cast<int64_t>(ionAssetId));
   env->ReleaseStringUTFChars(cacheDir, cacheDirC);
   env->ReleaseStringUTFChars(cacertPath, cacertC);
+  env->ReleaseStringUTFChars(ionAccessToken, tokenC);
 }
 
 JNIEXPORT void JNICALL

package/android/src/main/cpp/CesiumBridgeAndroid.h

@@ -36,7 +36,8 @@ struct CesiumBridgeAndroid {
   CesiumBridgeAndroid& operator=(CesiumBridgeAndroid&&) = delete;
 
   void init(JNIEnv* env, jobject surface, int width, int height,
-            const std::string& cacheDir, const std::string& cacertPath);
+            const std::string& cacheDir, const std::string& cacertPath,
+            const std::string& ionAccessToken, int64_t ionAssetId);
   void shutdown();
 
   void resize(int width, int height);

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

@@ -9,8 +9,9 @@ import android.view.Surface
 class CesiumBridgeJNI {
   private var nativePtr: Long = nativeCreate()
 
-  fun init(surface: Surface, width: Int, height: Int, cacheDir: String, cacertPath: String) {
-    nativeInit(nativePtr, surface, width, height, cacheDir, cacertPath)
+  fun init(surface: Surface, width: Int, height: Int, cacheDir: String, cacertPath: String,
+           ionAccessToken: String = "", ionAssetId: Long = 1L) {
+    nativeInit(nativePtr, surface, width, height, cacheDir, cacertPath, ionAccessToken, ionAssetId)
   }
 
   fun shutdown() = nativeShutdown(nativePtr)
@@ -98,7 +99,7 @@ class CesiumBridgeJNI {
   fun setMinAltitudeAboveTerrain(v: Float) = nativeSetMinAltitudeAboveTerrain(nativePtr, v)
 
   private external fun nativeCreate(): Long
-  private external fun nativeInit(ptr: Long, surface: Surface, w: Int, h: Int, cacheDir: String, cacertPath: String)
+  private external fun nativeInit(ptr: Long, surface: Surface, w: Int, h: Int, cacheDir: String, cacertPath: String, ionAccessToken: String, ionAssetId: Long)
   private external fun nativeShutdown(ptr: Long)
   private external fun nativeDestroy(ptr: Long)
   private external fun nativeResize(ptr: Long, w: Int, h: Int)

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

@@ -286,7 +286,12 @@ class HybridCesiumView(private val appContext: Context) : HybridCesiumViewSpec()
       val cacertPath = extractCacert()
       rh.post {
         val b = CesiumBridgeJNI()
-        b.init(surface, w, h, cacheDir, cacertPath)
+        // sqliteCacheMaxRows and taskProcessorThreads are consumed once inside
+        // CesiumEngine::initialize() (SqliteCache + TaskProcessor sizing).
+        // They must be seeded into config_ before init() calls buildEngine().
+        sqliteCacheMaxRows?.let { b.setSqliteCacheMaxRows(it.toInt()) }
+        taskProcessorThreads?.let { b.setTaskProcessorThreads(it.toInt()) }
+        b.init(surface, w, h, cacheDir, cacertPath, ionAccessToken, ionAssetId.toLong())
         bridge = b
         syncBridgePropsOnRenderThread(b)
 
@@ -313,12 +318,13 @@ class HybridCesiumView(private val appContext: Context) : HybridCesiumViewSpec()
           b.setViewCorrection(q.w, q.x, q.y, q.z); pendingViewCorrection = null
         }
 
+        // Ion credentials were seeded at init() time for parallel tileset
+        // fetch; call updateIonAccessToken here only as a hot-reload safety
+        // net in case the token changed between bridge teardown and rebuild.
         if (ionAccessToken.isNotEmpty()) {
           b.updateIonAccessToken(ionAccessToken, ionAssetId.toLong())
         }
-        if (ionImageryAssetId != 1.0) {
-          b.updateImageryAssetId(ionImageryAssetId.toLong())
-        }
+        b.updateImageryAssetId(ionImageryAssetId.toLong())
         b.setMsaa(msaaSampleCount.toInt())
 
         pushRateCaps()
@@ -510,8 +516,8 @@ class HybridCesiumView(private val appContext: Context) : HybridCesiumViewSpec()
     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()) }
+    // sqliteCacheMaxRows and taskProcessorThreads are applied before init() in
+    // surfaceCreated; calling them here (after buildEngine) has no effect.
     minAltitudeAboveTerrain?.let { b.setMinAltitudeAboveTerrain(it.toFloat()) }
   }
 

package/cpp/engine/CesiumEngine.cpp

@@ -13,7 +13,9 @@
 #include <Cesium3DTilesSelection/TilesetExternals.h>
 #include <Cesium3DTilesSelection/TilesetOptions.h>
 #include <CesiumGeospatial/BoundingRegion.h>
+#include <CesiumGeospatial/Ellipsoid.h>
 #include <CesiumGeospatial/GlobeRectangle.h>
+#include <CesiumGeospatial/GlobeTransforms.h>
 #include <CesiumAsync/CachingAssetAccessor.h>
 #include <CesiumAsync/SqliteCache.h>
 #include <CesiumCurl/CurlAssetAccessor.h>
@@ -607,7 +609,8 @@ void CesiumEngine::updateFrame(double w, double h, FrameResult& result) {
   const double camLatRad = glm::radians(camParams.latitude);
   const double camLonRad = glm::radians(camParams.longitude);
   float  bestTerrainFloor = terrainFloorEllipsoidM_; // carry previous value if no tile matches
-  double bestTerrainDist  = std::numeric_limits<double>::max();
+  double bestHorizDistSq  = std::numeric_limits<double>::max();
+  bool   floorScanFound   = false;
 
   // ── floor-scan cache lookup ─────────────────────────────────────────
   // Skip the per-vertex scan when the camera has moved less than ~10 cm in
@@ -630,6 +633,18 @@ void CesiumEngine::updateFrame(double w, double h, FrameResult& result) {
   // semantics aligned).
   const bool runFloorScan = trackTerrainFloor && !floorScanFromCache;
 
+  // ENU basis at the camera — horizontal distance to each terrain vertex.
+  glm::dvec3 floorEast(1.0, 0.0, 0.0);
+  glm::dvec3 floorNorth(0.0, 1.0, 0.0);
+  if (runFloorScan) {
+    const auto& ellipsoid = CesiumGeospatial::Ellipsoid::WGS84;
+    const glm::dmat4 enuToEcef =
+        CesiumGeospatial::GlobeTransforms::eastNorthUpToFixedFrame(
+            cameraPos, ellipsoid);
+    floorEast  = glm::normalize(glm::dvec3(enuToEcef[0]));
+    floorNorth = glm::normalize(glm::dvec3(enuToEcef[1]));
+  }
+
   // ── fast path ────────────────────────────────────────────────────────
   // The visible primitive list has been identical for kMaxFramesInFlight
   // frames in a row, so every backend slot is guaranteed to hold a copy of
@@ -660,10 +675,18 @@ void CesiumEngine::updateFrame(double w, double h, FrameResult& result) {
             for (size_t vi = 0; vi < vc; ++vi) {
               const glm::dvec3 vECEF =
                   glm::dvec3(prim.localPositions[vi]) + prim.rtcCenter;
-              const double dist = glm::length(vECEF - cameraPos);
-              if (dist < bestTerrainDist) {
-                bestTerrainDist  = dist;
+              const glm::dvec3 delta = vECEF - cameraPos;
+              const double    de     = glm::dot(delta, floorEast);
+              const double    dn     = glm::dot(delta, floorNorth);
+              const double    horizSq = de * de + dn * dn;
+              if (horizSq < bestHorizDistSq) {
+                bestHorizDistSq  = horizSq;
                 bestTerrainFloor = prim.altitudes[vi];
+                floorScanFound   = true;
+              } else if (horizSq <= bestHorizDistSq * (1.0 + 1e-9) + 1e-4) {
+                bestTerrainFloor =
+                    std::min(bestTerrainFloor, prim.altitudes[vi]);
+                floorScanFound = true;
               }
             }
           }
@@ -703,8 +726,9 @@ void CesiumEngine::updateFrame(double w, double h, FrameResult& result) {
     result.cameraLon = paramsFP.longitude;
     result.cameraAlt = paramsFP.altitude;
 
-    if (trackTerrainFloor) {
+    if (trackTerrainFloor && (floorScanFound || floorScanFromCache)) {
       terrainFloorEllipsoidM_ = bestTerrainFloor;
+      terrainFloorValid_      = true;
       // P5: refresh the floor cache on a fresh scan; skip when we hit the
       // cache (the stored value already reflects this signature).
       if (runFloorScan && signature != 0ULL) {
@@ -763,10 +787,18 @@ void CesiumEngine::updateFrame(double w, double h, FrameResult& result) {
           for (size_t vi = 0; vi < vertexCount; ++vi) {
             const glm::dvec3 vECEF =
                 glm::dvec3(prim.localPositions[vi]) + prim.rtcCenter;
-            const double dist = glm::length(vECEF - cameraPos);
-            if (dist < bestTerrainDist) {
-              bestTerrainDist  = dist;
+            const glm::dvec3 delta  = vECEF - cameraPos;
+            const double    de      = glm::dot(delta, floorEast);
+            const double    dn      = glm::dot(delta, floorNorth);
+            const double    horizSq = de * de + dn * dn;
+            if (horizSq < bestHorizDistSq) {
+              bestHorizDistSq  = horizSq;
               bestTerrainFloor = prim.altitudes[vi];
+              floorScanFound   = true;
+            } else if (horizSq <= bestHorizDistSq * (1.0 + 1e-9) + 1e-4) {
+              bestTerrainFloor =
+                  std::min(bestTerrainFloor, prim.altitudes[vi]);
+              floorScanFound = true;
             }
           }
         }
@@ -1018,8 +1050,9 @@ void CesiumEngine::updateFrame(double w, double h, FrameResult& result) {
   result.cameraLon     = params.longitude;
   result.cameraAlt     = params.altitude;
 
-  if (trackTerrainFloor) {
+  if (trackTerrainFloor && (floorScanFound || floorScanFromCache)) {
     terrainFloorEllipsoidM_ = bestTerrainFloor;
+    terrainFloorValid_      = true;
     // refresh the floor cache on a fresh scan (slow path always runs a
     // scan unless the cache short-circuit fired above). Only memoise when
     // the geometry signature is stable enough to key on.

package/cpp/engine/CesiumEngine.hpp

@@ -142,10 +142,11 @@ public:
 
   const EngineConfig& getConfig() const { return config_; }
 
-  // Ellipsoid height (metres) of the terrain vertex nearest to the camera nadir,
-  // updated each frame from the loaded tile mesh. 0.0 until the first terrain
-  // tile covering the camera position has been rendered.
+  // Ellipsoid height (metres) of the terrain surface under the camera nadir,
+  // sampled from loaded tile meshes. Meaningless until terrainFloorKnown().
   float terrainFloorEllipsoidMeters() const { return terrainFloorEllipsoidM_; }
+  // True after at least one frame has sampled the floor from real terrain tiles.
+  bool terrainFloorKnown() const { return terrainFloorValid_; }
 
 private:
   void createTileset();
@@ -184,9 +185,10 @@ private:
   GlobeCamera          camera_;
   TileLifecycleManager lifecycle_;
 
-  // Ellipsoid height of the terrain surface at the camera nadir, updated each
-  // frame. Initialised to 0 (sea level) until a terrain tile is first loaded.
+  // Ellipsoid height of the terrain surface at the camera nadir (horizontal
+  // nearest-neighbour sample). Only written after a successful tile scan.
   float terrainFloorEllipsoidM_ = 0.0f;
+  bool  terrainFloorValid_      = false;
 
   // Wall-clock timestamp of the previous updateFrame call. Used to compute
   // deltaTime for Tileset::updateViewGroup, which drives LOD transition fading.
@@ -225,7 +227,8 @@ private:
   // ── terrain-floor scan cache ──────────────────────────────────────
   // The minAltitudeAboveTerrain clamp scans every vertex of every tile whose
   // bounding region contains the camera lon/lat and picks the altitude of
-  // the vertex with the smallest 3D distance to the camera. That's an O(NV)
+  // the vertex with the smallest horizontal (ENU) distance to the camera
+  // nadir (tie-break: lower ellipsoid height). That's an O(NV)
   // scan over the visible primitives — dominant CPU cost when the camera
   // sits over a dense LOD chain. Result depends only on the camera lon/lat
   // and the set of visible primitives, so we cache it keyed on

package/cpp/engine/GlobeCamera.cpp

@@ -12,7 +12,6 @@
 namespace reactnativecesium {
 
 static constexpr double kNearPlane = 1.0;
-static constexpr double kFarPlane  = 50000000.0;
 static constexpr double kMinVfov   = 20.0;
 static constexpr double kMaxVfov   = 100.0;
 

package/ios/CesiumBridge.h

@@ -12,12 +12,17 @@ NS_ASSUME_NONNULL_BEGIN
 /// Pass `ionAccessToken` and `ionAssetId` here so the engine can start the
 /// async tileset.json network round-trip immediately, before Metal pipeline
 /// compilation begins — letting the two operations overlap in time.
+/// `sqliteCacheMaxRows` and `taskProcessorThreads` must also be provided here
+/// because they are consumed once when the SqliteCache / TaskProcessor are
+/// constructed inside `buildEngine`; setting them after init has no effect.
 - (instancetype)initWithMetalLayer:(CAMetalLayer *)layer
                               width:(int)width
                              height:(int)height
                            cacheDir:(NSString *)cacheDir
                     ionAccessToken:(NSString *)token
-                         ionAssetId:(int64_t)assetId;
+                         ionAssetId:(int64_t)assetId
+                 sqliteCacheMaxRows:(int32_t)sqliteRows
+               taskProcessorThreads:(int32_t)threads;
 
 - (void)updateIonAccessToken:(NSString *)token assetId:(int64_t)assetId;
 - (void)updateImageryAssetId:(int64_t)assetId;

package/ios/CesiumBridge.mm

@@ -56,7 +56,9 @@
                              height:(int)height
                            cacheDir:(NSString *)cacheDir
                     ionAccessToken:(NSString *)token
-                         ionAssetId:(int64_t)assetId {
+                         ionAssetId:(int64_t)assetId
+                 sqliteCacheMaxRows:(int32_t)sqliteRows
+               taskProcessorThreads:(int32_t)threads {
   self = [super init];
   if (self) {
     _viewportWidth     = width;
@@ -90,6 +92,16 @@
       _config.ionAssetId     = assetId;
     }
 
+    // These two params are consumed once inside CesiumEngine::initialize()
+    // (SqliteCache constructor and TaskProcessor thread-pool sizing). Setting
+    // them after buildEngine() has no effect, so they must be seeded here.
+    if (sqliteRows > 0) {
+      _config.sqliteCacheMaxRows = std::max<int32_t>(64, sqliteRows);
+    }
+    if (threads >= 0) {
+      _config.taskProcessorThreads = threads;
+    }
+
     _metalBackend = std::make_unique<reactnativecesium::MetalBackend>();
 
     // Start the async tileset.json fetch before Metal PSO compilation so both
@@ -375,17 +387,15 @@
     // Uses terrain floor from the previous frame (one-frame lag is
     // imperceptible at 60 fps). Skipped when minAltitudeAboveTerrain == 0.
     const float minAbove = _engine->getConfig().minAltitudeAboveTerrain;
-    if (minAbove > 0.0f) {
-      const double geoidOffset =
+    if (minAbove > 0.0f && _engine->terrainFloorKnown()) {
+      const double geoidN =
           reactnativecesium::mslToEllipsoidMeters(actual.latitude, actual.longitude, 0.0);
-      const double camEllipsoid =
-          reactnativecesium::mslToEllipsoidMeters(actual.latitude, actual.longitude, actual.altitude);
-      const double minEllipsoid =
-          static_cast<double>(_engine->terrainFloorEllipsoidMeters()) + minAbove;
-      if (camEllipsoid < minEllipsoid) {
-        const double clampedMsl = minEllipsoid - geoidOffset;
-        _integrator->clampActualAltitude(clampedMsl);
-        actual.altitude = clampedMsl;
+      const double floorMsl =
+          static_cast<double>(_engine->terrainFloorEllipsoidMeters()) - geoidN;
+      const double minMsl = floorMsl + static_cast<double>(minAbove);
+      if (actual.altitude < minMsl) {
+        _integrator->clampActualAltitude(minMsl);
+        actual.altitude = minMsl;
       }
     }
 

package/ios/HybridCesiumView.swift

@@ -381,7 +381,9 @@ class HybridCesiumView: HybridCesiumViewSpec {
       height: Int32(h),
       cacheDir: cacheDir,
       ionAccessToken: ionAccessToken,
-      ionAssetId: Int64(ionAssetId)
+      ionAssetId: Int64(ionAssetId),
+      sqliteCacheMaxRows: Int32(sqliteCacheMaxRows ?? 0),
+      taskProcessorThreads: Int32(taskProcessorThreads ?? 0)
     )
 
     syncBridgeOptionsFromProps()
@@ -416,9 +418,7 @@ class HybridCesiumView: HybridCesiumViewSpec {
     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))
-    }
+    bridge?.updateImageryAssetId(Int64(ionImageryAssetId))
 
     let sc = Int32(msaaSampleCount)
     bridge?.setMsaaSampleCount(sc)
@@ -457,8 +457,8 @@ class HybridCesiumView: HybridCesiumViewSpec {
     if let v = culledScreenSpaceError { bridge?.setCulledScreenSpaceError(v) }
     if let v = enableLodTransitionPeriod { bridge?.setEnableLodTransitionPeriod(v) }
     if let v = lodTransitionLength { bridge?.setLodTransitionLength(v) }
-    if let v = sqliteCacheMaxRows { bridge?.setSqliteCacheMaxRows(Int32(v)) }
-    if let v = taskProcessorThreads { bridge?.setTaskProcessorThreads(Int32(v)) }
+    // sqliteCacheMaxRows and taskProcessorThreads are applied at construction
+    // time via the CesiumBridge initializer; calling them here has no effect.
     if let v = minAltitudeAboveTerrain { bridge?.setMinAltitudeAboveTerrain(Float(v)) }
   }
 

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

@@ -57,7 +57,7 @@ export interface CesiumViewProps extends HybridViewProps {
     preloadAncestors?: boolean;
     /** Pre-load sibling tiles around the visible set. Default true. */
     preloadSiblings?: boolean;
-    /** Refuse to render holes in the terrain. Default true. Relax for fast pans. */
+    /** Refuse to render holes in the terrain. Default false (matching Cesium Native). Relax for fast pans. */
     forbidHoles?: boolean;
     /** Decode water-mask textures (coastline shading). Default true. */
     enableWaterMask?: boolean;
@@ -71,15 +71,25 @@ export interface CesiumViewProps extends HybridViewProps {
     enableLodTransitionPeriod?: boolean;
     /** Length (s) of the LOD cross-fade. Default 1. */
     lodTransitionLength?: number;
-    /** Sqlite asset cache row budget. Default 4096. */
+    /**
+     * Sqlite asset cache row budget. Default 4096.
+     * Must be set on initial mount — changes after the first render are ignored
+     * because the cache is opened once at engine construction time.
+     */
     sqliteCacheMaxRows?: number;
-    /** Worker thread count. 0 = auto (hardware_concurrency-1, clamped 2..8). */
+    /**
+     * Worker thread count. 0 = auto (hardware_concurrency-1, clamped 2..16).
+     * Must be set on initial mount — the thread pool is sized once at engine
+     * construction time and cannot be resized at runtime.
+     */
     taskProcessorThreads?: number;
     /**
-     * Minimum altitude above the loaded terrain surface, in metres MSL.
-     * Default 0 (no constraint). Set to e.g. 2 to prevent the camera from going underground.
-     * The clamp is applied every frame in native, based on the altitude of the nearest
-     * terrain mesh vertex to the camera nadir.
+     * Minimum clearance above the loaded terrain surface, in metres (added on top of the
+     * terrain MSL height at the camera position). Default 0 (no constraint).
+     * Set to e.g. 2 to prevent the camera from going underground.
+     * The clamp runs only after terrain tiles have been sampled; until then the demand
+     * altitude is used as-is. The demand altitude is not modified — only the rendered
+     * (actual) camera may be raised to meet this minimum.
      */
     minAltitudeAboveTerrain?: number;
     /** Maximum yaw rate (degrees per second). 0 = uncapped. */

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react-native-cesium",
-  "version": "1.2.8",
-  "description": "Experimental Cesium rendering for React Native via Nitro (iOS/Metal today; Android planned)",
+  "version": "1.2.10",
+  "description": "Experimental Cesium rendering for React Native via Nitro",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -64,7 +64,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "react-native-nitro-modules": "^0.35.6"
+    "react-native-nitro-modules": "^0.35.7"
   },
   "publishConfig": {
     "access": "public",
@@ -77,7 +77,7 @@
     "@types/jest": "^29.5.14",
     "@types/react": "19.2.14",
     "conventional-changelog-conventionalcommits": "^9.3.1",
-    "nitrogen": "0.35.6",
+    "nitrogen": "0.35.7",
     "react": "19.2.3",
     "react-native": "0.85.3",
     "react-native-builder-bob": "^0.41.0",

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

@@ -61,13 +61,17 @@ export interface CesiumViewProps extends HybridViewProps {
   ionImageryAssetId: number
 
   // ── Optional perf / quality knobs ────────────────────────────────────────
+  // Note: all optional props below use "set once" semantics. Once a value has
+  // been applied to the native engine, removing the prop (returning it to
+  // `undefined`) does NOT revert the engine to its built-in default — the last
+  // explicitly set value is retained. To reset, pass the desired default value.
   /** RAM budget for live tileset, in mebibytes. Default 256. */
   maximumCachedMiB?: number
   /** Pre-load ancestor tiles around the visible set (smoother panning, more loads). Default true. */
   preloadAncestors?: boolean
   /** Pre-load sibling tiles around the visible set. Default true. */
   preloadSiblings?: boolean
-  /** Refuse to render holes in the terrain. Default true. Relax for fast pans. */
+  /** Refuse to render holes in the terrain. Default false (matching Cesium Native). Relax for fast pans. */
   forbidHoles?: boolean
   /** Decode water-mask textures (coastline shading). Default true. */
   enableWaterMask?: boolean
@@ -81,15 +85,25 @@ export interface CesiumViewProps extends HybridViewProps {
   enableLodTransitionPeriod?: boolean
   /** Length (s) of the LOD cross-fade. Default 1. */
   lodTransitionLength?: number
-  /** Sqlite asset cache row budget. Default 4096. */
+  /**
+   * Sqlite asset cache row budget. Default 4096.
+   * Must be set on initial mount — changes after the first render are ignored
+   * because the cache is opened once at engine construction time.
+   */
   sqliteCacheMaxRows?: number
-  /** Worker thread count. 0 = auto (hardware_concurrency-1, clamped 2..8). */
+  /**
+   * Worker thread count. 0 = auto (hardware_concurrency-1, clamped 2..16).
+   * Must be set on initial mount — the thread pool is sized once at engine
+   * construction time and cannot be resized at runtime.
+   */
   taskProcessorThreads?: number
   /**
-   * Minimum altitude above the loaded terrain surface, in metres MSL.
-   * Default 0 (no constraint). Set to e.g. 2 to prevent the camera from going underground.
-   * The clamp is applied every frame in native, based on the altitude of the nearest
-   * terrain mesh vertex to the camera nadir.
+   * Minimum clearance above the loaded terrain surface, in metres (added on top of the
+   * terrain MSL height at the camera position). Default 0 (no constraint).
+   * Set to e.g. 2 to prevent the camera from going underground.
+   * The clamp runs only after terrain tiles have been sampled; until then the demand
+   * altitude is used as-is. The demand altitude is not modified — only the rendered
+   * (actual) camera may be raised to meet this minimum.
    */
   minAltitudeAboveTerrain?: number
 
@@ -98,6 +112,8 @@ export interface CesiumViewProps extends HybridViewProps {
   // angular / linear speed on the integrator's per-DoF velocity. Useful when
   // your sensor feed is noisy and you would rather drop the change than
   // visually whip the camera.
+  // Note: same "set once" semantics as the knobs above — removing the prop
+  // keeps the last value rather than reverting to 0 (uncapped).
   /** Maximum yaw rate (degrees per second). 0 = uncapped. */
   maxYawRateDegSec?: number
   /** Maximum pitch rate (degrees per second). 0 = uncapped. */