react-native-cesium 1.2.6 → 1.2.8

package/cpp/engine/CesiumEngine.hpp

@@ -11,6 +11,7 @@
 #include <CesiumAsync/IAssetAccessor.h>
 #include <CesiumUtility/IntrusivePointer.h>
 
+#include <chrono>
 #include <memory>
 #include <string>
 
@@ -54,9 +55,18 @@ struct EngineConfig {
   bool preloadSiblings  = true;
 
   // Refuse to render holes in the terrain (Cesium will keep ancestor tiles
-  // visible until all children load). Relax during fast pans to lower
-  // upload pressure.
-  bool forbidHoles = true;
+  // visible until all children load).  Cesium Native's default is `false`.
+  //
+  // We default to `false` (matching Cesium Native) because `true` serialises
+  // the load tree on the deepest-child critical path: a parent at LOD N
+  // cannot be rendered until every descendant down to the selected LOD has
+  // arrived.  For a typical Alps view that's 5-6 levels deep × ~4 tiles per
+  // level fan-out = a ~30-60 s critical path even with cache hits.  Setting
+  // this to `false` lets the renderer show the best tile it has *now* and
+  // refine progressively — the same UX as CesiumJS / Google Earth.
+  // Brief low-LOD pop-ins during fast pans are an acceptable trade for
+  // first-frame correctness in seconds rather than tens of seconds.
+  bool forbidHoles = false;
 
   // Water-mask textures (carries coastline shading data). Cheap to disable on
   // memory-constrained devices.
@@ -71,12 +81,25 @@ struct EngineConfig {
   // Seconds an unused tile remains in memory before being evicted.
   double tileCacheUnloadTimeInSeconds = 5.0;
 
+  // Soft cap (ms) on per-frame main-thread tile finalisation work.  Cesium
+  // Native's default of 0.0 means "complete every pending main-thread load
+  // every tick", which on a heavy startup burst can stall the render thread
+  // for hundreds of ms at a time — the user sees the scene "lock up" while
+  // tiles upload.  20 ms keeps the render thread responsive at 30 Hz minimum
+  // (16.67 ms = one frame at 60 Hz; we sacrifice the worst-case frame during
+  // startup bursts but never go below 30 Hz interactivity).  Lower values
+  // (5–10 ms) make individual frames smoother but visibly extend total load
+  // time because finalisation is throughput-bound: ~5 ms per tile, so a
+  // 5 ms cap → only 1 tile finalised per frame → ~60 tiles/sec ceiling
+  // regardless of how many CPUs are decoding in parallel.
+  double mainThreadLoadingTimeLimitMs = 20.0;
+
   // ── Disk cache (SqliteCache) ─────────────────────────────────────────
   int32_t sqliteCacheMaxRows = tunables::kDefaultSqliteCacheMaxRows;
 
   // ── Worker pool ──────────────────────────────────────────────────────
   // 0 means "auto-detect" via std::thread::hardware_concurrency() clamped to
-  // [2, 8]. Override only for benchmarking / regression testing.
+  // [2, 16]. Override only for benchmarking / regression testing.
   int32_t taskProcessorThreads = 0;
 
   // ── Camera constraints ───────────────────────────────────────────────
@@ -165,9 +188,55 @@ private:
   // frame. Initialised to 0 (sea level) until a terrain tile is first loaded.
   float terrainFloorEllipsoidM_ = 0.0f;
 
+  // Wall-clock timestamp of the previous updateFrame call. Used to compute
+  // deltaTime for Tileset::updateViewGroup, which drives LOD transition fading.
+  // Zero-initialised "not yet set" state — first frame passes 0 deltaTime.
+  std::chrono::steady_clock::time_point lastFrameTime_{};
+  bool                                  hasLastFrameTime_ = false;
+
   // Pre-computed fallback ellipsoid geometry (ECEF, absolute).
   std::vector<glm::dvec3> ellipsoidPositions_;
   std::vector<uint32_t>   ellipsoidIndices_;
+
+  // ── frame-signature cache ─────────────────────────────────────────
+  // Signature is hashed over the tilesToRenderThisFrame primitive pointers
+  // and counts. When the same signature appears for kMaxFramesInFlight
+  // consecutive frames *and* no LOD fades are active, we know every backend
+  // slot's persistent geometry buffer already holds the right bytes, so we
+  // can skip rebuilding the merged CPU arrays entirely. On the fast path we
+  // still emit one DrawPrimitive per visible primitive (re-reading overlay /
+  // water-mask state from TileGPUResources and recomputing per-tile MVP for
+  // camera motion), but the heavy per-vertex memcpys are gone.
+  struct CachedDraw {
+    const TileGPUResources* res;
+    glm::dvec3              rtcCenter;
+    uint32_t                indexByteOffset;
+    uint32_t                indexCount;
+    bool                    hasUVs;
+    glm::vec4               wmTileBounds;
+  };
+  std::vector<CachedDraw> cachedDraws_;
+  uint64_t                lastDrawSignature_    = 0;
+  // Consecutive frames where geometrySignature has been the same non-zero
+  // value. Once this reaches kMaxFramesInFlight every persistent buffer slot
+  // is guaranteed to contain the right bytes — fast path becomes legal.
+  int                     stableSigFrames_      = 0;
+
+  // ── 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)
+  // 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
+  // (camLon, camLat, geometrySignature). Threshold of ~1e-6 degrees (~10 cm)
+  // is far below the inter-vertex spacing of the densest tiles served by
+  // Cesium Ion world terrain, so the cached nearest vertex stays correct.
+  bool     floorCacheValid_      = false;
+  double   floorCacheCamLonDeg_  = 0.0;
+  double   floorCacheCamLatDeg_  = 0.0;
+  uint64_t floorCacheSignature_  = 0;
+  float    floorCacheValue_      = 0.0f;
 };
 
 } // namespace reactnativecesium

