react-native-cesium 1.2.6 → 1.2.8

package/android/CMakeLists.txt

@@ -24,24 +24,39 @@ set(SHADER_DIR "${CMAKE_SOURCE_DIR}/src/main/cpp/vulkan/shaders")
 set(SPIRV_OUTPUT_DIR "${CMAKE_BINARY_DIR}/shaders")
 file(MAKE_DIRECTORY "${SPIRV_OUTPUT_DIR}")
 
-set(SHADER_SOURCES
-  "${SHADER_DIR}/terrain.vert"
-  "${SHADER_DIR}/terrain.frag"
-  "${SHADER_DIR}/sky.vert"
-  "${SHADER_DIR}/sky.frag"
+# Each entry: "SOURCE|OUTPUT_BASENAME|GLSLC_DEFINES"
+# terrain.frag is built TWICE — once plain (solid pipeline, no discard so
+# early-Z stays enabled) and once with TERRAIN_DITHER=1 (dither pipeline used
+# only for tiles actively crossing an LOD transition).  See VulkanBackend
+# createTerrain{Solid,Dither}Pipeline for how the two SPV blobs are consumed.
+set(SHADER_BUILDS
+  "${SHADER_DIR}/terrain.vert|terrain.vert|"
+  "${SHADER_DIR}/terrain.frag|terrain.frag|"
+  "${SHADER_DIR}/terrain.frag|terrain_dither.frag|TERRAIN_DITHER=1"
+  "${SHADER_DIR}/sky.vert|sky.vert|"
+  "${SHADER_DIR}/sky.frag|sky.frag|"
 )
 
-foreach(SHADER ${SHADER_SOURCES})
-  get_filename_component(SHADER_NAME ${SHADER} NAME)
+foreach(BUILD ${SHADER_BUILDS})
+  string(REPLACE "|" ";" PARTS "${BUILD}")
+  list(GET PARTS 0 SHADER)
+  list(GET PARTS 1 SHADER_NAME)
+  list(GET PARTS 2 SHADER_DEFINES)
+
   set(SPV_FILE "${SPIRV_OUTPUT_DIR}/${SHADER_NAME}.spv")
   set(SPV_HEADER "${SPIRV_OUTPUT_DIR}/${SHADER_NAME}.spv.h")
   string(REGEX REPLACE "[^a-zA-Z0-9]" "_" ARRAY_NAME "spv_${SHADER_NAME}")
 
+  set(GLSLC_ARGS -O)
+  if (SHADER_DEFINES)
+    set(GLSLC_ARGS ${GLSLC_ARGS} "-D${SHADER_DEFINES}")
+  endif()
+
   add_custom_command(
     OUTPUT "${SPV_FILE}"
-    COMMAND "${GLSLC}" -O -o "${SPV_FILE}" "${SHADER}"
+    COMMAND "${GLSLC}" ${GLSLC_ARGS} -o "${SPV_FILE}" "${SHADER}"
     DEPENDS "${SHADER}"
-    COMMENT "Compiling ${SHADER_NAME} -> SPIR-V"
+    COMMENT "Compiling ${SHADER_NAME} -> SPIR-V (defines: ${SHADER_DEFINES})"
   )
 
   # Generate a C header embedding the SPIR-V as a uint32_t array

package/android/src/main/cpp/vulkan/VulkanBackend.cpp

@@ -50,6 +50,7 @@
 // Pre-compiled SPIR-V headers (generated at build time by glslc + spv_to_header.cmake)
 #include "terrain.vert.spv.h"
 #include "terrain.frag.spv.h"
+#include "terrain_dither.frag.spv.h"
 #include "sky.vert.spv.h"
 #include "sky.frag.spv.h"
 
@@ -109,7 +110,7 @@ struct TerrainFragmentPC {
   float    translationY;         // 4 bytes
   float    scaleX;               // 4 bytes
   float    scaleY;               // 4 bytes
-  float    _pad;                 // 4 bytes
+  float    lodFade;              // 4 bytes  — LOD dither threshold
 };                               // 64 bytes
 
 namespace reactnativecesium {
@@ -296,6 +297,10 @@ void VulkanBackend::shutdown() {
   }
 
   for (int i = 0; i < kMaxFramesInFlight; ++i) {
+    if (vtxMapped_[i]) { vkUnmapMemory(device_, vtxMems_[i]); vtxMapped_[i] = nullptr; }
+    if (idxMapped_[i]) { vkUnmapMemory(device_, idxMems_[i]); idxMapped_[i] = nullptr; }
+    if (uvMapped_[i])  { vkUnmapMemory(device_, uvMems_[i]);  uvMapped_[i]  = nullptr; }
+    if (altMapped_[i]) { vkUnmapMemory(device_, altMems_[i]); altMapped_[i] = nullptr; }
     if (vtxBufs_[i]) vkDestroyBuffer(device_, vtxBufs_[i], nullptr);
     if (vtxMems_[i]) vkFreeMemory(device_, vtxMems_[i], nullptr);
     if (idxBufs_[i]) vkDestroyBuffer(device_, idxBufs_[i], nullptr);
@@ -858,7 +863,7 @@ void VulkanBackend::createSyncObjects() {
   // renderFinishedSemaphores_ created in beginFrame after swapchain is ready
 }
 
-// ── Pipeline cache (P1-vk-pipeline-cache) ───────────────────────────────────────
+// ── Pipeline cache (vk-pipeline-cache) ───────────────────────────────────────
 
 namespace {
 std::string pipelineCachePath(const std::string& cacheDir) {
@@ -1173,9 +1178,6 @@ void VulkanBackend::createSkyPipeline() {
 }
 
 void VulkanBackend::createTerrainPipeline() {
-  VkShaderModule vertModule = createShaderModule(device_, spv_terrain_vert, spv_terrain_vert_size);
-  VkShaderModule fragModule = createShaderModule(device_, spv_terrain_frag, spv_terrain_frag_size);
-
   // Vertex bindings: position (vec3) | uv (vec2) | altitude (float).
   static const VkVertexInputBindingDescription bindings[3] = {
       {0, 3 * sizeof(float), VK_VERTEX_INPUT_RATE_VERTEX},
@@ -1188,22 +1190,41 @@ void VulkanBackend::createTerrainPipeline() {
       {2, 2, VK_FORMAT_R32_SFLOAT,       0},
   };
 
-  PipelineBuildSpec spec{};
-  spec.vert = vertModule;
-  spec.frag = fragModule;
-  spec.bindingCount   = 3;
-  spec.bindings       = bindings;
-  spec.attributeCount = 3;
-  spec.attributes     = attrs;
-  spec.depthTest      = true;
-  spec.depthWrite     = true;
-  spec.cull           = VK_CULL_MODE_BACK_BIT;
-  spec.samples        = sampleCount_;
-  terrainPipeline_ = buildPipeline(device_, terrainPipelineLayout_, renderPass_,
-                                   pipelineCache_, spec);
+  VkShaderModule vertModule       = createShaderModule(
+      device_, spv_terrain_vert, spv_terrain_vert_size);
+  VkShaderModule fragSolidModule  = createShaderModule(
+      device_, spv_terrain_frag, spv_terrain_frag_size);
+  VkShaderModule fragDitherModule = createShaderModule(
+      device_, spv_terrain_dither_frag, spv_terrain_dither_frag_size);
+
+  auto buildOne = [&](VkShaderModule fragModule) {
+    PipelineBuildSpec spec{};
+    spec.vert = vertModule;
+    spec.frag = fragModule;
+    spec.bindingCount   = 3;
+    spec.bindings       = bindings;
+    spec.attributeCount = 3;
+    spec.attributes     = attrs;
+    spec.depthTest      = true;
+    spec.depthWrite     = true;
+    spec.cull           = VK_CULL_MODE_BACK_BIT;
+    spec.samples        = sampleCount_;
+    return buildPipeline(device_, terrainPipelineLayout_, renderPass_,
+                         pipelineCache_, spec);
+  };
 
-  vkDestroyShaderModule(device_, vertModule, nullptr);
-  vkDestroyShaderModule(device_, fragModule, nullptr);
+  // Solid pipeline: no LOD-fade discard in the fragment shader, so the GPU's
+  // early-Z optimisation runs at full speed.  This is the pipeline used for
+  // the overwhelming majority of draws outside an active LOD transition.
+  terrainSolidPipeline_  = buildOne(fragSolidModule);
+  // Dither pipeline: includes IGN-based discard.  Used only for draws where
+  // DrawPrimitive::lodFade < 1.0f (see CesiumEngine::updateFrame which
+  // partitions draws so the switch happens at most once per frame).
+  terrainDitherPipeline_ = buildOne(fragDitherModule);
+
+  vkDestroyShaderModule(device_, vertModule,       nullptr);
+  vkDestroyShaderModule(device_, fragSolidModule,  nullptr);
+  vkDestroyShaderModule(device_, fragDitherModule, nullptr);
 }
 
 void VulkanBackend::createGraphicsPipelinesAll() {
@@ -1212,9 +1233,12 @@ void VulkanBackend::createGraphicsPipelinesAll() {
 }
 
 void VulkanBackend::destroyGraphicsPipelinesAll() {
-  if (terrainPipeline_) vkDestroyPipeline(device_, terrainPipeline_, nullptr);
-  if (skyPipeline_)     vkDestroyPipeline(device_, skyPipeline_, nullptr);
-  terrainPipeline_ = skyPipeline_ = VK_NULL_HANDLE;
+  if (terrainSolidPipeline_)  vkDestroyPipeline(device_, terrainSolidPipeline_,  nullptr);
+  if (terrainDitherPipeline_) vkDestroyPipeline(device_, terrainDitherPipeline_, nullptr);
+  if (skyPipeline_)           vkDestroyPipeline(device_, skyPipeline_,           nullptr);
+  terrainSolidPipeline_  = VK_NULL_HANDLE;
+  terrainDitherPipeline_ = VK_NULL_HANDLE;
+  skyPipeline_           = VK_NULL_HANDLE;
 }
 
 // ── Memory / buffer helpers ─────────────────────────────────────────────────────
@@ -1285,23 +1309,29 @@ bool VulkanBackend::createBuffer(VkDeviceSize size, VkBufferUsageFlags usage,
 }
 
 void VulkanBackend::ensureBuffer(VkBuffer& buffer, VkDeviceMemory& memory,
-                                 size_t& capacity, size_t needed,
+                                 void*& mapped, size_t& capacity, size_t needed,
                                  const void* data, VkBufferUsageFlags usage) {
   if (needed == 0) return;
   if (needed > capacity) {
+    if (mapped) { vkUnmapMemory(device_, memory); mapped = nullptr; }
     if (buffer) vkDestroyBuffer(device_, buffer, nullptr);
     if (memory) vkFreeMemory(device_, memory, nullptr);
     size_t newCap = std::max(needed, capacity > 0 ? capacity * 2 : needed);
     newCap = (newCap + 4095UL) & ~4095UL;
-    createBuffer(static_cast<VkDeviceSize>(newCap), usage,
-                 VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT,
-                 buffer, memory);
+    if (!createBuffer(static_cast<VkDeviceSize>(newCap), usage,
+                      VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT,
+                      buffer, memory)) {
+      capacity = 0;
+      return;
+    }
     capacity = newCap;
+    if (vkMapMemory(device_, memory, 0, VK_WHOLE_SIZE, 0, &mapped) != VK_SUCCESS) {
+      mapped = nullptr;
+      return;
+    }
   }
-  void* mapped = nullptr;
-  if (vkMapMemory(device_, memory, 0, needed, 0, &mapped) != VK_SUCCESS) return;
+  if (!mapped) return;
   memcpy(mapped, data, needed);
-  vkUnmapMemory(device_, memory);
 }
 
 VkCommandBuffer VulkanBackend::beginSingleTimeCommands() {
@@ -1449,25 +1479,34 @@ void VulkanBackend::initStagingRing(VkDeviceSize bytes) {
     stagingMemory_ = VK_NULL_HANDLE;
     return;
   }
-  stagingMapped_ = static_cast<uint8_t*>(mapped);
-  stagingHead_   = 0;
+  stagingMapped_         = static_cast<uint8_t*>(mapped);
+  stagingHead_           = 0;
+  stagingBytesThisBatch_ = 0;
 }
 
 VkDeviceSize VulkanBackend::allocateStagingSlice(VkDeviceSize size) {
   if (!stagingMapped_ || size == 0 || size > kStagingSize) return SIZE_MAX;
 
   VkDeviceSize aligned = (size + kStagingAlignment - 1) & ~(kStagingAlignment - 1);
+
+  // per-batch budget. Refuse the allocation if granting it would let a
+  // single beginFrame->flushPendingUploads cycle eat more than 1/N of the
+  // ring. The caller (createImageFromPixels) falls back to the synchronous
+  // single-tile path for that tile so the rest of the batch still goes via
+  // the async ring.
+  if (stagingBytesThisBatch_ + aligned > kStagingPerFrameBudget) {
+    return SIZE_MAX;
+  }
+
   VkDeviceSize off;
   if (stagingHead_ + aligned > kStagingSize) {
-    // Wrap to the start of the ring. Anything still in flight from before the
-    // wrap will keep its previous offset alive until its upload fence
-    // signalled in beginFrame.
     off = 0;
     stagingHead_ = aligned;
   } else {
     off = stagingHead_;
     stagingHead_ += aligned;
   }
+  stagingBytesThisBatch_ += aligned;
   return off;
 }
 
@@ -1486,7 +1525,7 @@ void VulkanBackend::flushPendingUploads() {
     LOGE("flushPendingUploads: upload command buffer is NULL!");
     return;
   }
-  
+
   vkResetCommandBuffer(cmd, 0);
 
   VkCommandBufferBeginInfo bi{};
@@ -1506,7 +1545,7 @@ void VulkanBackend::flushPendingUploads() {
       safeMipLevels = 1;
       u.tex->mipLevels = 1;
     }
-    
+
     VkImageMemoryBarrier b{};
     b.sType               = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER;
     b.srcAccessMask       = 0;
@@ -1574,23 +1613,41 @@ void VulkanBackend::flushPendingUploads() {
 
   vkEndCommandBuffer(cmd);
 
-  // SYNCHRONOUS submit and wait - simpler and more reliable than fence-based
-  // batching. The performance hit is minimal since uploads are infrequent.
+  // async submit. The fence lets beginFrame reclaim the staging slices in
+  // kMaxFramesInFlight frames' time without ever calling vkQueueWaitIdle.
+  // Ordering: this submit precedes endFrame()'s draw submit on the same
+  // graphicsQueue_, so the image layout transitions recorded above are
+  // visible to subsequent fragment-shader reads via the standard in-queue
+  // execution + memory-barrier rules — no extra semaphore needed.
+  vkResetFences(device_, 1, &uploadFences_[frameIndex_]);
+
   VkSubmitInfo si{};
   si.sType              = VK_STRUCTURE_TYPE_SUBMIT_INFO;
   si.commandBufferCount = 1;
   si.pCommandBuffers    = &cmd;
-  
-  VkResult submitResult = vkQueueSubmit(graphicsQueue_, 1, &si, VK_NULL_HANDLE);
+
+  VkResult submitResult =
+      vkQueueSubmit(graphicsQueue_, 1, &si, uploadFences_[frameIndex_]);
   if (submitResult != VK_SUCCESS) {
     LOGE("flushPendingUploads: vkQueueSubmit failed: %d", submitResult);
     return;
   }
-  
-  vkQueueWaitIdle(graphicsQueue_);
 
   // Mark each texture as visible to subsequent draws (no longer pending).
+  // Safe to flip here because the next draw submit happens after this one on
+  // the same queue, and the upload CB ends in a TRANSFER → FRAGMENT_SHADER
+  // memory barrier.
   for (auto& u : uploads) u.tex->pendingUpload = false;
+
+  // Move uploads into this slot's in-flight list so beginFrame can free
+  // their staging slices once uploadFences_[frameIndex_] is signalled (which
+  // happens at most kMaxFramesInFlight frames from now).
+  {
+    std::lock_guard<std::mutex> lk(stagingMutex_);
+    auto& inflight = uploadsInFlight_[frameIndex_];
+    inflight.insert(inflight.end(), uploads.begin(), uploads.end());
+    stagingBytesThisBatch_ = 0;
+  }
 }
 
 // ── Generic image creator (P2-pipelines-dedupe) ─────────────────────────────
@@ -1898,13 +1955,13 @@ void VulkanBackend::recreateSwapchain() {
 
 void VulkanBackend::beginFrame(const FrameParams& /*params*/) {
   if (device_ == VK_NULL_HANDLE) return;
-  
+
   // On Android, defer swapchain creation until the first frame to ensure the
   // surface compositor is fully ready. Creating it too early can cause
   // vkAcquireNextImageKHR to block indefinitely.
   if (swapchain_ == VK_NULL_HANDLE) {
     createSwapchain();
-    
+
     // Create renderFinishedSemaphores now that we know swapchainImages_.size()
     renderFinishedSemaphores_.resize(swapchainImages_.size());
     VkSemaphoreCreateInfo semInfo{};
@@ -1912,7 +1969,7 @@ void VulkanBackend::beginFrame(const FrameParams& /*params*/) {
     for (size_t i = 0; i < renderFinishedSemaphores_.size(); ++i) {
       VK_CHECK(vkCreateSemaphore(device_, &semInfo, nullptr, &renderFinishedSemaphores_[i]));
     }
-    
+
     createRenderPass();
     createDepthResources();
     if (sampleCount_ != VK_SAMPLE_COUNT_1_BIT) createMsaaResources();
@@ -1958,11 +2015,14 @@ void VulkanBackend::beginFrame(const FrameParams& /*params*/) {
   ++totalFrameCount_;
   flushPendingDeletes();
 
-  // Reclaim staging slices for uploads that have now finished on the GPU.
-  // (Their submit was made N=kMaxFramesInFlight frames ago against
-  // uploadFences_[frameIndex_]; the wait above is on inFlightFences_, but
-  // since uploads were submitted on the same queue *before* the previous
-  // frame's draw they must have completed too.)
+  // reclaim staging slices owned by this slot's previous async upload
+  // submit. The upload fence is created SIGNALED, so the first wait through
+  // each slot is a no-op; on subsequent passes it ensures the GPU has finished
+  // reading those staging bytes before we let allocateStagingSlice hand them
+  // back out.
+  if (uploadFences_[frameIndex_] != VK_NULL_HANDLE) {
+    vkWaitForFences(device_, 1, &uploadFences_[frameIndex_], VK_TRUE, UINT64_MAX);
+  }
   {
     std::lock_guard<std::mutex> lk(stagingMutex_);
     uploadsInFlight_[frameIndex_].clear();
@@ -1976,7 +2036,7 @@ void VulkanBackend::beginFrame(const FrameParams& /*params*/) {
   VkResult result = vkAcquireNextImageKHR(device_, swapchain_, 1000000000ULL,
                                           imageAvailableSemaphores_[frameIndex_],
                                           VK_NULL_HANDLE, &imageIndex_);
-  
+
   if (result == VK_TIMEOUT) {
     LOGE("VulkanBackend::beginFrame: vkAcquireNextImageKHR timed out");
     frameBegan_ = false;
@@ -2065,26 +2125,48 @@ void VulkanBackend::drawScene(const FrameResult& frame) {
     vkCmdDraw(cmd, 3, 1, 0, 0);
   }
 
-  if (frame.draws.empty() || frame.localPositions.empty() || frame.indices.empty() ||
-      frame.altitudes.empty() || !terrainPipeline_) {
+  if (frame.draws.empty() || !terrainSolidPipeline_ || !terrainDitherPipeline_) {
     return;
   }
 
   const int fi = frameIndex_;
 
-  const size_t vtxBytes = frame.localPositions.size() * sizeof(float);
-  const size_t idxBytes = frame.indices.size()        * sizeof(uint32_t);
-  const size_t uvBytes  = frame.uvs.size()            * sizeof(float);
-  const size_t altBytes = frame.altitudes.size()      * sizeof(float);
+  // check the per-slot geometry signature cache. When it matches we
+  // know the persistent vtx/idx/uv/alt buffers already hold the right bytes
+  // and the engine intentionally left the merged CPU arrays empty.
+  const uint64_t sig         = frame.geometrySignature;
+  const bool     slotMatches = (sig != 0ULL) && (sig == geomSlotSig_[fi]);
 
-  ensureBuffer(vtxBufs_[fi], vtxMems_[fi], vtxCaps_[fi], vtxBytes,
-               frame.localPositions.data(), VK_BUFFER_USAGE_VERTEX_BUFFER_BIT);
-  ensureBuffer(idxBufs_[fi], idxMems_[fi], idxCaps_[fi], idxBytes,
-               frame.indices.data(), VK_BUFFER_USAGE_INDEX_BUFFER_BIT);
-  ensureBuffer(uvBufs_[fi], uvMems_[fi], uvCaps_[fi], uvBytes,
-               frame.uvs.data(), VK_BUFFER_USAGE_VERTEX_BUFFER_BIT);
-  ensureBuffer(altBufs_[fi], altMems_[fi], altCaps_[fi], altBytes,
-               frame.altitudes.data(), VK_BUFFER_USAGE_VERTEX_BUFFER_BIT);
+  if (!slotMatches && (frame.localPositions.empty() || frame.indices.empty() ||
+                       frame.altitudes.empty())) {
+    return;
+  }
+
+  if (!slotMatches) {
+    const size_t vtxBytes = frame.localPositions.size() * sizeof(float);
+    const size_t idxBytes = frame.indices.size()        * sizeof(uint32_t);
+    const size_t uvBytes  = frame.uvs.size()            * sizeof(float);
+    const size_t altBytes = frame.altitudes.size()      * sizeof(float);
+
+    ensureBuffer(vtxBufs_[fi], vtxMems_[fi], vtxMapped_[fi], vtxCaps_[fi],
+                 vtxBytes, frame.localPositions.data(),
+                 VK_BUFFER_USAGE_VERTEX_BUFFER_BIT);
+    ensureBuffer(idxBufs_[fi], idxMems_[fi], idxMapped_[fi], idxCaps_[fi],
+                 idxBytes, frame.indices.data(),
+                 VK_BUFFER_USAGE_INDEX_BUFFER_BIT);
+    ensureBuffer(uvBufs_[fi], uvMems_[fi], uvMapped_[fi], uvCaps_[fi],
+                 uvBytes, frame.uvs.data(),
+                 VK_BUFFER_USAGE_VERTEX_BUFFER_BIT);
+    ensureBuffer(altBufs_[fi], altMems_[fi], altMapped_[fi], altCaps_[fi],
+                 altBytes, frame.altitudes.data(),
+                 VK_BUFFER_USAGE_VERTEX_BUFFER_BIT);
+
+    // Record what this slot now holds — set only after every buffer has
+    // been refreshed. If `sig == 0` we deliberately propagate it so future
+    // frames re-upload on this slot (e.g. an active fade is invalidating
+    // the cache).
+    geomSlotSig_[fi] = sig;
+  }
 
   if (!vtxBufs_[fi] || !idxBufs_[fi]) return;
 
@@ -2095,7 +2177,11 @@ void VulkanBackend::drawScene(const FrameResult& frame) {
   terrU.cameraEcef[3] = 0.0f;
   memcpy(terrainUboMapped_[fi], &terrU, sizeof(TerrainUBO));
 
-  vkCmdBindPipeline(cmd, VK_PIPELINE_BIND_POINT_GRAPHICS, terrainPipeline_);
+  // Start with the solid pipeline. CesiumEngine has stable_partition-ed draws so
+  // every lodFade==1 draw is first; we only switch to the dither pipeline once,
+  // when the first fading draw is reached.
+  VkPipeline currentPipeline = terrainSolidPipeline_;
+  vkCmdBindPipeline(cmd, VK_PIPELINE_BIND_POINT_GRAPHICS, currentPipeline);
 
   VkBuffer     vertexBuffers[] = {vtxBufs_[fi], uvBufs_[fi], altBufs_[fi]};
   VkDeviceSize offsets[]       = {0, 0, 0};
@@ -2125,6 +2211,18 @@ void VulkanBackend::drawScene(const FrameResult& frame) {
   for (const auto& draw : frame.draws) {
     if (draw.indexCount == 0) continue;
 
+    // ── Pipeline switch for LOD-fade dither ─────────────────────────────────
+    // Solid pipeline (no discard) for fully-visible tiles keeps Adreno/Mali
+    // early-Z enabled at full speed; dither pipeline only used for actively-
+    // fading tiles. Draws are partitioned so this switch fires at most once
+    // per frame.
+    VkPipeline wantedPipeline = (draw.lodFade < 1.0f)
+        ? terrainDitherPipeline_ : terrainSolidPipeline_;
+    if (wantedPipeline != currentPipeline) {
+      currentPipeline = wantedPipeline;
+      vkCmdBindPipeline(cmd, VK_PIPELINE_BIND_POINT_GRAPHICS, currentPipeline);
+    }
+
     const float* mp = glm::value_ptr(draw.mvpMatrix);
     for (int i = 0; i < 16; ++i) pc.v.mvpMatrix[i] = mp[i];
 
@@ -2143,6 +2241,7 @@ void VulkanBackend::drawScene(const FrameResult& frame) {
     pc.f.translationY        = draw.overlayTranslation.y;
     pc.f.scaleX              = draw.overlayScale.x;
     pc.f.scaleY              = draw.overlayScale.y;
+    pc.f.lodFade             = draw.lodFade;
     vkCmdPushConstants(cmd, terrainPipelineLayout_,
                        VK_SHADER_STAGE_VERTEX_BIT | VK_SHADER_STAGE_FRAGMENT_BIT,
                        0, sizeof(CombinedPC), &pc);

package/android/src/main/cpp/vulkan/VulkanBackend.h

@@ -104,8 +104,14 @@ private:
   bool createBuffer(VkDeviceSize size, VkBufferUsageFlags usage,
                     VkMemoryPropertyFlags props, VkBuffer& buffer,
                     VkDeviceMemory& memory);
-  void ensureBuffer(VkBuffer& buffer, VkDeviceMemory& memory, size_t& capacity,
-                    size_t needed, const void* data, VkBufferUsageFlags usage);
+  // Grow `buffer`/`memory` if needed and copy `data` (size = needed bytes)
+  // into it via the persistently mapped pointer (`mapped`). On reallocation
+  // the previous mapping is unmapped and `mapped` is rewritten with the new
+  // map; otherwise the existing map is reused, saving a map/unmap pair per
+  // frame for each of the four merged terrain buffers.
+  void ensureBuffer(VkBuffer& buffer, VkDeviceMemory& memory, void*& mapped,
+                    size_t& capacity, size_t needed, const void* data,
+                    VkBufferUsageFlags usage);
 
   // ── Deferred upload pipeline ─────────────────────────────────────────────
   // Each call to createRasterTexture / createWaterMaskTexture allocates a slice
@@ -198,7 +204,12 @@ private:
   VkDescriptorSetLayout skyDescSetLayout_     = VK_NULL_HANDLE;
   VkPipelineLayout      terrainPipelineLayout_ = VK_NULL_HANDLE;
   VkPipelineLayout      skyPipelineLayout_     = VK_NULL_HANDLE;
-  VkPipeline            terrainPipeline_       = VK_NULL_HANDLE;
+  // Two terrain pipelines built from the same GLSL source (compiled twice via
+  // -DTERRAIN_DITHER=1 in android/CMakeLists.txt).  The solid pipeline omits
+  // the LOD-fade discard so early-Z stays enabled at full speed on Adreno/Mali;
+  // the dither pipeline is used only for draws where DrawPrimitive::lodFade<1.
+  VkPipeline            terrainSolidPipeline_  = VK_NULL_HANDLE;
+  VkPipeline            terrainDitherPipeline_ = VK_NULL_HANDLE;
   VkPipeline            skyPipeline_           = VK_NULL_HANDLE;
 
   VkDescriptorPool descriptorPool_     = VK_NULL_HANDLE;
@@ -234,22 +245,38 @@ private:
   uint32_t imageIndex_  = 0;
   bool     frameBegan_  = false;
 
-  // Triple-buffered persistent vertex/index/UV/altitude buffers
-  VkBuffer       vtxBufs_[kMaxFramesInFlight] = {};
-  VkDeviceMemory vtxMems_[kMaxFramesInFlight] = {};
-  size_t         vtxCaps_[kMaxFramesInFlight] = {};
-
-  VkBuffer       idxBufs_[kMaxFramesInFlight] = {};
-  VkDeviceMemory idxMems_[kMaxFramesInFlight] = {};
-  size_t         idxCaps_[kMaxFramesInFlight] = {};
-
-  VkBuffer       uvBufs_[kMaxFramesInFlight]  = {};
-  VkDeviceMemory uvMems_[kMaxFramesInFlight]  = {};
-  size_t         uvCaps_[kMaxFramesInFlight]  = {};
-
-  VkBuffer       altBufs_[kMaxFramesInFlight] = {};  // float altitude per vertex
-  VkDeviceMemory altMems_[kMaxFramesInFlight] = {};
-  size_t         altCaps_[kMaxFramesInFlight] = {};
+  // Triple-buffered persistent vertex/index/UV/altitude buffers.
+  // The mapped pointers are kept alive for the lifetime of the buffer (only
+  // unmapped when the underlying memory is freed on reallocation/shutdown),
+  // mirroring how skyUboMapped_ / terrainUboMapped_ are handled — this saves
+  // four map/unmap pairs per frame.
+  VkBuffer       vtxBufs_[kMaxFramesInFlight]   = {};
+  VkDeviceMemory vtxMems_[kMaxFramesInFlight]   = {};
+  void*          vtxMapped_[kMaxFramesInFlight] = {};
+  size_t         vtxCaps_[kMaxFramesInFlight]   = {};
+
+  VkBuffer       idxBufs_[kMaxFramesInFlight]   = {};
+  VkDeviceMemory idxMems_[kMaxFramesInFlight]   = {};
+  void*          idxMapped_[kMaxFramesInFlight] = {};
+  size_t         idxCaps_[kMaxFramesInFlight]   = {};
+
+  VkBuffer       uvBufs_[kMaxFramesInFlight]    = {};
+  VkDeviceMemory uvMems_[kMaxFramesInFlight]    = {};
+  void*          uvMapped_[kMaxFramesInFlight]  = {};
+  size_t         uvCaps_[kMaxFramesInFlight]    = {};
+
+  VkBuffer       altBufs_[kMaxFramesInFlight]   = {};  // float altitude per vertex
+  VkDeviceMemory altMems_[kMaxFramesInFlight]   = {};
+  void*          altMapped_[kMaxFramesInFlight] = {};
+  size_t         altCaps_[kMaxFramesInFlight]   = {};
+
+  // ── per-slot geometry signature cache ────────────────────────────────
+  // When FrameResult::geometrySignature matches the value last written into
+  // this slot, the four merged buffers above already contain exactly the
+  // bytes the engine would have produced this frame and the host memcpys can
+  // be skipped. 0 means "this slot is stale" — backends should always
+  // memcpy when geomSlotSig_[fi] is 0 or differs from the incoming sig.
+  uint64_t geomSlotSig_[kMaxFramesInFlight] = {};
 
   // Per-frame UBO: just cameraEcef (fragment stage, used for lighting vd).
   // MVP is now per-draw via push constants.
@@ -270,10 +297,24 @@ private:
   // beginFrame when the matching upload fence is signalled).
   static constexpr VkDeviceSize kStagingSize = 64ULL * 1024ULL * 1024ULL;
   static constexpr VkDeviceSize kStagingAlignment = 256;
+  // Per-batch (per beginFrame flush) allocation budget. With async upload
+  // submission, the ring head must never wrap past slices still being read by
+  // the GPU. Capping a single batch to kStagingSize / kMaxFramesInFlight
+  // guarantees that by the time the head wraps back, the slot that wrote
+  // those bytes has already had its uploadFences_ signalled (we wait on it
+  // in beginFrame before clearing uploadsInFlight_). When a single batch
+  // would exceed the budget the call site falls back to the synchronous
+  // per-tile upload path that already exists for the pre-init case.
+  static constexpr VkDeviceSize kStagingPerFrameBudget =
+      kStagingSize / kMaxFramesInFlight;
   VkBuffer       stagingBuffer_ = VK_NULL_HANDLE;
   VkDeviceMemory stagingMemory_ = VK_NULL_HANDLE;
   uint8_t*       stagingMapped_ = nullptr;
   VkDeviceSize   stagingHead_   = 0;
+  // Bytes allocated from the staging ring since the last flush. Reset to 0
+  // inside flushPendingUploads() once those bytes have been moved into
+  // uploadsInFlight_[frameIndex_].
+  VkDeviceSize   stagingBytesThisBatch_ = 0;
   VkFence        uploadFences_[kMaxFramesInFlight] = {};
   std::vector<PendingUpload> pendingUploadsCurrent_;     // queued, not yet submitted
   std::vector<PendingUpload> uploadsInFlight_[kMaxFramesInFlight]; // submitted