react-native-cesium 1.2.6 → 1.2.8

package/cpp/engine/CesiumEngine.cpp

@@ -5,12 +5,6 @@
 
 #include "CesiumEngine.hpp"
 
-#ifdef __ANDROID__
-#include <android/log.h>
-#define ENGINE_LOGI(...) __android_log_print(ANDROID_LOG_INFO, "CesiumEngine", __VA_ARGS__)
-#else
-#define ENGINE_LOGI(...)
-#endif
 
 #include <Cesium3DTilesContent/registerAllTileContentTypes.h>
 #include <Cesium3DTilesSelection/BoundingVolume.h>
@@ -38,8 +32,10 @@
 
 #include <algorithm>
 #include <cmath>
+#include <cstring>
 #include <thread>
 
+
 namespace reactnativecesium {
 
 int32_t CesiumEngine::resolveTaskThreadCount(int32_t requested) {
@@ -47,9 +43,15 @@ int32_t CesiumEngine::resolveTaskThreadCount(int32_t requested) {
   unsigned int hw = std::thread::hardware_concurrency();
   if (hw == 0) return 4;
   // Reserve one core for the UI / display thread; clamp into a sensible band.
+  // The upper bound was 8 historically but modern phones / tablets routinely
+  // ship 8-10 cores (iPhone 15 Pro, iPad M2/M4, Pixel 8 Pro, Galaxy S24
+  // Ultra) and tile decoding (Draco, KTX2, glTF parse) is embarrassingly
+  // parallel — capping at 8 left half the CPU idle during cold-start tile
+  // burst.  16 covers everything up to a Mac M4 Pro and is harmless on
+  // smaller chips because we simply create empty workers.
   int32_t target = static_cast<int32_t>(hw) - 1;
-  if (target < 2) target = 2;
-  if (target > 8) target = 8;
+  if (target < 2)  target = 2;
+  if (target > 16) target = 16;
   return target;
 }
 
@@ -276,6 +278,10 @@ void CesiumEngine::createTileset() {
   opts.culledScreenSpaceError = std::max(1.0, config_.culledScreenSpaceError);
   opts.enableLodTransitionPeriod = config_.enableLodTransitionPeriod;
   opts.lodTransitionLength = std::max(0.0, config_.lodTransitionLength);
+  // Rate-limit per-frame main-thread tile finalisation so the render thread
+  // stays responsive during heavy startup bursts (see EngineConfig docs).
+  opts.mainThreadLoadingTimeLimit =
+      std::max(0.0, config_.mainThreadLoadingTimeLimitMs);
 
   tileset_ = std::make_unique<Cesium3DTilesSelection::Tileset>(
       externals, config_.ionAssetId, config_.ionAccessToken, opts);
@@ -359,6 +365,11 @@ bool CesiumEngine::applyRuntimeConfig(const EngineConfig& cfg) {
     opts.lodTransitionLength = newLodLen;
     changed = true;
   }
+  const double newMainLimit = std::max(0.0, cfg.mainThreadLoadingTimeLimitMs);
+  if (opts.mainThreadLoadingTimeLimit != newMainLimit) {
+    opts.mainThreadLoadingTimeLimit = newMainLimit;
+    changed = true;
+  }
   return changed;
 }
 
@@ -379,6 +390,18 @@ void CesiumEngine::applyImageryOverlay(int64_t targetAssetId) {
     tileset_->getOverlays().add(ov);
     currentOverlay_ = ov;
   }
+
+  // an overlay swap mutates res->overlayTexture pointers on already-loaded
+  // tiles. The fast path re-reads the texture from `res` each frame so output
+  // pixels stay correct, but burn one stale frame to be safe: drop the cache
+  // and force the engine to take the slow path again until N stable frames
+  // confirm the new state.
+  lastDrawSignature_   = 0;
+  stableSigFrames_     = 0;
+  cachedDraws_.clear();
+  // floor cache is keyed on signature — drop it too so the next frame
+  // re-scans before establishing a new entry.
+  floorCacheValid_     = false;
 }
 
 void CesiumEngine::destroyTileset() {
@@ -388,6 +411,14 @@ void CesiumEngine::destroyTileset() {
   if (taskProcessor_) {
     taskProcessor_->waitUntilIdle();
   }
+  // every TileGPUResources* baked into cachedDraws_ has just been freed.
+  // Clearing the cache guarantees no dangling pointer survives into the next
+  // updateFrame and forces a clean slow-path rebuild.
+  lastDrawSignature_   = 0;
+  stableSigFrames_     = 0;
+  cachedDraws_.clear();
+  // P5: the cached value was keyed on TileGPUResources we just freed.
+  floorCacheValid_     = false;
 }
 
 void CesiumEngine::setImageryAssetId(int64_t assetId) {
@@ -396,6 +427,19 @@ void CesiumEngine::setImageryAssetId(int64_t assetId) {
   applyImageryOverlay(config_.ionImageryAssetId);
 }
 
+namespace {
+// FNV-1a 64-bit hash mix. Used to compute the geometry signature from the
+// ordered list of (TileGPUResources*, primitive*, primitive.indices.size())
+// triples for tilesToRenderThisFrame. Two frames whose visible primitives
+// hash to the same value are guaranteed (modulo astronomically unlikely
+// 64-bit collision) to produce identical merged vertex / index / UV buffers.
+inline uint64_t fnv1a64Mix(uint64_t h, uint64_t v) {
+  h ^= v;
+  h *= 0x100000001b3ULL;
+  return h;
+}
+} // namespace
+
 void CesiumEngine::updateFrame(double w, double h, FrameResult& result) {
   result.localPositions.clear();
   result.altitudes.clear();
@@ -403,6 +447,7 @@ void CesiumEngine::updateFrame(double w, double h, FrameResult& result) {
   result.indices.clear();
   result.draws.clear();
   result.creditHtmlLines.clear();
+  result.geometrySignature = 0;
 
   result.ionTokenConfigured = !config_.ionAccessToken.empty();
   result.tilesetActive      = (tileset_ != nullptr);
@@ -422,6 +467,9 @@ void CesiumEngine::updateFrame(double w, double h, FrameResult& result) {
 
   if (!tileset_) {
     appendEllipsoidDraws(result);
+    lastDrawSignature_ = 0;
+    stableSigFrames_   = 0;
+    cachedDraws_.clear();
     lifecycle_.advanceFrame();
     return;
   }
@@ -433,9 +481,22 @@ void CesiumEngine::updateFrame(double w, double h, FrameResult& result) {
 
   asyncSystem_.dispatchMainThreadTasks();
 
+  // Wall-clock deltaTime since previous frame. Cesium Native requires this to
+  // advance LOD transition fade percentages (without it, fade stays at 0 and
+  // newly-selected tiles never become visible). Clamped to a max of 100ms so a
+  // long pause / app foreground transition doesn't instantly complete fades.
+  const auto now = std::chrono::steady_clock::now();
+  float deltaTime = 0.0f;
+  if (hasLastFrameTime_) {
+    const auto diff = std::chrono::duration<float>(now - lastFrameTime_).count();
+    deltaTime = std::min(diff, 0.1f);
+  }
+  lastFrameTime_    = now;
+  hasLastFrameTime_ = true;
+
   const auto viewState     = camera_.computeViewState(w, h);
   const auto& updateResult =
-      tileset_->updateViewGroup(tileset_->getDefaultViewGroup(), {viewState});
+      tileset_->updateViewGroup(tileset_->getDefaultViewGroup(), {viewState}, deltaTime);
   tileset_->loadTiles();
 
   // Only emit the fallback ellipsoid when no real terrain is being rendered
@@ -444,6 +505,12 @@ void CesiumEngine::updateFrame(double w, double h, FrameResult& result) {
   const bool noVisibleTerrain = updateResult.tilesToRenderThisFrame.empty();
   if (noVisibleTerrain) {
     appendEllipsoidDraws(result);
+    // Ellipsoid fallback emits its own geometry; any cached terrain state is
+    // stale until real tiles arrive. Reset so fast path can't fire on the
+    // very next frame after a tile re-appears.
+    lastDrawSignature_ = 0;
+    stableSigFrames_   = 0;
+    cachedDraws_.clear();
   }
 
   if (creditSystem_) {
@@ -457,6 +524,81 @@ void CesiumEngine::updateFrame(double w, double h, FrameResult& result) {
     }
   }
 
+  // ── geometry signature ────────────────────────────────────────────
+  // Fingerprint the ordered visible primitive list. When the same fingerprint
+  // shows up for kMaxFramesInFlight consecutive frames *and* there are no
+  // LOD-fade draws, every backend slot's persistent buffer already holds the
+  // right bytes — the fast path can then skip the entire merge loop and the
+  // memcpys it produces.
+  uint64_t signature = 0xcbf29ce484222325ULL; // FNV-1a 64-bit offset basis
+  if (!noVisibleTerrain) {
+    for (const auto& tile : updateResult.tilesToRenderThisFrame) {
+      if (!tile) continue;
+      const auto* rc = tile->getContent().getRenderContent();
+      if (!rc) continue;
+      const auto* res = static_cast<const TileGPUResources*>(rc->getRenderResources());
+      if (!res) continue;
+      signature = fnv1a64Mix(signature, reinterpret_cast<uint64_t>(res));
+      signature = fnv1a64Mix(signature,
+                              static_cast<uint64_t>(res->primitives.size()));
+      for (const auto& prim : res->primitives) {
+        signature = fnv1a64Mix(signature, reinterpret_cast<uint64_t>(&prim));
+        signature = fnv1a64Mix(signature,
+                                static_cast<uint64_t>(prim.indices.size()));
+      }
+    }
+    // Reserve 0 as the "force upload" sentinel; we should never emit 0 as a
+    // valid signature.
+    if (signature == 0ULL) signature = 1ULL;
+  } else {
+    signature = 0ULL;
+  }
+
+  // ── scan tilesFadingOut for any in-flight fades ──────────────────────
+  // Fast path is illegal whenever a single fading-out draw would be emitted
+  // (lodFade < 1 means the per-tile dither cutoff changes every frame and the
+  // emitted set of draws may grow/shrink mid-transition).
+  bool anyFadeDraws = false;
+  for (const auto& tile : updateResult.tilesFadingOut) {
+    if (!tile) continue;
+    const auto* rc = tile->getContent().getRenderContent();
+    if (!rc) continue;
+    if (1.0f - rc->getLodTransitionFadePercentage() > 0.0f) {
+      anyFadeDraws = true;
+      break;
+    }
+  }
+
+  // ── update stability counter ─────────────────────────────────────────
+  // IMPORTANT: reset to 0, NOT 1. Setting it to 1 was an off-by-one that
+  // let the fast path fire while one slot still held the previous signature:
+  //   fi=A (reset to 1): slow path → geomSlotSig_[A]=sig
+  //   fi=B (counter=2) : slow path → geomSlotSig_[B]=sig
+  //   fi=C (counter=3≥3): fast path → geomSlotSig_[C] STILL stale → blank!
+  // With reset=0 the fast path is deferred until ALL kMaxFramesInFlight
+  // slots have been written with the current signature.
+  if (!noVisibleTerrain && signature != 0ULL) {
+    if (signature == lastDrawSignature_) {
+      ++stableSigFrames_;
+    } else {
+      stableSigFrames_   = 0;
+      lastDrawSignature_ = signature;
+      cachedDraws_.clear();
+    }
+  }
+
+  // NOTE: must be STRICTLY GREATER (>) than kMaxFramesInFlight, not >=.
+  // With >= kMaxFramesInFlight the fast path fires on the Nth stable frame,
+  // which is exactly the frame where the Nth backend slot *would* have been
+  // written in the slow path. At that point the slot still holds the previous
+  // (or zero) signature and the backend returns a blank frame.
+  // With > kMaxFramesInFlight the Nth slow-path frame writes the last slot,
+  // and the fast path activates on frame N+1 when all slots are primed.
+  const bool canFastPath = !noVisibleTerrain && !anyFadeDraws &&
+                           signature != 0ULL &&
+                           stableSigFrames_ > tunables::kMaxFramesInFlight &&
+                           !cachedDraws_.empty();
+
   // ── Terrain floor tracking (for minAltitudeAboveTerrain clamp) ───────────
   // Computed once before the tile loop and updated per-tile inside it.
   // Only active when the feature is enabled to avoid any overhead otherwise.
@@ -467,6 +609,125 @@ void CesiumEngine::updateFrame(double w, double h, FrameResult& result) {
   float  bestTerrainFloor = terrainFloorEllipsoidM_; // carry previous value if no tile matches
   double bestTerrainDist  = std::numeric_limits<double>::max();
 
+  // ── floor-scan cache lookup ─────────────────────────────────────────
+  // Skip the per-vertex scan when the camera has moved less than ~10 cm in
+  // both lat and lon AND the visible primitive set is unchanged (same
+  // geometry signature). The cached value is only trusted for non-zero
+  // signatures — sig==0 means a fade or rebuild is in flight, in which case
+  // we always re-scan and refresh the cache afterwards.
+  bool floorScanFromCache = false;
+  if (trackTerrainFloor && floorCacheValid_ && signature != 0ULL &&
+      signature == floorCacheSignature_) {
+    const double dLon = std::abs(camParams.longitude - floorCacheCamLonDeg_);
+    const double dLat = std::abs(camParams.latitude  - floorCacheCamLatDeg_);
+    if (dLon < 1e-6 && dLat < 1e-6) {
+      bestTerrainFloor   = floorCacheValue_;
+      floorScanFromCache = true;
+    }
+  }
+  // When tracking is off, suppress the per-tile scan branches (legacy
+  // behaviour already gated on trackTerrainFloor; this just keeps the cache
+  // semantics aligned).
+  const bool runFloorScan = trackTerrainFloor && !floorScanFromCache;
+
+  // ── 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
+  // the merged buffers. Skip the merge entirely: re-emit one DrawPrimitive
+  // per cached entry with a fresh per-tile MVP and the latest overlay /
+  // water-mask state read straight from TileGPUResources. The leftover
+  // result.localPositions / altitudes / uvs / indices stay empty — backends
+  // detect this via result.geometrySignature and use their cached slot data.
+  if (canFastPath) {
+    result.draws.reserve(cachedDraws_.size());
+    const TileGPUResources* lastScanRes = nullptr;
+    for (const auto& c : cachedDraws_) {
+      lifecycle_.stampTileUsed(const_cast<TileGPUResources*>(c.res));
+
+      // Floor scan (run once per res so multi-primitive tiles aren't scanned
+      // twice). Skipped when the P5 cache hit above produced a usable value.
+      if (runFloorScan && c.res != lastScanRes) {
+        lastScanRes = c.res;
+        const bool inside =
+            (c.wmTileBounds.x <= static_cast<float>(camLonRad) &&
+             static_cast<float>(camLonRad) <= c.wmTileBounds.z) &&
+            (c.wmTileBounds.y <= static_cast<float>(camLatRad) &&
+             static_cast<float>(camLatRad) <= c.wmTileBounds.w);
+        if (inside) {
+          for (const auto& prim : c.res->primitives) {
+            if (prim.altitudes.empty() || prim.localPositions.empty()) continue;
+            const size_t vc = prim.localPositions.size();
+            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;
+                bestTerrainFloor = prim.altitudes[vi];
+              }
+            }
+          }
+        }
+      }
+
+      const glm::dvec3 rtcCamRel = c.rtcCenter - glm::dvec3(cameraPos);
+      const glm::dmat4 translateD = glm::translate(glm::dmat4(1.0), rtcCamRel);
+
+      DrawPrimitive draw;
+      draw.indexByteOffset    = c.indexByteOffset;
+      draw.indexCount         = c.indexCount;
+      draw.hasUVs             = c.hasUVs;
+      draw.overlayTexture     = c.res->overlayTexture;
+      draw.overlayTranslation = c.res->overlayTranslation;
+      draw.overlayScale       = c.res->overlayScale;
+      draw.waterMaskTexture   = c.res->waterMaskTexture;
+      draw.isOnlyWater        = c.res->isOnlyWater;
+      draw.wmTileBounds       = c.wmTileBounds;
+      draw.wmTranslation      = c.res->wmTranslation;
+      draw.wmScale            = c.res->wmScale;
+      draw.mvpMatrix          = glm::mat4(vpDouble * translateD);
+      draw.rtcCenterEcef      = glm::vec3(c.rtcCenter);
+      draw.lodFade            = 1.0f;
+      result.draws.push_back(draw);
+    }
+
+    result.geometrySignature = signature;
+
+    result.tilesRendered = static_cast<int>(updateResult.tilesToRenderThisFrame.size());
+    result.tilesLoading  = updateResult.workerThreadTileLoadQueueLength +
+                           updateResult.mainThreadTileLoadQueueLength;
+    result.tilesVisited  = static_cast<int>(updateResult.tilesVisited);
+
+    const auto paramsFP = camera_.getParams();
+    result.cameraLat = paramsFP.latitude;
+    result.cameraLon = paramsFP.longitude;
+    result.cameraAlt = paramsFP.altitude;
+
+    if (trackTerrainFloor) {
+      terrainFloorEllipsoidM_ = bestTerrainFloor;
+      // 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) {
+        floorCacheValid_     = true;
+        floorCacheSignature_ = signature;
+        floorCacheCamLonDeg_ = camParams.longitude;
+        floorCacheCamLatDeg_ = camParams.latitude;
+        floorCacheValue_     = bestTerrainFloor;
+      }
+    }
+
+    lifecycle_.advanceFrame();
+    return;
+  }
+
+  // ── Slow path: rebuild cachedDraws_ inline ───────────────────────────────
+  // Wipe so the loop below can append. After the loop, if there were no
+  // fade-out draws we keep it for the fast path; otherwise we clear and
+  // reset the stability counter (the cache is only valid for stable
+  // no-fade frames).
+  cachedDraws_.clear();
+  if (!noVisibleTerrain) cachedDraws_.reserve(updateResult.tilesToRenderThisFrame.size());
+
   for (const auto& tile : updateResult.tilesToRenderThisFrame) {
     if (!tile) continue;
 
@@ -492,7 +753,9 @@ void CesiumEngine::updateFrame(double w, double h, FrameResult& result) {
           static_cast<float>(rect.getNorth()));
 
       // ── Terrain floor: find nearest vertex to camera nadir ────────────
-      if (trackTerrainFloor &&
+      // Suppressed when the cache returned a usable value for the
+      // current (signature, camLon, camLat) tuple.
+      if (runFloorScan &&
           rect.contains(CesiumGeospatial::Cartographic(camLonRad, camLatRad, 0.0))) {
         for (const auto& prim : res->primitives) {
           if (prim.altitudes.empty() || prim.localPositions.empty()) continue;
@@ -520,32 +783,47 @@ void CesiumEngine::updateFrame(double w, double h, FrameResult& result) {
       const bool     hasPrimUVs    =
           !prim.uvs.empty() && prim.uvs.size() == vertexCount;
 
-      // ── RTC: copy tile-local positions & altitudes ────────────────────────
-      result.localPositions.resize(result.localPositions.size() + vertexCount * 3);
-      result.altitudes.resize(result.altitudes.size() + vertexCount);
-      result.uvs.resize(result.uvs.size() + vertexCount * 2);
-
-      float* posOut = result.localPositions.data() + baseVertex * 3;
-      float* altOut = result.altitudes.data()      + baseVertex;
-      float* uvOut  = result.uvs.data()            + baseVertex * 2;
-
-      for (size_t vi = 0; vi < vertexCount; ++vi) {
-        const glm::vec3& lp = prim.localPositions[vi];
-        *posOut++ = lp.x;
-        *posOut++ = lp.y;
-        *posOut++ = lp.z;
-        *altOut++ = prim.altitudes.empty() ? 0.0f : prim.altitudes[vi];
-        if (hasPrimUVs) {
-          *uvOut++ = prim.uvs[vi].x;
-          *uvOut++ = prim.uvs[vi].y;
-        } else {
-          *uvOut++ = 0.5f;
-          *uvOut++ = 0.5f;
-        }
+      // ── RTC: bulk-copy tile-local positions, altitudes, UVs ─────────────────
+      // Use insert(end(), ptr, ptr+n) rather than resize()+memcpy: libc++
+      // dispatches insert for trivially-copyable float ranges to memmove
+      // (NEON-accelerated even at -O0), skipping the per-element zero-init
+      // loop that resize() performs before we'd overwrite the same bytes
+      // with memcpy. This halves the memory writes and eliminates the
+      // un-vectorised zero-init bottleneck in Debug builds.
+      static_assert(sizeof(glm::vec3) == 3 * sizeof(float), "glm::vec3 must be packed");
+      static_assert(sizeof(glm::vec2) == 2 * sizeof(float), "glm::vec2 must be packed");
+
+      {
+        const float* posData = reinterpret_cast<const float*>(prim.localPositions.data());
+        result.localPositions.insert(result.localPositions.end(),
+                                     posData, posData + vertexCount * 3);
       }
 
-      for (uint32_t idx : prim.indices) {
-        result.indices.push_back(static_cast<uint32_t>(baseVertex) + idx);
+      if (!prim.altitudes.empty()) {
+        result.altitudes.insert(result.altitudes.end(),
+                                prim.altitudes.data(),
+                                prim.altitudes.data() + vertexCount);
+      } else {
+        result.altitudes.resize(result.altitudes.size() + vertexCount, 0.0f);
+      }
+
+      if (hasPrimUVs) {
+        const float* uvData = reinterpret_cast<const float*>(prim.uvs.data());
+        result.uvs.insert(result.uvs.end(), uvData, uvData + vertexCount * 2);
+      } else {
+        result.uvs.resize(result.uvs.size() + vertexCount * 2, 0.5f);
+      }
+
+      // Indices: add base-vertex offset then insert. Use a temporary vector
+      // so the transform writes directly into pre-sized storage.
+      {
+        const size_t   nIdx    = prim.indices.size();
+        const size_t   idxBase = result.indices.size();
+        result.indices.resize(idxBase + nIdx);
+        const uint32_t bv32    = static_cast<uint32_t>(baseVertex);
+        const uint32_t* __restrict srcIdx = prim.indices.data();
+              uint32_t* __restrict dstIdx = result.indices.data() + idxBase;
+        for (size_t ii = 0; ii < nIdx; ++ii) { dstIdx[ii] = srcIdx[ii] + bv32; }
       }
 
       // ── RTC: per-tile MVP matrix (double → float) ─────────────────────────
@@ -570,14 +848,171 @@ void CesiumEngine::updateFrame(double w, double h, FrameResult& result) {
       draw.wmScale              = res->wmScale;
       draw.mvpMatrix            = perTileMVP;
       draw.rtcCenterEcef        = glm::vec3(prim.rtcCenter);
+      // ── LOD fade strategy: incoming tiles are SOLID, outgoing tiles dither ──
+      // We deliberately ignore Cesium Native's "fade-in" percentage on the
+      // tilesToRenderThisFrame list and always render newly-selected tiles at
+      // full opacity.  The reason is visibility correctness: if the incoming
+      // child were also dithering, both child (fading in) and parent (fading
+      // out, see loop below) would simultaneously have holes — and behind the
+      // holes is the sky.  By rendering the incoming tile fully solid we
+      // guarantee a complete opaque "floor" for every screen pixel covered by
+      // terrain, and the outgoing tile dithers OUT on top of it.  The original
+      // ring artefact is still masked because the outgoing tile is the
+      // coarser/older surface fading away (its disappearance is what used to
+      // be visible as a hard ring).
+      draw.lodFade              = 1.0f;
+      result.draws.push_back(draw);
+
+      // capture the per-primitive bits the fast path needs to re-emit
+      // this draw next frame (camera-dependent MVP is recomputed; everything
+      // else is stable as long as the signature is unchanged).
+      CachedDraw cd;
+      cd.res             = res;
+      cd.rtcCenter       = prim.rtcCenter;
+      cd.indexByteOffset = indexByteOff;
+      cd.indexCount      = static_cast<uint32_t>(prim.indices.size());
+      cd.hasUVs          = hasPrimUVs;
+      cd.wmTileBounds    = wmTileBounds;
+      cachedDraws_.push_back(cd);
+    }
+  }
+
+  // ── Fading-out tiles (LOD transition) ──────────────────────────────────────
+  // The outgoing (de-selected) tiles dither out on top of the already-solid
+  // incoming tiles drawn in the loop above.  Because the layer behind every
+  // dithered pixel is the new solid tile, the dither holes never reveal the
+  // sky — eliminating the bleed-through artefacts visible with the previous
+  // "both layers fade simultaneously" approach.
+  //
+  // Cesium Native fade semantics (Tileset.cpp _updateLodTransitions):
+  //   "We always fade tiles from 0.0 --> 1.0. Whether the tile is fading in or
+  //    out is determined by whether the tile is in the tilesToRenderThisFrame
+  //    or tilesFadingOut list."
+  //
+  // For tilesFadingOut, raw fade goes 0→1 but means "just stopped being
+  // selected → fully gone".  Our shader treats lodFade as visibility
+  // (1=visible, 0=hide), so we invert: visibility = 1 - rawFade.
+  // Terrain-floor tracking is skipped (these tiles are being replaced).
+  for (const auto& tile : updateResult.tilesFadingOut) {
+    if (!tile) continue;
+    const auto* renderContent = tile->getContent().getRenderContent();
+    if (!renderContent) continue;
+    const float fade = 1.0f - renderContent->getLodTransitionFadePercentage();
+    if (fade <= 0.0f) continue;  // fully faded out — "hide right away" per Cesium Native docs
+
+    const auto* res = static_cast<const TileGPUResources*>(
+        renderContent->getRenderResources());
+    if (!res) continue;
+    lifecycle_.stampTileUsed(const_cast<TileGPUResources*>(res));
+
+    glm::vec4 wmTileBounds(0.0f);
+    const auto& bv = tile->getBoundingVolume();
+    const CesiumGeospatial::BoundingRegion* bRegion =
+        Cesium3DTilesSelection::getBoundingRegionFromBoundingVolume(bv);
+    if (bRegion) {
+      const auto& rect = bRegion->getRectangle();
+      wmTileBounds = glm::vec4(
+          static_cast<float>(rect.getWest()),
+          static_cast<float>(rect.getSouth()),
+          static_cast<float>(rect.getEast()),
+          static_cast<float>(rect.getNorth()));
+    }
+
+    for (const auto& prim : res->primitives) {
+      if (prim.indices.empty() || prim.localPositions.empty()) continue;
+
+      const size_t   baseVertex   = result.localPositions.size() / 3;
+      const uint32_t indexByteOff =
+          static_cast<uint32_t>(result.indices.size() * sizeof(uint32_t));
+      const size_t   vertexCount  = prim.localPositions.size();
+      const bool     hasPrimUVs   =
+          !prim.uvs.empty() && prim.uvs.size() == vertexCount;
+
+      {
+        const float* posData = reinterpret_cast<const float*>(prim.localPositions.data());
+        result.localPositions.insert(result.localPositions.end(),
+                                     posData, posData + vertexCount * 3);
+      }
+
+      if (!prim.altitudes.empty()) {
+        result.altitudes.insert(result.altitudes.end(),
+                                prim.altitudes.data(),
+                                prim.altitudes.data() + vertexCount);
+      } else {
+        result.altitudes.resize(result.altitudes.size() + vertexCount, 0.0f);
+      }
+
+      if (hasPrimUVs) {
+        const float* uvData = reinterpret_cast<const float*>(prim.uvs.data());
+        result.uvs.insert(result.uvs.end(), uvData, uvData + vertexCount * 2);
+      } else {
+        result.uvs.resize(result.uvs.size() + vertexCount * 2, 0.5f);
+      }
+
+      {
+        const size_t   nIdx    = prim.indices.size();
+        const size_t   idxBase = result.indices.size();
+        result.indices.resize(idxBase + nIdx);
+        const uint32_t bv32    = static_cast<uint32_t>(baseVertex);
+        const uint32_t* __restrict srcIdx = prim.indices.data();
+              uint32_t* __restrict dstIdx = result.indices.data() + idxBase;
+        for (size_t ii = 0; ii < nIdx; ++ii) { dstIdx[ii] = srcIdx[ii] + bv32; }
+      }
+
+      const glm::dvec3 rtcCamRel =
+          prim.rtcCenter - glm::dvec3(cameraPos);
+      const glm::dmat4 translateD =
+          glm::translate(glm::dmat4(1.0), rtcCamRel);
+      const glm::mat4 perTileMVP =
+          glm::mat4(vpDouble * translateD);
+
+      DrawPrimitive draw;
+      draw.indexByteOffset      = indexByteOff;
+      draw.indexCount           = static_cast<uint32_t>(prim.indices.size());
+      draw.hasUVs               = hasPrimUVs;
+      draw.overlayTexture       = res->overlayTexture;
+      draw.overlayTranslation   = res->overlayTranslation;
+      draw.overlayScale         = res->overlayScale;
+      draw.waterMaskTexture     = res->waterMaskTexture;
+      draw.isOnlyWater          = res->isOnlyWater;
+      draw.wmTileBounds         = wmTileBounds;
+      draw.wmTranslation        = res->wmTranslation;
+      draw.wmScale              = res->wmScale;
+      draw.mvpMatrix            = perTileMVP;
+      draw.rtcCenterEcef        = glm::vec3(prim.rtcCenter);
+      draw.lodFade              = fade;
       result.draws.push_back(draw);
     }
   }
 
+  // ── Partition draws so all solid (lodFade==1) tiles render first ────────────
+  // Backends use this to bind the solid pipeline first (early-Z enabled on
+  // TBDR / Adreno / Mali) and switch to the dither pipeline at most once per
+  // frame when the first fading tile is reached. Stable to keep tile order
+  // deterministic so identical scenes produce identical command buffers.
+  std::stable_partition(result.draws.begin(), result.draws.end(),
+      [](const DrawPrimitive& d) { return d.lodFade >= 1.0f; });
+
+  // ── finalise cache state for next frame ──────────────────────────────
+  // Backends consume `geometrySignature` to short-circuit the host→GPU
+  // memcpy when their per-slot cached signature matches. We emit a non-zero
+  // signature only when this frame is byte-for-byte reproducible from the
+  // cached state — i.e. terrain is present and no LOD fades are in flight.
+  // Any fading-out draw forces a full upload because the dither cutoff
+  // changes every frame.
+  if (anyFadeDraws || noVisibleTerrain) {
+    result.geometrySignature = 0ULL;
+    cachedDraws_.clear();
+    stableSigFrames_ = 0;
+  } else {
+    result.geometrySignature = signature;
+  }
+
   result.tilesRendered = static_cast<int>(updateResult.tilesToRenderThisFrame.size());
   result.tilesLoading  = updateResult.workerThreadTileLoadQueueLength +
                          updateResult.mainThreadTileLoadQueueLength;
   result.tilesVisited  = static_cast<int>(updateResult.tilesVisited);
+
   const auto params    = camera_.getParams();
   result.cameraLat     = params.latitude;
   result.cameraLon     = params.longitude;
@@ -585,6 +1020,24 @@ void CesiumEngine::updateFrame(double w, double h, FrameResult& result) {
 
   if (trackTerrainFloor) {
     terrainFloorEllipsoidM_ = bestTerrainFloor;
+    // 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.
+    if (runFloorScan && signature != 0ULL) {
+      floorCacheValid_     = true;
+      floorCacheSignature_ = signature;
+      floorCacheCamLonDeg_ = camParams.longitude;
+      floorCacheCamLatDeg_ = camParams.latitude;
+      floorCacheValue_     = bestTerrainFloor;
+    } else if (!runFloorScan) {
+      // Cache hit on the slow path is unusual but possible (e.g. fade
+      // started this frame after a stable cache was warm). Nothing to do
+      // — terrainFloorEllipsoidM_ is already the cached value.
+    } else {
+      // Cannot key on signature=0; invalidate so the next stable frame
+      // re-populates the cache deterministically.
+      floorCacheValid_ = false;
+    }
   }
 
   lifecycle_.advanceFrame();