package/cpp/engine/EngineTunables.hpp

@@ -118,6 +118,13 @@ inline constexpr double kVelocityBleedTauFactor     = 2.0;
 // EWMA blend coefficient for the inter-arrival mean. Higher = faster adapt
 // to cadence changes (e.g. user switches from gesture to sparse GPS feed).
 inline constexpr double kIntervalEwmaAlpha          = 0.3;
+// Demand-pull time constant (seconds). When measurements have stopped
+// arriving (silence > grace), the actual value is gently pulled toward
+// the last demand at this rate. This guarantees convergence for one-shot
+// API calls (e.g. setAltitude from a button) without affecting continuous
+// sensor or gesture streams — those always deliver a new measurement before
+// the grace window expires, so this term is never active. 0 = disabled.
+inline constexpr double kDemandPullTauSec           = 0.8;
 
 // Optional outlier rejection (off if 0). When > 0, a single measurement whose
 // residual against the predicted state exceeds the threshold is dropped (and

package/cpp/renderer/RenderTypes.hpp

@@ -71,6 +71,11 @@ struct DrawPrimitive {
   // reconstruct the world position as  wp = localPos + rtcCenterEcef,  which
   // avoids the catastrophic cancellation of eyeRelPos + cameraEcef at altitude.
   glm::vec3 rtcCenterEcef{0.0f};
+
+  // LOD transition dither threshold from TileRenderContent::getLodTransitionFadePercentage().
+  // 1.0 = fully visible (no dither); 0.0 = fully hidden.  Both tilesToRenderThisFrame
+  // (fading in, 0→1) and tilesFadingOut (fading out, →0) use this field.
+  float     lodFade = 1.0f;
 };
 
 struct FrameResult {
@@ -101,6 +106,14 @@ struct FrameResult {
   bool                     tilesetActive      = false;
   double                   verticalFovDeg     = 60.0;
   std::vector<std::string> creditHtmlLines;
+
+  // hash over the bytes that get merged into localPositions / altitudes /
+  // uvs / indices. Backends compare this against their per-slot cache and
+  // skip the host→GPU memcpy when it matches (the buffers already hold the
+  // exact same bytes). 0 means "force upload" — set by the engine whenever
+  // anything that affects the merged arrays may have changed (active LOD
+  // fade, tileset rebuild, overlay swap, ellipsoid fallback path, etc).
+  uint64_t geometrySignature = 0;
 };
 
 // ── Frame setup ─────────────────────────────────────────────────────────────

package/ios/CesiumBridge.h

@@ -8,10 +8,16 @@ NS_ASSUME_NONNULL_BEGIN
 // in shared C++ next to CesiumEngine.
 @interface CesiumBridge : NSObject
 
+/// Designated initialiser.
+/// 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.
 - (instancetype)initWithMetalLayer:(CAMetalLayer *)layer
-                             width:(int)width
-                            height:(int)height
-                         cacheDir:(NSString *)cacheDir;
+                              width:(int)width
+                             height:(int)height
+                           cacheDir:(NSString *)cacheDir
+                    ionAccessToken:(NSString *)token
+                         ionAssetId:(int64_t)assetId;
 
 - (void)updateIonAccessToken:(NSString *)token assetId:(int64_t)assetId;
 - (void)updateImageryAssetId:(int64_t)assetId;

package/ios/CesiumBridge.mm

@@ -41,13 +41,22 @@
   // and recreates the bridge does not pollute the new bridge's first frame.
   double _lastTickSec;
 
+  // Last time tilesLoading was > 0. Used to keep the render loop at full speed
+  // for a grace period after loading finishes so LOD transitions can complete
+  // quickly and updateViewGroup can immediately discover the next refinement
+  // level — preventing the cascade of 5-second idle gaps between load phases.
+  // Sentinel (epoch) means "no loading seen yet".
+  std::chrono::steady_clock::time_point _lastLoadingTime;
+
   NSString* _cacheDir;
 }
 
 - (instancetype)initWithMetalLayer:(CAMetalLayer *)layer
-                             width:(int)width
-                            height:(int)height
-                         cacheDir:(NSString *)cacheDir {
+                              width:(int)width
+                             height:(int)height
+                           cacheDir:(NSString *)cacheDir
+                    ionAccessToken:(NSString *)token
+                         ionAssetId:(int64_t)assetId {
   self = [super init];
   if (self) {
     _viewportWidth     = width;
@@ -72,10 +81,23 @@
             @"ios/cacert.pem (run pod install).");
     }
 
+    // Seed the ion credentials before buildEngine so createTileset() can
+    // immediately start the async tileset.json HTTP round-trip. This request
+    // (~1.7 s network) will then run concurrently with Metal PSO compilation
+    // below rather than serially after it.
+    if (token.length > 0) {
+      _config.ionAccessToken = std::string([token UTF8String]);
+      _config.ionAssetId     = assetId;
+    }
+
     _metalBackend = std::make_unique<reactnativecesium::MetalBackend>();
-    _metalBackend->initialize((__bridge void*)layer, width, height);
 
+    // Start the async tileset.json fetch before Metal PSO compilation so both
+    // operations run concurrently. The network round-trip (~1.7 s) overlaps
+    // with pipeline compilation rather than waiting behind it.
     [self buildEngine];
+    _metalBackend->initialize((__bridge void*)layer, width, height);
+
     _initialized = YES;
 
     [[NSNotificationCenter defaultCenter]
@@ -306,8 +328,34 @@
 - (BOOL)shouldRenderNextFrame {
   if (!_initialized || _suspended || !_engine) return NO;
   if (_forceRender.load(std::memory_order_acquire))            return YES;
-  if (_frameResult.tilesLoading > 0 || !_frameResult.tilesetActive) return YES;
+  if (!_frameResult.tilesetActive)                             return YES;
+  if (_frameResult.tilesLoading > 0)                          return YES;
   if (_integrator && _integrator->isActive())                  return YES;
+  // ── Post-loading grace period ─────────────────────────────────────────────
+  // Keep the render loop at full speed for 2 seconds after the last non-zero
+  // loading frame. This fixes a cascade of multi-second idle gaps that
+  // otherwise appear between load phases:
+  //
+  //  1. Loading queue drains → shouldRenderNextFrame returns NO
+  //  2. Loop drops to 4 fps (0.25 s idle probe)
+  //  3. deltaTime is clamped to 100 ms → a 0.5 s LOD fade takes 5 idle
+  //     frames × 0.25 s = 1.25 s of wall-clock time instead of 0.5 s
+  //  4. kickDescendantsWhileFadingIn=true means descendants can't be
+  //     *requested* until the parent finishes fading
+  //  5. loadTiles() is only called inside renderFrame, so tile requests are
+  //     throttled to 4 per second during idle
+  //  The net effect: each of the ~5 refinement levels adds a 5-second gap.
+  //
+  // With a 2-second grace period:
+  //  • LOD fades complete at full speed (0.5 s real, not 1.25 s)
+  //  • updateViewGroup discovers the next level immediately after the fade
+  //  • Workers start downloading before we ever slow down
+  //  → The 5-second inter-phase gaps collapse to ~0.5 s
+  if (_lastLoadingTime.time_since_epoch().count() > 0) {
+    const double secSinceLoad = std::chrono::duration<double>(
+        std::chrono::steady_clock::now() - _lastLoadingTime).count();
+    if (secSinceLoad < 2.0) return YES;
+  }
   return NO;
 }
 
@@ -344,6 +392,13 @@
     _engine->camera().setParams(actual);
 
     _engine->updateFrame(_viewportWidth, _viewportHeight, _frameResult);
+
+    // Track the last time tiles were actively loading so shouldRenderNextFrame
+    // can suppress the idle transition for a grace period (see that method).
+    if (_frameResult.tilesLoading > 0) {
+      _lastLoadingTime = std::chrono::steady_clock::now();
+    }
+
     // For metrics purposes only — keeps the FPS EMA in something close to the
     // wall-clock cadence. Not used by the integrator.
     double dt = (_lastTickSec > 0.0) ? (nowSeconds - _lastTickSec) : (1.0 / 60.0);

package/ios/HybridCesiumView.swift

@@ -372,20 +372,22 @@ class HybridCesiumView: HybridCesiumViewSpec {
       .cachesDirectory, .userDomainMask, true
     ).first ?? NSTemporaryDirectory()
 
+    // Pass the ion token at construction time so the engine can start the
+    // tileset.json network round-trip immediately, before Metal PSO compilation
+    // begins (the two operations then overlap rather than run in series).
     bridge = CesiumBridge(
       metalLayer: metalLayer,
       width: Int32(w),
       height: Int32(h),
-      cacheDir: cacheDir
+      cacheDir: cacheDir,
+      ionAccessToken: ionAccessToken,
+      ionAssetId: Int64(ionAssetId)
     )
 
     syncBridgeOptionsFromProps()
 
-    if !ionAccessToken.isEmpty {
-      bridge?.updateIonAccessToken(ionAccessToken, assetId: Int64(ionAssetId))
-    }
-    // Seed from initialCamera, then replay anything the consumer set before
-    // we were ready.
+    // Seed the camera so the very first updateViewGroup call (which fires in
+    // the first renderFrame after init) uses the correct view position.
     let seed = pendingTeleport ?? initialCamera
     bridge?.teleportLatitude(seed.latitude,
                              longitude: seed.longitude,
@@ -396,6 +398,13 @@ class HybridCesiumView: HybridCesiumViewSpec {
                              verticalFovDeg: seed.verticalFovDeg)
     pendingTeleport = nil
 
+    // updateIonAccessToken is a no-op here (token already in config from the
+    // constructor) but is kept for safety in case of hot-reload where the
+    // token changes between bridge teardown and reconstruction.
+    if !ionAccessToken.isEmpty {
+      bridge?.updateIonAccessToken(ionAccessToken, assetId: Int64(ionAssetId))
+    }
+
     if let la = pendingLat, let lo = pendingLon {
       bridge?.setPositionLatitude(la, longitude: lo); pendingLat = nil; pendingLon = nil
     }
@@ -471,9 +480,17 @@ class HybridCesiumView: HybridCesiumViewSpec {
     if hasConfiguredFrameRate && usingLowRefreshRate == idle { return }
     hasConfiguredFrameRate = true
     usingLowRefreshRate = idle
+    // Active range tops out at ProMotion's 120 Hz — on a 60 Hz panel iOS just
+    // clamps to 60 and ignores the upper bound, so this is safe on every
+    // device.  The lower bound (60 Hz) prevents iOS from dynamically dropping
+    // to 30 Hz mid-gesture if the system thinks the scene is "static enough"
+    // (which is what produced the visible camera/terrain judder during
+    // continuous pitch/roll motion — the input was smooth, the render rate
+    // wasn't).  Idle range stays low to preserve power when the camera and
+    // tileset are at rest.
     dl.preferredFrameRateRange = idle
-      ? CAFrameRateRange(minimum: 5, maximum: 15, preferred: 10)
-      : CAFrameRateRange(minimum: 30, maximum: 60, preferred: 60)
+      ? CAFrameRateRange(minimum: 5,  maximum: 15,  preferred: 10)
+      : CAFrameRateRange(minimum: 60, maximum: 120, preferred: 120)
   }
 
   /// Invoked by `DisplayLinkProxy` on every CADisplayLink tick (main thread).

package/ios/metal/MetalBackend.h

@@ -43,8 +43,13 @@ private:
   void* device_;               // id<MTLDevice>
   void* commandQueue_;         // id<MTLCommandQueue>
   void* metalLayer_;           // CAMetalLayer* (weak — owned by the view)
-  void* terrainPipeline_;      // id<MTLRenderPipelineState>
-  void* skyPipeline_;          // id<MTLRenderPipelineState>
+  // Two terrain pipelines built from the same MSL source.  The solid pipeline
+  // omits the LOD-fade discard so Apple TBDR Hidden Surface Removal stays
+  // enabled at full speed for the 99% of tiles not currently transitioning.
+  // The dither pipeline is used only for draws where DrawPrimitive::lodFade<1.
+  void* terrainSolidPipeline_;  // id<MTLRenderPipelineState> (no discard)
+  void* terrainDitherPipeline_; // id<MTLRenderPipelineState> (LOD-fade dither)
+  void* skyPipeline_;           // id<MTLRenderPipelineState>
   void* terrainDepthState_;    // reversed-Z GREATER, write=YES
   void* skyDepthState_;        // Always, write=NO
   void* depthTexture_;              // id<MTLTexture>
@@ -77,6 +82,21 @@ private:
   size_t idxCaps_[kMaxFramesInFlight];
   size_t uvCaps_[kMaxFramesInFlight];
   size_t altCaps_[kMaxFramesInFlight];
+
+  // per-draw uniforms ring. One MTLBuffer per frame slot, filled with
+  // [draw0 VS uniforms][draw0 FS uniforms][draw1 VS][draw1 FS]… each padded
+  // to kUniformAlign so setVertexBufferOffset / setFragmentBufferOffset can
+  // index into it without re-binding the buffer each draw. Replaces the
+  // per-draw setVertexBytes/setFragmentBytes calls that show up as encoder
+  // overhead on the GPU frame capture.
+  static constexpr size_t kUniformAlign = 256;
+  void*  uniformsBufs_[kMaxFramesInFlight]; // id<MTLBuffer>
+  size_t uniformsCaps_[kMaxFramesInFlight];
+
+  // per-slot geometry signature cache. Same semantics as the Vulkan
+  // backend's geomSlotSig_: when FrameResult::geometrySignature matches the
+  // value last written to this slot we skip the merged-geometry memcpy.
+  uint64_t geomSlotSig_[kMaxFramesInFlight] = {};
 };
 
 } // namespace reactnativecesium